rvlib-shipkit 0.38.0 → 1.0.0

package/src/serve/project-gutter-route.ts

@@ -0,0 +1,350 @@
+// the project gutter, the serving half: /api/projects.json answers every
+// sibling repo that includes this repo's house wiki index, measured at most
+// once per POLL_MS whatever the number of tabs asking. The release distance
+// and the uncommitted count ask git only when a stat says a commit, a tag or
+// the index moved, a few repos per poll, and a repo's run record is opened
+// only when it moved, so a steady poll spawns ps and lsof and nothing else. The icon route
+// serves only the icon files a discovered repo carries, and POST
+// /api/projects/open opens a discovered repo in VS Code: a request names a
+// repo, never a path. The rail ORDER is one text file for the whole machine
+// (ORDER_FILE), so every hub shows the same order and a hand edit is seen
+// within one poll; POST /api/projects/order writes it.
+import { mkdirSync, readdirSync, readFileSync, renameSync, writeFileSync } from 'fs'
+import { readFile, stat } from 'fs/promises'
+import { homedir } from 'os'
+import { dirname, join } from 'path'
+import {
+    asksDirOf, branchOf, countSessions, descriptionOf, dirtyCount, gateOf, gitStamp, houseRepos, iconStamp, ICON_TYPES, lastActivity,
+    lastRunAt, lastSessionAt, liveUrlOf, mergeOrder, openAsks, openFolders, parseClaudePids, parseDescribe, parseLsofCwd, parseOrder,
+    recordOf, recordStamp, RELEASE_TAGS, renderOrder, versionOf, vscodeStoragePath, type Gate, type WiredRepo,
+} from './project-gutter.ts'
+import { readLastStatusReadonly } from '../ledger/run-log.ts'
+
+export type { Gate }
+
+export const POLL_MS = 5_000
+/** how long a release answer holds for a checkout whose `.git` is not a
+ *  folder, since no stat can say when it moved */
+export const RELEASE_TTL_MS = 60_000
+/** git asks per measure, so a cold start spreads its ~20 repos over a few
+ *  polls instead of spending half a second on the first one */
+export const RELEASE_ASKS_PER_POLL = 6
+/** the rail order, under the user's home: one repo name per line */
+export const ORDER_FILE = '.config/shipkit/projects-order.txt'
+
+/** the last release tag, the commits since it and when it was cut (epoch
+ *  ms), `never` when no tag has a release shape, null when git cannot say */
+export type Release = { tag: string; ahead: number; at: number } | 'never' | null
+
+export type ProjectRow = {
+    name: string
+    path: string
+    /** the icon url, or null for the initial on a hashed colour */
+    icon: string | null
+    current: boolean
+    /** null = unknown (no window state on this machine) */
+    vscode: boolean | null
+    /** null = unknown (no ps or lsof) */
+    sessions: number | null
+    /** open asks waiting on a human in the repo's queue */
+    asks: number
+    /** their titles, in file order */
+    askTitles: string[]
+    /** package.json `description`, else the README's first line of prose */
+    description: string | null
+    /** package.json `version` */
+    version: string | null
+    /** the checked out branch, or `detached <sha>` */
+    branch: string | null
+    /** uncommitted paths as of the last git operation, null = unknown */
+    dirty: number | null
+    /** the last gate its own run record holds */
+    gate: Gate
+    release: Release
+    /** the deployed url `smoke.base` declares, or null */
+    live: string | null
+    /** epoch ms of the newest of: the last commit, the last shipkit run, the
+     *  newest Claude Code transcript. null when none of them exists */
+    activity: number | null
+}
+export type ProjectsAnswer = { projects: ProjectRow[]; ms: number; at: number }
+
+/** a command's exit code and stdout, or null when its binary is missing */
+export type Run = (cmd: string[], cwd?: string) => Promise<{ code: number; out: string } | null>
+
+export type GutterDeps = {
+    root: string
+    platform?: string
+    home?: string
+    run?: Run
+    /** opens a folder in VS Code; throws with the reason it could not */
+    open?: (path: string) => void
+    warn?: (line: string) => void
+    now?: () => number
+    /** where the rail order lives, default ~/ORDER_FILE */
+    orderFile?: string
+    /** the Claude Code `projects` folders, default the `projects` folder of every ~/.claude config root */
+    transcriptRoots?: string[]
+}
+
+const runCmd: Run = async (cmd, cwd) => {
+    if (Bun.which(cmd[0]!) == null) return null
+    const p = Bun.spawn(cmd, { cwd, stdout: 'pipe', stderr: 'ignore' })
+    const out = await new Response(p.stdout).text()
+    return { code: await p.exited, out }
+}
+
+function openInCode(path: string): void {
+    const code = Bun.which('code')
+    if (code != null) {
+        Bun.spawn([code, path], { stdio: ['ignore', 'ignore', 'ignore'] }).unref()
+        return
+    }
+    if (process.platform === 'darwin' && Bun.which('open') != null) {
+        Bun.spawn(['open', '-a', 'Visual Studio Code', path], { stdio: ['ignore', 'ignore', 'ignore'] }).unref()
+        return
+    }
+    throw new Error('the `code` command is not on PATH: in VS Code, run "Shell Command: Install \'code\' command in PATH"')
+}
+
+const epochMs = (out: string | undefined): number | null => {
+    const secs = Number(out?.trim())
+    return Number.isFinite(secs) && secs > 0 ? secs * 1000 : null
+}
+
+/** the rows in the rail order: the saved names first, the rest after */
+const inOrder = (rows: ProjectRow[], saved: string[]): ProjectRow[] => {
+    const by = new Map(rows.map((r) => [r.name, r]))
+    return mergeOrder(saved, rows.map((r) => r.name)).map((n) => by.get(n)!)
+}
+
+const readText = (file: string): string => {
+    try {
+        return readFileSync(file, 'utf8')
+    } catch {
+        return ''
+    }
+}
+
+export function projectGutter(d: GutterDeps) {
+    let home = d.root
+    const userHome = d.home ?? homedir()
+    const run = d.run ?? runCmd
+    const warn = d.warn ?? ((l: string) => console.warn(l))
+    const now = d.now ?? Date.now
+    const storage = vscodeStoragePath(d.platform ?? process.platform, userHome)
+    const warned = new Set<string>()
+    const warnOnce = (key: string, line: string): void => {
+        if (warned.has(key)) return
+        warned.add(key)
+        warn(line)
+    }
+
+    let repos: WiredRepo[] = []
+    let last: ProjectsAnswer | null = null
+    let inFlight: Promise<ProjectsAnswer> | null = null
+    let folders: { mtime: number; list: string[] } | null = null
+    const releases = new Map<string, { stamp: string | null; at: number; release: Release; commitAt: number | null; dirty: number | null }>()
+    const gates = new Map<string, { stamp: string; gate: Gate }>()
+    /** a repo's last gate, its record opened only when it moved */
+    const gateOfRepo = (path: string): Gate => {
+        const record = recordOf(path)
+        if (record == null) return null
+        const stamp = recordStamp(record)
+        const hit = gates.get(path)
+        if (hit != null && hit.stamp === stamp) return hit.gate
+        const gate = gateOf(readLastStatusReadonly(record))
+        gates.set(path, { stamp, gate })
+        return gate
+    }
+    const orderFile = d.orderFile ?? join(userHome, ORDER_FILE)
+    const transcriptRoots = (): string[] => {
+        if (d.transcriptRoots != null) return d.transcriptRoots
+        try {
+            return readdirSync(userHome).filter((n) => n.startsWith('.claude')).map((n) => join(userHome, n, 'projects'))
+        } catch {
+            return []
+        }
+    }
+
+    async function vscodeFolders(): Promise<string[] | null> {
+        if (storage == null) {
+            warnOnce('vscode', `WARN project gutter: no VS Code window state known on ${d.platform ?? process.platform}, no open dots`)
+            return null
+        }
+        try {
+            const mtime = (await stat(storage)).mtimeMs
+            if (folders?.mtime !== mtime) folders = { mtime, list: openFolders(await readFile(storage, 'utf8')) }
+            return folders.list
+        } catch (e) {
+            warnOnce('vscode', `WARN project gutter: VS Code window state unreadable at ${storage} (${(e as Error).message}), no open dots`)
+            return null
+        }
+    }
+
+    async function sessionCwds(): Promise<string[] | null> {
+        const ps = await run(['ps', '-axo', 'pid=,comm='])
+        if (ps == null) {
+            warnOnce('sessions', 'WARN project gutter: ps is not on PATH, no Claude session badges')
+            return null
+        }
+        const list = parseClaudePids(ps.out)
+        if (list.length === 0) return []
+        const out = await run(['lsof', '-b', '-w', '-a', '-p', list.join(','), '-d', 'cwd', '-Fpn'])
+        if (out == null) {
+            warnOnce('sessions', 'WARN project gutter: lsof is not on PATH, no Claude session badges')
+            return null
+        }
+        return [...parseLsofCwd(out.out).values()]
+    }
+
+    async function askRelease(path: string): Promise<Release> {
+        const desc = await run(['git', 'describe', '--tags', '--long', ...RELEASE_TAGS.map((g) => `--match=${g}`)], path)
+        if (desc == null) {
+            warnOnce('git', 'WARN project gutter: git is not on PATH, no release distance')
+            return null
+        }
+        const hit = desc.code === 0 ? parseDescribe(desc.out) : null
+        if (hit == null) {
+            // no tag in reach, or no commit at all: tell the two apart
+            const head = await run(['git', 'rev-parse', '--verify', '--quiet', 'HEAD'], path)
+            return head?.code === 0 ? 'never' : null
+        }
+        const log = await run(['git', 'log', '-1', '--format=%ct', hit.tag], path)
+        return { tag: hit.tag, ahead: hit.ahead, at: epochMs(log?.out) ?? 0 }
+    }
+
+    /** the release and the last commit time, asked of git together, since
+     *  the same stat says when either can have moved */
+    async function askGit(path: string): Promise<{ release: Release; commitAt: number | null; dirty: number | null }> {
+        const release = await askRelease(path)
+        if (release == null) return { release, commitAt: null, dirty: null }
+        // --no-optional-locks: a status that rewrote the index would move the
+        // stamp and ask again on every poll
+        const [head, status] = await Promise.all([
+            run(['git', 'log', '-1', '--format=%ct', 'HEAD'], path),
+            run(['git', '--no-optional-locks', 'status', '--porcelain'], path),
+        ])
+        return { release, commitAt: head?.code === 0 ? epochMs(head.out) : null, dirty: status?.code === 0 ? dirtyCount(status.out) : null }
+    }
+
+    /** every repo's release, asking git for at most RELEASE_ASKS_PER_POLL of
+     *  the stale ones per measure, the never asked first then the oldest.
+     *  The rest keep their last answer, or unknown until their turn */
+    async function gitFacts(paths: string[]): Promise<{ release: Release; commitAt: number | null; dirty: number | null }[]> {
+        const stamps = new Map(paths.map((p) => [p, gitStamp(p)]))
+        const stale = paths.filter((p) => {
+            const k = releases.get(p)
+            if (k == null) return true
+            const s = stamps.get(p)!
+            return s != null ? k.stamp !== s : now() - k.at >= RELEASE_TTL_MS
+        })
+        stale.sort((a, b) => (releases.get(a)?.at ?? -1) - (releases.get(b)?.at ?? -1))
+        await Promise.all(stale.slice(0, RELEASE_ASKS_PER_POLL).map(async (p) => {
+            const g = await askGit(p)
+            releases.set(p, { stamp: stamps.get(p)!, at: now(), ...g })
+        }))
+        return paths.map((p) => ({ release: releases.get(p)?.release ?? null, commitAt: releases.get(p)?.commitAt ?? null, dirty: releases.get(p)?.dirty ?? null }))
+    }
+
+    async function measure(): Promise<ProjectsAnswer> {
+        const t0 = performance.now()
+        const house = houseRepos(d.root, userHome)
+        home = house.home
+        if (house.index == null) warnOnce('house', `WARN project gutter: ${home} includes no house wiki index, so no sibling shares one and the gutter is empty`)
+        repos = house.repos
+        const [open, cwds, facts] = await Promise.all([vscodeFolders(), sessionCwds(), gitFacts(repos.map((r) => r.path))])
+        const transcripts = lastSessionAt(transcriptRoots(), repos.map((r) => r.path))
+        const counts = cwds == null ? null : countSessions(cwds, repos.map((r) => r.path))
+        const projects = repos.map((r, i): ProjectRow => {
+            const config = readText(join(r.path, 'repo.config.ts'))
+            const pkg = readText(join(r.path, 'package.json'))
+            const asks = openAsks(join(r.path, asksDirOf(config, r.path)))
+            // the README is read only when package.json says nothing
+            const description = descriptionOf(pkg, '') ?? descriptionOf('', readText(join(r.path, 'README.md')))
+            return {
+                name: r.name,
+                path: r.path,
+                icon: r.icon == null ? null : `/api/projects/icon/${encodeURIComponent(r.name)}?v=${iconStamp(join(r.path, r.icon))}`,
+                current: r.path === home,
+                vscode: open == null ? null : open.some((f) => f === r.path),
+                sessions: counts?.get(r.path) ?? null,
+                asks: asks.length,
+                askTitles: asks,
+                description,
+                version: versionOf(pkg),
+                branch: branchOf(readText(join(r.path, '.git', 'HEAD'))),
+                dirty: facts[i]!.dirty,
+                gate: gateOfRepo(r.path),
+                release: facts[i]!.release,
+                live: liveUrlOf(config),
+                activity: lastActivity(facts[i]!.commitAt, lastRunAt(r.path), transcripts.get(r.path)),
+            }
+        })
+        return { projects: inOrder(projects, parseOrder(readText(orderFile))), ms: Math.round(performance.now() - t0), at: now() }
+    }
+
+    /** the last answer while it is younger than POLL_MS, one measure otherwise,
+     *  shared by every request that arrives while it runs */
+    async function answer(): Promise<ProjectsAnswer> {
+        if (last != null && now() - last.at < POLL_MS) return last
+        inFlight ??= measure().then((a) => {
+            last = a
+            return a
+        }).finally(() => { inFlight = null })
+        return inFlight
+    }
+
+    const find = (name: string): WiredRepo | undefined => repos.find((r) => r.name === name)
+
+    /** saves the rail order: the names given, then every discovered repo they
+     *  leave out. Written whole through a temp file, so a reader never sees
+     *  half of it */
+    function saveOrder(names: string[]): string[] {
+        const order = mergeOrder(names, repos.map((r) => r.name))
+        mkdirSync(dirname(orderFile), { recursive: true })
+        const tmp = `${orderFile}.tmp-${process.pid}`
+        writeFileSync(tmp, renderOrder(order))
+        renameSync(tmp, orderFile)
+        if (last != null) last = { ...last, projects: inOrder(last.projects, order) }
+        return order
+    }
+
+    /** null when the path is not this route's */
+    async function handle(req: Request, path: string): Promise<Response | null> {
+        if (path === '/api/projects.json') return Response.json(await answer())
+        if (path.startsWith('/api/projects/icon/')) {
+            if (repos.length === 0) await answer()
+            const r = find(decodeURIComponent(path.slice('/api/projects/icon/'.length)))
+            if (r?.icon == null) return new Response('no icon', { status: 404 })
+            return new Response(Bun.file(join(r.path, r.icon)), {
+                headers: { 'content-type': ICON_TYPES[r.icon.split('.').pop()!] ?? 'application/octet-stream', 'cache-control': 'max-age=86400' },
+            })
+        }
+        if (path === '/api/projects/order' && req.method === 'POST') {
+            if (repos.length === 0) await answer()
+            const b = (await req.json().catch(() => ({}))) as { names?: unknown }
+            if (!Array.isArray(b.names) || !b.names.every((n) => typeof n === 'string')) return new Response('names must be a list of repo names', { status: 400 })
+            try {
+                return Response.json({ order: saveOrder(b.names as string[]) })
+            } catch (e) {
+                return new Response(`the order could not be saved to ${orderFile}: ${(e as Error).message}`, { status: 500 })
+            }
+        }
+        if (path === '/api/projects/open' && req.method === 'POST') {
+            if (repos.length === 0) await answer()
+            const b = (await req.json().catch(() => ({}))) as { name?: string }
+            const r = find(b.name ?? '')
+            if (r == null) return new Response(`not a wired repo: ${b.name ?? ''}`, { status: 404 })
+            try {
+                ;(d.open ?? openInCode)(r.path)
+            } catch (e) {
+                return new Response((e as Error).message, { status: 400 })
+            }
+            return Response.json({ ok: true })
+        }
+        return null
+    }
+
+    return { handle, answer }
+}