rvlib-shipkit 0.22.0 → 0.22.2

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 0.22.2
+
+- **Frozen gates never write the motherhome row.** The bump preflight ate the machine dirt, then the gate INSIDE the bump re-wrote the local-projects row and the post-gate cleanliness check refused, the same wart's second head. A frozen run is release-shaped: it reports nothing to the motherhome, so the tree it proves clean stays clean. Interactive ci/check keep reporting.
+- **The hub banner says only what exists.** It printed the hub URL twice (the banner plus the '/' tool row) and advertised a wiki graph in repos with no wiki: the default wiki graph now mounts only when a `wiki/` dir exists (a config-declared one always mounts), the '/' tool stays in /hub.json but never re-prints, and a game repo's startup reads one hub line plus the routes it really serves.
+
+## 0.22.1
+
+- **Fix: the cache stamp is baked in at RUN time, replays print it verbatim.** 0.22.0 annotated only the REPLAY, so a fresh run and a cache hit rendered different strings and STATUS.md still diffed on every alternation (his catch, the second one on this line). A TTL clean pass now writes "(cached at <stamp> until <stamp>)" into the line once, live output and every replay are byte-identical, and the line changes only when a re-validation happens. Proven: fresh-then-cached runs produce a zero-diff STATUS body.
+
 ## 0.22.0
 
 - **Fix: the machine-row auto-commit could not see STATUS.md.** The git helper trims its whole output, so the FIRST porcelain line loses its leading space and the old column-3 slice read "TATUS.md", making the preflight silently decline the exact dirt it was built to eat. `dirtyPathList` parses status prefixes robustly now (renames and quoted paths included, regression-tested on the trimmed-first-line case), and a decline is never silent: the preflight names the non-machine paths it refused.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "rvlib-shipkit",
-    "version": "0.22.0",
+    "version": "0.22.2",
     "description": "All-in-one repo companion: ci gate (task DAG), auto-discovered health checks, release-contract fulfillness, asks queue, md-wiki tools, asset atelier, live tui",
     "license": "MIT",
     "type": "module",

package/src/core/check-suite.ts

@@ -143,13 +143,14 @@ export class CheckSuite {
                 && entry != null && entry.version === r.version && entry.key === key
                 && this.now() - entry.at < r.ttlMs && this.now() >= entry.at
             if (fresh) {
-                // absolute stamp, never "Xm ago": a relative age re-renders on
-                // every run and turns committed STATUS.md checkpoints into
-                // noise diffs (his call 2026-08-05). The line now changes only
-                // when the cache actually refreshes.
-                const lines = entry.lines.map((l, i): Line => (i === 0 ? { ...l, text: `${l.text} (cached ${fmtStamp(entry.at)})` } : l))
-                out.push(...lines)
-                this.onResult?.(r.name, { lines, status: 'pass', cached: true }) // only clean passes are cached
+                // the stamp was baked in when the check RAN (below): a replay
+                // prints the stored lines VERBATIM, so the live run and every
+                // later replay render the same string, and the line changes
+                // only when a re-validation happens (his call 2026-08-05,
+                // second round: annotating replays but not live runs still
+                // diffed on every fresh-vs-cached alternation)
+                out.push(...entry.lines)
+                this.onResult?.(r.name, { lines: entry.lines, status: 'pass', cached: true }) // only clean passes are cached
                 continue
             }
             const t = new CheckCtx(this.toolPaths)
@@ -160,14 +161,18 @@ export class CheckSuite {
                 else if (e instanceof ToolUnresolved) t.note(`${r.name} skipped (${e.message})`)
                 else t.fail(`${r.name} errored (${String(e).slice(0, 200)}) — network down, or a bug in this check`)
             }
-            out.push(...t.lines)
-            this.onResult?.(r.name, { lines: t.lines, status: t.failed ? 'fail' : t.warned ? 'warn' : 'pass', cached: false })
+            // a skip line is an UNKNOWN, not a clean pass — replaying
+            // "registry unreachable" for a TTL asserts a dead network as
+            // fact long after it recovered
+            const cacheable = r.ttlMs > 0 && !t.failed && !t.warned && !t.lines.some((l) => l.kind === 'skip')
+            const lines = cacheable
+                ? t.lines.map((l, i): Line => (i === 0 ? { ...l, text: `${l.text} (cached at ${fmtStamp(this.now())} until ${fmtStamp(this.now() + r.ttlMs)})` } : l))
+                : t.lines
+            out.push(...lines)
+            this.onResult?.(r.name, { lines, status: t.failed ? 'fail' : t.warned ? 'warn' : 'pass', cached: false })
             if (t.failed) anyFail = true
             if (r.ttlMs > 0) {
-                // a skip line is an UNKNOWN, not a clean pass — replaying
-                // "registry unreachable" for a TTL asserts a dead network as
-                // fact long after it recovered
-                if (!t.failed && !t.warned && !t.lines.some((l) => l.kind === 'skip')) { cache[r.name] = { version: r.version, key, at: this.now(), lines: t.lines }; cacheDirty = true }
+                if (cacheable) { cache[r.name] = { version: r.version, key, at: this.now(), lines }; cacheDirty = true }
                 // a WARN/FAIL evicts the stale pass — a later run must re-probe,
                 // not replay an ok recorded before the breakage
                 else if (entry != null) { delete cache[r.name]; cacheDirty = true }

package/src/core/run-check.ts

@@ -123,7 +123,9 @@ export async function collectChecks(root: string, o: CheckOpts = {}): Promise<Ch
     const r = await suite.execute()
     if (prevFresh == null) delete process.env.SHIPKIT_FRESH; else process.env.SHIPKIT_FRESH = prevFresh
     if (prevFrozen == null) delete process.env.SHIPKIT_FROZEN; else process.env.SHIPKIT_FROZEN = prevFrozen
-    reportToMotherhome(root, c)
+    // frozen = a release-shaped run: reporting would re-dirty the tree the
+    // caller is about to demand clean (field wart 2026-08-05, second head)
+    if (o.frozen !== true) reportToMotherhome(root, c)
     return { lines: r.lines, blocked: r.exitCode !== 0, advisoryFailures, undeclared }
 }
 

package/src/core/run-ci.ts

@@ -120,9 +120,13 @@ export async function runCi(root: string, o: CiOpts = {}): Promise<number> {
         } else sink(`WARN ${checks.advisoryFailures.length} non-blocking check(s) failing, about the world rather than this repo: ${checks.advisoryFailures.join(', ')}`)
     }
     const code = summary.ok && !fixFailed && !checks.blocked && !advisoryFatal && checks.undeclared.length === 0 ? 0 : 1
-    // motherhome row (docsBase wiki on this disk) — never affects the gate
-    const mh = reportToMotherhome(root, c)
-    if (mh.note != null) print(mh.note)
+    // motherhome row (docsBase wiki on this disk) — never affects the gate,
+    // and never fires under frozen: a bump/release gate must not re-dirty
+    // the tree it just proved clean (field wart 2026-08-05, second head)
+    if (o.frozen !== true) {
+        const mh = reportToMotherhome(root, c)
+        if (mh.note != null) print(mh.note)
+    }
     if (o.status !== false) {
         // scope is named in the file: ci proves the gate, not repo health, and
         // a bare GREEN here would claim clear-to-ship on a repo with red checks

package/src/serve/run-serve.ts

@@ -27,9 +27,14 @@ export function defaultHubPort(name: string): number {
 }
 
 export async function resolveHubDeps(root: string, c: RepoConfig, io: ServeIo, o?: { port?: number }): Promise<HubDeps> {
+    // the default wiki graph exists only when the repo HAS a wiki dir: a
+    // game repo's hub advertising a wiki route was startup noise (his catch
+    // 2026-08-05). A config-declared wikiGraph always mounts.
     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 }) }
+        : existsSync(join(root, 'wiki'))
+            ? { title: `${c.name} wiki`, load: () => scanMdGraph({ root }) }
+            : null
     const agentRoot = join(root, 'agent')
     const agentGraph = existsSync(agentRoot)
         ? { title: `${c.name} agent/`, load: () => scanMdGraph({ root: agentRoot, index: c.serve?.agentIndex }) }
@@ -105,7 +110,8 @@ export async function runServe(root: string, io: ServeIo, o?: { port?: number })
         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}`)
+        // the '/' tool IS the banner line above — printing it again was noise
+        for (const t of hub.tools) if (t.path !== '/') io.print(`ok: ${t.label} → ${base}${t.path}`)
         // the off-machine door (phone, other machines) — publicHost is config
         if (c.serve?.publicHost != null) io.print(`ok: public → http://${c.serve.publicHost}:${hub.server.port}/`)
         await new Promise(() => {}) // the hub owns the process — never resolve
@@ -121,7 +127,7 @@ export async function runServe(root: string, io: ServeIo, o?: { port?: number })
                 // 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}`)
+                for (const t of owner.tools ?? []) if (t.path !== '/') 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`)

package/src/serve/serve-hub.ts

@@ -19,7 +19,8 @@ export type HubDeps = {
     name: string
     /** 0 = random (tests); real launches pass repo.config/default */
     port: number
-    wikiGraph: HubGraph
+    /** null = this repo has no wiki to graph — the route stays unmounted */
+    wikiGraph: HubGraph | null
     /** null = no agent/ dir */
     agentGraph: HubGraph | null
     /** the media API (mounted under /media/*); null only if the route
@@ -44,7 +45,7 @@ export type Hub = { server: ReturnType<typeof Bun.serve>; tools: HubTool[]; stop
 // so they can never disagree
 export function hubTools(d: Pick<HubDeps, 'wikiGraph' | 'agentGraph'>): HubTool[] {
     const tools: HubTool[] = [{ path: '/', label: 'hub', desc: 'THE page — media · asks · creds · posts · health · graphs' }]
-    tools.push({ path: '/graph/wiki', label: 'wiki graph', desc: d.wikiGraph.title })
+    if (d.wikiGraph != null) tools.push({ 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 })
     return tools
 }
@@ -124,8 +125,8 @@ export function serveHub(d: HubDeps): Hub {
                 return new Response(proc.stdout, { headers: { 'content-type': 'text/plain; charset=utf-8', 'cache-control': 'no-store' } })
             }
             const page = (s: string): Response => new Response(withHome(s), { headers: { 'content-type': 'text/html; charset=utf-8' } })
-            if (path === '/graph/wiki') return page(graphHtml(d.wikiGraph.load(), { title: d.wikiGraph.title }))
-            if (path === '/graph/wiki/graph.json') return Response.json(d.wikiGraph.load())
+            if (d.wikiGraph != null && path === '/graph/wiki') return page(graphHtml(d.wikiGraph.load(), { title: d.wikiGraph.title }))
+            if (d.wikiGraph != null && path === '/graph/wiki/graph.json') return Response.json(d.wikiGraph.load())
             if (d.agentGraph != null && path === '/graph/agent') return page(graphHtml(d.agentGraph.load(), { title: d.agentGraph.title }))
             if (d.agentGraph != null && path === '/graph/agent/graph.json') return Response.json(d.agentGraph.load())
             // the media API namespace — the studio route table, ONE prefix strip