rvlib-shipkit 0.38.1 → 1.0.1

package/src/serve/project-gutter.ts

@@ -0,0 +1,449 @@
+// THE discovery of the house repos on this disk (houseRepos), and what is
+// read of each one: which folders VS Code has open, which Claude Code
+// sessions run in which repo, its open asks, its distance to the last
+// release, its declared live url, its run record and its hub port. The
+// project gutter and the live strip both list repos through houseRepos, so
+// the two surfaces show the same repos by construction. The parsers read
+// text they are handed, so sample output pins them; project-gutter-route.ts
+// and other-repos.ts own the spawns, the reads and the caches.
+import { existsSync, readdirSync, readFileSync, statSync } from 'fs'
+import { basename, dirname, join, resolve, sep } from 'path'
+import { fileURLToPath } from 'url'
+import { gitRoot } from '../core/git-root.ts'
+import { DB_FILE } from '../ledger/db.ts'
+import { defaultHubPort } from './hub-port.ts'
+import { LAYOUT } from '../core/layout.ts'
+
+export type WiredRepo = { name: string; path: string; icon: string | null }
+
+/** the files a repo carries its includes in */
+const CLAUDE_FILES = ['CLAUDE.md', 'CLAUDE.local.md']
+
+/** the absolute md file of every `@<path>.md` include line a repo's CLAUDE
+ *  files carry, in order. A sentence that mentions a path is no include */
+export function includeTargets(repo: string, home: string): string[] {
+    const out: string[] = []
+    for (const f of CLAUDE_FILES) {
+        let text: string
+        try {
+            text = readFileSync(join(repo, f), 'utf8')
+        } catch {
+            continue
+        }
+        for (const line of text.split('\n')) {
+            const raw = /^@(\S+\.md)$/.exec(line.trim())?.[1]
+            if (raw != null) out.push(raw.startsWith('~/') ? join(home, raw.slice(2)) : resolve(repo, raw))
+        }
+    }
+    return out
+}
+
+/** the house wiki index this repo includes: the first include outside the
+ *  repo, else (the repo that hosts the house) the first one that exists and
+ *  is not another CLAUDE file */
+export function houseIndex(repo: string, home: string): string | null {
+    const targets = includeTargets(repo, home).filter((t) => existsSync(t))
+    return targets.find((t) => !inside(t, repo)) ?? targets.find((t) => !basename(t).startsWith('CLAUDE')) ?? null
+}
+
+/** a repo's own icon, first hit wins. The identity kit writes the first one */
+export const ICON_FILES = ['public/favicon.png', 'public/favicon.svg', 'public/favicon.ico', 'favicon.ico', 'public/logo.png']
+
+export const ICON_TYPES: Record<string, string> = { png: 'image/png', svg: 'image/svg+xml', ico: 'image/x-icon' }
+
+/** every direct child of `parent` that includes `index`, sorted by name */
+export function wiredRepos(parent: string, index: string, home: string): WiredRepo[] {
+    let names: string[]
+    try {
+        names = readdirSync(parent)
+    } catch {
+        return []
+    }
+    const out: WiredRepo[] = []
+    for (const name of names.sort()) {
+        if (name.startsWith('.')) continue
+        const path = join(parent, name)
+        if (!includeTargets(path, home).includes(index)) continue
+        out.push({ name, path, icon: ICON_FILES.find((f) => existsSync(join(path, f))) ?? null })
+    }
+    return out
+}
+
+/** the house repos around the repo at `root`: its main checkout (`home`),
+ *  the house index its own includes name, and every sibling that includes the
+ *  same index, `home` among them. No index = no repos */
+export function houseRepos(root: string, userHome: string): { home: string; index: string | null; repos: WiredRepo[] } {
+    const home = homeRepo(root)
+    const index = houseIndex(home, userHome)
+    return { home, index, repos: index == null ? [] : wiredRepos(dirname(home), index, userHome) }
+}
+
+/** the checkout a linked worktree belongs to, so a hub started in a worktree
+ *  still lists its siblings and marks its own repo */
+export function homeRepo(root: string): string {
+    const g = gitRoot(root)
+    if (g == null || basename(g.commonDir) !== '.git') return root
+    return dirname(g.commonDir)
+}
+
+/** the version stamp an icon url carries, so the browser caches it until the
+ *  file changes */
+export const iconStamp = (file: string): number => {
+    try {
+        return Math.floor(statSync(file).mtimeMs)
+    } catch {
+        return 0
+    }
+}
+
+// ── VS Code ───────────────────────────────────────────────────────────────
+
+/** where VS Code keeps its window state, or null on a platform it has none
+ *  we know of */
+export function vscodeStoragePath(platform: string, home: string): string | null {
+    if (platform === 'darwin') return join(home, 'Library/Application Support/Code/User/globalStorage/storage.json')
+    if (platform === 'linux') return join(home, '.config/Code/User/globalStorage/storage.json')
+    return null
+}
+
+type Win = { folder?: unknown }
+
+/** the folders VS Code has open, as absolute paths. A workspace file window
+ *  or a remote folder carries no local folder and is skipped */
+export function openFolders(storageJson: string): string[] {
+    const j = JSON.parse(storageJson) as { windowsState?: { lastActiveWindow?: Win; openedWindows?: Win[] } }
+    const ws = j.windowsState
+    const wins: Win[] = [...(ws?.openedWindows ?? []), ...(ws?.lastActiveWindow != null ? [ws.lastActiveWindow] : [])]
+    const out = new Set<string>()
+    for (const w of wins) {
+        if (typeof w.folder !== 'string' || !w.folder.startsWith('file://')) continue
+        try {
+            out.add(fileURLToPath(w.folder).replace(/\/+$/, ''))
+        } catch {
+            // a malformed uri names no folder
+        }
+    }
+    return [...out]
+}
+
+/** true when `p` is `dir` or sits inside it */
+export const inside = (p: string, dir: string): boolean => p === dir || p.startsWith(dir + sep)
+
+// ── Claude Code sessions ──────────────────────────────────────────────────
+
+/** the Claude Code pids in `ps -axo pid=,comm=`: a command named exactly
+ *  `claude`, bare or as a path. BSD pgrep would be cheaper, but it hides its
+ *  own ancestors, so a hub started from a session could never count it */
+export function parseClaudePids(ps: string): number[] {
+    const out: number[] = []
+    for (const l of ps.split('\n')) {
+        const m = /^\s*(\d+)\s+(.+?)\s*$/.exec(l)
+        if (m != null && basename(m[2]!) === 'claude') out.push(Number(m[1]))
+    }
+    return out
+}
+
+/** `lsof -a -p <pids> -d cwd -Fpn`: a `p<pid>` line, then `f` and `n<path>`
+ *  lines for that process */
+export function parseLsofCwd(out: string): Map<number, string> {
+    const cwd = new Map<number, string>()
+    let pid: number | null = null
+    for (const l of out.split('\n')) {
+        if (l.startsWith('p')) pid = Number(l.slice(1))
+        else if (l.startsWith('n') && pid != null && Number.isFinite(pid)) cwd.set(pid, l.slice(1))
+    }
+    return cwd
+}
+
+/** sessions per repo path: a cwd counts for the repo it sits in */
+export function countSessions(cwds: Iterable<string>, repos: string[]): Map<string, number> {
+    const n = new Map<string, number>(repos.map((r) => [r, 0]))
+    for (const c of cwds) {
+        const r = repos.find((p) => inside(c, p))
+        if (r != null) n.set(r, n.get(r)! + 1)
+    }
+    return n
+}
+
+// ── asks, release, live ───────────────────────────────────────────────────
+// a repo's config is READ as text, never imported: importing runs that
+// repo's code in the hub process, on every poll
+
+/** the body of `<key>: { … }` in a config source, line comments dropped, or
+ *  null when the key declares no object */
+export function configBlock(src: string, key: string): string | null {
+    const clean = src.replace(/(^|\s)\/\/.*$/gm, '$1')
+    const m = new RegExp(`\\b${key}\\s*:\\s*\\{`).exec(clean)
+    if (m == null) return null
+    let depth = 1
+    for (let i = m.index + m[0].length; i < clean.length; i++) {
+        if (clean[i] === '{') depth++
+        else if (clean[i] === '}' && --depth === 0) return clean.slice(m.index + m[0].length, i)
+    }
+    return null
+}
+
+const stringKey = (block: string | null, key: string): string | null =>
+    block == null ? null : (new RegExp(`\\b${key}\\s*:\\s*['"\`]([^'"\`]+)['"\`]`).exec(block)?.[1] ?? null)
+
+/** `asks: { dir }`, the queue's folder, `.shipkit/asks` when the config names
+ *  none. A repo that has not run the new shipkit yet still keeps its queue in
+ *  `asks/` (this read dies once `shipkit fleet` shows no repo on the old layout) */
+export const asksDirOf = (configSrc: string, repo?: string): string =>
+    stringKey(configBlock(configSrc, 'asks'), 'dir') ?? (repo != null && !existsSync(join(repo, LAYOUT.asks)) && existsSync(join(repo, 'asks')) ? 'asks' : LAYOUT.asks)
+
+/** `smoke: { base }`, the one deployed url a repo declares in a machine
+ *  readable place, or null */
+export function liveUrlOf(configSrc: string): string | null {
+    const u = stringKey(configBlock(configSrc, 'smoke'), 'base')
+    return u != null && /^https?:\/\//.test(u) ? u : null
+}
+
+/** an ask file is open until its frontmatter says `status: done` */
+export const isOpenAsk = (md: string): boolean => !/^status:\s*done\b/m.test(md)
+
+/** the open asks in a queue folder: its top level md files, the done/
+ *  archive and every other folder left out. Read only: a missing folder is 0 */
+export const openAskCount = (dir: string): number => openAsks(dir).length
+
+/** an ask's title: its first heading, else its first line of prose, the
+ *  frontmatter skipped */
+export function askTitle(md: string): string | null {
+    const body = md.replace(/^---\n[\s\S]*?\n---\n?/, '')
+    const lines = body.split('\n').map((l) => l.trim()).filter((l) => l !== '')
+    const heading = lines.find((l) => /^#{1,6}\s+\S/.test(l))
+    const title = heading?.replace(/^#{1,6}\s+/, '') ?? lines[0]
+    return title == null || title === '' ? null : title
+}
+
+/** the titles of the open asks in a queue folder, by file name order, the
+ *  file name when an ask has no text */
+export function openAsks(dir: string): string[] {
+    let files: string[]
+    try {
+        files = readdirSync(dir).filter((f) => f.endsWith('.md')).sort()
+    } catch {
+        return []
+    }
+    const out: string[] = []
+    for (const f of files) {
+        try {
+            const md = readFileSync(join(dir, f), 'utf8')
+            if (isOpenAsk(md)) out.push(askTitle(md) ?? f.replace(/\.md$/, ''))
+        } catch {
+            // a folder named like an md file, or a file gone mid read
+        }
+    }
+    return out
+}
+
+// ── the card facts: description, version, branch, last gate ─────────────
+
+/** a one line summary cut at `max` characters, on a word when it can */
+export const clip = (text: string, max = 90): string => {
+    const t = text.replace(/\s+/g, ' ').trim()
+    if (t.length <= max) return t
+    const cut = t.slice(0, max - 1)
+    const at = cut.lastIndexOf(' ')
+    return `${(at > max / 2 ? cut.slice(0, at) : cut).replace(/[\s,;:.]+$/, '')}…`
+}
+
+/** what the repo says it is: package.json `description`, else the first line
+ *  of prose in its README after the title (badges, headings, html,
+ *  blockquotes and a bare url skipped, a markdown link kept as its text) */
+export function descriptionOf(packageJson: string, readme: string): string | null {
+    try {
+        const d = (JSON.parse(packageJson) as { description?: unknown }).description
+        if (typeof d === 'string' && d.trim() !== '') return clip(d)
+    } catch {
+        // no package.json, or not json: the README answers
+    }
+    const body = readme.replace(/^---\n[\s\S]*?\n---\n?/, '').replace(/<!--[\s\S]*?-->/g, '')
+    for (const raw of body.split('\n')) {
+        const l = raw.trim()
+        if (l === '' || /^(#|>|<|!\[|\[!\[|```|---|===|\|)/.test(l) || /^<?https?:\/\/\S+>?$/.test(l)) continue
+        return clip(l.replace(/\[([^\]]*)\]\([^)]*\)/g, '$1').replace(/\*\*|__|`/g, ''))
+    }
+    return null
+}
+
+/** package.json `version`, or null */
+export function versionOf(packageJson: string): string | null {
+    try {
+        const v = (JSON.parse(packageJson) as { version?: unknown }).version
+        return typeof v === 'string' && v.trim() !== '' ? v.trim() : null
+    } catch {
+        return null
+    }
+}
+
+/** the branch `.git/HEAD` names, or `detached <sha>` for a detached head */
+export function branchOf(head: string): string | null {
+    const t = head.trim()
+    const ref = /^ref: refs\/heads\/(.+)$/.exec(t)?.[1]
+    if (ref != null) return ref
+    return /^[0-9a-f]{7,40}$/.test(t) ? `detached ${t.slice(0, 7)}` : null
+}
+
+/** `git status --porcelain`: one line per changed or untracked path */
+export const dirtyCount = (porcelain: string): number => porcelain.split('\n').filter((l) => l.trim() !== '').length
+
+/** the last gate as its record holds it: green, or the checks whose last
+ *  outcome failed. No row at all = unknown */
+export type Gate = 'green' | { reds: string[] } | null
+export function gateOf(rows: { id: string; status: string }[]): Gate {
+    if (rows.length === 0) return null
+    const reds = rows.filter((r) => r.status === 'fail').map((r) => r.id).sort()
+    return reds.length === 0 ? 'green' : { reds }
+}
+
+/** the tag shapes a release leaves: `v1.2.3`, `name@1.2.3` (the shipkit
+ *  defaults) and a bare `1.2.3`. A date or a merge marker is no release */
+export const RELEASE_TAGS = ['v[0-9]*', '*@[0-9]*', '[0-9]*.[0-9]*']
+
+/** `git describe --tags --long`: `<tag>-<commits since>-g<sha>` */
+export function parseDescribe(out: string): { tag: string; ahead: number } | null {
+    const m = /^(.+)-(\d+)-g[0-9a-f]+$/.exec(out.trim())
+    return m == null ? null : { tag: m[1]!, ahead: Number(m[2]) }
+}
+
+/** what moves when a commit or a tag lands, read with a few stats, so the
+ *  release distance is asked of git only when it can have changed. null for
+ *  a checkout whose `.git` is not a folder */
+export function gitStamp(repo: string): string | null {
+    const git = join(repo, '.git')
+    const mt = (p: string): number => {
+        try {
+            return statSync(join(git, p)).mtimeMs
+        } catch {
+            return 0
+        }
+    }
+    try {
+        if (!statSync(git).isDirectory()) return null
+        const head = readFileSync(join(git, 'HEAD'), 'utf8').trim()
+        const ref = /^ref: (.+)$/.exec(head)?.[1]
+        // the index moves on every add, commit, stash and checkout, which is
+        // when the uncommitted count is asked again
+        return [head, ref == null ? 0 : mt(ref), mt('packed-refs'), mt('refs/tags'), mt('index')].join('|')
+    } catch {
+        return null
+    }
+}
+
+// ── last activity ─────────────────────────────────────────────────────────
+
+/** the newest of the stamps that exist, or null when none does */
+export const lastActivity = (...stamps: (number | null | undefined)[]): number | null => {
+    const known = stamps.filter((s): s is number => s != null && Number.isFinite(s) && s > 0)
+    return known.length === 0 ? null : Math.max(...known)
+}
+
+const mtimeOf = (file: string): number | null => {
+    try {
+        return statSync(file).mtimeMs
+    } catch {
+        return null
+    }
+}
+
+/** when the repo's own run record was last written: every gate and health
+ *  run writes it, so its mtime is the last shipkit run */
+export const lastRunAt = (repo: string): number | null => {
+    const record = recordOf(repo)
+    return record == null ? null : lastActivity(mtimeOf(record), mtimeOf(`${record}-wal`))
+}
+
+/** where a repo's run record lives, without asking git: a `.git` directory
+ *  holds it. A `.git` FILE (a linked worktree) is left out: its record sits
+ *  with the main checkout, which is on the list itself */
+export function recordOf(dir: string): string | null {
+    const git = join(dir, '.git')
+    try {
+        if (!statSync(git).isDirectory()) return null
+    } catch {
+        return null
+    }
+    return join(git, 'shipkit', DB_FILE)
+}
+
+/** what the record's files look like from outside: the db and its write
+ *  ahead log, since a commit in WAL mode moves only the log */
+export const recordStamp = (path: string): string => {
+    const one = (p: string): string => {
+        try {
+            const s = statSync(p)
+            return `${s.mtimeMs}:${s.size}`
+        } catch {
+            return '-'
+        }
+    }
+    return `${one(path)}|${one(`${path}-wal`)}`
+}
+
+/** the port a repo's hub listens on: `serve.port` in its repo.config.ts when
+ *  it names one, else the port its name hashes to, as `shipkit serve` picks */
+export function hubPortOf(dir: string): number {
+    let src = ''
+    try {
+        src = readFileSync(join(dir, 'repo.config.ts'), 'utf8')
+    } catch {
+        // no config: the directory name answers
+    }
+    const port = /\bport\s*:\s*(\d{2,5})/.exec(configBlock(src, 'serve') ?? '')?.[1]
+    if (port != null) return Number(port)
+    const name = /\bname\s*:\s*['"]([^'"]+)['"]/.exec(src)?.[1]
+    return defaultHubPort(name ?? basename(dir))
+}
+
+/** the folder name Claude Code keeps a directory's transcripts under */
+export const transcriptSlug = (dir: string): string => dir.replace(/[^a-zA-Z0-9]/g, '-')
+
+/** the newest transcript mtime per repo, from every `<root>/projects/<slug>/`:
+ *  the repo's own slug, or one under a dot folder of it (`<slug>--claude-…`).
+ *  A plain subfolder slug is not claimed, since `repo-sub` also reads as a
+ *  sibling named `repo-sub` */
+export function lastSessionAt(projectRoots: string[], repos: string[]): Map<string, number> {
+    const bySlug = new Map(repos.map((r) => [transcriptSlug(r), r]))
+    const out = new Map<string, number>()
+    for (const root of projectRoots) {
+        let slugs: string[]
+        try {
+            slugs = readdirSync(root)
+        } catch {
+            continue
+        }
+        for (const slug of slugs) {
+            const repo = bySlug.get(slug) ?? [...bySlug.entries()].find(([s]) => slug.startsWith(`${s}--`))?.[1]
+            if (repo == null) continue
+            let files: string[]
+            try {
+                files = readdirSync(join(root, slug)).filter((f) => f.endsWith('.jsonl'))
+            } catch {
+                continue
+            }
+            const newest = lastActivity(out.get(repo), ...files.map((f) => mtimeOf(join(root, slug, f))))
+            if (newest != null) out.set(repo, newest)
+        }
+    }
+    return out
+}
+
+// ── the rail order ────────────────────────────────────────────────────────
+
+/** the order file: one repo name per line, `#` lines and blanks ignored,
+ *  the first mention of a name wins */
+export const parseOrder = (text: string): string[] => [...new Set(text.split('\n').map((l) => l.trim()).filter((l) => l !== '' && !l.startsWith('#')))]
+
+export const ORDER_HEADER = '# the project rail order of every shipkit hub on this machine: one repo name per line, top first'
+
+export const renderOrder = (names: string[]): string => `${ORDER_HEADER}\n${names.join('\n')}\n`
+
+/** the rail: the saved order for the repos that still exist, then every repo
+ *  the file does not name, in discovery order. A vanished name drops out */
+export function mergeOrder(saved: string[], discovered: string[]): string[] {
+    const here = new Set(discovered)
+    const kept = saved.filter((n) => here.has(n))
+    const known = new Set(kept)
+    return [...kept, ...discovered.filter((n) => !known.has(n))]
+}