rvlib-shipkit 0.1.1 → 0.2.0

package/src/tui/tui-panel.ts

@@ -0,0 +1,57 @@
+// TUI panel contract — render-free and mobx-free on purpose: a panel is
+// DATA (rows + wire-format detail lines), the generic view (tui-app.tsx)
+// owns all ink. Built-ins: tasks-panel.ts (the ci gate) + checks-panel.ts
+// (contracts + discovered *.check.ts); a repo injects extras via
+// repo.config `tui: { panels: [...] }`.
+
+export type TuiRowStatus = 'pass' | 'fail' | 'warn' | 'skip' | 'pending' | 'info'
+
+export type TuiRow = {
+    key: string
+    /** left-list label */
+    label: string
+    /** drives the list mark + detail border color; 'pending' shows the spinner */
+    status: TuiRowStatus
+    /** dim right-side hint (duration, age, cached, owner) */
+    hint?: string
+    /** list-mark override (default derives from status — asks rows use '?') */
+    mark?: string
+    /** detail-panel lines — wire format (ok:/WARN/FAIL:/skip:/fix:) or plain text */
+    detail: string[]
+}
+
+export type TuiPanelDef = {
+    id: string
+    /** tab label */
+    title: string
+    /** shown green when rows() is empty after refresh (e.g. "no open asks …") */
+    emptyText?: string
+    /** current rows — the store re-reads after every update() */
+    rows: () => TuiRow[]
+    /** (re)load data; call update() after each mutation so the view repaints.
+     *  The spinner runs until every panel's returned promise settled. */
+    refresh: (update: () => void) => void | Promise<void>
+}
+
+export const ROW_MARK: Record<TuiRowStatus, { mark: string; color?: string }> = {
+    pass: { mark: '✓', color: 'green' },
+    fail: { mark: '✗', color: 'red' },
+    warn: { mark: '⚠', color: 'yellow' },
+    skip: { mark: '~', color: 'gray' },
+    pending: { mark: '', color: 'cyan' }, // the view substitutes the spinner frame
+    info: { mark: '·' },
+}
+
+// normalize a wire/detail line to the one visual language (✓/✗/⚠/~/»),
+// no raw 'ok'/'FAIL' prefixes in the detail panel
+export type MarkedLine = { mark: string; color?: string; text: string; bold?: boolean }
+
+export const markLine = (l: string): MarkedLine => {
+    if (/^ok[:\s]/.test(l)) return { mark: '✓', color: 'green', text: l.replace(/^ok[:\s]+/, '') }
+    if (l.startsWith('FAIL')) return { mark: '✗', color: 'red', text: l.replace(/^FAIL[:\s]+/, '') }
+    if (l.startsWith('WARN')) return { mark: '⚠', color: 'yellow', text: l.replace(/^WARN[:\s]+/, '') }
+    if (l.startsWith('skip:')) return { mark: '~', color: 'gray', text: l.replace(/^skip:\s*/, '') }
+    if (/^\s+fix: /.test(l)) return { mark: '»', color: 'yellow', text: l.trim() }
+    if (l.startsWith('VERDICT')) return { mark: '»', text: l, bold: true }
+    return { mark: ' ', text: l }
+}

package/src/tui/tui-store.ts

@@ -0,0 +1,98 @@
+// TUI state — MobX per the house playbook (build/state + build/mobx):
+// `makeAutoObservable` WITH exceptions (the 2026-07-21 doctrine — no
+// decorators), runInAction around every post-await mutation. Panels are
+// plain data providers (no mobx): they signal mutations through update(),
+// which bumps the observable `version` counter every rows() read tracks.
+import { makeAutoObservable, runInAction } from 'mobx'
+import type { TuiPanelDef, TuiRow, TuiRowStatus } from './tui-panel.ts'
+
+export class TuiStore {
+    tab = 0
+    sel = 0
+    spin = 0 // spinner frame, ticked while any panel refresh is in flight
+    version = 0 // bumped by panel update() — activeRows re-derives from it
+    error: string | null = null
+    inflight = 0 // panel refresh promises not yet settled
+
+    readonly name: string
+    readonly panels: TuiPanelDef[]
+    private spinTimer: ReturnType<typeof setInterval> | null = null
+
+    constructor(name: string, panels: TuiPanelDef[]) {
+        if (panels.length === 0) throw new Error('TuiStore: at least one panel required')
+        this.name = name
+        this.panels = panels
+        // panels/name/spinTimer are infra, never observed
+        makeAutoObservable<TuiStore, 'spinTimer'>(this, { name: false, panels: false, spinTimer: false })
+    }
+
+    get activePanel(): TuiPanelDef {
+        return this.panels[this.tab]!
+    }
+
+    get activeRows(): TuiRow[] {
+        void this.version // panels mutate outside mobx — update() bumps this
+        return this.activePanel.rows()
+    }
+
+    get selectedRow(): TuiRow | null {
+        return this.activeRows[this.sel] ?? null
+    }
+
+    /** per-status counts over the ACTIVE panel — the header summary */
+    get counts(): Record<TuiRowStatus, number> {
+        const c: Record<TuiRowStatus, number> = { pass: 0, fail: 0, warn: 0, skip: 0, pending: 0, info: 0 }
+        for (const r of this.activeRows) c[r.status]++
+        return c
+    }
+
+    rowsOf(panel: TuiPanelDef): TuiRow[] {
+        void this.version
+        return panel.rows()
+    }
+
+    setTab(i: number): void {
+        if (i < 0 || i >= this.panels.length || i === this.tab) return
+        this.tab = i
+        this.sel = 0
+    }
+
+    cycleTab(delta = 1): void {
+        this.setTab((this.tab + delta + this.panels.length) % this.panels.length)
+    }
+
+    move(delta: number): void {
+        const max = Math.max(0, this.activeRows.length - 1)
+        this.sel = Math.min(max, Math.max(0, this.sel + delta))
+    }
+
+    // kick every panel's refresh; results stream in via update(). A refresh
+    // while one is in flight is ignored — panels own no superseding logic.
+    refresh(): void {
+        if (this.inflight > 0) return
+        this.error = null
+        this.startSpinner()
+        const update = (): void => runInAction(() => { this.version++ })
+        for (const p of this.panels) {
+            this.inflight++
+            void Promise.resolve()
+                .then(() => p.refresh(update))
+                .catch((e) => runInAction(() => { this.error = `${p.id}: ${String(e).slice(0, 200)}` })) // never fail silently — surfaced in the header
+                .finally(() => runInAction(() => {
+                    this.version++
+                    if (--this.inflight === 0) this.stopSpinner()
+                }))
+        }
+    }
+
+    private startSpinner(): void {
+        if (this.spinTimer != null) return
+        this.spinTimer = setInterval(() => runInAction(() => { this.spin++ }), 120)
+    }
+
+    private stopSpinner(): void {
+        if (this.spinTimer == null) return
+        clearInterval(this.spinTimer)
+        this.spinTimer = null
+    }
+}

package/src/wiki/run-wiki.ts

@@ -0,0 +1,50 @@
+// md-wiki graph server + link lint (folded in from the standalone mdwiki
+// lib; that npm package is frozen). Plain modules behind cmd_Wiki —
+// clipanion owns the option parsing.
+import { basename, relative, resolve } from 'path'
+import { lintMd } from './lint-md.ts'
+import { scanMdGraph } from './scan-md.ts'
+import { serveMdGraph } from './serve-graph.ts'
+
+export type WikiScanOpts = { root: string; index?: string; skip?: string }
+
+const scanConfig = (o: WikiScanOpts): { root: string; index?: string; skipDirs?: string[] } => ({
+    root: resolve(process.cwd(), o.root),
+    index: o.index,
+    skipDirs: o.skip?.split(',').filter(Boolean),
+})
+
+export async function runWikiServe(o: WikiScanOpts & { port: number; title?: string }): Promise<number> {
+    const cfg = scanConfig(o)
+    const rel = relative(process.cwd(), cfg.root)
+    const title = o.title ?? (rel === '' ? basename(cfg.root) : `${basename(process.cwd())} ${rel}`)
+    try {
+        serveMdGraph({ port: o.port, title, load: () => scanMdGraph(cfg) })
+        console.log(`wiki graph → http://localhost:${o.port} (open in browser, or VSCode "Simple Browser: Show")`)
+        // keep the server alive — the command must not resolve
+        await new Promise(() => {})
+        return 0
+    } catch (e) {
+        if (e instanceof Error && e.message.includes('in use')) {
+            console.log(`wiki graph already served → http://localhost:${o.port} (another window owns it)`)
+            return 0
+        }
+        throw e
+    }
+}
+
+export function runWikiLint(o: WikiScanOpts): number {
+    const cfg = scanConfig(o)
+    const r = lintMd(cfg)
+    if (r.index == null) {
+        console.log(o.index != null
+            ? `FAIL entrypoint '${o.index}' not found in ${cfg.root}`
+            : `FAIL no entrypoint: neither index.md nor README.md in ${cfg.root} — pass --index <entry.md>`)
+        return 1
+    }
+    for (const f of r.orphans) console.log(`FAIL orphan: ${f} — unreachable from ${r.index}; link it or delete it`)
+    for (const d of r.dangling) console.log(`FAIL dangling: ${d.from} → ${d.token} — target not found`)
+    if (!r.ok) { console.log(`FAIL mdwiki lint: ${r.orphans.length} orphan(s), ${r.dangling.length} dangling ref(s) in ${cfg.root}`); return 1 }
+    console.log(`ok mdwiki lint: ${r.files} files, all reachable from ${r.index}, no dangling refs`)
+    return 0
+}

package/src/cli/shipkit-asks.ts

@@ -1,26 +0,0 @@
-// shipkit asks — the per-repo human queue. `asks` lists, `asks check`
-// probes + archives, `ask "<title>"` (dispatch rewrites to `asks new`).
-import { join } from 'path'
-import { checkAsks, createAsk, renderAsksTable } from '../asks/asks-queue.ts'
-import { loadRepoConfig } from '../repo-config.ts'
-
-const flagVal = (args: string[], name: string): string | undefined => {
-    const i = args.indexOf(`--${name}`)
-    return i !== -1 ? args[i + 1] : undefined
-}
-
-export async function main(args: string[]): Promise<number> {
-    const root = process.cwd()
-    const dir = join(root, (await loadRepoConfig(root)).asks?.dir ?? 'asks')
-    const sub = args[0]
-    if (sub === 'check') { checkAsks(dir); return 0 }
-    if (sub === 'new') {
-        const title = args[1]
-        if (title == null || title === '') { console.error('usage: shipkit ask "<title>" [--kind action|info] [--blocks <what>] [--check "<cmd>"]'); return 2 }
-        const file = createAsk(dir, title, { kind: flagVal(args, 'kind'), blocks: flagVal(args, 'blocks'), check: flagVal(args, 'check') })
-        console.log(`created ${dir}/${file}`)
-        return 0
-    }
-    renderAsksTable(dir)
-    return 0
-}

package/src/cli/shipkit-check.ts

@@ -1,26 +0,0 @@
-// shipkit check — periodic health: contracts + the repo's TTL'd checks.
-// Clean passes replay from cache; SHIPKIT_FRESH=1 (or --fresh) busts.
-import { join } from 'path'
-import { CheckSuite } from '../core/check-suite.ts'
-import { activeContracts, applyContractsResult, contractsConfigFrom, loadRepoConfig } from '../repo-config.ts'
-import { evaluateContracts } from '../contracts/contracts-engine.ts'
-
-export async function main(args: string[]): Promise<number> {
-    const root = process.cwd()
-    const c = await loadRepoConfig(root)
-    if (args.includes('--fresh')) process.env.SHIPKIT_FRESH = '1'
-    const suite = new CheckSuite({ name: c.name, cacheDir: join(root, 'tmp/.shipkit-cache') })
-    suite.addCheck({
-        name: 'contracts',
-        logic: async (t) => {
-            applyContractsResult(t, await evaluateContracts(activeContracts(c), contractsConfigFrom(c, root)))
-        },
-    })
-    for (const chk of c.checks ?? []) suite.addCheck({ name: chk.id, remainValidFor: chk.remainValidFor, version: chk.version, logic: chk.logic })
-    const r = await suite.execute()
-    if (args.includes('--json')) { console.log(JSON.stringify(r)); return r.exitCode }
-    const { formatLine } = await import('../core/wire.ts')
-    const color = process.stdout.isTTY && process.env.NO_COLOR == null
-    for (const l of r.lines) console.log(formatLine(l, color))
-    return r.exitCode
-}

package/src/cli/shipkit-ci.ts

@@ -1,30 +0,0 @@
-// shipkit ci — the commit/deploy gate: floor + contracts + repo tasks
-// through the DAG runner. Exit 0/1; --json prints the structured summary.
-import { join } from 'path'
-import { allTasks, loadRepoConfig } from '../repo-config.ts'
-import { runTasks } from '../core/task-runner.ts'
-
-const flagVals = (args: string[], name: string): string[] => {
-    const out: string[] = []
-    for (let i = 0; i < args.length; i++) if (args[i] === name && args[i + 1] != null) out.push(args[i + 1]!)
-    return out
-}
-
-export async function main(args: string[]): Promise<number> {
-    const root = process.cwd()
-    const c = await loadRepoConfig(root)
-    const { tasks, disabled } = allTasks(c, root)
-    for (const d of disabled) console.log(`skip: ${d} (skipped-by-config)`)
-    const summary = await runTasks({
-        tasks,
-        logDir: c.logDir ?? join(root, 'tmp/shipkit-ci'),
-        cwd: root,
-        bail: args.includes('--bail'),
-        skipGroups: flagVals(args, '--skip'),
-        withIds: flagVals(args, '--with'),
-        onlyIds: flagVals(args, '--only'),
-    })
-    if (args.includes('--json'))
-        console.log(JSON.stringify({ ok: summary.ok, interrupted: summary.interrupted, disabled, tasks: summary.results.map((r) => ({ ...r, lines: undefined })) }))
-    return summary.ok ? 0 : 1
-}

package/src/cli/shipkit-contracts.ts

@@ -1,26 +0,0 @@
-// shipkit contracts — fulfillness alone, fast and filesystem-only.
-// Venue deploy scripts call this before any upload.
-import { activeContracts, contractsConfigFrom, loadRepoConfig } from '../repo-config.ts'
-import { evaluateContracts } from '../contracts/contracts-engine.ts'
-import { formatLine } from '../core/wire.ts'
-
-export async function main(args: string[]): Promise<number> {
-    const root = process.cwd()
-    const c = await loadRepoConfig(root)
-    const venueIdx = args.indexOf('--venue')
-    const only = venueIdx !== -1 ? args[venueIdx + 1] : null
-    let manifests = activeContracts(c)
-    if (only != null) {
-        manifests = manifests.filter((m) => m.venue === only)
-        if (manifests.length === 0) { console.error(`FAIL: unknown venue '${only}'`); return 1 }
-    }
-    const r = await evaluateContracts(manifests, contractsConfigFrom(c, root))
-    if (args.includes('--json')) {
-        console.log(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) console.log(formatLine(l, color))
-    if (r.lines.length === 0) console.log('ok: no contracts apply (nothing declared, nothing detected)')
-    return r.exitCode
-}

package/src/cli/shipkit-init.ts

@@ -1,41 +0,0 @@
-// shipkit init — scaffold repo.config.ts + package.json scripts. Refuses to
-// overwrite an existing config; script merge never clobbers existing keys.
-import { existsSync, readFileSync, writeFileSync } from 'fs'
-import { join } from 'path'
-
-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
-    checks: [], // periodic health, TTL-cached
-})
-`
-
-export async function main(_args: string[]): Promise<number> {
-    const root = process.cwd()
-    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> }
-    writeFileSync(configPath, CONFIG_TEMPLATE(pkg.name ?? 'my-repo'))
-    console.log('ok: repo.config.ts created')
-    const indent = pkgRaw.match(/^(\s+)"/m)?.[1] ?? '  '
-    pkg.scripts ??= {}
-    let added = 0
-    for (const [k, v] of [['ci', 'shipkit ci'], ['check', 'shipkit check'], ['contracts', 'shipkit contracts']] as const) {
-        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`)
-    }
-    console.log('next: fill venues/social in repo.config.ts, then `bun run ci`')
-    console.log('next: identity+assets — `bun add -d rvlib-atelier`, mint .rv-identity/brand.ts + .rv-assets/kit.ts, `rvlib-atelier identity` (the identity contract expects public/ favicon+og+logo)')
-    return 0
-}

package/src/cli/shipkit-wiki.ts

@@ -1,74 +0,0 @@
-// shipkit wiki — md-wiki graph server + link lint (folded in from the
-// standalone mdwiki lib; that npm package is frozen).
-//   shipkit wiki serve --root agent --port 4800 [--title t] [--index e.md] [--skip a,b]
-//   shipkit wiki lint  --root agent [--index e.md]
-import { basename, relative, resolve } from 'path'
-import { parseArgs } from 'util'
-import { lintMd } from '../wiki/lint-md.ts'
-import { scanMdGraph } from '../wiki/scan-md.ts'
-import { serveMdGraph } from '../wiki/serve-graph.ts'
-
-const USAGE = `usage: shipkit wiki <serve|lint> [--root <dir>] [--index <entry.md>] [--skip <dir,dir>]
-  serve  --port <n> (default 6161) --title <t>   live link-graph server, reload = rescan
-  lint                                           fail on orphans + dangling refs (exit 1)
-  --root defaults to cwd; default entrypoints: index.md + README.md (--index <e> = only that one)`
-
-export async function main(args: string[]): Promise<number> {
-    let parsed: ReturnType<typeof parseArgs<{ options: { root: { type: 'string'; default: string }; port: { type: 'string'; default: string }; title: { type: 'string' }; index: { type: 'string' }; skip: { type: 'string' } }; allowPositionals: true }>>
-    try {
-        parsed = parseArgs({
-            args,
-            allowPositionals: true,
-            options: {
-                root: { type: 'string', default: '.' },
-                port: { type: 'string', default: '6161' },
-                title: { type: 'string' },
-                index: { type: 'string' },
-                skip: { type: 'string' },
-            },
-        })
-    } catch (e) {
-        console.log(`FAIL ${e instanceof Error ? e.message : e}\n${USAGE}`)
-        return 2
-    }
-    const { values, positionals } = parsed
-    const cmd = positionals[0]
-    const root = resolve(process.cwd(), values.root)
-    const scanCfg = { root, index: values.index, skipDirs: values.skip?.split(',').filter(Boolean) }
-
-    if (cmd === 'serve') {
-        const port = Number(values.port)
-        if (!Number.isInteger(port) || port <= 0) { console.log(`FAIL --port '${values.port}' is not a port number`); return 2 }
-        const rel = relative(process.cwd(), root)
-        const title = values.title ?? (rel === '' ? basename(root) : `${basename(process.cwd())} ${rel}`)
-        try {
-            serveMdGraph({ port, title, load: () => scanMdGraph(scanCfg) })
-            console.log(`wiki graph → http://localhost:${port} (open in browser, or VSCode "Simple Browser: Show")`)
-            // keep the server alive — dispatch must not exit
-            await new Promise(() => {})
-            return 0
-        } catch (e) {
-            if (e instanceof Error && e.message.includes('in use')) {
-                console.log(`wiki graph already served → http://localhost:${port} (another window owns it)`)
-                return 0
-            }
-            throw e
-        }
-    }
-    if (cmd === 'lint') {
-        const r = lintMd(scanCfg)
-        if (r.index == null) {
-            console.log(values.index != null
-                ? `FAIL entrypoint '${values.index}' not found in ${root}`
-                : `FAIL no entrypoint: neither index.md nor README.md in ${root} — pass --index <entry.md>`)
-            return 1
-        }
-        for (const f of r.orphans) console.log(`FAIL orphan: ${f} — unreachable from ${r.index}; link it or delete it`)
-        for (const d of r.dangling) console.log(`FAIL dangling: ${d.from} → ${d.token} — target not found`)
-        if (!r.ok) { console.log(`FAIL mdwiki lint: ${r.orphans.length} orphan(s), ${r.dangling.length} dangling ref(s) in ${root}`); return 1 }
-        console.log(`ok mdwiki lint: ${r.files} files, all reachable from ${r.index}, no dangling refs`)
-        return 0
-    }
-    console.log(USAGE)
-    return 2
-}