rvlib-shipkit 2.2.0 → 2.3.0

package/src/review/project.ts

@@ -0,0 +1,110 @@
+// a repo's review unit at work (wiki build/shipkit/review.md, A project's parts): its file found by a walk cached on the
+// walked dirs' times and its text, imported, its spec bound to the store; its sources pulled, its kinds' facts and data
+// view computed on the server, so the hub never bundles project code
+import { existsSync, mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { importFresh, repoUnitFiles } from '../core/discover-checks.ts'
+import { LAYOUT } from '../core/layout.ts'
+import type { ReviewItem } from './model.ts'
+import { bindSpec, readAll, storeDir } from './store.ts'
+import { specOfUnit, type Fact, type Link, type ReviewUnit, type ViewText } from './unit.ts'
+
+/** the walk's answer kept in the cache: the unit files and every dir it read, each with its time; a dir whose time moved
+ *  means a file came or went, so the walk runs again */
+interface Found {
+    dirs: [string, number][]
+    files: [string, number, boolean][]
+}
+
+const foundFile = (root: string): string => join(root, LAYOUT.cache, 'review-unit.json')
+const mtime = (p: string): number => statSync(p, { throwIfNoEntry: false })?.mtimeMs ?? -1
+
+/** the unit files that declare a review unit, by a text test, never an import: the walk's dirs cached on their times */
+export function reviewUnitFiles(root: string): string[] {
+    const cache = foundFile(root)
+    let found: Found | null = null
+    try {
+        found = JSON.parse(readFileSync(cache, 'utf8')) as Found
+    } catch {
+        found = null
+    }
+    const fresh = (f: Found): boolean => f.dirs.every(([d, t]) => mtime(d) === t) && f.files.every(([p, t]) => mtime(p) === t)
+    if (!found || !fresh(found)) {
+        const dirs: string[] = []
+        const files = repoUnitFiles(root, dirs).filter((f) => !f.endsWith('.check.shipkit.ts'))
+        found = { dirs: dirs.map((d) => [d, mtime(d)]), files: files.map((f) => [f, mtime(f), /\breview\s*\(/.test(readFileSync(f, 'utf8'))]) }
+        try {
+            mkdirSync(join(root, LAYOUT.cache), { recursive: true })
+            writeFileSync(`${cache}.${process.pid}.tmp`, JSON.stringify(found))
+            renameSync(`${cache}.${process.pid}.tmp`, cache)
+        } catch {
+            // a read only checkout: the next run walks again
+        }
+    }
+    return found.files.filter(([, , has]) => has).map(([f]) => f)
+}
+
+/** the repo's review unit, or null; two of them is an error naming both files */
+export async function loadReviewUnit(root: string): Promise<ReviewUnit | null> {
+    if (!existsSync(root)) return null
+    const units: { file: string; unit: ReviewUnit }[] = []
+    for (const f of reviewUnitFiles(root)) {
+        const d = (await importFresh(f)) as { kind?: unknown } | undefined
+        if (d?.kind === 'review') units.push({ file: f, unit: d as ReviewUnit })
+    }
+    if (units.length > 1) throw new Error(`two review units: ${units.map((u) => u.file).join(' and ')}; keep one`)
+    return units[0]?.unit ?? null
+}
+
+/** a repo's store with its unit read and its spec bound, so every read and write of `dir` checks what the unit declares */
+export async function openReview(root: string): Promise<{ dir: string; unit: ReviewUnit | null }> {
+    const unit = await loadReviewUnit(root)
+    const dir = storeDir(root)
+    bindSpec(dir, specOfUnit(unit))
+    return { dir, unit }
+}
+
+/** every source pulled once: the ids written; a source that fails says one line through `say`, never stops the others */
+export async function pullSources(dir: string, unit: ReviewUnit | null, say: (line: string) => void): Promise<string[]> {
+    const out: string[] = []
+    for (const s of unit?.sources ?? []) {
+        try {
+            out.push(...(await s.pull({ dir, items: readAll(dir).items, say })))
+        } catch (e) {
+            say(`review: FAIL source ${s.id} not pulled: ${(e as Error).message}`)
+        }
+    }
+    return out
+}
+
+/** the lines `show` and `inbox` print under an item's head: its kind's facts, then the facts of the source that raised it */
+export function factLines(unit: ReviewUnit | null, x: ReviewItem): string[] {
+    const facts: Fact[] = []
+    try {
+        facts.push(...(unit?.kinds?.[x.item.subject.kind]?.facts?.(x) ?? []))
+        if (x.item.origin.by === 'player') for (const s of unit?.sources ?? []) facts.push(...(s.facts?.(x) ?? []))
+    } catch (e) {
+        facts.push({ label: 'FAIL', value: `the unit's facts threw: ${(e as Error).message}` })
+    }
+    return facts.map((f) => `  ${f.label}: ${f.value}`)
+}
+
+/** a kind's data view of one item, what the hub draws: its facts, links, live url and text; a function that throws says so as a fact */
+export function viewOfItem(unit: ReviewUnit | null, x: ReviewItem): { facts: Fact[]; links: Link[]; live: string | null; text: ViewText | null } {
+    const k = unit?.kinds?.[x.item.subject.kind]
+    const tryOr = <T>(what: string, f: (() => T) | undefined, none: T, errors: Fact[]): T => {
+        try {
+            return f ? f() : none
+        } catch (e) {
+            errors.push({ label: 'FAIL', value: `${what} threw: ${(e as Error).message}` })
+            return none
+        }
+    }
+    const errors: Fact[] = []
+    const facts = tryOr('facts', k?.facts && (() => k.facts?.(x) ?? []), [] as Fact[], errors)
+    const source = x.item.origin.by === 'player' ? (unit?.sources ?? []).flatMap((s) => tryOr(`source ${s.id} facts`, s.facts && (() => s.facts?.(x) ?? []), [] as Fact[], errors)) : []
+    const links = tryOr('links', k?.links && (() => k.links?.(x) ?? []), [] as Link[], errors)
+    const live = tryOr<string | null>('live', k?.live && (() => k.live?.(x) ?? null), null, errors)
+    const text = tryOr<ViewText | null>('text', k?.text && (() => k.text?.(x) ?? null), null, errors)
+    return { facts: [...facts, ...source, ...errors], links, live, text }
+}

package/src/review/role.ts

@@ -0,0 +1,48 @@
+// the dispatcher role (wiki build/shipkit/review.md, Raised items): one session routes what the owner, the players and
+// the rules raise. Its file sits beside the store, out of the store's watch
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { AGENT_RE } from './model.ts'
+
+/** the role's holder, and when it last acted */
+export interface Role {
+    name: string
+    since: string
+    beat: string
+}
+
+const roleFile = (dir: string): string => join(dir, '..', 'review-dispatcher.json')
+/** another session may take the role once its holder did nothing for this long */
+export const ROLE_IDLE_MS = 30 * 60 * 1000
+
+export function roleOf(dir: string): Role | null {
+    try {
+        return JSON.parse(readFileSync(roleFile(dir), 'utf8')) as Role
+    } catch {
+        return null
+    }
+}
+
+/** `name` takes the role: refused while another holder acted within ROLE_IDLE_MS, unless `take` */
+export function takeRole(dir: string, name: string, take: boolean, now = new Date()): { ok: true; was: Role | null } | { ok: false; why: string } {
+    if (!AGENT_RE.test(name)) return { ok: false, why: `« ${name} » is no agent name (${AGENT_RE.source})` }
+    const was = roleOf(dir)
+    if (was && was.name !== name && !take && now.getTime() - Date.parse(was.beat) < ROLE_IDLE_MS)
+        return { ok: false, why: `${was.name} holds the dispatcher role (active ${Math.round((now.getTime() - Date.parse(was.beat)) / 60000)} min ago): --take to take it over` }
+    const at = now.toISOString()
+    writeRole(dir, { name, since: was?.name === name ? was.since : at, beat: at })
+    return { ok: true, was }
+}
+
+/** the holder acted: its beat moves to `now` */
+export function beatRole(dir: string, now: Date): void {
+    const r = roleOf(dir)
+    if (r) writeRole(dir, { ...r, beat: now.toISOString() })
+}
+
+function writeRole(dir: string, r: Role): void {
+    const file = roleFile(dir)
+    mkdirSync(join(file, '..'), { recursive: true })
+    writeFileSync(`${file}.tmp`, `${JSON.stringify(r, null, 4)}\n`)
+    renameSync(`${file}.tmp`, file)
+}

package/src/review/routes.ts

@@ -0,0 +1,228 @@
+// the hub's review routes (wiki build/shipkit/review.md, The hub): the store's list, an item's images and clips, the
+// owner's verdicts, replies and read marks appended to its thread. The trailer view's routes: trailer-routes.ts. Paths are
+// relative to the repo hub's base. null: not a path of these
+import { existsSync, mkdirSync, mkdtempSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { extname, join } from 'node:path'
+import { isAnimFormat, isAnimLabels, isAnimMode, pairAnimation } from './anim.ts'
+import { startAuto } from './auto.ts'
+import { bad, KEEP, NO_STORE, ranged, TYPES } from './http.ts'
+import type { Rect, Subject } from './model.ts'
+import { openReview, viewOfItem } from './project.ts'
+import { roleOf } from './role.ts'
+import { addMessage, imageFile, markRead, raiseItem, rateSubject, readAllCached, readItem, specOf, storeDir, storeStamp, threadImage, writeVerdict } from './store.ts'
+import { trailerRoutes } from './trailer-routes.ts'
+import { specData, type ReviewUnit } from './unit.ts'
+import { liveWatchers } from './watchers.ts'
+
+// ── each repo's review unit, read again at most every 5 s; its auto rules scheduled in this server while it serves ──
+
+interface Opened {
+    at: number
+    unit: ReviewUnit | null
+    auto: { stop(): void } | null
+}
+const opened = new Map<string, Opened>()
+
+/** the repo's store, its unit bound; a unit that changed restarts its rules. A unit that does not load throws */
+async function project(root: string): Promise<{ dir: string; unit: ReviewUnit | null }> {
+    const held = opened.get(root)
+    if (held && Date.now() - held.at < 5000) return { dir: storeDir(root), unit: held.unit }
+    const { dir, unit } = await openReview(root)
+    if (held && held.unit === unit) {
+        held.at = Date.now()
+        return { dir, unit }
+    }
+    held?.auto?.stop()
+    const rules = unit?.auto ?? []
+    opened.set(root, { at: Date.now(), unit, auto: rules.length > 0 ? startAuto(dir, rules, () => readAllCached(dir).items) : null })
+    return { dir, unit }
+}
+
+/** an image the page sent as a data url, written to a scratch file the caller removes */
+function dataUrlFile(url: unknown): { file: string; done(): void } | null {
+    if (url === undefined || url === null) return null
+    const m = typeof url === 'string' ? /^data:image\/(png|jpeg|webp);base64,(.+)$/.exec(url) : null
+    if (!m) throw new Error('image: a png, jpeg or webp data url')
+    const tmp = mkdtempSync(join(tmpdir(), 'review-raise-'))
+    const file = join(tmp, `image.${m[1] === 'jpeg' ? 'jpg' : m[1]}`)
+    writeFileSync(file, Buffer.from(m[2] ?? '', 'base64'))
+    return { file, done: () => rmSync(tmp, { recursive: true, force: true }) }
+}
+
+const obj = (v: unknown): v is Record<string, unknown> => typeof v === 'object' && v !== null && !Array.isArray(v)
+
+// ── the list's thumbnails: a 480 px webp of an item's image, cached beside the items (readAll skips dot names) ──
+
+const THUMB_W = 480
+const THUMB_JOBS = 3
+let running = 0
+const waiting: (() => void)[] = []
+const making = new Map<string, Promise<string | null>>()
+
+async function slot<T>(work: () => Promise<T>): Promise<T> {
+    if (running >= THUMB_JOBS) await new Promise<void>((go) => waiting.push(go))
+    running++
+    try {
+        return await work()
+    } finally {
+        running--
+        waiting.shift()?.()
+    }
+}
+
+export function thumbFile(dir: string, id: string, name: string): Promise<string | null> {
+    const src = imageFile(dir, id, name)
+    if (!src || !/\.(png|jpe?g|webp)$/.test(name)) return Promise.resolve(null)
+    const out = join(dir, '.thumbs', id, `${name}.webp`)
+    if (existsSync(out) && statSync(out).mtimeMs >= statSync(src).mtimeMs) return Promise.resolve(out)
+    const pending = making.get(out)
+    if (pending) return pending
+    const job = slot(async () => {
+        mkdirSync(join(dir, '.thumbs', id), { recursive: true })
+        const tmp = `${out}.${process.pid}.tmp`
+        try {
+            const { default: sharp } = await import('sharp')
+            await sharp(src).resize({ width: THUMB_W, withoutEnlargement: true }).webp({ quality: 75 }).toFile(tmp)
+        } catch (e) {
+            console.error(`FAIL: review thumbnail of ${id}/${name}: ${(e as Error).message}`)
+            return null
+        }
+        renameSync(tmp, out)
+        return out
+    }).finally(() => making.delete(out))
+    making.set(out, job)
+    return job
+}
+
+let listing: { dir: string; tag: string; body: string; zipped: Uint8Array<ArrayBuffer> | null } | null = null
+
+async function reviewRoute(req: Request, path: string, dir: string, unit: ReviewUnit | null): Promise<Response | null> {
+    if (path === '/api/review' && req.method === 'GET') {
+        // the page polls this list: it is read from disk and sent again only when a file of it changed
+        const tag = `"${storeStamp(dir)}"`
+        if (req.headers.get('If-None-Match') === tag) return new Response(null, { status: 304, headers: { ETag: tag } })
+        if (listing?.dir !== dir || listing.tag !== tag) listing = { dir, tag, body: JSON.stringify(readAllCached(dir)), zipped: null }
+        const headers = { 'Content-Type': 'application/json', ETag: tag, 'Cache-Control': 'no-cache', Vary: 'Accept-Encoding' }
+        if (!/\bgzip\b/.test(req.headers.get('Accept-Encoding') ?? '')) return new Response(listing.body, { headers })
+        listing.zipped ??= Bun.gzipSync(new TextEncoder().encode(listing.body))
+        return new Response(listing.zipped, { headers: { ...headers, 'Content-Encoding': 'gzip' } })
+    }
+    if (path === '/api/review/watchers' && req.method === 'GET') return Response.json(liveWatchers(dir), { headers: NO_STORE })
+    // the unit's words, the dispatcher's holder: what the page draws the list's filters, labels and board with
+    if (path === '/api/review/spec' && req.method === 'GET')
+        return Response.json({ ...specData(specOf(dir)), role: roleOf(dir), sources: (unit?.sources ?? []).map((s) => s.id), auto: (unit?.auto ?? []).map((r) => ({ id: r.id, every: r.every })) }, { headers: NO_STORE })
+    if ((path === '/api/review/raise' || path === '/api/review/rate') && req.method === 'POST') {
+        let img: ReturnType<typeof dataUrlFile> = null
+        try {
+            const b = (await req.json()) as Record<string, unknown>
+            if (!obj(b.subject) || typeof b.subject.kind !== 'string') throw new Error('subject: { kind, … }')
+            if (typeof b.from !== 'string' || b.from === '') throw new Error('from: the tool he raises it from')
+            if (typeof b.title !== 'string' || b.title.trim() === '') throw new Error('title: a text')
+            const str = (k: string): string | undefined => (typeof b[k] === 'string' && b[k] !== '' ? (b[k] as string) : undefined)
+            const subject = b.subject as Subject
+            if (path === '/api/review/rate') {
+                if (!obj(b.rate)) throw new Error('rate: { stars?, mark?, part? }')
+                const topic = str('topic')
+                const text = str('text')
+                const m = await rateSubject(dir, { subject, from: b.from, title: b.title, rate: b.rate, ...(topic ? { topic } : {}), ...(text ? { text } : {}) })
+                return Response.json(m, { headers: NO_STORE })
+            }
+            img = dataUrlFile(b.image)
+            const lane = str('lane')
+            const kind = b.kind === 'bug' || b.kind === 'demande' ? b.kind : undefined
+            const topic = str('topic')
+            const what = str('what')
+            const commit = str('commit')
+            const x = await raiseItem(dir, {
+                subject,
+                origin: { by: 'owner', from: b.from, ...(kind ? { kind } : {}), ...(lane ? { lane } : {}) },
+                title: b.title,
+                ...(typeof b.text === 'string' ? { text: b.text } : {}),
+                ...(Array.isArray(b.rects) && b.rects.length > 0 ? { rects: b.rects as Rect[] } : {}),
+                ...(topic ? { topic } : {}),
+                ...(what ? { what } : {}),
+                ...(commit ? { commit } : {}),
+                ...(img ? { image: img.file } : {}),
+            })
+            return Response.json(x, { headers: NO_STORE })
+        } catch (e) {
+            return bad(e)
+        } finally {
+            img?.done()
+        }
+    }
+    const t = /^\/api\/review\/([^/]+)\/thread\/([^/]+)$/.exec(path)
+    if (t && req.method === 'GET') {
+        const f = threadImage(dir, t[1] ?? '', t[2] ?? '')
+        return f ? new Response(Bun.file(f), { headers: { 'Content-Type': TYPES[extname(f)] ?? 'application/octet-stream', ...KEEP } }) : bad('no such image', 404)
+    }
+    const th = /^\/api\/review\/([^/]+)\/thumb\/([^/]+)$/.exec(path)
+    if (th && req.method === 'GET') {
+        const f = await thumbFile(dir, th[1] ?? '', th[2] ?? '')
+        return f ? new Response(Bun.file(f), { headers: { 'Content-Type': 'image/webp', ...KEEP } }) : bad('no such image', 404)
+    }
+    const m = /^\/api\/review\/([^/]+)\/([^/]+)$/.exec(path)
+    if (!m) return null
+    const [, id = '', name = ''] = m
+    if (req.method === 'POST') {
+        try {
+            if (name === 'feedback') {
+                const r = writeVerdict(dir, id, await req.json())
+                return r.ok ? Response.json(r.message, { headers: NO_STORE }) : Response.json({ error: r.errors.join('\n'), errors: r.errors }, { status: 400, headers: NO_STORE })
+            }
+            if (name === 'reply') return Response.json(addMessage(dir, id, 'owner', ((await req.json()) as { text?: unknown }).text), { headers: NO_STORE })
+            if (name === 'read') return Response.json({ read: markRead(dir, id, 'owner') }, { headers: NO_STORE })
+            // the card's folder, or one of its files, shown in the Finder: only names the store's own checks accept
+            if (name === 'reveal') {
+                const b = (await req.json().catch(() => ({}))) as { file?: unknown }
+                const target = typeof b.file === 'string' ? imageFile(dir, id, b.file) : readItem(dir, id) ? join(dir, id) : null
+                if (!target) return bad(`no ${typeof b.file === 'string' ? `file ${id}/${b.file}` : `item ${id}`}`, 404)
+                const r = Bun.spawnSync(['open', ...(typeof b.file === 'string' ? ['-R'] : []), target], { stdout: 'ignore', stderr: 'pipe' })
+                return r.exitCode === 0 ? Response.json({ ok: true }, { headers: NO_STORE }) : bad(`open: ${r.stderr.toString().trim() || `exit ${r.exitCode}`}`, 500)
+            }
+        } catch (e) {
+            return bad(e)
+        }
+        return bad(`POST ${path}?`, 404)
+    }
+    if (req.method !== 'GET') return null
+    // a kind's data view of one item, computed here: the page never runs the repo's code
+    if (name === 'view') {
+        try {
+            const x = readItem(dir, id)
+            return x ? Response.json(viewOfItem(unit, x), { headers: NO_STORE }) : bad(`no item ${id}`, 404)
+        } catch (e) {
+            return bad(e)
+        }
+    }
+    if (name === 'anim') {
+        const q = new URL(req.url).searchParams
+        const mode = q.get('mode') ?? 'fade'
+        const format = q.get('format') ?? 'mp4'
+        const labels = q.get('labels') ?? 'en'
+        if (!isAnimMode(mode) || !isAnimFormat(format) || !isAnimLabels(labels)) return bad(`mode ${mode}, format ${format} or labels ${labels}: unknown`)
+        try {
+            const font = unit?.anim?.font ? join(dir, '..', '..', unit.anim.font) : undefined
+            const a = await pairAnimation(dir, id, { view: Number(q.get('view') ?? 0) || 0, mode, format, labels, ...(font ? { font } : {}) })
+            return new Response(Bun.file(a.file), { headers: { 'Content-Type': format === 'gif' ? 'image/gif' : 'video/mp4', 'Content-Disposition': `attachment; filename="${a.name}"`, ...NO_STORE } })
+        } catch (e) {
+            console.error(`FAIL: review animation of ${id}: ${(e as Error).message}`)
+            return bad(e)
+        }
+    }
+    const f = imageFile(dir, id, name)
+    return f ? ranged(req, f) : bad(`no file ${id}/${name}`, 404)
+}
+
+/** the review and trailer routes of the repo at `root`; null for any other path */
+export async function reviewRoutes(root: string, req: Request, path: string): Promise<Response | null> {
+    if (!path.startsWith('/api/review') && !path.startsWith('/api/trailer')) return null
+    let opened: { dir: string; unit: ReviewUnit | null }
+    try {
+        opened = await project(root)
+    } catch (e) {
+        return bad(`the repo's review unit does not load: ${(e as Error).message}`, 500)
+    }
+    return (await reviewRoute(req, path, opened.dir, opened.unit)) ?? (await trailerRoutes(req, path, root, opened.dir))
+}