rvlib-shipkit 0.1.0

package/src/core/task-runner.ts

@@ -0,0 +1,274 @@
+// Task runner — dep-DAG scheduler with wire-protocol output (wire.ts).
+// Plain mode only by design: one `ok:`/`FAIL:` line per finished task +
+// final summary; greppable by humans and agents alike. Semantics:
+// - a dep must PASS to unblock; a filtered-out dep counts as satisfied;
+//   a failed/skipped dep skips dependents transitively (note says why).
+//   Deps double as serialization guards (document racy edges at the def).
+// - subprocess tasks: full log streamed to <logDir>/<id>.log, last non-empty
+//   line kept for the FAIL summary; SIGTERM at timeoutMs, SIGKILL +2s.
+// - logic tasks run in-process against a CheckCtx: WARN never flips the
+//   exit code, FAIL does. Their lines print under the task line.
+// - bail/SIGINT KILL in-flight children (SIGTERM, SIGKILL +2s); a killed
+//   task reports 'skipped (killed …)', never a fake fail.
+// - sharp edge, by design: `onlyIds` on a task whose race-guard dep is
+//   optIn/skipped-group drops that dep (filtered = satisfied) — explicit
+//   filters win over guards.
+import { createWriteStream, existsSync, mkdirSync, rmSync } from 'fs'
+import { join } from 'path'
+import { CheckCtx } from './check-ctx.ts'
+import { formatLine, type Line } from './wire.ts'
+
+export type TaskDef = {
+    id: string
+    cmd?: string[]
+    logic?: (t: CheckCtx) => unknown
+    deps?: string[]
+    env?: Record<string, string>
+    cwd?: string
+    group?: string
+    /** excluded unless listed in RunOpts.withIds */
+    optIn?: boolean
+    timeoutMs?: number
+}
+
+export type TaskResult = {
+    id: string
+    status: 'pass' | 'fail' | 'skipped'
+    exitCode: number | null
+    durationMs: number
+    logPath: string | null
+    lastLine: string
+    note: string
+    lines: Line[]
+}
+
+export type RunOpts = {
+    tasks: TaskDef[]
+    logDir: string
+    cwd?: string
+    maxParallel?: number
+    bail?: boolean
+    skipGroups?: string[]
+    onlyIds?: string[]
+    withIds?: string[]
+    /** print sink — tests capture, production defaults to console.log */
+    print?: (line: string) => void
+    color?: boolean
+}
+
+export type RunSummary = { ok: boolean; results: TaskResult[]; interrupted: boolean }
+
+type Live = TaskDef & TaskResult & { startedAt: number }
+
+const stripAnsi = (s: string): string => s.replace(/\x1b\[[0-9;]*m/g, '').replace(/\r/g, '')
+
+// only-mode keeps the transitive dep closure — running `--only typecheck`
+// with a lint race-guard dep must still run lint first
+function closure(tasks: TaskDef[], ids: string[]): Set<string> {
+    const byId = new Map(tasks.map((t) => [t.id, t]))
+    const keep = new Set<string>()
+    const visit = (id: string): void => {
+        if (keep.has(id)) return
+        keep.add(id)
+        for (const d of byId.get(id)?.deps ?? []) visit(d)
+    }
+    for (const id of ids) visit(id)
+    return keep
+}
+
+export function selectTasks(o: RunOpts): { selected: TaskDef[]; errors: string[] } {
+    const errors: string[] = []
+    const ids = new Set(o.tasks.map((t) => t.id))
+    if (ids.size !== o.tasks.length) errors.push('duplicate task ids')
+    for (const t of o.tasks) {
+        if ((t.cmd == null) === (t.logic == null)) errors.push(`task ${t.id}: exactly one of cmd/logic required`)
+        for (const d of t.deps ?? []) if (!ids.has(d)) errors.push(`task ${t.id}: unknown dep '${d}'`)
+    }
+    for (const id of [...(o.onlyIds ?? []), ...(o.withIds ?? [])]) if (!ids.has(id)) errors.push(`unknown task id '${id}'`)
+    // cycle check — a dep cycle must die loud at select time, not hang the loop
+    const state = new Map<string, 0 | 1>()
+    const byId = new Map(o.tasks.map((t) => [t.id, t]))
+    const walk = (id: string, trail: string[]): void => {
+        if (state.get(id) === 1) return
+        if (state.get(id) === 0) { errors.push(`dep cycle: ${[...trail, id].join(' → ')}`); return }
+        state.set(id, 0)
+        for (const d of byId.get(id)?.deps ?? []) walk(d, [...trail, id])
+        state.set(id, 1)
+    }
+    for (const t of o.tasks) walk(t.id, [])
+    if (errors.length > 0) return { selected: [], errors }
+
+    const withSet = new Set(o.withIds ?? [])
+    const skipGroups = new Set(o.skipGroups ?? [])
+    let selected = o.tasks.filter((t) => !(t.optIn === true && !withSet.has(t.id)) && !(t.group != null && skipGroups.has(t.group)))
+    if (o.onlyIds != null && o.onlyIds.length > 0) {
+        const keep = closure(o.tasks, o.onlyIds)
+        selected = selected.filter((t) => keep.has(t.id))
+    }
+    return { selected, errors }
+}
+
+export async function runTasks(o: RunOpts): Promise<RunSummary> {
+    const print = o.print ?? ((l: string) => console.log(l))
+    const color = o.color ?? (process.stdout.isTTY && process.env.NO_COLOR == null)
+    const sel = selectTasks(o)
+    if (sel.errors.length > 0) {
+        for (const e of sel.errors) print(formatLine({ kind: 'fail', text: e }, color))
+        return { ok: false, results: [], interrupted: false }
+    }
+    const selectedIds = new Set(sel.selected.map((t) => t.id))
+    rmSync(o.logDir, { recursive: true, force: true })
+    mkdirSync(o.logDir, { recursive: true })
+
+    const tasks: Live[] = sel.selected.map((t) => ({
+        ...t,
+        status: 'skipped', exitCode: null, durationMs: 0, startedAt: 0,
+        logPath: t.cmd != null ? join(o.logDir, `${t.id.replace(/[^a-zA-Z0-9-]/g, '_')}.log`) : null,
+        lastLine: '', note: '', lines: [],
+    }))
+    const byId = new Map(tasks.map((t) => [t.id, t]))
+    const queued = new Set(tasks.map((t) => t.id))
+    const done = new Map<string, Live>()
+    const running = new Map<string, Promise<void>>()
+    const cap = o.maxParallel ?? Math.max(2, Math.floor((navigator.hardwareConcurrency || 4) / 2))
+    let interrupted = false
+    let bailed = false
+    const procs = new Map<string, ReturnType<typeof Bun.spawn>>()
+    const killed = new Map<string, string>() // task id → reason
+    const killAll = (reason: string): void => {
+        for (const [id, proc] of procs) {
+            killed.set(id, reason)
+            try { proc.kill() } catch {}
+            setTimeout(() => { try { proc.kill('SIGKILL') } catch {} }, 2000)
+        }
+    }
+
+    const depState = (t: Live): 'ready' | 'blocked' | 'dead' => {
+        for (const d of t.deps ?? []) {
+            if (!selectedIds.has(d)) continue // filtered dep = satisfied
+            const dep = done.get(d)
+            if (dep == null) return 'blocked'
+            if (dep.status !== 'pass') { t.note = `dep ${d} ${dep.status}`; return 'dead' }
+        }
+        return 'ready'
+    }
+
+    const finish = (t: Live, status: Live['status'], code: number | null): void => {
+        t.status = status
+        t.exitCode = code
+        t.durationMs = t.startedAt > 0 ? Date.now() - t.startedAt : 0
+        done.set(t.id, t)
+        const dur = ` (${(t.durationMs / 1000).toFixed(1)}s)`
+        if (status === 'pass') {
+            // WARNs nag and skips stay visible (exempt contracts) even on pass
+            const surfaced = t.lines.filter((l) => l.kind === 'warn' || l.kind === 'fix-warn' || l.kind === 'skip')
+            print(formatLine({ kind: 'ok', text: `${t.id}${dur}` }, color))
+            for (const l of surfaced) print(formatLine(l, color))
+        } else if (status === 'fail') {
+            print(formatLine({ kind: 'fail', text: `${t.id}${dur}${t.lastLine !== '' ? ` — ${t.lastLine}` : ''}` }, color))
+            for (const l of t.lines.filter((l) => l.kind !== 'ok' && l.kind !== 'note')) print(formatLine(l, color))
+            if (t.logPath != null) print(formatLine({ kind: 'fix-fail', text: `full log: ${t.logPath}` }, color))
+            if (o.bail && !bailed) { bailed = true; killAll('bail') }
+        }
+        // skipped tasks report only in the summary — dep noise stays low
+    }
+
+    const startTask = (t: Live): void => {
+        queued.delete(t.id)
+        t.startedAt = Date.now()
+        const p = (async (): Promise<void> => {
+            if (t.logic != null) {
+                const ctx = new CheckCtx(new Map())
+                try { await t.logic(ctx) } catch (e) { ctx.fail(`${t.id} threw: ${String(e).slice(0, 200)}`) }
+                t.lines = ctx.lines
+                // headline prefers the last FAIL — an exempt/skip line landing
+                // last must not masquerade as the failure
+                const last = ctx.lines.filter((l) => l.kind === 'fail').at(-1) ?? ctx.lines.at(-1)
+                t.lastLine = last != null ? last.text.slice(0, 200) : ''
+                finish(t, ctx.failed ? 'fail' : 'pass', ctx.failed ? 1 : 0)
+                return
+            }
+            const cmd = t.cmd!
+            const head = cmd[0]
+            const bin = head == null ? null : head.includes('/') ? head : Bun.which(head)
+            // path-style heads verified too — Bun.spawn on a missing path
+            // throws, which must surface as a wire FAIL, never a crash
+            if (bin == null || !existsSync(bin)) { t.lastLine = `${head}: not found`; finish(t, 'fail', -1); return }
+            try {
+                const out = createWriteStream(t.logPath!, { flags: 'a' })
+                const proc = Bun.spawn([bin, ...cmd.slice(1)], {
+                    stdout: 'pipe', stderr: 'pipe',
+                    env: { ...process.env, ...t.env },
+                    cwd: t.cwd ?? o.cwd,
+                })
+                procs.set(t.id, proc)
+                let timedOut = false
+                const ms = t.timeoutMs ?? 600_000
+                const timer = setTimeout(() => { timedOut = true; try { proc.kill() } catch {} }, ms)
+                const killer = setTimeout(() => { try { proc.kill('SIGKILL') } catch {} }, ms + 2000)
+                const eat = async (stream: ReadableStream<Uint8Array>): Promise<void> => {
+                    const dec = new TextDecoder()
+                    for await (const chunk of stream) {
+                        const text = dec.decode(chunk)
+                        out.write(text)
+                        for (const raw of text.split(/\r?\n/)) {
+                            const s = stripAnsi(raw).trim()
+                            if (s !== '') t.lastLine = s.slice(0, 200)
+                        }
+                    }
+                }
+                await Promise.all([eat(proc.stdout), eat(proc.stderr)])
+                const code = await proc.exited
+                clearTimeout(timer)
+                clearTimeout(killer)
+                procs.delete(t.id)
+                out.end()
+                const killReason = killed.get(t.id)
+                if (killReason != null) { t.note = `killed (${killReason})`; finish(t, 'skipped', code); return }
+                if (timedOut) t.lastLine = `timeout after ${ms}ms — ${t.lastLine}`
+                finish(t, code === 0 ? 'pass' : 'fail', code)
+            } catch (e) {
+                procs.delete(t.id)
+                t.lastLine = `spawn error: ${String(e).slice(0, 200)}`
+                finish(t, 'fail', -1)
+            }
+        })().finally(() => running.delete(t.id))
+        running.set(t.id, p)
+    }
+
+    const onSigint = (): void => { interrupted = true; killAll('interrupt') }
+    process.on('SIGINT', onSigint)
+    try {
+        while (queued.size > 0 || running.size > 0) {
+            if (interrupted || bailed) {
+                for (const id of [...queued]) { const t = byId.get(id)!; t.note = bailed ? 'bailed' : 'interrupted'; queued.delete(id); done.set(id, t) }
+                await Promise.all(running.values())
+                break
+            }
+            let started = false
+            for (const id of [...queued]) {
+                if (running.size >= cap) break
+                const t = byId.get(id)!
+                const st = depState(t)
+                if (st === 'dead') { queued.delete(id); finish(t, 'skipped', null); started = true }
+                else if (st === 'ready') { startTask(t); started = true }
+            }
+            if (running.size > 0) await Promise.race(running.values())
+            else if (!started && queued.size > 0) {
+                // nothing running, nothing startable — impossible unless a bug: die loud
+                for (const id of [...queued]) print(formatLine({ kind: 'fail', text: `${id}: scheduler stuck (unsatisfiable deps?)` }, color))
+                break
+            }
+        }
+    } finally {
+        process.off('SIGINT', onSigint)
+    }
+
+    const results = tasks.map((t): TaskResult => ({ id: t.id, status: t.status, exitCode: t.exitCode, durationMs: t.durationMs, logPath: t.logPath, lastLine: t.lastLine, note: t.note, lines: t.lines }))
+    const failed = results.filter((r) => r.status === 'fail')
+    const skipped = results.filter((r) => r.status === 'skipped')
+    if (failed.length > 0) print(formatLine({ kind: 'fail', text: `${failed.length}/${results.length} failed: ${failed.map((r) => r.id).join(', ')}` }, color))
+    if (skipped.length > 0) print(formatLine({ kind: 'note', text: `skip: ${skipped.map((r) => `${r.id}${r.note !== '' ? ` (${r.note})` : ''}`).join(', ')}` }, color))
+    if (failed.length === 0 && !interrupted) print(formatLine({ kind: 'ok', text: `all ${results.filter((r) => r.status === 'pass').length} tasks green` }, color))
+    return { ok: failed.length === 0 && !interrupted, results, interrupted }
+}

package/src/core/wire.ts

@@ -0,0 +1,36 @@
+// v0 wire contract — the line protocol every shipkit surface speaks:
+// `ok:` / `WARN` / `FAIL:` / `skip:` prefixes + indented `fix:` pointers,
+// exit 0/1. FROZEN: consumers grep startsWith('FAIL'/'WARN'/'skip:') — a
+// prefix change is a breaking change of the whole toolkit.
+
+export type Line = { kind: 'ok' | 'warn' | 'fail' | 'note' | 'fix-warn' | 'fix-fail' | 'skip'; text: string }
+
+const green = (s: string): string => `\x1b[32m${s}\x1b[0m`
+const red = (s: string): string => `\x1b[31m${s}\x1b[0m`
+const yellow = (s: string): string => `\x1b[33m${s}\x1b[0m`
+
+export function formatLine(l: Line, color: boolean): string {
+    const c = (f: (s: string) => string, s: string) => (color ? f(s) : s)
+    switch (l.kind) {
+        case 'ok': return `${c(green, 'ok:')} ${l.text}`
+        case 'warn': return c(yellow, `WARN ${l.text}`)
+        case 'fail': return c(red, `FAIL: ${l.text}`)
+        case 'fix-warn': return `      ${c(yellow, `fix: ${l.text}`)}`
+        case 'fix-fail': return `      ${c(red, `fix: ${l.text}`)}`
+        case 'skip': return `skip: ${l.text}`
+        case 'note': return l.text
+    }
+}
+
+export function parseDuration(d: string | number): number {
+    if (typeof d === 'number') return d
+    const m = d.match(/^(\d+(?:\.\d+)?)\s*(ms|s|m|h|d)$/)
+    if (m == null) throw new Error(`bad duration '${d}' — use e.g. '90s', '30m', '6h', '1d'`)
+    return Number(m[1]) * { ms: 1, s: 1000, m: 60_000, h: 3600_000, d: 86400_000 }[m[2] as 'ms' | 's' | 'm' | 'h' | 'd']
+}
+
+export const fmtAge = (ms: number): string =>
+    ms < 60_000 ? `${Math.round(ms / 1000)}s`
+    : ms < 3600_000 ? `${Math.round(ms / 60_000)}m`
+    : ms < 86400_000 ? `${Math.round(ms / 3600_000)}h`
+    : `${Math.round(ms / 86400_000)}d`

package/src/repo-config.ts

@@ -0,0 +1,119 @@
+// defineRepo — the ONE import a repo needs: repo.config.ts at the root
+// declares venues/social/tasks/checks, and the toolkit derives everything
+// else. The FLOOR (lint/typecheck/test/imports:check/cycles) auto-registers
+// iff the matching package.json script exists; disabling via
+// `defaults: { x: false }` always prints a skipped-by-config line, never
+// silence. The `contracts` task is always present when any contract applies.
+import { existsSync, readFileSync } from 'fs'
+import { join } from 'path'
+import { allContracts } from './contracts/contract-manifests.ts'
+import { evaluateContracts, type ContractsConfig, type ContractsResult } from './contracts/contracts-engine.ts'
+import type { ContractManifest } from './contracts/contract-types.ts'
+import type { TaskDef } from './core/task-runner.ts'
+import type { CheckCtx } from './core/check-ctx.ts'
+
+export type RepoCheck = { id: string; logic: (t: CheckCtx) => unknown; remainValidFor?: string | number; version?: number }
+
+export type RepoConfig = {
+    name: string
+    /** venue ids this repo ships on — selects which contracts are REQUIRED */
+    venues?: string[]
+    /** social channels with a .rv-social/<channel>/ post folder */
+    social?: string[]
+    /** prefix for contract fix: pointers (docs checkout or URL) — written by init, never baked in */
+    docsBase?: string
+    /** override a floor task's def, or `false` to disable (always visible) */
+    defaults?: Record<string, TaskDef | false>
+    /** repo-specific commit-gate tasks; deps double as race guards */
+    tasks?: TaskDef[]
+    /** periodic health checks, TTL-cached via the check suite */
+    checks?: RepoCheck[]
+    asks?: { dir?: string }
+    contracts?: { exempt?: Record<string, string>; extra?: ContractManifest[] }
+    logDir?: string
+}
+
+export function defineRepo(c: RepoConfig): RepoConfig {
+    if (typeof c.name !== 'string' || c.name === '') throw new Error('defineRepo: name is required')
+    for (const v of c.venues ?? []) if (!/^[a-z0-9-]+$/.test(v)) throw new Error(`defineRepo: venue '${v}' must be kebab-case`)
+    return c
+}
+
+export async function loadRepoConfig(root: string): Promise<RepoConfig> {
+    const path = join(root, 'repo.config.ts')
+    if (!existsSync(path)) throw new Error(`no repo.config.ts in ${root} — run: shipkit init`)
+    const mod = (await import(path)) as { default?: RepoConfig }
+    if (mod.default == null) throw new Error(`${path}: must default-export defineRepo({...})`)
+    return mod.default
+}
+
+export function contractsConfigFrom(c: RepoConfig, root: string): ContractsConfig {
+    const venues = c.venues ?? []
+    const social = c.social ?? []
+    const declared = [
+        ...venues,
+        ...(social.length > 0 ? ['social'] : []),
+        ...(social.includes('discord') ? ['discord'] : []),
+    ]
+    return {
+        root,
+        declared,
+        social,
+        publicSurface: venues.length > 0 || existsSync(join(root, 'deploy.sh')),
+        exempt: c.contracts?.exempt,
+        docsBase: c.docsBase,
+    }
+}
+
+export function activeContracts(c: RepoConfig): ContractManifest[] {
+    return [...allContracts, ...(c.contracts?.extra ?? [])]
+}
+
+// ONE mapping from an engine result into a CheckCtx — used by BOTH the ci
+// task and `shipkit check`; kinds pass through raw so fix pointers and
+// visible exempts survive every printer
+export function applyContractsResult(t: CheckCtx, r: ContractsResult): void {
+    for (const l of r.lines) t.lines.push(l)
+    if (r.exitCode === 1) t.failed = true
+    if (r.lines.some((l) => l.kind === 'warn')) t.warned = true
+    if (r.lines.length === 0) t.ok('no contracts apply (nothing declared, nothing detected)')
+}
+
+// the contracts commit-gate task — venue deploy tasks should dep on it
+export function contractsTask(c: RepoConfig, root: string): TaskDef {
+    return {
+        id: 'contracts',
+        logic: async (t) => {
+            applyContractsResult(t, await evaluateContracts(activeContracts(c), contractsConfigFrom(c, root)))
+        },
+    }
+}
+
+const FLOOR_IDS = ['lint', 'typecheck', 'test', 'imports:check', 'cycles'] as const
+
+export type FloorResolution = { tasks: TaskDef[]; disabled: string[] }
+
+export function resolveFloor(c: RepoConfig, root: string): FloorResolution {
+    const pkgPath = join(root, 'package.json')
+    let scripts: Record<string, string> = {}
+    if (existsSync(pkgPath)) {
+        // unparseable package.json must NOT silently empty the floor — the
+        // gate would run only `contracts` and report green
+        try { scripts = (JSON.parse(readFileSync(pkgPath, 'utf8')) as { scripts?: Record<string, string> }).scripts ?? {} }
+        catch (e) { throw new Error(`package.json unparseable — floor tasks cannot register: ${String(e).slice(0, 120)}`) }
+    }
+    const tasks: TaskDef[] = []
+    const disabled: string[] = []
+    for (const id of FLOOR_IDS) {
+        const override = c.defaults?.[id]
+        if (override === false) { disabled.push(id); continue }
+        if (override != null) { tasks.push(override); continue }
+        if (scripts[id] != null) tasks.push({ id, cmd: ['bun', 'run', id] })
+    }
+    return { tasks, disabled }
+}
+
+export function allTasks(c: RepoConfig, root: string): { tasks: TaskDef[]; disabled: string[] } {
+    const floor = resolveFloor(c, root)
+    return { tasks: [...floor.tasks, contractsTask(c, root), ...(c.tasks ?? [])], disabled: floor.disabled }
+}

package/src/shipkit.ts

@@ -0,0 +1,23 @@
+// rvlib-shipkit — barrel. One import per repo: defineRepo in repo.config.ts;
+// everything else is the machinery behind the shipkit CLI.
+export { defineRepo, loadRepoConfig, resolveFloor, allTasks, contractsTask, contractsConfigFrom, activeContracts } from './repo-config.ts'
+export type { RepoConfig, RepoCheck } from './repo-config.ts'
+export { runTasks, selectTasks } from './core/task-runner.ts'
+export type { TaskDef, TaskResult, RunOpts, RunSummary } from './core/task-runner.ts'
+export { CheckSuite } from './core/check-suite.ts'
+export type { CheckSuiteOpts, GetSecret, SecretSpec } from './core/check-suite.ts'
+export { CheckCtx, RateLimited, ToolUnresolved } from './core/check-ctx.ts'
+export { formatLine, parseDuration, fmtAge } from './core/wire.ts'
+export type { Line } from './core/wire.ts'
+export { evaluateContracts, pngDims } from './contracts/contracts-engine.ts'
+export type { ContractsConfig, ContractsResult, ContractOutcome } from './contracts/contracts-engine.ts'
+export { defineContract, validateManifest, file, png, glob, md, dir, custom, script, fileContains, dirExists } from './contracts/contract-types.ts'
+export type { ContractManifest, ArtifactRule, Detector, ContractEnv } from './contracts/contract-types.ts'
+export { allContracts } from './contracts/contract-manifests.ts'
+export { listAsks, openAsks, checkAsks, createAsk, renderAsksTable } from './asks/asks-queue.ts'
+export type { Ask, CreateOpts } from './asks/asks-queue.ts'
+export { scanMdGraph } from './wiki/scan-md.ts'
+export { lintMd } from './wiki/lint-md.ts'
+export { serveMdGraph } from './wiki/serve-graph.ts'
+export { graphHtml } from './wiki/graph-page.ts'
+export type { MdGraph, MdNode, MdEdge } from './wiki/md-graph.ts'

package/src/wiki/graph-page.ts

@@ -0,0 +1,169 @@
+// Self-contained HTML: a force-directed canvas graph (no deps, no CDN).
+// Small balls (group-colored, eager layer highlighted), directed edges with
+// arrowheads — solid = eager auto-include, dashed = lazy ref. Drag balls,
+// drag background to pan, wheel to zoom, hover to focus a node's links.
+import type { MdGraph } from 'rvlib-shipkit/src/wiki/md-graph.ts'
+
+const PALETTE = ['#e05252', '#e0a552', '#c6d34f', '#5ec95e', '#52c9b0', '#529fe0', '#8f6fe8', '#d46fd4', '#9a8a72']
+
+export function graphHtml(g: MdGraph, opts?: { title?: string }): string {
+    // arbitrary wikis can hold hostile-looking titles/labels — keep the page unbreakable
+    const title = (opts?.title ?? 'wiki graph').replace(/&/g, '&amp;').replace(/</g, '&lt;')
+    const groups = [...new Set(g.nodes.map((n) => n.group ?? ''))].sort()
+    const color = (grp: string | null) => PALETTE[groups.indexOf(grp ?? '') % PALETTE.length]!
+    const data = {
+        nodes: g.nodes.map((n) => ({ ...n, color: n.eager ? '#8b5cf6' : color(n.group) })),
+        edges: g.edges,
+    }
+    const dataJson = JSON.stringify(data).replaceAll('<', '\\u003c')
+    return `<!doctype html>
+<html>
+<head>
+<meta charset="utf-8">
+<title>${title}</title>
+<style>
+  :root { color-scheme: light dark; }
+  html, body { margin: 0; height: 100%; overflow: hidden;
+               font: 12px/1.4 -apple-system, system-ui, sans-serif;
+               background: light-dark(#fafafa, #101014); color: light-dark(#333, #ccc); }
+  header { position: fixed; inset: 0 auto auto 0; z-index: 1; padding: .5em .9em; opacity: .85;
+           display: flex; gap: 1.2em; align-items: baseline; pointer-events: none; }
+  header b { font-size: 13px; }
+  canvas { display: block; cursor: grab; }
+</style>
+</head>
+<body>
+<header><b>${title}</b><span>solid → @ co-load · dashed → lazy ref · purple = eager layer · number = hops from index · drag / pan / zoom · reload = regenerate</span></header>
+<canvas id="c"></canvas>
+<script>
+const DATA = ${dataJson}
+const canvas = document.getElementById('c')
+const ctx = canvas.getContext('2d')
+const dark = matchMedia('(prefers-color-scheme: dark)').matches
+const N = DATA.nodes, byId = new Map(N.map(n => [n.id, n]))
+const E = DATA.edges.filter(e => byId.has(e.from) && byId.has(e.to))
+const deg = new Map()
+for (const e of E) { deg.set(e.from, (deg.get(e.from) ?? 0) + 1); deg.set(e.to, (deg.get(e.to) ?? 0) + 1) }
+for (const n of N) {
+    const a = Math.random() * Math.PI * 2, d = 120 + Math.random() * 240
+    n.x = Math.cos(a) * d; n.y = Math.sin(a) * d; n.vx = 0; n.vy = 0
+    n.r = 4 + Math.min(6, Math.sqrt(deg.get(n.id) ?? 0) * 1.6)
+}
+let scale = 1, ox = 0, oy = 0, alpha = 1, hover = null, drag = null, panning = null
+function resize() {
+    const dpr = devicePixelRatio || 1
+    canvas.width = innerWidth * dpr; canvas.height = innerHeight * dpr
+    canvas.style.width = innerWidth + 'px'; canvas.style.height = innerHeight + 'px'
+    ctx.setTransform(dpr, 0, 0, dpr, 0, 0)
+    ox = ox || innerWidth / 2; oy = oy || innerHeight / 2
+}
+resize(); addEventListener('resize', resize)
+
+function step() {
+    // repulsion between every pair, springs on edges (eager pulls tighter),
+    // light gravity to the origin — classic Fruchterman-style, 60fps for ~100s of nodes
+    for (let i = 0; i < N.length; i++) for (let j = i + 1; j < N.length; j++) {
+        const a = N[i], b = N[j]
+        let dx = a.x - b.x, dy = a.y - b.y
+        let d2 = dx * dx + dy * dy; if (d2 < 1) { dx = Math.random() - .5; dy = Math.random() - .5; d2 = 1 }
+        const f = 1200 / d2
+        const d = Math.sqrt(d2)
+        dx /= d; dy /= d
+        a.vx += dx * f; a.vy += dy * f; b.vx -= dx * f; b.vy -= dy * f
+    }
+    for (const e of E) {
+        const a = byId.get(e.from), b = byId.get(e.to)
+        const dx = b.x - a.x, dy = b.y - a.y
+        const d = Math.sqrt(dx * dx + dy * dy) || 1
+        const rest = e.eager ? 60 : 110
+        const f = (d - rest) * (e.eager ? 0.02 : 0.008)
+        a.vx += dx / d * f; a.vy += dy / d * f; b.vx -= dx / d * f; b.vy -= dy / d * f
+    }
+    for (const n of N) {
+        n.vx -= n.x * 0.0015; n.vy -= n.y * 0.0015
+        if (n === drag) { n.vx = 0; n.vy = 0; continue }
+        n.x += n.vx * alpha; n.y += n.vy * alpha
+        n.vx *= 0.85; n.vy *= 0.85
+    }
+    if (!drag) alpha = Math.max(0.05, alpha * 0.998)
+}
+
+function draw() {
+    ctx.clearRect(0, 0, innerWidth, innerHeight)
+    ctx.save(); ctx.translate(ox, oy); ctx.scale(scale, scale)
+    const focus = hover ? new Set([hover.id, ...E.flatMap(e => e.from === hover.id ? [e.to] : e.to === hover.id ? [e.from] : [])]) : null
+    for (const e of E) {
+        const a = byId.get(e.from), b = byId.get(e.to)
+        const lit = focus == null || e.from === hover.id || e.to === hover.id
+        ctx.globalAlpha = lit ? (e.eager ? 1 : 0.55) : 0.08
+        ctx.strokeStyle = e.eager ? '#8b5cf6' : (dark ? '#8a8a95' : '#777')
+        ctx.lineWidth = (e.eager ? 3.5 : 1) / scale
+        ctx.setLineDash(e.eager ? [] : [4 / scale, 4 / scale])
+        const dx = b.x - a.x, dy = b.y - a.y, d = Math.sqrt(dx * dx + dy * dy) || 1
+        const tx = b.x - dx / d * (b.r + 3), ty = b.y - dy / d * (b.r + 3)
+        ctx.beginPath(); ctx.moveTo(a.x + dx / d * a.r, a.y + dy / d * a.r); ctx.lineTo(tx, ty); ctx.stroke()
+        ctx.setLineDash([])
+        const ah = 5 / scale
+        ctx.fillStyle = ctx.strokeStyle
+        ctx.beginPath()
+        ctx.moveTo(tx, ty)
+        ctx.lineTo(tx - dx / d * ah * 2 - dy / d * ah, ty - dy / d * ah * 2 + dx / d * ah)
+        ctx.lineTo(tx - dx / d * ah * 2 + dy / d * ah, ty - dy / d * ah * 2 - dx / d * ah)
+        ctx.fill()
+    }
+    for (const n of N) {
+        const lit = focus == null || focus.has(n.id)
+        ctx.globalAlpha = lit ? 1 : 0.15
+        ctx.fillStyle = n.color
+        ctx.beginPath(); ctx.arc(n.x, n.y, n.r, 0, 7); ctx.fill()
+        if (n.eager) { ctx.strokeStyle = '#8b5cf6'; ctx.lineWidth = 2 / scale; ctx.beginPath(); ctx.arc(n.x, n.y, n.r + 2.5 / scale, 0, 7); ctx.stroke() }
+        if (n.depth != null && scale * n.r > 3) {
+            ctx.fillStyle = '#fff'
+            ctx.font = '600 ' + n.r * 1.1 + 'px system-ui'
+            ctx.textAlign = 'center'; ctx.textBaseline = 'middle'
+            ctx.fillText(n.depth, n.x, n.y + n.r * 0.08)
+            ctx.textBaseline = 'alphabetic'
+        }
+        const showLabel = n === hover || scale > 0.8 || lit && focus != null
+        if (showLabel) {
+            ctx.globalAlpha = n === hover ? 1 : lit ? 0.8 : 0.1
+            ctx.fillStyle = dark ? '#ddd' : '#333'
+            ctx.font = (n === hover ? 13 : 11) / scale + 'px system-ui'
+            ctx.textAlign = 'center'
+            ctx.fillText(n.group ? n.group + '/' + n.label : n.label, n.x, n.y + n.r + 13 / scale)
+        }
+    }
+    ctx.restore()
+}
+function loop() { step(); draw(); requestAnimationFrame(loop) }
+loop()
+
+const world = (px, py) => [(px - ox) / scale, (py - oy) / scale]
+const nodeAt = (px, py) => {
+    const [x, y] = world(px, py)
+    return N.find(n => (n.x - x) ** 2 + (n.y - y) ** 2 < (n.r + 4 / scale) ** 2) ?? null
+}
+canvas.addEventListener('pointerdown', ev => {
+    const n = nodeAt(ev.clientX, ev.clientY)
+    if (n) { drag = n; alpha = 1 } else panning = { x: ev.clientX - ox, y: ev.clientY - oy }
+    canvas.setPointerCapture(ev.pointerId)
+    canvas.style.cursor = 'grabbing'
+})
+canvas.addEventListener('pointermove', ev => {
+    if (drag) { const [x, y] = world(ev.clientX, ev.clientY); drag.x = x; drag.y = y; alpha = 1 }
+    else if (panning) { ox = ev.clientX - panning.x; oy = ev.clientY - panning.y }
+    else hover = nodeAt(ev.clientX, ev.clientY)
+})
+addEventListener('pointerup', () => { drag = null; panning = null; canvas.style.cursor = 'grab' })
+canvas.addEventListener('wheel', ev => {
+    ev.preventDefault()
+    const z = Math.exp(-ev.deltaY * 0.0015)
+    const [wx, wy] = world(ev.clientX, ev.clientY)
+    scale = Math.min(6, Math.max(0.15, scale * z))
+    ox = ev.clientX - wx * scale; oy = ev.clientY - wy * scale
+}, { passive: false })
+</script>
+</body>
+</html>
+`
+}

package/src/wiki/lint-md.ts

@@ -0,0 +1,24 @@
+// Markdown-wiki lint: every page must be reachable from the entrypoint, and
+// every deliberate ref (@ / → / [](…)) must resolve to a real file. Pure fs,
+// no config — same scan the graph view uses, so lint and view never disagree.
+import { scanMd, type MdDanglingRef, type ScanMdConfig } from 'rvlib-shipkit/src/wiki/scan-md.ts'
+
+export type MdLintReport = {
+    index: string | null // resolved entrypoint (null = neither index.md nor README.md found)
+    files: number
+    orphans: string[] // .md files with no path from the entrypoint
+    dangling: MdDanglingRef[] // refs whose target does not exist in the scan
+    ok: boolean
+}
+
+export function lintMd(cfg: ScanMdConfig): MdLintReport {
+    const scan = scanMd(cfg)
+    const orphans = scan.index == null ? [] : scan.graph.nodes.filter((n) => n.depth == null).map((n) => n.id)
+    return {
+        index: scan.index,
+        files: scan.graph.nodes.length,
+        orphans,
+        dangling: scan.dangling,
+        ok: scan.index != null && orphans.length === 0 && scan.dangling.length === 0,
+    }
+}

package/src/wiki/md-graph.ts

@@ -0,0 +1,6 @@
+// A markdown wiki's link graph, ready to render. Two edge kinds mirror the two
+// loading modes a doc system can have: eager (auto-included with its parent,
+// e.g. `@path` imports) and lazy (loaded on demand, e.g. `→ path` refs).
+export type MdNode = { id: string; label: string; group: string | null; eager: boolean; depth?: number } // depth = hops from the wiki's root, drawn inside the ball
+export type MdEdge = { from: string; to: string; eager: boolean }
+export type MdGraph = { nodes: MdNode[]; edges: MdEdge[] }