tickets

14.5 KB

1. // lib/projects.hl — PROJECTS AND THEIR MEMBERS (ticket #20, 2026-09-26). Statics only, the server realm.
2. // Two hl:mpackdb tables (storage/mpackdb/, UUID keys — creator's convention):
3. // projectsTable pk @id index !slug { title, slug, description (Markdown), oldSlugs ('a,b' — the
4. // slugs it had before; they still resolve), created }
5. // membersTable pk @id index project user { project (project @id), user (users @id), role, created }
6. // role = 'use' | 'edit' | 'admin' (below). One row per (project, user).
7. //
8. // THE THREE ROLES (a member of a project; anybody else only reads):
9. // use = comment, and move a ticket between open and review
10. // edit = use + create, edit, assign, any state, relations
11. // admin = edit + the project's settings and its members
12. // ANY logged-in user with a display name opens a project and is its first admin; a project always keeps one admin.
13. // THE PROJECT SLUG (the URL part) is generated from the title and only holds letters,
14. // digits, '.', '_' and '-' (URL-safe); an admin can change it, the old one keeps resolving.
15. // Removing a member also unassigns their tickets: that is tickets.hl removeMember (it owns the tickets table).
16. import { MPackDB } from 'hl:mpackdb'
17. import { now } from 'hl:time'
18. import { storageDir, countOf, first, merged, clean, localStamp, oldestFirst, projectHrefOf, settingsHrefOf } from './util.hl'
19. import { nameOfUser, userRecord, userRecords } from './users.hl'
21. static projectsTable = new MPackDB(file = storageDir + '/projects.db', primaryKey = '@id', indexes = ['!slug'])
22. static membersTable = new MPackDB(file = storageDir + '/members.db', primaryKey = '@id', indexes = ['project', 'user'])
24. static roles = ['use' 'edit' 'admin']
25. static rankOf = (role) => { return role == 'admin' ? 3 : (role == 'edit' ? 2 : (role == 'use' ? 1 : 0)) }
27. // the refusals a write answers (`forbidden = true` → the API answers 403)
28. static notAdmin = { error = 'only an admin of the project can do that' field = '' forbidden = true }
29. static userOk = (u) => { return u != null && u.id != null && u.name != null && u.name != '' }
30. static authorMissing = { error = 'a write needs a logged-in user' field = 'author' }
32. // ---- finding a project ---------------------------------------------------------------------------
33. static projectRecord = (id) => { return id == null || id == '' || hlTypeName(id) != 'String' ? null : projectsTable.fetch(id) }
34. static projectBySlug = (slug) => { return slug == null || hlTypeName(slug) != 'String' ? null : first(projectsTable.find('slug', slug)) }
36. // projects in the order they were created (stored time, not key order)
37. static projectRecords = () => {
38. all = projectsTable.find(null, null)
39. ps = []
40. if (countOf(all) == 0) { return ps }
41. for (p of all) { ps.push(p) }
42. return oldestFirst(ps, 'created')
43. }
45. static oldSlugsOf = (p) => {
46. out = []
47. if (p.oldSlugs == null || p.oldSlugs == '') { return out }
48. for (s of p.oldSlugs.split(',')) { if (s != '') { out.push(s) } }
49. return out
50. }
52. // a project by its CURRENT slug, or by a slug it once had (old links keep working)
53. static projectByAnySlug = (slug) => {
54. p = projectBySlug(slug)
55. if (p != null) { return p }
56. if (slug == null || hlTypeName(slug) != 'String' || slug == '') { return null }
57. for (q of projectRecords()) { if (oldSlugsOf(q).includes(slug)) { return q } }
58. return null
59. }
61. // what the API takes for a project: its slug (also an old one) or its id
62. static projectByRef = (ref) => {
63. if (ref == null || hlTypeName(ref) != 'String' || ref == '') { return null }
64. p = projectByAnySlug(ref)
65. return p != null ? p : projectRecord(ref)
66. }
68. static projectNames = () => {
69. out = []
70. for (p of projectRecords()) { out.push(p.slug) }
71. return out
72. }
74. // the slug of a ticket's project ('' when the project is gone)
75. static projectSlugOf = (t) => {
76. p = projectRecord(t.project)
77. return p != null ? p.slug : ''
78. }
80. static projectRowOf = (p) => {
81. return { id = p.id title = p.title slug = p.slug description = p.description != null ? p.description : '' href = projectHrefOf(p.slug) settingsHref = settingsHrefOf(p.slug) created = localStamp(p.created) createdMs = p.created }
82. }
84. // ---- the slug ------------------------------------------------------------------------------------
85. // a project slug that a URL carries as is: letters, digits, . _ -
86. static isSlugChar = (c) => {
87. return (c >= 48 && c <= 57) || (c >= 65 && c <= 90) || (c >= 97 && c <= 122) || c == 46 || c == 95 || c == 45
88. }
89. static validProjectName = (p) => {
90. if (p == null || hlTypeName(p) != 'String' || p.length == 0 || p.length > 100) { return false }
91. let i = 0
92. while (i < p.length) {
93. if (!isSlugChar(p.charCodeAt(i))) { return false }
94. i = i + 1
95. }
96. return true
97. }
99. // RESERVED SLUGS (ticket #25): a project's page is /<slug>, so a slug may not be the first part of a path the app
100. // or hl:web answers itself (every explicit route of project.hl, hl:web's /__hl/… and the component modules under
101. // /components/…), nor a name we may want for a page later. Compared in lower case. The gate checks that every
102. // first segment of a project.hl route is in this list.
103. static reservedSlugs = ['api' '__hl' 'components' 'shared' 'icons' 'assets' 'favicon.ico' 'robots.txt' 'login' 'login.js' 'logout' 'md-editor.js' 'connect' 'project' 'projects' 'state' 'inbox' 'new-project' 'you' 'my' 'me' 'sign-in' 'sign-out' 'settings' 'tickets' 'search' 'help' 'about' 'admin' '.' '..']
104. static isReservedSlug = (s) => { return s != null && hlTypeName(s) == 'String' && reservedSlugs.includes(s.toLowerCase()) }
105. static reservedError = (s) => { return { error = 'the slug ' + s + ' is reserved: /' + s + ' is a page of tickets itself' field = 'slug' } }
107. // the slug a title proposes: lower case letters and digits, other runs become one '-'
108. static slugFromTitle = (title) => {
109. t = clean(title).toLowerCase()
110. let out = ''
111. let i = 0
112. while (i < t.length && out.length < 60) {
113. let c = t.charCodeAt(i)
114. if ((c >= 48 && c <= 57) || (c >= 97 && c <= 122)) { out = out + t[i] } else if (out != '' && !out.endsWith('-')) { out = out + '-' }
115. i = i + 1
116. }
117. while (out.endsWith('-')) { out = out.slice(0, out.length - 1) }
118. return out == '' ? 'project' : out
119. }
120. // is this slug free? (`except` = the project that may keep it)
121. static slugFree = (slug, except) => {
122. for (q of projectRecords()) {
123. if (except == null || q.id != except) {
124. if (q.slug == slug || oldSlugsOf(q).includes(slug)) { return false }
125. }
126. }
127. return true
128. }
129. // the slug a new project gets: the proposal, or with -2, -3 … when it is taken or reserved
130. static uniqueSlug = (base) => {
131. if (slugFree(base, null) && !isReservedSlug(base)) { return base }
132. let n = 2
133. while (!slugFree(base + '-' + n, null) && n < 10000) { n = n + 1 }
134. return base + '-' + n
135. }
137. // ---- opening and changing a project ---------------------------------------------------------------
138. // answers { error, field } or { project (row), members }. A slug is generated from the title unless one is given.
139. static createProject = (user, title, slug, description) => {
140. if (!userOk(user)) { return authorMissing }
141. t = clean(title)
142. if (t == '') { return { error = 'the title is required' field = 'title' } }
143. if (t.length > 100) { return { error = 'the title is too long (at most 100 characters)' field = 'title' } }
144. let s = clean(slug)
145. if (s == '') { s = uniqueSlug(slugFromTitle(t)) }
146. if (!validProjectName(s)) { return { error = "a slug has no spaces or slashes: letters, digits, '.', '_' and '-' only" field = 'slug' } }
147. if (isReservedSlug(s)) { return reservedError(s) }
148. if (!slugFree(s, null)) { return { error = 'the slug ' + s + ' is already used by a project' field = 'slug' } }
149. id = projectsTable.put({ title = t slug = s description = clean(description) oldSlugs = '' created = now() })
150. if (id == null) { return { error = 'could not store the project: ' + projectsTable.lastError() field = '' } }
151. addMember(id, user.id, 'admin')
152. return { project = projectRowOf(projectsTable.fetch(id)) members = memberRows(id) }
153. }
155. // an admin changes title / slug / description (null = keep). A new slug keeps the old one working.
156. static updateProject = (projectId, actor, title, slug, description) => {
157. p = projectRecord(projectId)
158. if (p == null) { return { error = 'no such project' } }
159. if (!userOk(actor)) { return authorMissing }
160. if (!isAdminOf(p.id, actor)) { return notAdmin }
161. if (title == null && slug == null && description == null) { return { error = 'nothing to change: give title, slug and/or description' field = '' } }
162. t = title != null ? clean(title) : p.title
163. if (t == '') { return { error = 'the title is required' field = 'title' } }
164. if (t.length > 100) { return { error = 'the title is too long (at most 100 characters)' field = 'title' } }
165. s = slug != null ? clean(slug) : p.slug
166. if (s == '') { return { error = 'the slug is required' field = 'slug' } }
167. if (!validProjectName(s)) { return { error = "a slug has no spaces or slashes: letters, digits, '.', '_' and '-' only" field = 'slug' } }
168. if (s != p.slug && isReservedSlug(s)) { return reservedError(s) }
169. if (!slugFree(s, p.id)) { return { error = 'the slug ' + s + ' is already used by another project' field = 'slug' } }
170. d = description != null ? clean(description) : (p.description != null ? p.description : '')
171. let olds = oldSlugsOf(p)
172. if (s != p.slug) {
173. kept = []
174. for (o of olds) { if (o != s) { kept.push(o) } }
175. kept.push(p.slug)
176. olds = kept
177. }
178. projectsTable.update(p.id, merged(p, { title = t slug = s description = d oldSlugs = olds.join(',') }))
179. return { project = projectRowOf(projectsTable.fetch(p.id)) }
180. }
182. // ---- members and roles ------------------------------------------------------------------------
183. static memberRecord = (projectId, userId) => {
184. if (projectId == null || userId == null || userId == '') { return null }
185. all = membersTable.find('project', projectId)
186. if (countOf(all) == 0) { return null }
187. for (m of all) { if (m.user == userId) { return m } }
188. return null
189. }
190. // the role of a user in a project ('use' | 'edit' | 'admin'), or null
191. static roleOf = (projectId, user) => {
192. if (user == null || user.id == null) { return null }
193. m = memberRecord(projectId, user.id)
194. return m == null ? null : m.role
195. }
196. static atLeast = (projectId, user, role) => { return rankOf(roleOf(projectId, user)) >= rankOf(role) }
197. static isMember = (projectId, user) => { return roleOf(projectId, user) != null }
198. static mayEditIn = (projectId, user) => { return atLeast(projectId, user, 'edit') }
199. static isAdminOf = (projectId, user) => { return atLeast(projectId, user, 'admin') }
201. // the member rows of a project: [{ id, user (users @id), name, role, rank, created }], the oldest first
202. static memberRows = (projectId) => {
203. out = []
204. all = membersTable.find('project', projectId)
205. if (countOf(all) == 0) { return out }
206. for (m of all) { out.push({ id = m.id user = m.user name = nameOfUser(m.user) role = m.role rank = rankOf(m.role) created = m.created }) }
207. return oldestFirst(out, 'created')
208. }
210. // makes `userId` a member with `role` (no permission check: the caller decided); an existing
211. // member keeps the HIGHER of the two roles. Answers the member record.
212. static addMember = (projectId, userId, role) => {
213. m = memberRecord(projectId, userId)
214. if (m != null) {
215. if (rankOf(role) > rankOf(m.role)) { membersTable.update(m.id, merged(m, { role = role })) }
216. return membersTable.fetch(m.id)
217. }
218. id = membersTable.put({ project = projectId user = userId role = role created = now() })
219. return id == null ? null : membersTable.fetch(id)
220. }
222. static adminCount = (projectId) => {
223. let n = 0
224. for (m of memberRows(projectId)) { if (m.role == 'admin') { n = n + 1 } }
225. return n
226. }
228. // an admin sets a member's role, or adds a person by the ident id / display name of a user that
229. // has logged in here. Answers { members } or { error, forbidden? }
230. static setMemberRole = (projectId, actor, userId, role) => {
231. p = projectRecord(projectId)
232. if (p == null) { return { error = 'no such project' } }
233. if (!isAdminOf(p.id, actor)) { return notAdmin }
234. if (!roles.includes(role)) { return { error = 'role must be one of: ' + roles.join(', ') field = 'role' } }
235. if (userRecord(userId) == null) { return { error = 'no such user' field = 'user' } }
236. m = memberRecord(p.id, userId)
237. if (m != null && m.role == 'admin' && role != 'admin' && adminCount(p.id) < 2) { return { error = 'a project needs at least one admin' field = 'role' } }
238. if (m == null) { addMember(p.id, userId, role) } else { membersTable.update(m.id, merged(m, { role = role })) }
239. return { members = memberRows(p.id) }
240. }
242. // an admin removes a member (tickets.hl removeMember then unassigns their tickets). Answers { members } or { error }
243. static removeMembership = (projectId, actor, userId) => {
244. p = projectRecord(projectId)
245. if (p == null) { return { error = 'no such project' } }
246. if (!isAdminOf(p.id, actor)) { return notAdmin }
247. m = memberRecord(p.id, userId)
248. if (m == null) { return { error = 'not a member' field = 'user' } }
249. if (m.role == 'admin' && adminCount(p.id) < 2) { return { error = 'a project needs at least one admin' field = 'user' } }
250. membersTable.delete(m.id)
251. return { members = memberRows(p.id) }
252. }
254. // the user a name (exact display name), an ident id (identity) or a users @id stands for, among
255. // the members of a project when `projectId` is given; { user } | { error }
256. static userByRef = (ref, projectId) => {
257. r = clean(ref)
258. if (r == '') { return { error = 'name a person' } }
259. found = []
260. all = userRecords()
261. if (countOf(all) > 0) {
262. for (u of all) {
263. if (projectId == null || memberRecord(projectId, u.id) != null) {
264. if (u.id == r || u.identity == r || (u.name != '' && u.name == r)) { found.push(u) }
265. }
266. }
267. }
268. if (found.length == 0) { return { error = 'no such person' + (projectId != null ? ' among the members' : '') + ': ' + r } }
269. if (found.length > 1) { return { error = 'more than one person is called ' + r } }
270. return { user = found[0] }
271. }
273. // the members a ticket can be assigned to: [{ value (users @id), label (display name) }]
274. static assignChoices = (projectId) => {
275. out = []
276. for (m of memberRows(projectId)) { out.push({ value = m.user label = m.name }) }
277. return out
278. }
280. // projects a user may create tickets in: [{ slug, title }] (creation order)
281. static editableProjects = (user) => {
282. out = []
283. if (user == null) { return out }
284. for (p of projectRecords()) { if (mayEditIn(p.id, user)) { out.push({ slug = p.slug title = p.title }) } }
285. return out
286. }
287. // the projects a user is a member of, with the role: [{ slug, title, role, href }]
288. static projectsOfUser = (user) => {
289. out = []
290. if (user == null) { return out }
291. for (p of projectRecords()) {
292. let r = roleOf(p.id, user)
293. if (r != null) { out.push({ slug = p.slug title = p.title role = r href = projectHrefOf(p.slug) }) }
294. }
295. return out
296. }