rvlib-shipkit 0.1.1 → 0.3.0

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 }
+}

package/src/core/task-runner.ts

@@ -13,9 +13,10 @@
 // - 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 { createWriteStream, mkdirSync, rmSync, type WriteStream } from 'fs'
 import { join } from 'path'
 import { CheckCtx } from './check-ctx.ts'
+import { spawnWithTimeout } from './spawn-timeout.ts'
 import { formatLine, type Line } from './wire.ts'
 
 export type TaskDef = {
@@ -54,6 +55,10 @@ export type RunOpts = {
     /** print sink — tests capture, production defaults to console.log */
     print?: (line: string) => void
     color?: boolean
+    /** per-task completion tap (the TUI streams results in as they land) —
+     *  fires for pass/fail/dep-skip; bail/interrupt leftovers never finish,
+     *  callers sweep their own pending state after runTasks resolves */
+    onTaskFinish?: (r: TaskResult) => void
 }
 
 export type RunSummary = { ok: boolean; results: TaskResult[]; interrupted: boolean }
@@ -158,6 +163,7 @@ export async function runTasks(o: RunOpts): Promise<RunSummary> {
         t.exitCode = code
         t.durationMs = t.startedAt > 0 ? Date.now() - t.startedAt : 0
         done.set(t.id, t)
+        o.onTaskFinish?.({ 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 dur = ` (${(t.durationMs / 1000).toFixed(1)}s)`
         if (status === 'pass') {
             // WARNs nag and skips stay visible (exempt contracts) even on pass
@@ -189,49 +195,36 @@ export async function runTasks(o: RunOpts): Promise<RunSummary> {
                 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)
-                        }
+            const ms = t.timeoutMs ?? 600_000
+            // log stream opens only once the child actually spawned — a
+            // missing binary must not leave a dangling open on the log dir
+            let out: WriteStream | null = null
+            const r = await spawnWithTimeout(cmd, {
+                timeoutMs: ms,
+                env: { ...process.env, ...t.env },
+                cwd: t.cwd ?? o.cwd,
+                onSpawn: (proc) => {
+                    out = createWriteStream(t.logPath!, { flags: 'a' })
+                    procs.set(t.id, proc)
+                },
+                onChunk: (text) => {
+                    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)
-            }
+                },
+            })
+            procs.delete(t.id)
+            // TS narrows `out` to its initializer across the await (assignment
+            // happens in the onSpawn closure) — widen explicitly
+            ;(out as WriteStream | null)?.end()
+            // missing binary / spawn throw surface as a wire FAIL, never a crash
+            if (r.spawnFailed) { t.lastLine = r.out; finish(t, 'fail', -1); return }
+            const killReason = killed.get(t.id)
+            if (killReason != null) { t.note = `killed (${killReason})`; finish(t, 'skipped', r.code); return }
+            if (r.timedOut) t.lastLine = `timeout after ${ms}ms — ${t.lastLine}`
+            finish(t, r.code === 0 ? 'pass' : 'fail', r.code)
         })().finally(() => running.delete(t.id))
         running.set(t.id, p)
     }

package/src/core/wire.ts

@@ -22,6 +22,26 @@ export function formatLine(l: Line, color: boolean): string {
     }
 }
 
+// inverse of formatLine, for subprocess checks: parse a child's wire output
+// back into Lines. ANSI is stripped, blank lines dropped, unknown lines kept
+// as notes (children may print context); an indented `fix:` binds to the
+// preceding WARN/FAIL severity.
+export function parseWireOutput(text: string): Line[] {
+    const lines: Line[] = []
+    let lastSeverity: 'fix-warn' | 'fix-fail' = 'fix-fail'
+    for (const raw of text.split('\n')) {
+        const l = raw.replace(/\x1b\[[0-9;]*m/g, '').trimEnd()
+        if (l.trim() === '') continue
+        if (l.startsWith('ok: ')) lines.push({ kind: 'ok', text: l.slice(4) })
+        else if (l.startsWith('WARN ')) { lastSeverity = 'fix-warn'; lines.push({ kind: 'warn', text: l.slice(5) }) }
+        else if (l.startsWith('FAIL: ')) { lastSeverity = 'fix-fail'; lines.push({ kind: 'fail', text: l.slice(6) }) }
+        else if (l.startsWith('skip: ')) lines.push({ kind: 'skip', text: l.slice(6) })
+        else if (/^\s+fix: /.test(l)) lines.push({ kind: lastSeverity, text: l.trim().slice(5) })
+        else lines.push({ kind: 'note', text: l })
+    }
+    return lines
+}
+
 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)$/)

package/src/core/write-status.ts

@@ -0,0 +1,70 @@
+// THE STATUS.md writer — every repo gets one (O4, one-runner GO
+// 2026-07-22): timestamp header + verdict + fenced compact render, the
+// shape rv-doctor pioneered. Atomic (tmp file + rename) and lock-guarded:
+// concurrent runners never interleave — the loser skips with a WARN
+// outcome, never corrupts the file.
+
+import { renameSync, rmSync, statSync, writeFileSync } from 'fs'
+import { join } from 'path'
+
+export type StatusInput = {
+    /** repo name — headline */
+    name: string
+    /** the command that produced this render, e.g. 'shipkit ci' */
+    command: string
+    /** the run's printed lines (ANSI stripped here) */
+    lines: string[]
+    exitCode: number
+}
+
+export type StatusOutcome = { written: boolean; warn?: string }
+
+const stripAnsi = (s: string): string => s.replace(/\x1b\[[0-9;]*m/g, '')
+// a runner that died without unlocking must not wedge STATUS.md forever
+const LOCK_STALE_MS = 120_000
+
+export function writeStatus(root: string, s: StatusInput): StatusOutcome {
+    const lockPath = join(root, 'STATUS.md.lock')
+    const grab = (): boolean => {
+        try { writeFileSync(lockPath, String(process.pid), { flag: 'wx' }); return true } catch { return false }
+    }
+    if (!grab()) {
+        let stale = false
+        try { stale = Date.now() - statSync(lockPath).mtimeMs > LOCK_STALE_MS } catch {
+            // lock vanished between grab and stat — the racing writer just
+            // finished; still skip this round rather than fight over it
+        }
+        if (stale) rmSync(lockPath, { force: true })
+        if (!stale || !grab())
+            return { written: false, warn: `STATUS.md locked by another runner (${lockPath}) — skipped this write` }
+    }
+    try {
+        const clean = s.lines.map(stripAnsi)
+        const fails = clean.filter((l) => l.startsWith('FAIL')).length
+        const warns = clean.filter((l) => l.startsWith('WARN')).length
+        const verdict = s.exitCode !== 0 || fails > 0
+            ? `RED — ${Math.max(fails, 1)} FAIL line${fails === 1 ? '' : 's'}. Fixes are printed under each FAIL.`
+            : warns > 0
+                ? `GREEN with nags — ${warns} WARN. Proceed.`
+                : 'GREEN — clear to ship.'
+        // local time, not UTC — an evening run must not stamp yesterday's date
+        const now = new Date()
+        const p = (n: number): string => String(n).padStart(2, '0')
+        const stamp = `${now.getFullYear()}-${p(now.getMonth() + 1)}-${p(now.getDate())} ${p(now.getHours())}:${p(now.getMinutes())}`
+        const body = `<!-- generated by \`${s.command}\` — commit me to track progress over time -->
+# ${s.name} status — ${stamp}
+
+**${verdict}**
+
+\`\`\`
+${clean.join('\n').trim()}
+\`\`\`
+`
+        const tmpPath = join(root, `.STATUS.md.tmp-${process.pid}`)
+        writeFileSync(tmpPath, body)
+        renameSync(tmpPath, join(root, 'STATUS.md'))
+        return { written: true }
+    } finally {
+        rmSync(lockPath, { force: true })
+    }
+}

package/src/init-repo.ts

@@ -0,0 +1,60 @@
+// scaffold repo.config.ts + package.json scripts, then print how the floor
+// resolved (zero-config O6: imports/cycles/typecheck fill from shipkit's
+// deps — every gap is printed, never silent). Plain module behind cmd_Init.
+// Refuses to overwrite an existing config; script merge never clobbers
+// existing keys. `bin` switches script bodies from the npm bin to an
+// in-repo-source CLI path (`bun <path> ci`) for repos that consume shipkit
+// by path instead of from node_modules.
+import { existsSync, readFileSync, writeFileSync } from 'fs'
+import { join } from 'path'
+import { defineRepo, resolveFloor } from './repo-config.ts'
+
+const CONFIG_TEMPLATE = (name: string): string => `import { defineRepo } from 'rvlib-shipkit'
+
+export default defineRepo({
+    name: '${name}',
+    venues: [], // e.g. ['itch', 'steam'] — selects which .rv-<venue>/ contracts are REQUIRED
+    social: [], // e.g. ['x', 'discord'] — .rv-social/<channel>/ post folders (+ .rv-discord/)
+    tasks: [],  // repo commit-gate tasks; deps double as race guards
+    // health checks: no config — drop a <name>.check.ts file anywhere,
+    // \`shipkit check\` auto-discovers and runs it (wire output, exit code)
+})
+`
+
+export type InitOpts = {
+    /** in-repo-source consumers: path to shipkit's cli.ts — scripts become `bun <path> <cmd>` instead of `shipkit <cmd>` */
+    bin?: string
+}
+
+export async function initRepo(root: string, opts: InitOpts = {}): Promise<number> {
+    const configPath = join(root, 'repo.config.ts')
+    if (existsSync(configPath)) { console.log(`skip: repo.config.ts already exists`); return 0 }
+    const pkgPath = join(root, 'package.json')
+    if (!existsSync(pkgPath)) { console.error('FAIL: no package.json here — run from the repo root'); return 1 }
+    const pkgRaw = readFileSync(pkgPath, 'utf8')
+    const pkg = JSON.parse(pkgRaw) as { name?: string; scripts?: Record<string, string> }
+    const name = pkg.name ?? 'my-repo'
+    writeFileSync(configPath, CONFIG_TEMPLATE(name))
+    console.log('ok: repo.config.ts created')
+    const indent = pkgRaw.match(/^(\s+)"/m)?.[1] ?? '  '
+    pkg.scripts ??= {}
+    const run = (cmd: string): string => (opts.bin != null ? `bun ${opts.bin} ${cmd}` : `shipkit ${cmd}`)
+    let added = 0
+    for (const k of ['ci', 'check', 'contracts'] as const) {
+        const v = run(k)
+        if (pkg.scripts[k] == null) { pkg.scripts[k] = v; added++ }
+        else if (pkg.scripts[k] !== v) console.log(`skip: package.json script '${k}' exists — left untouched`)
+    }
+    if (added > 0) {
+        writeFileSync(pkgPath, JSON.stringify(pkg, null, indent) + '\n')
+        console.log(`ok: ${added} package.json script(s) added`)
+    }
+    // show what the gate actually is — a thin floor must be seen at init
+    // time, not discovered after a bad commit slipped through
+    const floor = resolveFloor(defineRepo({ name }), root)
+    for (const t of floor.tasks) console.log(`ok: floor ${t.id} ← ${floor.sources[t.id] ?? 'unknown'}`)
+    for (const u of floor.unfilled) console.log(`skip: ${u.id} (${u.reason})`)
+    console.log('next: fill venues/social in repo.config.ts, then `bun run ci`')
+    console.log('next: identity+assets — mint .rv-identity/brand.ts + .rv-assets/kit.ts, `shipkit assets identity` (the identity contract expects public/ favicon+og+logo)')
+    return 0
+}

package/src/repo-config.ts

@@ -1,18 +1,35 @@
 // 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.
+// declares venues/social/tasks, and the toolkit derives everything else.
+// Health checks are NOT declared here: drop a `<name>.check.ts` file and
+// `shipkit check` discovers it (core/discover-checks.ts). The FLOOR
+// (lint/typecheck/test/imports:check/cycles): a package.json script wins;
+// with no script, imports:check/cycles fill from shipkit's own
+// rvlib-ts-tools dep and typecheck from the repo's tsc (O6 zero-config);
+// a slot that can't fill emits a visible reason, disabling via
+// `defaults: { x: false }` 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 { fileURLToPath } from 'url'
 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'
+import type { TuiPanelDef } from './tui/tui-panel.ts'
+import type { MdGraph } from './wiki/md-graph.ts'
 
-export type RepoCheck = { id: string; logic: (t: CheckCtx) => unknown; remainValidFor?: string | number; version?: number }
+// `shipkit serve` — the ONE hub server per repo (run-serve.ts resolves the
+// rest by convention: agent/ graph when the dir exists, studio when the
+// kit loads)
+export type ServeConfig = {
+    /** hub port — house range 4800+; default hashes the repo name into 4800-4979 */
+    port?: number
+    /** custom wiki-graph provider for repos with their own link semantics; default: generic md scan of the repo root */
+    wikiGraph?: { title?: string; load: () => MdGraph }
+    /** agent/ graph entrypoint (default: index.md AND README.md) */
+    agentIndex?: string
+}
 
 export type RepoConfig = {
     name: string
@@ -26,16 +43,29 @@ export type RepoConfig = {
     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 }
+    /** emptyText: the `shipkit asks` all-clear line, in the repo's own voice */
+    asks?: { dir?: string; emptyText?: string }
     contracts?: { exempt?: Record<string, string>; extra?: ContractManifest[] }
+    /** extra dashboard panels appended after the built-in Tasks/Checks (`shipkit tui`) */
+    tui?: { panels?: TuiPanelDef[] }
+    /** the `shipkit serve` hub: port + optional graph hooks */
+    serve?: ServeConfig
     logDir?: string
 }
 
+const KNOWN_KEYS = new Set(['name', 'venues', 'social', 'docsBase', 'defaults', 'tasks', 'asks', 'contracts', 'tui', 'serve', 'logDir'])
+
 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`)
+    // unknown keys die loud — a typo'd or removed key silently changing the
+    // gate is exactly the never-silence failure mode (A23)
+    for (const k of Object.keys(c))
+        if (!KNOWN_KEYS.has(k))
+            throw new Error(`defineRepo: unknown key '${k}'${k === 'checks' ? ` — checks:[] was removed; drop a <name>.check.ts file instead ('shipkit check' auto-discovers it)` : ''}`)
+    for (const k of Object.keys(c.defaults ?? {}))
+        if (!(FLOOR_IDS as readonly string[]).includes(k))
+            throw new Error(`defineRepo: defaults.${k} is not a floor task (floor: ${FLOOR_IDS.join(', ')})`)
     return c
 }
 
@@ -91,7 +121,39 @@ export function contractsTask(c: RepoConfig, root: string): TaskDef {
 
 const FLOOR_IDS = ['lint', 'typecheck', 'test', 'imports:check', 'cycles'] as const
 
-export type FloorResolution = { tasks: TaskDef[]; disabled: string[] }
+export type FloorSource = 'package.json script' | 'repo.config override' | 'built-in (rvlib-ts-tools)' | 'built-in (tsc)'
+export type FloorResolution = {
+    tasks: TaskDef[]
+    /** slots disabled by `defaults: { x: false }` — always printed */
+    disabled: string[]
+    /** slots nothing could fill — always printed, never silent */
+    unfilled: { id: string; reason: string }[]
+    /** where each registered slot came from (init prints this) */
+    sources: Record<string, FloorSource>
+}
+
+// zero-config floor (O6): with no script, imports:check/cycles resolve to
+// shipkit's own rvlib-ts-tools dep, typecheck to the repo's tsc. Returns
+// the task, or the reason the slot stays empty.
+function builtinFloorTask(id: string, root: string): { task: TaskDef; source: FloorSource } | string {
+    if (id === 'imports:check' || id === 'cycles') {
+        let cli: string
+        try { cli = fileURLToPath(import.meta.resolve('rvlib-ts-tools/src/cli.ts')) }
+        catch { return `no '${id}' script and rvlib-ts-tools is unresolvable — reinstall shipkit's deps` }
+        return {
+            task: { id, cmd: id === 'cycles' ? ['bun', cli, 'cycles'] : ['bun', cli, 'imports', '--check'] },
+            source: 'built-in (rvlib-ts-tools)',
+        }
+    }
+    if (id === 'typecheck') {
+        if (!existsSync(join(root, 'tsconfig.json'))) return `no 'typecheck' script and no tsconfig.json`
+        const local = join(root, 'node_modules/.bin/tsc')
+        const tsc = existsSync(local) ? local : Bun.which('tsc')
+        if (tsc == null) return `no 'typecheck' script and tsc not found — add typescript or a typecheck script`
+        return { task: { id, cmd: [tsc, '--noEmit'] }, source: 'built-in (tsc)' }
+    }
+    return `no package.json '${id}' script`
+}
 
 export function resolveFloor(c: RepoConfig, root: string): FloorResolution {
     const pkgPath = join(root, 'package.json')
@@ -104,16 +166,21 @@ export function resolveFloor(c: RepoConfig, root: string): FloorResolution {
     }
     const tasks: TaskDef[] = []
     const disabled: string[] = []
+    const unfilled: { id: string; reason: string }[] = []
+    const sources: Record<string, FloorSource> = {}
     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] })
+        if (override != null) { tasks.push(override); sources[id] = 'repo.config override'; continue }
+        if (scripts[id] != null) { tasks.push({ id, cmd: ['bun', 'run', id] }); sources[id] = 'package.json script'; continue }
+        const b = builtinFloorTask(id, root)
+        if (typeof b === 'string') unfilled.push({ id, reason: b })
+        else { tasks.push(b.task); sources[id] = b.source }
     }
-    return { tasks, disabled }
+    return { tasks, disabled, unfilled, sources }
 }
 
-export function allTasks(c: RepoConfig, root: string): { tasks: TaskDef[]; disabled: string[] } {
+export function allTasks(c: RepoConfig, root: string): FloorResolution {
     const floor = resolveFloor(c, root)
-    return { tasks: [...floor.tasks, contractsTask(c, root), ...(c.tasks ?? [])], disabled: floor.disabled }
+    return { ...floor, tasks: [...floor.tasks, contractsTask(c, root), ...(c.tasks ?? [])] }
 }