tickets

14.9 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. // the project part of an /api/projects/<x>/… path (ticket #25): a slug (also an old one) stays as it is, a project's
69. // id gives its CURRENT slug, anything else stays as it is and names nothing. The routes then work on the slug as before.
70. static slugOfRef = (ref) => {
71. if (ref == null || hlTypeName(ref) != 'String' || ref == '' || projectByAnySlug(ref) != null) { return ref }
72. p = projectRecord(ref)
73. return p != null ? p.slug : ref
74. }
76. static projectNames = () => {
77. out = []
78. for (p of projectRecords()) { out.push(p.slug) }
79. return out
80. }
82. // the slug of a ticket's project ('' when the project is gone)
83. static projectSlugOf = (t) => {
84. p = projectRecord(t.project)
85. return p != null ? p.slug : ''
86. }
88. static projectRowOf = (p) => {
89. 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 }
90. }
92. // ---- the slug ------------------------------------------------------------------------------------
93. // a project slug that a URL carries as is: letters, digits, . _ -
94. static isSlugChar = (c) => {
95. return (c >= 48 && c <= 57) || (c >= 65 && c <= 90) || (c >= 97 && c <= 122) || c == 46 || c == 95 || c == 45
96. }
97. static validProjectName = (p) => {
98. if (p == null || hlTypeName(p) != 'String' || p.length == 0 || p.length > 100) { return false }
99. let i = 0
100. while (i < p.length) {
101. if (!isSlugChar(p.charCodeAt(i))) { return false }
102. i = i + 1
103. }
104. return true
105. }
107. // RESERVED SLUGS (ticket #25): a project's page is /<slug>, so a slug may not be the first part of a path the app
108. // or hl:web answers itself (every explicit route of project.hl, hl:web's /__hl/… and the component modules under
109. // /components/…), nor a name we may want for a page later. Compared in lower case. The gate checks that every
110. // first segment of a project.hl route is in this list.
111. 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' '.' '..']
112. static isReservedSlug = (s) => { return s != null && hlTypeName(s) == 'String' && reservedSlugs.includes(s.toLowerCase()) }
113. static reservedError = (s) => { return { error = 'the slug ' + s + ' is reserved: /' + s + ' is a page of tickets itself' field = 'slug' } }
115. // the slug a title proposes: lower case letters and digits, other runs become one '-'
116. static slugFromTitle = (title) => {
117. t = clean(title).toLowerCase()
118. let out = ''
119. let i = 0
120. while (i < t.length && out.length < 60) {
121. let c = t.charCodeAt(i)
122. if ((c >= 48 && c <= 57) || (c >= 97 && c <= 122)) { out = out + t[i] } else if (out != '' && !out.endsWith('-')) { out = out + '-' }
123. i = i + 1
124. }
125. while (out.endsWith('-')) { out = out.slice(0, out.length - 1) }
126. return out == '' ? 'project' : out
127. }
128. // is this slug free? (`except` = the project that may keep it)
129. static slugFree = (slug, except) => {
130. for (q of projectRecords()) {
131. if (except == null || q.id != except) {
132. if (q.slug == slug || oldSlugsOf(q).includes(slug)) { return false }
133. }
134. }
135. return true
136. }
137. // the slug a new project gets: the proposal, or with -2, -3 … when it is taken or reserved
138. static uniqueSlug = (base) => {
139. if (slugFree(base, null) && !isReservedSlug(base)) { return base }
140. let n = 2
141. while (!slugFree(base + '-' + n, null) && n < 10000) { n = n + 1 }
142. return base + '-' + n
143. }
145. // ---- opening and changing a project ---------------------------------------------------------------
146. // answers { error, field } or { project (row), members }. A slug is generated from the title unless one is given.
147. static createProject = (user, title, slug, description) => {
148. if (!userOk(user)) { return authorMissing }
149. t = clean(title)
150. if (t == '') { return { error = 'the title is required' field = 'title' } }
151. if (t.length > 100) { return { error = 'the title is too long (at most 100 characters)' field = 'title' } }
152. let s = clean(slug)
153. if (s == '') { s = uniqueSlug(slugFromTitle(t)) }
154. if (!validProjectName(s)) { return { error = "a slug has no spaces or slashes: letters, digits, '.', '_' and '-' only" field = 'slug' } }
155. if (isReservedSlug(s)) { return reservedError(s) }
156. if (!slugFree(s, null)) { return { error = 'the slug ' + s + ' is already used by a project' field = 'slug' } }
157. id = projectsTable.put({ title = t slug = s description = clean(description) oldSlugs = '' created = now() })
158. if (id == null) { return { error = 'could not store the project: ' + projectsTable.lastError() field = '' } }
159. addMember(id, user.id, 'admin')
160. return { project = projectRowOf(projectsTable.fetch(id)) members = memberRows(id) }
161. }
163. // an admin changes title / slug / description (null = keep). A new slug keeps the old one working.
164. static updateProject = (projectId, actor, title, slug, description) => {
165. p = projectRecord(projectId)
166. if (p == null) { return { error = 'no such project' } }
167. if (!userOk(actor)) { return authorMissing }
168. if (!isAdminOf(p.id, actor)) { return notAdmin }
169. if (title == null && slug == null && description == null) { return { error = 'nothing to change: give title, slug and/or description' field = '' } }
170. t = title != null ? clean(title) : p.title
171. if (t == '') { return { error = 'the title is required' field = 'title' } }
172. if (t.length > 100) { return { error = 'the title is too long (at most 100 characters)' field = 'title' } }
173. s = slug != null ? clean(slug) : p.slug
174. if (s == '') { return { error = 'the slug is required' field = 'slug' } }
175. if (!validProjectName(s)) { return { error = "a slug has no spaces or slashes: letters, digits, '.', '_' and '-' only" field = 'slug' } }
176. if (s != p.slug && isReservedSlug(s)) { return reservedError(s) }
177. if (!slugFree(s, p.id)) { return { error = 'the slug ' + s + ' is already used by another project' field = 'slug' } }
178. d = description != null ? clean(description) : (p.description != null ? p.description : '')
179. let olds = oldSlugsOf(p)
180. if (s != p.slug) {
181. kept = []
182. for (o of olds) { if (o != s) { kept.push(o) } }
183. kept.push(p.slug)
184. olds = kept
185. }
186. projectsTable.update(p.id, merged(p, { title = t slug = s description = d oldSlugs = olds.join(',') }))
187. return { project = projectRowOf(projectsTable.fetch(p.id)) }
188. }
190. // ---- members and roles ------------------------------------------------------------------------
191. static memberRecord = (projectId, userId) => {
192. if (projectId == null || userId == null || userId == '') { return null }
193. all = membersTable.find('project', projectId)
194. if (countOf(all) == 0) { return null }
195. for (m of all) { if (m.user == userId) { return m } }
196. return null
197. }
198. // the role of a user in a project ('use' | 'edit' | 'admin'), or null
199. static roleOf = (projectId, user) => {
200. if (user == null || user.id == null) { return null }
201. m = memberRecord(projectId, user.id)
202. return m == null ? null : m.role
203. }
204. static atLeast = (projectId, user, role) => { return rankOf(roleOf(projectId, user)) >= rankOf(role) }
205. static isMember = (projectId, user) => { return roleOf(projectId, user) != null }
206. static mayEditIn = (projectId, user) => { return atLeast(projectId, user, 'edit') }
207. static isAdminOf = (projectId, user) => { return atLeast(projectId, user, 'admin') }
209. // the member rows of a project: [{ id, user (users @id), name, role, rank, created }], the oldest first
210. static memberRows = (projectId) => {
211. out = []
212. all = membersTable.find('project', projectId)
213. if (countOf(all) == 0) { return out }
214. 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 }) }
215. return oldestFirst(out, 'created')
216. }
218. // makes `userId` a member with `role` (no permission check: the caller decided); an existing
219. // member keeps the HIGHER of the two roles. Answers the member record.
220. static addMember = (projectId, userId, role) => {
221. m = memberRecord(projectId, userId)
222. if (m != null) {
223. if (rankOf(role) > rankOf(m.role)) { membersTable.update(m.id, merged(m, { role = role })) }
224. return membersTable.fetch(m.id)
225. }
226. id = membersTable.put({ project = projectId user = userId role = role created = now() })
227. return id == null ? null : membersTable.fetch(id)
228. }
230. static adminCount = (projectId) => {
231. let n = 0
232. for (m of memberRows(projectId)) { if (m.role == 'admin') { n = n + 1 } }
233. return n
234. }
236. // an admin sets a member's role, or adds a person by the ident id / display name of a user that
237. // has logged in here. Answers { members } or { error, forbidden? }
238. static setMemberRole = (projectId, actor, userId, role) => {
239. p = projectRecord(projectId)
240. if (p == null) { return { error = 'no such project' } }
241. if (!isAdminOf(p.id, actor)) { return notAdmin }
242. if (!roles.includes(role)) { return { error = 'role must be one of: ' + roles.join(', ') field = 'role' } }
243. if (userRecord(userId) == null) { return { error = 'no such user' field = 'user' } }
244. m = memberRecord(p.id, userId)
245. if (m != null && m.role == 'admin' && role != 'admin' && adminCount(p.id) < 2) { return { error = 'a project needs at least one admin' field = 'role' } }
246. if (m == null) { addMember(p.id, userId, role) } else { membersTable.update(m.id, merged(m, { role = role })) }
247. return { members = memberRows(p.id) }
248. }
250. // an admin removes a member (tickets.hl removeMember then unassigns their tickets). Answers { members } or { error }
251. static removeMembership = (projectId, actor, userId) => {
252. p = projectRecord(projectId)
253. if (p == null) { return { error = 'no such project' } }
254. if (!isAdminOf(p.id, actor)) { return notAdmin }
255. m = memberRecord(p.id, userId)
256. if (m == null) { return { error = 'not a member' field = 'user' } }
257. if (m.role == 'admin' && adminCount(p.id) < 2) { return { error = 'a project needs at least one admin' field = 'user' } }
258. membersTable.delete(m.id)
259. return { members = memberRows(p.id) }
260. }
262. // the user a name (exact display name), an ident id (identity) or a users @id stands for, among
263. // the members of a project when `projectId` is given; { user } | { error }
264. static userByRef = (ref, projectId) => {
265. r = clean(ref)
266. if (r == '') { return { error = 'name a person' } }
267. found = []
268. all = userRecords()
269. if (countOf(all) > 0) {
270. for (u of all) {
271. if (projectId == null || memberRecord(projectId, u.id) != null) {
272. if (u.id == r || u.identity == r || (u.name != '' && u.name == r)) { found.push(u) }
273. }
274. }
275. }
276. if (found.length == 0) { return { error = 'no such person' + (projectId != null ? ' among the members' : '') + ': ' + r } }
277. if (found.length > 1) { return { error = 'more than one person is called ' + r } }
278. return { user = found[0] }
279. }
281. // the members a ticket can be assigned to: [{ value (users @id), label (display name) }]
282. static assignChoices = (projectId) => {
283. out = []
284. for (m of memberRows(projectId)) { out.push({ value = m.user label = m.name }) }
285. return out
286. }
288. // projects a user may create tickets in: [{ slug, title }] (creation order)
289. static editableProjects = (user) => {
290. out = []
291. if (user == null) { return out }
292. for (p of projectRecords()) { if (mayEditIn(p.id, user)) { out.push({ slug = p.slug title = p.title }) } }
293. return out
294. }
295. // the projects a user is a member of, with the role: [{ slug, title, role, href }]
296. static projectsOfUser = (user) => {
297. out = []
298. if (user == null) { return out }
299. for (p of projectRecords()) {
300. let r = roleOf(p.id, user)
301. if (r != null) { out.push({ slug = p.slug title = p.title role = r href = projectHrefOf(p.slug) }) }
302. }
303. return out
304. }