rvlib-shipkit 0.2.0 → 0.3.1

package/src/cli.ts

@@ -10,6 +10,7 @@ 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'
 
@@ -28,6 +29,7 @@ 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)

package/src/init-repo.ts

@@ -54,6 +54,16 @@ export async function initRepo(root: string, opts: InitOpts = {}): Promise<numbe
     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})`)
+    // scripts call the `shipkit` bin — dead on arrival unless the package is
+    // actually installed (field bug 2026-07-22: init via bunx, no dep, exit 127)
+    if (opts.bin == null) {
+        try {
+            Bun.resolveSync('rvlib-shipkit', root)
+        } catch {
+            console.log('WARN rvlib-shipkit not installed here — the scripts above call its bin and will exit 127')
+            console.log('      fix: bun add -d rvlib-shipkit')
+        }
+    }
     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

@@ -17,6 +17,19 @@ 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'
+
+// `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
@@ -35,10 +48,12 @@ export type RepoConfig = {
     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', 'logDir'])
+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')

package/src/serve/hub-pages.ts

@@ -0,0 +1,84 @@
+// The hub's two no-build pages (served by serve-hub.ts): the landing page
+// whose links ARE the toolbox, and the /status page (STATUS.md + a
+// "run check" button streaming wire lines). Same style family as the
+// studio: one template string, vanilla JS, no build step, no CDN.
+import type { HubTool } from './serve-hub.ts'
+
+const esc = (s: string): string => s.replace(/&/g, '&amp;').replace(/</g, '&lt;')
+
+const SHELL = `
+:root{--bg:#141210;--panel:#1e1a15;--panel2:#262019;--line:#332b22;--ink:#f3ebe0;--dim:#a89a88;
+ --accent:#e88c28;--gold:#ffcf5c;--teal:#58c0b0;--red:#e05252}
+*{box-sizing:border-box}
+body{margin:0;background:var(--bg);color:var(--ink);font:15px/1.6 system-ui,sans-serif;min-height:100vh}
+.wrap{max-width:860px;margin:0 auto;padding:40px 24px}
+h1{font-size:20px;margin:0}
+h1 small{color:var(--dim);font-weight:400;font-size:13px;margin-left:10px}
+.crumb{font-size:12px;letter-spacing:.14em;text-transform:uppercase;color:var(--accent);margin-bottom:6px}
+.crumb a{color:var(--accent);text-decoration:none}.crumb a:hover{color:var(--gold)}
+`
+
+export function landingPage(o: { name: string; port: number; tools: HubTool[] }): string {
+    const cards = o.tools
+        .map((t) => `<a class=card href="${esc(t.path)}"><b>${esc(t.label)}</b><span>${esc(t.desc)}</span><code>${esc(t.path)}</code></a>`)
+        .join('\n')
+    return `<!doctype html><html><head><meta charset=utf-8>
+<meta name=viewport content="width=device-width,initial-scale=1"><title>${esc(o.name)} · shipkit</title>
+<style>${SHELL}
+.cards{display:grid;grid-template-columns:repeat(auto-fill,minmax(240px,1fr));gap:14px;margin-top:26px}
+.card{display:flex;flex-direction:column;gap:6px;background:var(--panel);border:1px solid var(--line);border-radius:12px;
+ padding:16px;text-decoration:none;color:var(--ink)}
+.card:hover{border-color:var(--accent);background:var(--panel2)}
+.card b{font-size:15px}.card span{font-size:13px;color:var(--dim)}
+.card code{font:11px ui-monospace,Menlo,monospace;color:var(--teal)}
+</style></head><body><div class=wrap>
+<div class=crumb>shipkit hub</div>
+<h1>${esc(o.name)}<small>http://localhost:${o.port}</small></h1>
+<div class=cards>
+${cards}
+</div>
+</div></body></html>`
+}
+
+export function statusPage(o: { name: string; statusMd: string | null }): string {
+    const body = o.statusMd ?? 'no STATUS.md yet — hit "run check" (or run: shipkit check)'
+    return `<!doctype html><html><head><meta charset=utf-8>
+<meta name=viewport content="width=device-width,initial-scale=1"><title>${esc(o.name)} · status</title>
+<style>${SHELL}
+.bar{display:flex;align-items:center;gap:12px;margin:18px 0 12px}
+button{background:var(--accent);color:#1a1206;border:0;border-radius:9px;padding:8px 14px;font-weight:650;cursor:pointer}
+button:disabled{opacity:.45;cursor:default}
+#note{font-size:12px;color:var(--dim)}
+pre{background:var(--panel);border:1px solid var(--line);border-radius:12px;padding:16px;overflow-x:auto;
+ font:12.5px/1.55 ui-monospace,Menlo,monospace;white-space:pre-wrap}
+.ok{color:var(--teal)}.warn{color:var(--gold)}.fail{color:var(--red)}.dim{color:var(--dim)}
+</style></head><body><div class=wrap>
+<div class=crumb><a href="/">shipkit hub</a> / status</div>
+<h1>${esc(o.name)}<small>STATUS.md</small></h1>
+<div class=bar><button id=run>run check</button><span id=note>shells <code>shipkit check</code>, wire lines stream in below</span></div>
+<pre id=out></pre>
+<script>
+const out=document.getElementById('out'),btn=document.getElementById('run'),note=document.getElementById('note')
+// wire-line coloring: ok/WARN/FAIL/skip prefixes → the house palette
+const esc=s=>s.replace(/&/g,'&amp;').replace(/</g,'&lt;')
+const cls=l=>{const t=l.trimStart()
+ if(t.startsWith('FAIL')||t.startsWith('✗'))return 'fail'
+ if(t.startsWith('WARN')||t.startsWith('⚠'))return 'warn'
+ if(t.startsWith('ok')||t.startsWith('✓'))return 'ok'
+ if(t.startsWith('skip')||t.startsWith('fix:')||t.startsWith('#'))return 'dim'
+ return ''}
+const paint=text=>{out.innerHTML=text.split('\\n').map(l=>'<span class="'+cls(l)+'">'+esc(l)+'</span>').join('\\n')}
+paint(${JSON.stringify(body).replaceAll('<', '\\u003c')})
+btn.onclick=async()=>{
+ btn.disabled=true;note.textContent='running…';let text=''
+ try{
+  const r=await fetch('status/run',{method:'POST'})
+  const rd=r.body.getReader(),dec=new TextDecoder()
+  for(;;){const{done,value}=await rd.read();if(done)break;text+=dec.decode(value,{stream:true});paint(text)}
+  note.textContent='done — STATUS.md refreshed on disk'
+ }catch(e){text+='\\nFAIL stream broke: '+e;paint(text);note.textContent='stream broke'}
+ btn.disabled=false
+}
+</script>
+</div></body></html>`
+}

package/src/serve/run-serve.ts

@@ -0,0 +1,85 @@
+// shipkit serve — resolve the repo's toolbox and run the hub. What mounts
+// comes from convention + repo.config's `serve` block: the wiki graph is
+// always on (custom provider via serve.wikiGraph, else the generic md
+// scan), agent/ graph when the dir exists, the studio when .rv-assets/
+// kit.ts loads. Port: --port > serve.port > a deterministic house-range
+// default (4800-4979, hashed from the repo name — stable across launches;
+// pin serve.port when two repos collide).
+import { existsSync } from 'fs'
+import { join } from 'path'
+import { fileURLToPath } from 'url'
+import { loadKit } from '../assets/kit-config.ts'
+import { page as studioPage } from '../assets/server/studio-page.ts'
+import { studioRoutes, type StudioRoutes } from '../assets/server/studio-server.ts'
+import { loadRepoConfig, type RepoConfig } from '../repo-config.ts'
+import { scanMdGraph } from '../wiki/scan-md.ts'
+import { serveHub, type HubDeps } from './serve-hub.ts'
+
+export type ServeIo = { print: (l: string) => void; printErr: (l: string) => void }
+
+export function defaultHubPort(name: string): number {
+    let h = 0
+    for (const c of name) h = (h * 31 + c.charCodeAt(0)) >>> 0
+    return 4800 + (h % 180)
+}
+
+export async function resolveHubDeps(root: string, c: RepoConfig, io: ServeIo, o?: { port?: number }): Promise<HubDeps> {
+    const wikiGraph = c.serve?.wikiGraph != null
+        ? { title: c.serve.wikiGraph.title ?? `${c.name} wiki`, load: c.serve.wikiGraph.load }
+        : { title: `${c.name} wiki`, load: () => scanMdGraph({ root }) }
+    const agentRoot = join(root, 'agent')
+    const agentGraph = existsSync(agentRoot)
+        ? { title: `${c.name} agent/`, load: () => scanMdGraph({ root: agentRoot, index: c.serve?.agentIndex }) }
+        : null
+    let studio: StudioRoutes | null = null
+    if (existsSync(join(root, '.rv-assets/kit.ts'))) {
+        // a broken kit must not take the graphs and status down with it —
+        // WARN + mount everything else
+        try {
+            studio = await studioRoutes({ kit: await loadKit(root), root, page: studioPage })
+        } catch (e) {
+            io.print(`WARN assets studio not mounted: ${(e as Error).message}`)
+        }
+    }
+    const cli = fileURLToPath(new URL('../cli.ts', import.meta.url))
+    return {
+        root,
+        name: c.name,
+        port: o?.port ?? c.serve?.port ?? defaultHubPort(c.name),
+        wikiGraph,
+        agentGraph,
+        studio,
+        checkCmd: [process.execPath, cli, 'check'],
+    }
+}
+
+export async function runServe(root: string, io: ServeIo, o?: { port?: number }): Promise<number> {
+    const c = await loadRepoConfig(root)
+    const deps = await resolveHubDeps(root, c, io, o)
+    try {
+        const hub = serveHub(deps)
+        const base = `http://localhost:${hub.server.port}`
+        io.print(`ok: ${c.name} hub → ${base}`)
+        for (const t of hub.tools) io.print(`ok: ${t.label} → ${base}${t.path}`)
+        await new Promise(() => {}) // the hub owns the process — never resolve
+        return 0
+    } catch (e) {
+        if (e instanceof Error && e.message.includes('in use')) {
+            // same repo in another window is fine; a different repo hashed
+            // onto this port is a real collision — never claim its hub
+            const owner = await fetch(`http://127.0.0.1:${deps.port}/hub.json`, { signal: AbortSignal.timeout(1500) })
+                .then((r) => r.json() as Promise<{ hub?: string; name?: string; tools?: { path: string; label: string }[] }>)
+                .catch(() => null)
+            if (owner?.hub === 'shipkit' && owner.name === c.name) {
+                // a re-run terminal stays as clickable as a first run — the
+                // owner's /hub.json tool list is the same source of truth
+                io.print(`ok: hub already served → http://localhost:${deps.port} (another window owns it)`)
+                for (const t of owner.tools ?? []) io.print(`ok: ${t.label} → http://localhost:${deps.port}${t.path}`)
+                return 0
+            }
+            io.printErr(`FAIL: port ${deps.port} is taken by ${owner?.name != null ? `repo '${owner.name}'` : 'another process'} — set serve: { port } in repo.config.ts to a free one`)
+            return 1
+        }
+        throw e
+    }
+}

package/src/serve/serve-hub.ts

@@ -0,0 +1,77 @@
+// shipkit serve — ONE hub server per repo, ONE port (his call 2026-07-22:
+// "a single shipkit task in vscode with multiple urls I can click"). The
+// landing page's links are the whole toolbox: /graph/wiki · /graph/agent ·
+// /assets/ (the studio, mounted IN-PROCESS) · /status (STATUS.md + run
+// check). Route logic only — resolving WHAT to mount from repo.config is
+// run-serve.ts's job.
+import { existsSync } from 'fs'
+import { join } from 'path'
+import { graphHtml } from 'rvlib-shipkit/src/wiki/graph-page.ts'
+import type { MdGraph } from 'rvlib-shipkit/src/wiki/md-graph.ts'
+import type { StudioRoutes } from '../assets/server/studio-server.ts'
+import { landingPage, statusPage } from './hub-pages.ts'
+
+export type HubGraph = { title: string; load: () => MdGraph }
+export type HubTool = { path: string; label: string; desc: string }
+export type HubDeps = {
+    root: string
+    name: string
+    /** 0 = random (tests); real launches pass repo.config/default */
+    port: number
+    wikiGraph: HubGraph
+    /** null = no agent/ dir */
+    agentGraph: HubGraph | null
+    /** null = no .rv-assets/kit.ts (or it failed to load — caller prints the WARN) */
+    studio: StudioRoutes | null
+    /** argv shelling the check run streamed by /status/run (test seam) */
+    checkCmd: string[]
+}
+export type Hub = { server: ReturnType<typeof Bun.serve>; tools: HubTool[]; stop: () => void }
+
+// the toolbox as data — the landing page, /hub.json, and the stdout ok:
+// lines all render THIS list, so they can never disagree
+export function hubTools(d: Pick<HubDeps, 'wikiGraph' | 'agentGraph' | 'studio'>): HubTool[] {
+    const tools: HubTool[] = [{ path: '/graph/wiki', label: 'wiki graph', desc: d.wikiGraph.title }]
+    if (d.agentGraph != null) tools.push({ path: '/graph/agent', label: 'agent graph', desc: d.agentGraph.title })
+    if (d.studio != null) tools.push({ path: '/assets/', label: 'assets studio', desc: 'roll, curate, pick, ship' })
+    tools.push({ path: '/status', label: 'status', desc: 'STATUS.md + run check' })
+    return tools
+}
+
+export function serveHub(d: HubDeps): Hub {
+    const tools = hubTools(d)
+    const html = (s: string): Response => new Response(s, { headers: { 'content-type': 'text/html; charset=utf-8' } })
+    const server: ReturnType<typeof Bun.serve> = Bun.serve({
+        hostname: '127.0.0.1',
+        port: d.port,
+        async fetch(req): Promise<Response> {
+            const path = new URL(req.url).pathname
+            if (path === '/') return html(landingPage({ name: d.name, port: server.port ?? d.port, tools }))
+            // identity probe: lets a second launch tell "same repo, another
+            // window" from "a DIFFERENT repo hashed onto my port"
+            if (path === '/hub.json') return Response.json({ hub: 'shipkit', name: d.name, tools })
+            if (path === '/graph/wiki') return html(graphHtml(d.wikiGraph.load(), { title: d.wikiGraph.title }))
+            if (path === '/graph/wiki/graph.json') return Response.json(d.wikiGraph.load())
+            if (d.agentGraph != null && path === '/graph/agent') return html(graphHtml(d.agentGraph.load(), { title: d.agentGraph.title }))
+            if (d.agentGraph != null && path === '/graph/agent/graph.json') return Response.json(d.agentGraph.load())
+            if (path === '/status') {
+                const p = join(d.root, 'STATUS.md')
+                return html(statusPage({ name: d.name, statusMd: existsSync(p) ? await Bun.file(p).text() : null }))
+            }
+            if (path === '/status/run' && req.method === 'POST') {
+                // stream wire lines as the check emits them; sh merges stderr
+                // so FAIL lines reach the page, not just the terminal
+                const proc = Bun.spawn(['sh', '-c', 'exec "$0" "$@" 2>&1', ...d.checkCmd], { cwd: d.root, stdout: 'pipe', stderr: 'ignore' })
+                return new Response(proc.stdout, { headers: { 'content-type': 'text/plain; charset=utf-8', 'cache-control': 'no-store' } })
+            }
+            if (d.studio != null) {
+                // the studio page fetches RELATIVE urls — it must live under
+                // the slash-terminated prefix for them to resolve
+                if (path === '/assets') return new Response(null, { status: 307, headers: { location: '/assets/' } })
+                if (path.startsWith('/assets/')) return d.studio.handle(req, path.slice('/assets'.length))
+            }
+            return new Response('not found', { status: 404 })
+        },
+    })
+    return { server, tools, stop: () => server.stop(true) }
+}

package/src/shipkit.ts

@@ -1,7 +1,12 @@
 // 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, FloorResolution, FloorSource } from './repo-config.ts'
+export type { RepoConfig, ServeConfig, FloorResolution, FloorSource } from './repo-config.ts'
+// the hub (`shipkit serve`): one server, one port, every tool a click away
+export { serveHub, hubTools } from './serve/serve-hub.ts'
+export type { Hub, HubDeps, HubGraph, HubTool } from './serve/serve-hub.ts'
+export { runServe, resolveHubDeps, defaultHubPort } from './serve/run-serve.ts'
+export { landingPage, statusPage } from './serve/hub-pages.ts'
 export { discoverChecks } from './core/discover-checks.ts'
 export type { DiscoveredCheck } from './core/discover-checks.ts'
 export { runTasks, selectTasks } from './core/task-runner.ts'
@@ -29,11 +34,11 @@ export type { Ask, CreateOpts } from './asks/asks-queue.ts'
 // 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 { KitConfig, ResolvedKit, Kind, KindMeta, AssetSpec, GeneratorSpec, ComfyGen, CanvasGen, PanelSpec, GeometryPanelSpec, GridPanelSpec, CustomPanelSpec, FoundAsset, ShipContext, ShipFn } from './assets/kit-config.ts'
+export { identityKinds, renderIdentity, renderIdentityFromMark, NO_PICK_FIX, 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 { serveStudio, studioRoutes } from './assets/server/studio-server.ts'
+export type { Studio, StudioDeps, StudioRoutes } 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'

package/src/tui/run-tui.ts

@@ -0,0 +1,25 @@
+// The tui command body — a separate module so cli.ts NEVER loads
+// react/ink/mobx for non-tui commands (a fresh consumer running `shipkit ci`
+// must not touch the react dependency chain; field bug 2026-07-22: 0.3.0
+// crashed every command on repos without react-dom).
+import React from 'react'
+import { render } from 'ink'
+import { configure } from 'mobx'
+import { loadRepoConfig } from '../repo-config.ts'
+import { checksPanel } from './checks-panel.ts'
+import { tasksPanel } from './tasks-panel.ts'
+import { TuiApp } from './tui-app.tsx'
+import { TuiStore } from './tui-store.ts'
+
+export async function runTui(root: string): Promise<number> {
+    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
+}