rvlib-shipkit 0.1.0 → 0.2.0

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,22 @@
 // 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'
-
-export type RepoCheck = { id: string; logic: (t: CheckCtx) => unknown; remainValidFor?: string | number; version?: number }
+import type { TuiPanelDef } from './tui/tui-panel.ts'
 
 export type RepoConfig = {
     name: string
@@ -26,16 +30,27 @@ 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[] }
     logDir?: string
 }
 
+const KNOWN_KEYS = new Set(['name', 'venues', 'social', 'docsBase', 'defaults', 'tasks', 'asks', 'contracts', 'tui', '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 +106,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 +151,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 ?? [])] }
 }

package/src/shipkit.ts

@@ -1,13 +1,22 @@
 // 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 type { RepoConfig, FloorResolution, FloorSource } from './repo-config.ts'
+export { discoverChecks } from './core/discover-checks.ts'
+export type { DiscoveredCheck } from './core/discover-checks.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 type { CheckSuiteOpts, CheckOutcome, GetSecret, SecretSpec } from './core/check-suite.ts'
+// tui: type-only here — the store/view/panels import ink+mobx, which must
+// not load on every `shipkit ci`; runtime pieces live at rvlib-shipkit/src/tui/*
+export type { TuiPanelDef, TuiRow, TuiRowStatus, MarkedLine } from './tui/tui-panel.ts'
 export { CheckCtx, RateLimited, ToolUnresolved } from './core/check-ctx.ts'
-export { formatLine, parseDuration, fmtAge } from './core/wire.ts'
+export { spawnWithTimeout } from './core/spawn-timeout.ts'
+export type { SpawnOutcome, SpawnTimeoutOpts } from './core/spawn-timeout.ts'
+export { writeStatus } from './core/write-status.ts'
+export type { StatusInput, StatusOutcome } from './core/write-status.ts'
+export { formatLine, parseDuration, fmtAge, parseWireOutput } 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'
@@ -16,6 +25,28 @@ export type { ContractManifest, ArtifactRule, Detector, ContractEnv } from './co
 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'
+// assets surface (folded in from the standalone atelier lib; that npm
+// package is frozen). A repo's .rv-assets/kit.ts imports defineKit and
+// declares its kinds; `shipkit assets …` derives the rest.
+export { defineKit, defineKind, comfy, canvas, geometryPanel, gridPanel, customPanel, validateKit, missingPanelScripts, loadKit, findAsset, allAssets, categoriesOf } from './assets/kit-config.ts'
+export type { KitConfig, ResolvedKit, Kind, KindMeta, AssetSpec, GeneratorSpec, ComfyGen, CanvasGen, PanelSpec, GeometryPanelSpec, GridPanelSpec, CustomPanelSpec, FoundAsset } from './assets/kit-config.ts'
+export { identityKinds, renderIdentity, FAVICON_SIZE, OG_W, OG_H, LOGO_SIZE } from './assets/kits/identity-kit.ts'
+export type { Brand } from './assets/kits/identity-kit.ts'
+export { serveStudio } from './assets/server/studio-server.ts'
+export type { Studio, StudioDeps } from './assets/server/studio-server.ts'
+export { page as studioPage } from './assets/server/studio-page.ts'
+export { StudioQueue } from './assets/server/studio-queue.ts'
+export type { Job, QueueState } from './assets/server/studio-queue.ts'
+export { cleanRect, liveRect, defaultLegs, migrateCircle } from './assets/panels/geometry-rects.ts'
+export type { GroundRect, LegRect } from './assets/panels/geometry-rects.ts'
+export { generate, submit, waitFor, applyInputs, expectNode, randomSeed, batchFolderName } from './assets/gen/comfy-gen.ts'
+export type { ComfyOpts } from './assets/gen/comfy-gen.ts'
+export { loadWorkflows, workflowFor } from './assets/gen/workflow-loader.ts'
+export type { Workflow, Sidekick, Binding, Graph } from './assets/gen/workflow-loader.ts'
+export { toPng, alphaHeight } from './assets/image-ops.ts'
+export { updateJson, readJson } from './assets/json-store.ts'
+export { assetDir, listRolls, isRollFile, readPick, updatePick, metaPath, pickPath, readPromptOverlay, updatePromptOverlay, promptPath } from './assets/roll-workspace.ts'
+export type { PickState, PromptOverlay } from './assets/roll-workspace.ts'
 export { scanMdGraph } from './wiki/scan-md.ts'
 export { lintMd } from './wiki/lint-md.ts'
 export { serveMdGraph } from './wiki/serve-graph.ts'

package/src/tui/checks-panel.ts

@@ -0,0 +1,39 @@
+// built-in panel: contracts + every discovered *.check.ts through runCheck
+// (both TTL cache layers intact) — per-check results stream in via the
+// onResult tap. status:false: the tasks panel owns STATUS.md in a TUI run.
+import { discoverChecks } from '../core/discover-checks.ts'
+import { runCheck } from '../core/run-check.ts'
+import { formatLine } from '../core/wire.ts'
+import type { TuiPanelDef, TuiRow } from './tui-panel.ts'
+
+export function checksPanel(root: string): TuiPanelDef {
+    let rows: TuiRow[] = []
+    return {
+        id: 'checks',
+        title: 'Checks',
+        rows: () => rows,
+        refresh: async (update) => {
+            rows = ['contracts', ...discoverChecks(root).map((d) => d.name)]
+                .map((n): TuiRow => ({ key: n, label: n, status: 'pending', detail: [] }))
+            const byKey = new Map(rows.map((r, i) => [r.key, i]))
+            update()
+            await runCheck(root, {
+                status: false,
+                print: () => {},
+                onResult: (name, r) => {
+                    const row: TuiRow = {
+                        key: name,
+                        label: name,
+                        status: r.status,
+                        ...(r.cached ? { hint: 'cached' } : {}),
+                        detail: r.lines.map((l) => formatLine(l, false)),
+                    }
+                    const i = byKey.get(name)
+                    if (i == null) { byKey.set(name, rows.length); rows.push(row) } // suite-side names (secret checks) still land
+                    else rows[i] = row
+                    update()
+                },
+            })
+        },
+    }
+}

package/src/tui/tasks-panel.ts

@@ -0,0 +1,54 @@
+// built-in panel: the ci gate (floor + contracts + repo tasks) through
+// runCi — results stream in via the onTaskFinish tap. STATUS.md refreshes
+// exactly like a terminal `shipkit ci`; the checks panel writes nothing
+// (one STATUS writer per TUI session).
+import type { RepoConfig } from '../repo-config.ts'
+import { allTasks } from '../repo-config.ts'
+import { runCi } from '../core/run-ci.ts'
+import { formatLine } from '../core/wire.ts'
+import type { TaskResult } from '../core/task-runner.ts'
+import type { TuiPanelDef, TuiRow } from './tui-panel.ts'
+
+const taskRow = (r: TaskResult): TuiRow => ({
+    key: r.id,
+    label: r.id,
+    status: r.status === 'pass' ? (r.lines.some((l) => l.kind === 'warn') ? 'warn' : 'pass') : r.status === 'fail' ? 'fail' : 'skip',
+    hint: `${(r.durationMs / 1000).toFixed(1)}s`,
+    detail: [
+        ...r.lines.map((l) => formatLine(l, false)),
+        ...(r.status === 'fail' && r.lastLine !== '' ? [`FAIL: ${r.lastLine}`] : []),
+        ...(r.note !== '' ? [`skip: ${r.note}`] : []),
+        ...(r.logPath != null ? [`full log: ${r.logPath}`] : []),
+    ],
+})
+
+export function tasksPanel(root: string, config: RepoConfig): TuiPanelDef {
+    let rows: TuiRow[] = []
+    return {
+        id: 'tasks',
+        title: 'Tasks',
+        rows: () => rows,
+        refresh: async (update) => {
+            const { tasks, disabled, unfilled } = allTasks(config, root)
+            rows = [
+                ...tasks.map((t): TuiRow => ({ key: t.id, label: t.id, status: 'pending', detail: [] })),
+                ...disabled.map((id): TuiRow => ({ key: id, label: id, status: 'skip', detail: ['skip: disabled by repo.config defaults'] })),
+                ...unfilled.map((u): TuiRow => ({ key: u.id, label: u.id, status: 'skip', detail: [`skip: ${u.reason}`] })),
+            ]
+            const byKey = new Map(rows.map((r, i) => [r.key, i]))
+            update()
+            await runCi(root, {
+                print: () => {}, // rows carry everything the wire lines would
+                onTaskFinish: (r) => {
+                    const i = byKey.get(r.id)
+                    if (i == null) return
+                    rows[i] = taskRow(r)
+                    update()
+                },
+            })
+            // bail/interrupt leftovers never got a finish tap — visible, never a fake pass
+            rows = rows.map((r) => (r.status === 'pending' ? { ...r, status: 'skip', detail: ['skip: never ran (bailed or interrupted)'] } : r))
+            update()
+        },
+    }
+}

package/src/tui/tui-app.tsx

@@ -0,0 +1,91 @@
+// shipkit tui — the generic view: tab bar, list left, detail right, wire
+// lines normalized to one visual language (✓/✗/⚠/~/»). All data comes from
+// panels (tui-panel.ts); this file owns ONLY rendering + keys.
+import React from 'react'
+import { Box, Text, useApp, useInput } from 'ink'
+import { observer } from 'mobx-react-lite'
+import { markLine, ROW_MARK, type TuiRow } from './tui-panel.ts'
+import type { TuiStore } from './tui-store.ts'
+
+const SPIN = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏']
+
+const RowLine = observer(function RowLine(p: { row: TuiRow; selected: boolean; spin: number; width: number }) {
+    const m = ROW_MARK[p.row.status]
+    const mark = p.row.status === 'pending' ? SPIN[p.spin % SPIN.length]! : (p.row.mark ?? m.mark)
+    return (
+        <Text inverse={p.selected} wrap="truncate">
+            <Text color={m.color}>{mark.padEnd(2)}</Text>
+            <Text dimColor={p.row.status === 'pending'}>{p.row.label.padEnd(p.width)}</Text>
+            {p.row.hint != null && <Text dimColor> {p.row.hint}</Text>}
+        </Text>
+    )
+})
+
+const Detail = observer(function Detail(p: { row: TuiRow; spin: number }) {
+    const m = ROW_MARK[p.row.status]
+    return (
+        <Box flexDirection="column" borderStyle="round" borderColor={m.color ?? 'gray'} paddingX={1} flexGrow={1}>
+            <Box justifyContent="space-between">
+                <Text bold>{p.row.label}</Text>
+                {p.row.status === 'pending'
+                    ? <Text color="cyan">{SPIN[p.spin % SPIN.length]} running</Text>
+                    : <Text bold color={m.color}>{p.row.status.toUpperCase()}</Text>}
+            </Box>
+            {p.row.detail.map((l, i) => {
+                const c = markLine(l)
+                return <Text key={i} bold={c.bold} wrap="truncate-end"><Text color={c.color}>{c.mark}</Text> {c.text}</Text>
+            })}
+            {p.row.status !== 'pending' && p.row.detail.length === 0 && <Text dimColor>no output</Text>}
+        </Box>
+    )
+})
+
+const Summary = observer(function Summary(p: { store: TuiStore }) {
+    const c = p.store.counts
+    return (
+        <Text>
+            <Text color="green">{c.pass} ok</Text><Text dimColor> · </Text>
+            <Text color="yellow">{c.warn} warn</Text><Text dimColor> · </Text>
+            <Text color="red">{c.fail} fail</Text>
+            {c.pending > 0 && <Text color="cyan"> · {SPIN[p.store.spin % SPIN.length]} {c.pending} running</Text>}
+        </Text>
+    )
+})
+
+export const TuiApp = observer(function TuiApp(p: { store: TuiStore }) {
+    const app = useApp()
+    const s = p.store
+    useInput((input, key) => {
+        if (input === 'q') app.exit()
+        else if (input === 'r') s.refresh()
+        else if (/^[1-9]$/.test(input)) s.setTab(Number(input) - 1)
+        else if (key.tab || key.rightArrow) s.cycleTab(1)
+        else if (key.leftArrow) s.cycleTab(-1)
+        else if (key.downArrow || input === 'j') s.move(1)
+        else if (key.upArrow || input === 'k') s.move(-1)
+    })
+    const rows = s.activeRows
+    const width = Math.max(8, ...rows.map((r) => r.label.length))
+    return (
+        <Box flexDirection="column">
+            <Box justifyContent="space-between">
+                <Text bold color="cyan">⚙ {s.name} — shipkit</Text>
+                <Summary store={s} />
+            </Box>
+            <Box gap={2}>
+                {s.panels.map((panel, i) => (
+                    <Text key={panel.id} bold inverse={i === s.tab}> {i + 1} {panel.title}{s.rowsOf(panel).length > 0 ? ` (${s.rowsOf(panel).length})` : ''} </Text>
+                ))}
+                {s.error != null && <Text color="red">{s.error}</Text>}
+            </Box>
+            <Box gap={1}>
+                <Box flexDirection="column" flexShrink={0}>
+                    {rows.length === 0 && <Text color="green">{s.activePanel.emptyText ?? '(empty)'}</Text>}
+                    {rows.map((r, i) => <RowLine key={r.key} row={r} selected={i === s.sel} spin={s.spin} width={width} />)}
+                </Box>
+                {s.selectedRow != null && <Detail row={s.selectedRow} spin={s.spin} />}
+            </Box>
+            <Text dimColor>1-{s.panels.length}/tab switch · j/k move · r refresh · q quit</Text>
+        </Box>
+    )
+})