rvlib-shipkit 0.1.0 → 0.2.0

package/src/cli/cmd_Ci.ts

@@ -0,0 +1,41 @@
+// shipkit ci — the commit/deploy gate. Thin clipanion surface; logic in
+// core/run-ci.ts.
+import { Command, Option } from 'clipanion'
+import { runCi } from '../core/run-ci.ts'
+
+export class CiCommand extends Command {
+    static override paths = [['ci']]
+
+    static override usage = Command.Usage({
+        category: 'Gate',
+        description: 'commit gate: floor + contracts + repo tasks through the DAG runner',
+        examples: [
+            ['full gate', 'shipkit ci'],
+            ['stop at the first failure', 'shipkit ci --bail'],
+            ['one task + its dep closure', 'shipkit ci --only typecheck'],
+            ['include an opt-in task', 'shipkit ci --with up:itch'],
+        ],
+    })
+
+    bail = Option.Boolean('--bail', false, { description: 'stop at the first failure' })
+    json = Option.Boolean('--json', false, { description: 'machine-readable result instead of wire lines' })
+    skip = Option.Array('--skip', [], { description: 'skip a task group (repeatable)' })
+    withIds = Option.Array('--with', [], { description: 'include an opt-in task (repeatable)' })
+    only = Option.Array('--only', [], { description: 'run only this task + its dep closure (repeatable)' })
+
+    async execute(): Promise<number> {
+        try {
+            return await runCi(process.cwd(), {
+                bail: this.bail,
+                json: this.json,
+                skipGroups: this.skip,
+                withIds: this.withIds,
+                onlyIds: this.only,
+                print: (l) => this.context.stdout.write(`${l}\n`),
+            })
+        } catch (e) {
+            this.context.stderr.write(`FAIL: ${e instanceof Error ? e.message : String(e)}\n`)
+            return 1
+        }
+    }
+}

package/src/cli/cmd_Contracts.ts

@@ -0,0 +1,35 @@
+// shipkit contracts — venue fulfillness alone. Thin clipanion surface;
+// logic in contracts/run-contracts.ts.
+import { Command, Option } from 'clipanion'
+import { runContracts } from '../contracts/run-contracts.ts'
+
+export class ContractsCommand extends Command {
+    static override paths = [['contracts']]
+
+    static override usage = Command.Usage({
+        category: 'Gate',
+        description: 'release-contract fulfillness, fast and filesystem-only — deploy tasks dep on it',
+        examples: [
+            ['all applicable contracts', 'shipkit contracts'],
+            ['one venue', 'shipkit contracts --venue itch'],
+            ['machine-readable', 'shipkit contracts --json'],
+        ],
+    })
+
+    venue = Option.String('--venue', { required: false, description: 'check one venue only (itch, steam, …)' })
+    json = Option.Boolean('--json', false, { description: 'machine-readable result instead of wire lines' })
+
+    async execute(): Promise<number> {
+        try {
+            return await runContracts(process.cwd(), {
+                venue: this.venue,
+                json: this.json,
+                print: (l) => this.context.stdout.write(`${l}\n`),
+                printErr: (l) => this.context.stderr.write(`${l}\n`),
+            })
+        } catch (e) {
+            this.context.stderr.write(`FAIL: ${e instanceof Error ? e.message : String(e)}\n`)
+            return 1
+        }
+    }
+}

package/src/cli/cmd_Init.ts

@@ -0,0 +1,28 @@
+// shipkit init — scaffold repo.config.ts + package.json scripts. Thin
+// clipanion surface; logic in init-repo.ts.
+import { Command, Option } from 'clipanion'
+import { initRepo } from '../init-repo.ts'
+
+export class InitCommand extends Command {
+    static override paths = [['init']]
+
+    static override usage = Command.Usage({
+        category: 'Setup',
+        description: 'scaffold repo.config.ts + ci/check/contracts package.json scripts, then print how the floor resolved',
+        examples: [
+            ['bootstrap the current repo', 'shipkit init'],
+            ['in-repo-source consumer: scripts run the CLI by path', 'shipkit init --bin wiki/build/shipkit/rvlib-shipkit/src/cli.ts'],
+        ],
+    })
+
+    bin = Option.String('--bin', { description: 'path to shipkit cli.ts — scripts become `bun <path> <cmd>` instead of `shipkit <cmd>`' })
+
+    async execute(): Promise<number> {
+        try {
+            return await initRepo(process.cwd(), { bin: this.bin })
+        } catch (e) {
+            this.context.stderr.write(`FAIL: ${e instanceof Error ? e.message : String(e)}\n`)
+            return 1
+        }
+    }
+}

package/src/cli/cmd_Tui.ts

@@ -0,0 +1,36 @@
+// shipkit tui — the live dashboard: Tasks (the ci gate, streamed through
+// the DAG runner) + Checks (contracts + discovered *.check.ts) built in,
+// repo extras injected via repo.config `tui: { panels: [...] }`.
+import React from 'react'
+import { render } from 'ink'
+import { configure } from 'mobx'
+import { Command } from 'clipanion'
+import { loadRepoConfig } from '../repo-config.ts'
+import { checksPanel } from '../tui/checks-panel.ts'
+import { tasksPanel } from '../tui/tasks-panel.ts'
+import { TuiApp } from '../tui/tui-app.tsx'
+import { TuiStore } from '../tui/tui-store.ts'
+
+export class TuiCommand extends Command {
+    static override paths = [['tui']]
+
+    static override usage = Command.Usage({
+        category: 'Health',
+        description: 'live dashboard: ci tasks + discovered checks, plus panels the repo injects via repo.config tui.panels',
+        examples: [['open the dashboard', 'shipkit tui']],
+    })
+
+    async execute(): Promise<number> {
+        const root = process.cwd()
+        const c = await loadRepoConfig(root)
+        // playbook (build/mobx): enforceActions warns on stray mutations — the
+        // only signal. Read-warning flags stay off: useInput handler reads are
+        // legitimately untracked and would false-positive.
+        configure({ enforceActions: 'always' })
+        const store = new TuiStore(c.name, [tasksPanel(root, c), checksPanel(root), ...(c.tui?.panels ?? [])])
+        store.refresh() // instant static paint; results stream in
+        const app = render(React.createElement(TuiApp, { store }))
+        await app.waitUntilExit()
+        return 0
+    }
+}

package/src/cli/cmd_Wiki.ts

@@ -0,0 +1,53 @@
+// shipkit wiki — md link-graph server + orphan/dangling lint. Two thin
+// commands over wiki/run-wiki.ts.
+import { Command, Option } from 'clipanion'
+import { runWikiLint, runWikiServe } from '../wiki/run-wiki.ts'
+
+export class WikiServeCommand extends Command {
+    static override paths = [['wiki', 'serve']]
+
+    static override usage = Command.Usage({
+        category: 'Wiki',
+        description: 'live md link-graph server — reload = rescan',
+        examples: [
+            ['serve the cwd wiki', 'shipkit wiki serve'],
+            ['serve a subtree on a port', 'shipkit wiki serve --root agent --index process.md --port 6162'],
+        ],
+    })
+
+    root = Option.String('--root', '.', { description: 'wiki root directory' })
+    port = Option.String('--port', '6161', { description: 'server port' })
+    title = Option.String('--title', { required: false, description: 'page title shown in the graph header' })
+    index = Option.String('--index', { required: false, description: 'entrypoint page (default: index.md AND README.md)' })
+    skip = Option.String('--skip', { required: false, description: 'comma-separated dir names to exclude from the scan' })
+
+    async execute(): Promise<number> {
+        const port = Number(this.port)
+        if (!Number.isInteger(port) || port <= 0) {
+            this.context.stderr.write(`FAIL --port '${this.port}' is not a port number\n`)
+            return 1
+        }
+        return runWikiServe({ root: this.root, index: this.index, skip: this.skip, port, title: this.title })
+    }
+}
+
+export class WikiLintCommand extends Command {
+    static override paths = [['wiki', 'lint']]
+
+    static override usage = Command.Usage({
+        category: 'Wiki',
+        description: 'fail on orphan pages and dangling refs (exit 1)',
+        examples: [
+            ['lint the cwd wiki', 'shipkit wiki lint'],
+            ['lint a subtree', 'shipkit wiki lint --root agent --index process.md'],
+        ],
+    })
+
+    root = Option.String('--root', '.', { description: 'wiki root directory' })
+    index = Option.String('--index', { required: false, description: 'entrypoint page (default: index.md AND README.md)' })
+    skip = Option.String('--skip', { required: false, description: 'comma-separated dir names to exclude from the scan' })
+
+    async execute(): Promise<number> {
+        return runWikiLint({ root: this.root, index: this.index, skip: this.skip })
+    }
+}

package/src/cli.ts

@@ -1,28 +1,45 @@
 #!/usr/bin/env bun
-// shipkit — dispatch only; one command per file in cli/.
-const cmd = process.argv[2]
+// shipkit — clipanion entry: one command per file in cli/ (cmd_<Name>.ts),
+// logic in plain modules the commands call. runExit sets the exit code
+// without force-exiting, so serve commands keep the process alive.
+import { readFileSync } from 'fs'
+import { Builtins, Cli } from 'clipanion'
+import { AskNewCommand, AsksCheckCommand, AsksCommand } from './cli/cmd_Asks.ts'
+import { AssetsAddCommand, AssetsCheckCommand, AssetsFillCommand, AssetsGenCommand, AssetsIdentityCommand, AssetsServeCommand } from './cli/cmd_Assets.ts'
+import { CheckCommand } from './cli/cmd_Check.ts'
+import { CiCommand } from './cli/cmd_Ci.ts'
+import { ContractsCommand } from './cli/cmd_Contracts.ts'
+import { InitCommand } from './cli/cmd_Init.ts'
+import { TuiCommand } from './cli/cmd_Tui.ts'
+import { WikiLintCommand, WikiServeCommand } from './cli/cmd_Wiki.ts'
 
-const run = async (): Promise<number> => {
-    const args = process.argv.slice(3)
-    switch (cmd) {
-        case 'ci': return (await import('./cli/shipkit-ci.ts')).main(args)
-        case 'check': return (await import('./cli/shipkit-check.ts')).main(args)
-        case 'contracts': return (await import('./cli/shipkit-contracts.ts')).main(args)
-        case 'asks': return (await import('./cli/shipkit-asks.ts')).main(args)
-        case 'ask': return (await import('./cli/shipkit-asks.ts')).main(['new', ...args])
-        case 'wiki': return (await import('./cli/shipkit-wiki.ts')).main(args)
-        case 'init': return (await import('./cli/shipkit-init.ts')).main(args)
-        default:
-            console.log(`shipkit — repo toolkit
-usage: shipkit <command>
-  ci         commit gate: floor + contracts + repo tasks   [--bail --skip <group> --with <id> --only <id...> --json]
-  check      periodic health: contracts + repo checks, TTL'd  [--json --fresh]
-  contracts  contract fulfillness alone                     [--venue <v> --json]
-  asks       list open asks · asks check · ask "<title>" [--kind --blocks --check "<cmd>"]
-  wiki       serve|lint — md-wiki graph + link hygiene
-  init       scaffold repo.config.ts + package.json scripts`)
-            return 2
-    }
-}
+const version = (JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')) as { version: string }).version
 
-process.exit(await run())
+const cli = new Cli({
+    binaryLabel: 'shipkit — repo toolkit',
+    binaryName: 'shipkit',
+    binaryVersion: version,
+    enableCapture: true, // console output pipes into the command streams (testable)
+    enableColors: true,
+})
+
+cli.register(Builtins.HelpCommand)
+cli.register(Builtins.VersionCommand)
+cli.register(CiCommand)
+cli.register(CheckCommand)
+cli.register(TuiCommand)
+cli.register(ContractsCommand)
+cli.register(AsksCommand)
+cli.register(AsksCheckCommand)
+cli.register(AskNewCommand)
+cli.register(WikiServeCommand)
+cli.register(WikiLintCommand)
+cli.register(AssetsServeCommand)
+cli.register(AssetsFillCommand)
+cli.register(AssetsAddCommand)
+cli.register(AssetsGenCommand)
+cli.register(AssetsIdentityCommand)
+cli.register(AssetsCheckCommand)
+cli.register(InitCommand)
+
+cli.runExit(process.argv.slice(2))

package/src/contracts/run-contracts.ts

@@ -0,0 +1,33 @@
+// contract fulfillness alone, fast and filesystem-only. Plain module
+// behind cmd_Contracts; venue deploy scripts run it before any upload.
+import { activeContracts, contractsConfigFrom, loadRepoConfig } from '../repo-config.ts'
+import { evaluateContracts } from './contracts-engine.ts'
+import { formatLine } from '../core/wire.ts'
+
+export type ContractsOpts = {
+    venue?: string
+    json?: boolean
+    /** line sinks — commands pass their context streams; default to console */
+    print?: (line: string) => void
+    printErr?: (line: string) => void
+}
+
+export async function runContracts(root: string, o: ContractsOpts = {}): Promise<number> {
+    const print = o.print ?? ((l: string) => console.log(l))
+    const printErr = o.printErr ?? ((l: string) => console.error(l))
+    const c = await loadRepoConfig(root)
+    let manifests = activeContracts(c)
+    if (o.venue != null) {
+        manifests = manifests.filter((m) => m.venue === o.venue)
+        if (manifests.length === 0) { printErr(`FAIL: unknown venue '${o.venue}'`); return 1 }
+    }
+    const r = await evaluateContracts(manifests, contractsConfigFrom(c, root))
+    if (o.json === true) {
+        print(JSON.stringify({ ok: r.exitCode === 0, outcomes: r.outcomes }))
+        return r.exitCode
+    }
+    const color = process.stdout.isTTY && process.env.NO_COLOR == null
+    for (const l of r.lines) print(formatLine(l, color))
+    if (r.lines.length === 0) print('ok: no contracts apply (nothing declared, nothing detected)')
+    return r.exitCode
+}

package/src/core/check-ctx.ts

@@ -1,6 +1,6 @@
 // CheckCtx — the per-check handle a probe's logic receives: outcome lines
 // (wire.ts kinds), guarded fetch/exec helpers, resolved-tool lookup.
-import { existsSync } from 'fs'
+import { spawnWithTimeout } from './spawn-timeout.ts'
 import type { Line } from './wire.ts'
 
 // thrown by t.fetch on 429 — the suite converts it to WARN, never FAIL
@@ -43,21 +43,8 @@ export class CheckCtx {
     }
 
     // spawn without the Bun.spawn throw-on-missing-binary gotcha; SIGTERM at
-    // timeoutMs, SIGKILL 2s later (a child ignoring SIGTERM must not hang us)
+    // timeoutMs, SIGKILL 2s later (one code path: core/spawn-timeout.ts)
     async exec(cmd: string[], opts?: { env?: Record<string, string | undefined>; cwd?: string; timeoutMs?: number }): Promise<{ code: number; out: string; timedOut: boolean }> {
-        const head = cmd[0]
-        if (head == null) return { code: -1, out: 'empty command', timedOut: false }
-        const bin = head.includes('/') ? head : Bun.which(head)
-        if (bin == null || !existsSync(bin)) return { code: -1, out: `${head}: not found`, timedOut: false }
-        const p = Bun.spawn([bin, ...cmd.slice(1)], { stdout: 'pipe', stderr: 'pipe', env: opts?.env as Record<string, string>, cwd: opts?.cwd })
-        let timedOut = false
-        const ms = opts?.timeoutMs ?? 15_000
-        const timer = setTimeout(() => { timedOut = true; p.kill() }, ms)
-        const killer = setTimeout(() => p.kill('SIGKILL'), ms + 2000)
-        const out = (await new Response(p.stdout).text()) + (await new Response(p.stderr).text())
-        const code = await p.exited
-        clearTimeout(timer)
-        clearTimeout(killer)
-        return { code, out, timedOut }
+        return spawnWithTimeout(cmd, { timeoutMs: opts?.timeoutMs ?? 15_000, env: opts?.env, cwd: opts?.cwd })
     }
 }

package/src/core/check-suite.ts

@@ -27,6 +27,8 @@ export type SecretSpec = {
     skipHint: string
 }
 
+export type CheckOutcome = { lines: Line[]; status: 'pass' | 'fail' | 'warn' | 'skip'; cached: boolean }
+
 export type CheckSuiteOpts = {
     name: string
     cacheDir: string
@@ -35,6 +37,9 @@ export type CheckSuiteOpts = {
     getSecret?: GetSecret
     /** env var that busts the cache when set (consumer names it) */
     freshEnv?: string
+    /** per-check completion tap (the TUI streams results in) — cached replays
+     *  report cached:true, prep-skips (unstored secret) report status 'skip' */
+    onResult?: (name: string, r: CheckOutcome) => void
 }
 
 export class CheckSuite {
@@ -45,6 +50,7 @@ export class CheckSuite {
     private now: () => number
     private getSecret: GetSecret
     private freshEnv: string
+    private onResult?: (name: string, r: CheckOutcome) => void
 
     constructor(opts: CheckSuiteOpts) {
         this.name = opts.name
@@ -52,6 +58,7 @@ export class CheckSuite {
         this.now = opts.now ?? Date.now
         this.getSecret = opts.getSecret ?? (() => null)
         this.freshEnv = opts.freshEnv ?? 'SHIPKIT_FRESH'
+        this.onResult = opts.onResult
     }
 
     addCheck(spec: { name: string; remainValidFor?: string | number; version?: number; logic: Logic }): void {
@@ -124,7 +131,11 @@ export class CheckSuite {
 
         for (const r of this.runners) {
             const prep = r.prep?.() ?? {}
-            if (prep.skip != null) { skipped.push(prep.skip); continue }
+            if (prep.skip != null) {
+                skipped.push(prep.skip)
+                this.onResult?.(r.name, { lines: [{ kind: 'skip', text: prep.skip }], status: 'skip', cached: false })
+                continue
+            }
             ran++
             const key = prep.cacheExtra ?? ''
             const entry = cache[r.name]
@@ -133,7 +144,9 @@ export class CheckSuite {
                 && this.now() - entry.at < r.ttlMs && this.now() >= entry.at
             if (fresh) {
                 const age = fmtAge(this.now() - entry.at)
-                out.push(...entry.lines.map((l, i): Line => (i === 0 ? { ...l, text: `${l.text} (cached ${age} ago)` } : l)))
+                const lines = entry.lines.map((l, i): Line => (i === 0 ? { ...l, text: `${l.text} (cached ${age} ago)` } : l))
+                out.push(...lines)
+                this.onResult?.(r.name, { lines, status: 'pass', cached: true }) // only clean passes are cached
                 continue
             }
             const t = new CheckCtx(this.toolPaths)
@@ -145,6 +158,7 @@ export class CheckSuite {
                 else t.fail(`${r.name} errored (${String(e).slice(0, 200)}) — network down, or a bug in this check`)
             }
             out.push(...t.lines)
+            this.onResult?.(r.name, { lines: t.lines, status: t.failed ? 'fail' : t.warned ? 'warn' : 'pass', cached: false })
             if (t.failed) anyFail = true
             if (r.ttlMs > 0) {
                 if (!t.failed && !t.warned) { cache[r.name] = { version: r.version, key, at: this.now(), lines: t.lines }; cacheDirty = true }

package/src/core/discover-checks.ts

@@ -0,0 +1,48 @@
+// *.check.ts auto-discovery — THE way health checks register (repo.config
+// `checks:[]` is dead, one-runner GO 2026-07-22): drop a `<name>.check.ts`
+// anywhere in the repo and `shipkit check` runs it as a subprocess — wire
+// output parsed back, exit code is truth. Skipped dirs: node_modules, dist,
+// tmp, references (templates for other repos), and every dot-dir (.git,
+// caches, .rv-* contract folders).
+
+import { readdirSync, readFileSync } from 'fs'
+import { basename, join, relative } from 'path'
+
+const IGNORED_DIRS = new Set(['node_modules', 'dist', 'tmp', 'references'])
+const SUFFIX = '.check.ts'
+
+export type DiscoveredCheck = {
+    /** absolute path to the check file */
+    path: string
+    /** display + cache name — file base, disambiguated by relative path on collision */
+    name: string
+    /** file runs its own CheckSuite (own TTL cache) — the orchestrator must not double-cache it */
+    selfCached: boolean
+}
+
+export function discoverChecks(root: string): DiscoveredCheck[] {
+    const files: string[] = []
+    const walk = (dir: string): void => {
+        let entries
+        try { entries = readdirSync(dir, { withFileTypes: true }) } catch { return }
+        for (const e of entries) {
+            if (e.isDirectory()) {
+                if (!IGNORED_DIRS.has(e.name) && !e.name.startsWith('.')) walk(join(dir, e.name))
+            } else if (e.name.endsWith(SUFFIX)) files.push(join(dir, e.name))
+        }
+    }
+    walk(root)
+    files.sort()
+    const baseOf = (f: string): string => basename(f).slice(0, -SUFFIX.length)
+    const seen = new Map<string, number>()
+    for (const f of files) seen.set(baseOf(f), (seen.get(baseOf(f)) ?? 0) + 1)
+    return files.map((f) => {
+        const base = baseOf(f)
+        const name = (seen.get(base) ?? 0) > 1 ? relative(root, f).slice(0, -SUFFIX.length) : base
+        // a check built on CheckSuite/SkillValidator replays from its OWN
+        // TTL cache — caching it again up here would double the staleness
+        let selfCached = false
+        try { selfCached = /SkillValidator|CheckSuite/.test(readFileSync(f, 'utf8')) } catch {}
+        return { path: f, name, selfCached }
+    })
+}

package/src/core/run-check.ts

@@ -0,0 +1,73 @@
+// periodic health — contracts + every *.check.ts in the repo. Discovery IS
+// the registration (core/discover-checks.ts); each check runs as a
+// subprocess: wire lines parsed back, exit code is truth. A check that runs
+// its own CheckSuite keeps its own TTL cache and is never double-cached
+// here; plain checks get a short orchestrator TTL. `--fresh` busts both
+// layers (SHIPKIT_FRESH=1 + RV_CHECK_FRESH=1 travel to children).
+import { join, relative } from 'path'
+import { CheckSuite, type CheckOutcome } from './check-suite.ts'
+import { discoverChecks } from './discover-checks.ts'
+import { spawnWithTimeout } from './spawn-timeout.ts'
+import { activeContracts, applyContractsResult, contractsConfigFrom, loadRepoConfig } from '../repo-config.ts'
+import { evaluateContracts } from '../contracts/contracts-engine.ts'
+import { formatLine, parseWireOutput } from './wire.ts'
+import { writeStatus } from './write-status.ts'
+
+// orchestrator cache for checks WITHOUT their own suite — short on purpose:
+// this layer only absorbs back-to-back runs, real TTLs live in the checks
+const DISCOVERED_TTL = '30m'
+const CHECK_TIMEOUT_MS = 120_000
+
+export type CheckOpts = {
+    json?: boolean
+    fresh?: boolean
+    /** refresh STATUS.md after the run (default true — O4: every repo gets it) */
+    status?: boolean
+    /** line sink — commands pass their context stream; defaults to console */
+    print?: (line: string) => void
+    /** per-check completion tap — the TUI checks panel streams results in */
+    onResult?: (name: string, r: CheckOutcome) => void
+}
+
+export async function runCheck(root: string, o: CheckOpts = {}): Promise<number> {
+    const print = o.print ?? ((l: string) => console.log(l))
+    const c = await loadRepoConfig(root)
+    if (o.fresh === true) process.env.SHIPKIT_FRESH = '1'
+    const suite = new CheckSuite({ name: c.name, cacheDir: join(root, 'tmp/.shipkit-cache'), onResult: o.onResult })
+    suite.addCheck({
+        name: 'contracts',
+        logic: async (t) => {
+            applyContractsResult(t, await evaluateContracts(activeContracts(c), contractsConfigFrom(c, root)))
+        },
+    })
+    const childEnv: Record<string, string | undefined> = {
+        ...process.env,
+        ...(o.fresh === true ? { SHIPKIT_FRESH: '1', RV_CHECK_FRESH: '1' } : {}),
+    }
+    for (const d of discoverChecks(root)) {
+        const rel = relative(root, d.path)
+        suite.addCheck({
+            name: d.name,
+            remainValidFor: d.selfCached ? undefined : DISCOVERED_TTL,
+            logic: async (t) => {
+                const r = await spawnWithTimeout(['bun', d.path], { cwd: root, timeoutMs: CHECK_TIMEOUT_MS, env: childEnv })
+                for (const l of parseWireOutput(r.out)) t.lines.push(l)
+                if (t.lines.some((l) => l.kind === 'warn')) t.warned = true
+                if (t.lines.some((l) => l.kind === 'fail')) t.failed = true
+                // exit code is truth — a non-zero exit with no FAIL line
+                // (crash, non-wire output, timeout) must still fail loud
+                if (r.code !== 0 && !t.failed)
+                    t.fail(`${d.name} exited ${r.code}${r.timedOut ? ` (timeout after ${CHECK_TIMEOUT_MS}ms)` : ''} — ${r.out.trim().split('\n').at(-1)?.slice(0, 160) ?? ''}`, `bun ${rel}`)
+            },
+        })
+    }
+    const r = await suite.execute()
+    const statusOutcome = o.status !== false
+        ? writeStatus(root, { name: c.name, command: 'shipkit check', lines: r.lines.map((l) => formatLine(l, false)), exitCode: r.exitCode })
+        : null
+    if (o.json === true) { print(JSON.stringify(r)); return r.exitCode }
+    const color = process.stdout.isTTY && process.env.NO_COLOR == null
+    for (const l of r.lines) print(formatLine(l, color))
+    if (statusOutcome != null && !statusOutcome.written) print(`WARN ${statusOutcome.warn}`)
+    return r.exitCode
+}

package/src/core/run-ci.ts

@@ -0,0 +1,54 @@
+// the ci gate — floor + contracts + repo tasks through the DAG runner.
+// Plain module behind cmd_Ci (logic stays out of command classes) so tests
+// can run the gate in-process. Returns the exit code; json prints the
+// structured summary. Every run refreshes STATUS.md (write-status.ts —
+// atomic + lock) unless status:false.
+import { join } from 'path'
+import { allTasks, loadRepoConfig } from '../repo-config.ts'
+import { runTasks, type TaskResult } from './task-runner.ts'
+import { writeStatus } from './write-status.ts'
+
+export type CiOpts = {
+    bail?: boolean
+    json?: boolean
+    skipGroups?: string[]
+    withIds?: string[]
+    onlyIds?: string[]
+    /** refresh STATUS.md after the run (default true — O4: every repo gets it) */
+    status?: boolean
+    /** line sink — commands pass their context stream; defaults to console */
+    print?: (line: string) => void
+    /** per-task completion tap — the TUI tasks panel streams results in */
+    onTaskFinish?: (r: TaskResult) => void
+}
+
+export async function runCi(root: string, o: CiOpts = {}): Promise<number> {
+    const print = o.print ?? ((l: string) => console.log(l))
+    const collected: string[] = []
+    const sink = (l: string): void => { collected.push(l); print(l) }
+    const c = await loadRepoConfig(root)
+    const { tasks, disabled, unfilled } = allTasks(c, root)
+    for (const d of disabled) sink(`skip: ${d} (skipped-by-config)`)
+    // a floor slot nothing could fill is VISIBLE — a thin gate must never
+    // look like a full one (the fresh-repo floor gap)
+    for (const u of unfilled) sink(`skip: ${u.id} (${u.reason})`)
+    const summary = await runTasks({
+        tasks,
+        logDir: c.logDir ?? join(root, 'tmp/shipkit-ci'),
+        cwd: root,
+        bail: o.bail ?? false,
+        skipGroups: o.skipGroups ?? [],
+        withIds: o.withIds ?? [],
+        onlyIds: o.onlyIds ?? [],
+        print: sink,
+        onTaskFinish: o.onTaskFinish,
+    })
+    const code = summary.ok ? 0 : 1
+    if (o.status !== false) {
+        const st = writeStatus(root, { name: c.name, command: 'shipkit ci', lines: collected, exitCode: code })
+        if (!st.written) print(`WARN ${st.warn}`)
+    }
+    if (o.json === true)
+        print(JSON.stringify({ ok: summary.ok, interrupted: summary.interrupted, disabled, tasks: summary.results.map((r) => ({ ...r, lines: undefined })) }))
+    return code
+}

package/src/core/spawn-timeout.ts

@@ -0,0 +1,65 @@
+// THE spawn-with-timeout — one code path for every shipkit surface that
+// runs a child process (task runner, CheckCtx.exec, *.check.ts discovery).
+// Resolves the binary first (Bun.spawn throws on a missing one), streams
+// stdout+stderr, SIGTERM at timeoutMs, SIGKILL after a grace period so a
+// SIGTERM-ignoring child can never hang the caller.
+
+import { existsSync } from 'fs'
+
+export type SpawnOutcome = {
+    code: number
+    out: string
+    timedOut: boolean
+    /** true when the child never ran (empty cmd, binary missing, spawn threw) — `out` carries the reason */
+    spawnFailed: boolean
+}
+
+export type SpawnTimeoutOpts = {
+    timeoutMs: number
+    /** ms between SIGTERM and SIGKILL (default 2000) */
+    killGraceMs?: number
+    cwd?: string
+    env?: Record<string, string | undefined>
+    /** raw chunk tap (log streaming, last-line tracking) — `out` accumulates regardless */
+    onChunk?: (text: string) => void
+    /** handle tap so callers can kill externally (bail / SIGINT) */
+    onSpawn?: (proc: ReturnType<typeof Bun.spawn>) => void
+}
+
+export async function spawnWithTimeout(cmd: string[], opts: SpawnTimeoutOpts): Promise<SpawnOutcome> {
+    const head = cmd[0]
+    if (head == null) return { code: -1, out: 'empty command', timedOut: false, spawnFailed: true }
+    // path-style heads verified too — Bun.spawn on a missing path throws,
+    // which must surface as a result, never a crash
+    const bin = head.includes('/') ? head : Bun.which(head)
+    if (bin == null || !existsSync(bin)) return { code: -1, out: `${head}: not found`, timedOut: false, spawnFailed: true }
+    let proc: ReturnType<typeof Bun.spawn>
+    try {
+        proc = Bun.spawn([bin, ...cmd.slice(1)], {
+            stdout: 'pipe',
+            stderr: 'pipe',
+            cwd: opts.cwd,
+            env: opts.env as Record<string, string> | undefined,
+        })
+    } catch (e) {
+        return { code: -1, out: `spawn error: ${String(e).slice(0, 200)}`, timedOut: false, spawnFailed: true }
+    }
+    opts.onSpawn?.(proc)
+    let timedOut = false
+    const timer = setTimeout(() => { timedOut = true; try { proc.kill() } catch {} }, opts.timeoutMs)
+    const killer = setTimeout(() => { try { proc.kill('SIGKILL') } catch {} }, opts.timeoutMs + (opts.killGraceMs ?? 2000))
+    let out = ''
+    const eat = async (stream: ReadableStream<Uint8Array>): Promise<void> => {
+        const dec = new TextDecoder()
+        for await (const chunk of stream) {
+            const text = dec.decode(chunk)
+            out += text
+            opts.onChunk?.(text)
+        }
+    }
+    await Promise.all([eat(proc.stdout as ReadableStream<Uint8Array>), eat(proc.stderr as ReadableStream<Uint8Array>)])
+    const code = await proc.exited
+    clearTimeout(timer)
+    clearTimeout(killer)
+    return { code, out, timedOut, spawnFailed: false }
+}