tickets

13.4 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. let all = projectsTable.find(null, null)
39. let 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. let 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. let 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. let p = projectByAnySlug(ref)
65. return p != null ? p : projectRecord(ref)
66. }
68. static projectNames = () => {
69. let 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. let 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. // the slug a title proposes: lower case letters and digits, other runs become one '-'
100. static slugFromTitle = (title) => {
101. let t = clean(title).toLowerCase()
102. let out = ''
103. let i = 0
104. while (i < t.length && out.length < 60) {
105. let c = t.charCodeAt(i)
106. if ((c >= 48 && c <= 57) || (c >= 97 && c <= 122)) { out = out + t[i] } else if (out != '' && !out.endsWith('-')) { out = out + '-' }
107. i = i + 1
108. }
109. while (out.endsWith('-')) { out = out.slice(0, out.length - 1) }
110. return out == '' ? 'project' : out
111. }
112. // is this slug free? (`except` = the project that may keep it)
113. static slugFree = (slug, except) => {
114. for (q of projectRecords()) {
115. if (except == null || q.id != except) {
116. if (q.slug == slug || oldSlugsOf(q).includes(slug)) { return false }
117. }
118. }
119. return true
120. }
121. static uniqueSlug = (base) => {
122. if (slugFree(base, null)) { return base }
123. let n = 2
124. while (!slugFree(base + '-' + n, null) && n < 10000) { n = n + 1 }
125. return base + '-' + n
126. }
128. // ---- opening and changing a project ---------------------------------------------------------------
129. // answers { error, field } or { project (row), members }. A slug is generated from the title unless one is given.
130. static createProject = (user, title, slug, description) => {
131. if (!userOk(user)) { return authorMissing }
132. let t = clean(title)
133. if (t == '') { return { error = 'the title is required' field = 'title' } }
134. if (t.length > 100) { return { error = 'the title is too long (at most 100 characters)' field = 'title' } }
135. let s = clean(slug)
136. if (s == '') { s = uniqueSlug(slugFromTitle(t)) }
137. if (!validProjectName(s)) { return { error = "a slug has no spaces or slashes: letters, digits, '.', '_' and '-' only" field = 'slug' } }
138. if (!slugFree(s, null)) { return { error = 'the slug ' + s + ' is already used by a project' field = 'slug' } }
139. let id = projectsTable.put({ title = t slug = s description = clean(description) oldSlugs = '' created = now() })
140. if (id == null) { return { error = 'could not store the project: ' + projectsTable.lastError() field = '' } }
141. addMember(id, user.id, 'admin')
142. return { project = projectRowOf(projectsTable.fetch(id)) members = memberRows(id) }
143. }
145. // an admin changes title / slug / description (null = keep). A new slug keeps the old one working.
146. static updateProject = (projectId, actor, title, slug, description) => {
147. let p = projectRecord(projectId)
148. if (p == null) { return { error = 'no such project' } }
149. if (!userOk(actor)) { return authorMissing }
150. if (!isAdminOf(p.id, actor)) { return notAdmin }
151. if (title == null && slug == null && description == null) { return { error = 'nothing to change: give title, slug and/or description' field = '' } }
152. let t = title != null ? clean(title) : p.title
153. if (t == '') { return { error = 'the title is required' field = 'title' } }
154. if (t.length > 100) { return { error = 'the title is too long (at most 100 characters)' field = 'title' } }
155. let s = slug != null ? clean(slug) : p.slug
156. if (s == '') { return { error = 'the slug is required' field = 'slug' } }
157. if (!validProjectName(s)) { return { error = "a slug has no spaces or slashes: letters, digits, '.', '_' and '-' only" field = 'slug' } }
158. if (!slugFree(s, p.id)) { return { error = 'the slug ' + s + ' is already used by another project' field = 'slug' } }
159. let d = description != null ? clean(description) : (p.description != null ? p.description : '')
160. let olds = oldSlugsOf(p)
161. if (s != p.slug) {
162. let kept = []
163. for (o of olds) { if (o != s) { kept.push(o) } }
164. kept.push(p.slug)
165. olds = kept
166. }
167. projectsTable.update(p.id, merged(p, { title = t slug = s description = d oldSlugs = olds.join(',') }))
168. return { project = projectRowOf(projectsTable.fetch(p.id)) }
169. }
171. // ---- members and roles ------------------------------------------------------------------------
172. static memberRecord = (projectId, userId) => {
173. if (projectId == null || userId == null || userId == '') { return null }
174. let all = membersTable.find('project', projectId)
175. if (countOf(all) == 0) { return null }
176. for (m of all) { if (m.user == userId) { return m } }
177. return null
178. }
179. // the role of a user in a project ('use' | 'edit' | 'admin'), or null
180. static roleOf = (projectId, user) => {
181. if (user == null || user.id == null) { return null }
182. let m = memberRecord(projectId, user.id)
183. return m == null ? null : m.role
184. }
185. static atLeast = (projectId, user, role) => { return rankOf(roleOf(projectId, user)) >= rankOf(role) }
186. static isMember = (projectId, user) => { return roleOf(projectId, user) != null }
187. static mayEditIn = (projectId, user) => { return atLeast(projectId, user, 'edit') }
188. static isAdminOf = (projectId, user) => { return atLeast(projectId, user, 'admin') }
190. // the member rows of a project: [{ id, user (users @id), name, role, rank, created }], the oldest first
191. static memberRows = (projectId) => {
192. let out = []
193. let all = membersTable.find('project', projectId)
194. if (countOf(all) == 0) { return out }
195. 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 }) }
196. return oldestFirst(out, 'created')
197. }
199. // makes `userId` a member with `role` (no permission check: the caller decided); an existing
200. // member keeps the HIGHER of the two roles. Answers the member record.
201. static addMember = (projectId, userId, role) => {
202. let m = memberRecord(projectId, userId)
203. if (m != null) {
204. if (rankOf(role) > rankOf(m.role)) { membersTable.update(m.id, merged(m, { role = role })) }
205. return membersTable.fetch(m.id)
206. }
207. let id = membersTable.put({ project = projectId user = userId role = role created = now() })
208. return id == null ? null : membersTable.fetch(id)
209. }
211. static adminCount = (projectId) => {
212. let n = 0
213. for (m of memberRows(projectId)) { if (m.role == 'admin') { n = n + 1 } }
214. return n
215. }
217. // an admin sets a member's role, or adds a person by the ident id / display name of a user that
218. // has logged in here. Answers { members } or { error, forbidden? }
219. static setMemberRole = (projectId, actor, userId, role) => {
220. let p = projectRecord(projectId)
221. if (p == null) { return { error = 'no such project' } }
222. if (!isAdminOf(p.id, actor)) { return notAdmin }
223. if (!roles.includes(role)) { return { error = 'role must be one of: ' + roles.join(', ') field = 'role' } }
224. if (userRecord(userId) == null) { return { error = 'no such user' field = 'user' } }
225. let m = memberRecord(p.id, userId)
226. if (m != null && m.role == 'admin' && role != 'admin' && adminCount(p.id) < 2) { return { error = 'a project needs at least one admin' field = 'role' } }
227. if (m == null) { addMember(p.id, userId, role) } else { membersTable.update(m.id, merged(m, { role = role })) }
228. return { members = memberRows(p.id) }
229. }
231. // an admin removes a member (tickets.hl removeMember then unassigns their tickets). Answers { members } or { error }
232. static removeMembership = (projectId, actor, userId) => {
233. let p = projectRecord(projectId)
234. if (p == null) { return { error = 'no such project' } }
235. if (!isAdminOf(p.id, actor)) { return notAdmin }
236. let m = memberRecord(p.id, userId)
237. if (m == null) { return { error = 'not a member' field = 'user' } }
238. if (m.role == 'admin' && adminCount(p.id) < 2) { return { error = 'a project needs at least one admin' field = 'user' } }
239. membersTable.delete(m.id)
240. return { members = memberRows(p.id) }
241. }
243. // the user a name (exact display name), an ident id (identity) or a users @id stands for, among
244. // the members of a project when `projectId` is given; { user } | { error }
245. static userByRef = (ref, projectId) => {
246. let r = clean(ref)
247. if (r == '') { return { error = 'name a person' } }
248. let found = []
249. let all = userRecords()
250. if (countOf(all) > 0) {
251. for (u of all) {
252. if (projectId == null || memberRecord(projectId, u.id) != null) {
253. if (u.id == r || u.identity == r || (u.name != '' && u.name == r)) { found.push(u) }
254. }
255. }
256. }
257. if (found.length == 0) { return { error = 'no such person' + (projectId != null ? ' among the members' : '') + ': ' + r } }
258. if (found.length > 1) { return { error = 'more than one person is called ' + r } }
259. return { user = found[0] }
260. }
262. // the members a ticket can be assigned to: [{ value (users @id), label (display name) }]
263. static assignChoices = (projectId) => {
264. let out = []
265. for (m of memberRows(projectId)) { out.push({ value = m.user label = m.name }) }
266. return out
267. }
269. // projects a user may create tickets in: [{ slug, title }] (creation order)
270. static editableProjects = (user) => {
271. let out = []
272. if (user == null) { return out }
273. for (p of projectRecords()) { if (mayEditIn(p.id, user)) { out.push({ slug = p.slug title = p.title }) } }
274. return out
275. }
276. // the projects a user is a member of, with the role: [{ slug, title, role, href }]
277. static projectsOfUser = (user) => {
278. let out = []
279. if (user == null) { return out }
280. for (p of projectRecords()) {
281. let r = roleOf(p.id, user)
282. if (r != null) { out.push({ slug = p.slug title = p.title role = r href = projectHrefOf(p.slug) }) }
283. }
284. return out
285. }