rvlib-shipkit 0.1.1 → 0.3.0

package/src/cli/cmd_Assets.ts

@@ -0,0 +1,120 @@
+// shipkit assets — asset atelier: declare kinds in .rv-assets/kit.ts, roll
+// (ComfyUI or procedural canvas), curate in the studio, ship with metadata
+// write-through. Thin clipanion surfaces; logic in assets/run-assets.ts.
+import { Command, Option } from 'clipanion'
+import { runAssetsCheck, runAssetsGen, runAssetsIdentity, runAssetsServe, runAssetsTopUp, type AssetsIo } from '../assets/run-assets.ts'
+
+const ioOf = (cmd: Command): AssetsIo => ({
+    print: (l) => cmd.context.stdout.write(`${l}\n`),
+    printErr: (l) => cmd.context.stderr.write(`${l}\n`),
+})
+
+export class AssetsServeCommand extends Command {
+    static override paths = [['assets', 'serve']]
+
+    static override usage = Command.Usage({
+        category: 'Assets',
+        description: 'the studio — roll, curate, pick, ship (127.0.0.1, kit port)',
+        examples: [['launch the studio for the cwd kit', 'shipkit assets serve']],
+    })
+
+    async execute(): Promise<number> {
+        return runAssetsServe(process.cwd(), ioOf(this))
+    }
+}
+
+export class AssetsFillCommand extends Command {
+    static override paths = [['assets', 'fill']]
+
+    static override usage = Command.Usage({
+        category: 'Assets',
+        description: 'top rolls up to N per asset (canvas or comfy), sparsest-first',
+        examples: [
+            ['every asset up to 8 rolls', 'shipkit assets fill 8'],
+            ['only two categories', 'shipkit assets fill 8 icons sprites'],
+        ],
+    })
+
+    n = Option.String({ required: true })
+    categories = Option.Rest()
+
+    async execute(): Promise<number> {
+        const n = Number(this.n)
+        if (!Number.isInteger(n) || n <= 0) {
+            this.context.stderr.write(`FAIL: '${this.n}' is not a positive roll count — usage: shipkit assets fill <N> [category…]\n`)
+            return 1
+        }
+        return runAssetsTopUp(process.cwd(), ioOf(this), { mode: 'fill', n, categories: this.categories })
+    }
+}
+
+export class AssetsAddCommand extends Command {
+    static override paths = [['assets', 'add']]
+
+    static override usage = Command.Usage({
+        category: 'Assets',
+        description: 'N more rolls per asset (canvas or comfy), regardless of what it has',
+        examples: [['3 fresh rolls everywhere', 'shipkit assets add 3']],
+    })
+
+    n = Option.String({ required: true })
+    categories = Option.Rest()
+
+    async execute(): Promise<number> {
+        const n = Number(this.n)
+        if (!Number.isInteger(n) || n <= 0) {
+            this.context.stderr.write(`FAIL: '${this.n}' is not a positive roll count — usage: shipkit assets add <N> [category…]\n`)
+            return 1
+        }
+        return runAssetsTopUp(process.cwd(), ioOf(this), { mode: 'add', n, categories: this.categories })
+    }
+}
+
+export class AssetsGenCommand extends Command {
+    static override paths = [['assets', 'gen']]
+
+    static override usage = Command.Usage({
+        category: 'Assets',
+        description: 'one-shot rolls for a single asset (canvas or comfy)',
+        examples: [
+            ['one roll', 'shipkit assets gen hero'],
+            ['five rolls', 'shipkit assets gen hero --n 5'],
+        ],
+    })
+
+    assetId = Option.String({ required: true })
+    n = Option.String('--n', '1', { description: 'how many rolls (default 1)' })
+
+    async execute(): Promise<number> {
+        const n = Math.max(1, Number(this.n) || 1)
+        return runAssetsGen(process.cwd(), ioOf(this), { assetId: this.assetId, n })
+    }
+}
+
+export class AssetsIdentityCommand extends Command {
+    static override paths = [['assets', 'identity']]
+
+    static override usage = Command.Usage({
+        category: 'Assets',
+        description: 'render favicon/logo/OG from .rv-identity/brand.ts into public/',
+        examples: [['regenerate the identity outputs', 'shipkit assets identity']],
+    })
+
+    async execute(): Promise<number> {
+        return runAssetsIdentity(process.cwd(), ioOf(this))
+    }
+}
+
+export class AssetsCheckCommand extends Command {
+    static override paths = [['assets', 'check']]
+
+    static override usage = Command.Usage({
+        category: 'Assets',
+        description: 'kit loads, kinds valid, workflows bound, backend reachable, identity outputs present',
+        examples: [['health-check the asset pipeline', 'shipkit assets check']],
+    })
+
+    async execute(): Promise<number> {
+        return runAssetsCheck(process.cwd(), ioOf(this))
+    }
+}

package/src/cli/cmd_Check.ts

@@ -0,0 +1,30 @@
+// shipkit check — periodic health, TTL-cached. Thin clipanion surface;
+// logic in core/run-check.ts.
+import { Command, Option } from 'clipanion'
+import { runCheck } from '../core/run-check.ts'
+
+export class CheckCommand extends Command {
+    static override paths = [['check']]
+
+    static override usage = Command.Usage({
+        category: 'Health',
+        description: 'periodic health: contracts + every *.check.ts in the repo (auto-discovered, run as subprocesses), clean passes replay from a TTL cache',
+        examples: [
+            ['run (cached where valid)', 'shipkit check'],
+            ['bust every cache layer', 'shipkit check --fresh'],
+            ['machine-readable', 'shipkit check --json'],
+        ],
+    })
+
+    json = Option.Boolean('--json', false, { description: 'machine-readable result instead of wire lines' })
+    fresh = Option.Boolean('--fresh', false, { description: 'bust every TTL cache layer (travels to child checks)' })
+
+    async execute(): Promise<number> {
+        try {
+            return await runCheck(process.cwd(), { json: this.json, fresh: this.fresh, 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_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_Serve.ts

@@ -0,0 +1,34 @@
+// shipkit serve — the ONE hub server per repo (one vscode folder-open task,
+// clickable URLs). Thin clipanion surface; logic in serve/run-serve.ts.
+import { Command, Option } from 'clipanion'
+import { runServe } from '../serve/run-serve.ts'
+
+export class ServeCommand extends Command {
+    static override paths = [['serve']]
+
+    static override usage = Command.Usage({
+        category: 'Serve',
+        description: 'ONE hub server per repo: landing page linking the wiki/agent graphs, the assets studio, and live status',
+        examples: [
+            ['serve the repo toolbox', 'shipkit serve'],
+            ['pin the port for this launch', 'shipkit serve --port 4804'],
+        ],
+    })
+
+    port = Option.String('--port', { required: false, description: 'hub port (default: repo.config serve.port, else hashed from the repo name into 4800-4979)' })
+
+    async execute(): Promise<number> {
+        let port: number | undefined
+        if (this.port != null) {
+            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 runServe(process.cwd(), {
+            print: (l) => this.context.stdout.write(`${l}\n`),
+            printErr: (l) => this.context.stderr.write(`${l}\n`),
+        }, { port })
+    }
+}

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,47 @@
 #!/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 { ServeCommand } from './cli/cmd_Serve.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(ServeCommand)
+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 }
+    })
+}