rvlib-shipkit 0.30.0 → 0.31.0

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 0.31.0
+
+- **Every repo browses its shared wiki from its own hub.** A repo whose CLAUDE.md include chain points at a wiki living in another repo (`@~/dev/<other-repo>/wiki/index.md`, read from `CLAUDE.md`, `CLAUDE.local.md` or `CLAUDE.private.md`) mounts it at `/graph/base`, named after the repo that owns it. That wiki binds every agent working here, so the hub lets a human read it where the work happens. An index inside the repo is skipped, since it is already its own mount, and the card carries no lint verdict: the owning repo lints its own pages.
+- **The graphs section stops advertising a graph the server does not serve.** A repo without a `wiki/` dir, which every fresh `shipkit start` is, still got a `wiki graph` card, and opening it embedded the hub's own 404 body ("not found — the hub page is at /") inside the card. Routes, `/hub.json` tools and cards now read ONE `GraphMount[]` that `resolveHubDeps` resolves (`HubDeps.wikiGraph` and `HubDeps.agentGraph` are gone, `HubDeps.graphs` replaces both), instead of the collection re-deriving the wiki graph from the repo root. A graph that is not mounted has no card, and the test asserts every href the section advertises answers 200.
+
 ## 0.30.0
 
 - **The studio asset page is tools on one shared canvas, not tabs on a drawer.** Every metadata family is a toggleable TOOL: `oval`, `legs`, `size` (the geometry editor split into its parts), each repo `customPanel`, `asset json`, `roll meta`. Several can be on at once, the URL records the set (`#<assetId>?tools=a,b`, shareable, restored on load), and the last set per kind is remembered. Kit-declared TABS (`meta.tabs: [{ id, tools }]`) are one-click presets, validated at kit load (an undeclared panel OR an unknown tool id refuses, loud). Panel tools float as draggable cards ON the canvas (a drag clamps inside the stage), `customPanel({ anchor: 'bl' })` starts a card bottom-left, so switching a tab never reflows the stage, and the drawer, its tab row and the bottom json body are deleted. Toggling a custom editor on does fold the variants bar, the one deliberate reflow. Custom panels can draw on the art in place: `api.stageOverlay()` returns an element covering the displayed roll (the tint-mask painter paints THERE, controls stay in its floating card), `api.dropOverlays()` cleans up on unmount, and the host calls it. Variants (rolls) move to a thin resizable right bar (drag handle, width remembered, slim-rail collapse, auto-folds when a custom editor turns on). The prompt keeps its fold. The stage remeasures through a ResizeObserver, so overlays track the image through any layout change, not only window resizes.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "rvlib-shipkit",
-    "version": "0.30.0",
+    "version": "0.31.0",
     "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/collections/graphs.ts

@@ -1,34 +1,32 @@
-// graphs collection — the mounted md graphs as CHECKED section entries:
-// each graph instance carries its lint state (orphans + dangling refs =
-// yellow with counts; clean = quiet). Custom wiki-graph providers (repos
-// with their own loader + their own lint) get a link-only instance — their
-// repo lint owns correctness, never double-judged here.
-import { existsSync } from 'fs'
-import { join } from 'path'
+// graphs collection — the MOUNTED md graphs as CHECKED section entries. The
+// mounts arrive as data from the hub's own route resolution (serve/run-serve),
+// never re-derived here: a card linking at an unmounted route renders the 404
+// body inside its iframe. Each instance carries its lint state (orphans +
+// dangling refs = yellow with counts; clean = quiet). A graph whose lint
+// belongs to another repo is link-only, never double-judged here.
 import { lintMd } from '../wiki/lint-md.ts'
+import type { GraphMount } from '../wiki/graph-mount.ts'
 import type { Collection, Instance } from './collection-types.ts'
 
-export function graphsCollection(root: string, o: { customWiki: boolean; agentIndex?: string }): Collection {
+export function graphsCollection(mounts: GraphMount[]): Collection {
     return {
         id: 'graphs',
         title: 'graphs',
         media: 'data',
-        list: async () => {
-            const out: Instance[] = []
-            const checked = (id: string, title: string, href: string, dir: string, index?: string): Instance => {
-                const r = lintMd({ root: dir, index })
+        list: async () =>
+            mounts.map((m): Instance => {
+                const id = `graph:${m.id}`
+                const href = `/graph/${m.id}`
+                const label = m.note != null ? `${m.label} (${m.note})` : m.label
+                if (m.lint == null) return { id, text: label, href }
+                const r = lintMd({ root: m.lint.root, index: m.lint.index })
                 const issues = r.orphans.length + r.dangling.length
                 return {
                     id,
-                    text: issues === 0 ? title : `${title} — ${r.orphans.length} orphan(s), ${r.dangling.length} dangling ref(s)`,
+                    text: issues === 0 ? label : `${label} — ${r.orphans.length} orphan(s), ${r.dangling.length} dangling ref(s)`,
                     severity: issues === 0 ? undefined : 'yellow',
                     href,
                 }
-            }
-            if (o.customWiki) out.push({ id: 'graph:wiki', text: 'wiki graph (repo-owned lint)', href: '/graph/wiki' })
-            else out.push(checked('graph:wiki', 'wiki graph', '/graph/wiki', root))
-            if (existsSync(join(root, 'agent'))) out.push(checked('graph:agent', 'agent graph', '/graph/agent', join(root, 'agent'), o.agentIndex))
-            return out
-        },
+            }),
     }
 }

package/src/serve/run-serve.ts

@@ -1,12 +1,14 @@
 // 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/
+// scan), the base-context wiki when a CLAUDE.md include names one, 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, readFileSync } from 'fs'
-import { join } from 'path'
+import { homedir } from 'os'
+import { basename, dirname, join, resolve, sep } from 'path'
 import { fileURLToPath } from 'url'
 import { loadKit, type ResolvedKit } from '../assets/kit-config.ts'
 import { studioRoutes, type StudioRoutes } from '../assets/server/studio-server.ts'
@@ -15,6 +17,7 @@ import { graphsCollection } from '../collections/graphs.ts'
 import { pingTick } from '../collections/pings.ts'
 import { buildCollections } from '../collections/providers.ts'
 import { loadRepoConfig, type RepoConfig } from '../repo-config.ts'
+import type { GraphMount } from '../wiki/graph-mount.ts'
 import { scanMdGraph } from '../wiki/scan-md.ts'
 import { serveHub, type HubDeps } from './serve-hub.ts'
 
@@ -26,19 +29,54 @@ export function defaultHubPort(name: string): number {
     return 4800 + (h % 180)
 }
 
+// the BASE-CONTEXT wiki: the shared wiki this repo's CLAUDE.md include chain
+// points at (`@~/dev/<other-repo>/wiki/index.md`). It lives in ANOTHER repo and
+// binds every agent working here, so the hub makes it browsable. Never linted
+// from here. The local-include forms (`@./agent/index.md`,
+// `@./CLAUDE.local.md`) and any index inside this repo are skipped: those are
+// already their own mounts.
+export function baseWikiRoot(root: string): string | null {
+    const abs = resolve(root)
+    for (const f of ['CLAUDE.md', 'CLAUDE.local.md', 'CLAUDE.private.md']) {
+        const p = join(abs, f)
+        if (!existsSync(p)) continue
+        for (const line of readFileSync(p, 'utf8').split('\n')) {
+            const m = line.trim().match(/^@(\S+\.md)$/)
+            if (m == null) continue
+            const raw = m[1]!
+            const target = resolve(abs, raw.startsWith('~/') ? join(homedir(), raw.slice(2)) : raw)
+            const dir = dirname(target)
+            if (!existsSync(target)) continue
+            if (dir === abs || dir.startsWith(abs + sep)) continue
+            return dir
+        }
+    }
+    return null
+}
+
+// `~/dev/<repo>/wiki` reads as "<repo> wiki" — a dir literally named wiki says
+// nothing on its own, so the owning repo names the card
+const wikiLabel = (dir: string): string => (basename(dir) === 'wiki' ? `${basename(dirname(dir))} wiki` : basename(dir))
+
 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
-    // 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 }
-        : existsSync(join(root, 'wiki'))
-            ? { title: `${c.name} wiki`, load: () => scanMdGraph({ root }) }
-            : null
+    // ONE list: the routes, the /hub.json tools and the graphs section all
+    // read it, so nothing can advertise a graph the server does not serve.
+    // The repo's OWN wiki mounts when it has one (a game repo's hub
+    // advertising an empty wiki route was startup noise), a config-declared
+    // provider always mounts, and the base-context wiki (the shared one named
+    // by the CLAUDE.md include chain) mounts wherever it is reachable: an
+    // agent working here obeys that wiki, so a reader can open it.
+    const graphs: GraphMount[] = []
+    if (c.serve?.wikiGraph != null)
+        graphs.push({ id: 'wiki', label: 'wiki graph', title: c.serve.wikiGraph.title ?? `${c.name} wiki`, load: c.serve.wikiGraph.load, lint: null, note: 'repo-owned lint' })
+    else if (existsSync(join(root, 'wiki')))
+        graphs.push({ id: 'wiki', label: 'wiki graph', title: `${c.name} wiki`, load: () => scanMdGraph({ root }), lint: { root } })
+    const baseWiki = baseWikiRoot(root)
+    if (baseWiki != null)
+        graphs.push({ id: 'base', label: wikiLabel(baseWiki), title: wikiLabel(baseWiki), load: () => scanMdGraph({ root: baseWiki }), lint: null })
     const agentRoot = join(root, 'agent')
-    const agentGraph = existsSync(agentRoot)
-        ? { title: `${c.name} agent/`, load: () => scanMdGraph({ root: agentRoot, index: c.serve?.agentIndex }) }
-        : null
+    if (existsSync(agentRoot))
+        graphs.push({ id: 'agent', label: 'agent graph', title: `${c.name} agent/`, load: () => scanMdGraph({ root: agentRoot, index: c.serve?.agentIndex }), lint: { root: agentRoot, index: c.serve?.agentIndex } })
     // ONE page for every repo: the studio ALWAYS
     // mounts — kit-less repos get an empty media section, never a second
     // page. A broken kit degrades to the same empty kit, loudly.
@@ -60,15 +98,14 @@ export async function resolveHubDeps(root: string, c: RepoConfig, io: ServeIo, o
     const cli = fileURLToPath(new URL('../cli.ts', import.meta.url))
     const allCollections = () => [
         ...buildCollections(root, c, kit, { bootVersion: BOOT_VERSION, libVersion }),
-        graphsCollection(root, { customWiki: c.serve?.wikiGraph != null, agentIndex: c.serve?.agentIndex }),
+        graphsCollection(graphs),
     ]
     const port = o?.port ?? c.serve?.port ?? defaultHubPort(c.name)
     return {
         root,
         name: c.name,
         port,
-        wikiGraph,
-        agentGraph,
+        graphs,
         studio,
         checkCmd: [process.execPath, cli, 'check'],
         needs: () => projectNeeds(allCollections()),

package/src/serve/serve-hub.ts

@@ -6,23 +6,21 @@
 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 { appendAskRemark, appendAssetNote, appendPostFeedback, askDone, askProof, markPosted, pickPostVariant } from '../collections/actions.ts'
 import type { Collection, Instance, NeedItem } from '../collections/collection-types.ts'
+import type { GraphMount } from '../wiki/graph-mount.ts'
 import hubIndex from './hub-app/index.html'
 
-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
-    /** null = this repo has no wiki to graph — the route stays unmounted */
-    wikiGraph: HubGraph | null
-    /** null = no agent/ dir */
-    agentGraph: HubGraph | null
+    /** every md graph this hub serves, in card order: /graph/<id>. run-serve
+     *  resolves the list, the routes AND the graphs section read it */
+    graphs: GraphMount[]
     /** the media API (mounted under /media/*); null only if the route
      *  table failed to build — the page shows the WARN, never a second page */
     studio: StudioRoutes | null
@@ -43,11 +41,11 @@ export type Hub = { server: ReturnType<typeof Bun.serve>; tools: HubTool[]; stop
 
 // the toolbox as data — stdout ok: lines and /hub.json render THIS list,
 // 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' }]
-    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
+export function hubTools(d: Pick<HubDeps, 'graphs'>): HubTool[] {
+    return [
+        { path: '/', label: 'hub', desc: 'THE page — media · asks · creds · posts · health · graphs' },
+        ...d.graphs.map((g) => ({ path: `/graph/${g.id}`, label: g.label, desc: g.title })),
+    ]
 }
 
 // drill-down pages (graph canvases) get one fixed home link back to THE page
@@ -125,10 +123,10 @@ 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 (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())
+            for (const g of d.graphs) {
+                if (path === `/graph/${g.id}`) return page(graphHtml(g.load(), { title: g.title }))
+                if (path === `/graph/${g.id}/graph.json`) return Response.json(g.load())
+            }
             // the media API namespace — the studio route table, ONE prefix strip
             if (d.studio != null && path.startsWith('/media/')) return d.studio.handle(req, path.slice('/media'.length))
             // stale bookmarks (/assets/, /status, …) land here — name the way home

package/src/shipkit.ts

@@ -5,8 +5,9 @@ export type { RepoConfig, ServeConfig, FloorResolution, FloorSource } from './re
 export { contractsConfigFrom, activeContracts, applyContractsResult } from './contracts/apply-contracts.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 type { Hub, HubDeps, HubTool } from './serve/serve-hub.ts'
+export type { GraphMount } from './wiki/graph-mount.ts'
+export { runServe, resolveHubDeps, defaultHubPort, baseWikiRoot } from './serve/run-serve.ts'
 export { projectNeeds, redCount } from './collections/collection-types.ts'
 export type { Collection, Instance, NeedItem, NeedSeverity, CurationVerb } from './collections/collection-types.ts'
 export { buildCollections } from './collections/providers.ts'

package/src/wiki/graph-mount.ts

@@ -0,0 +1,21 @@
+// one MOUNTED md graph, as the hub serves it and as the graphs section shows
+// it. ONE list per repo (serve/run-serve builds it): the route, the card and
+// the lint verdict all read the same entries, so a card can never link at a
+// route that is not served.
+import type { MdGraph } from 'rvlib-shipkit/src/wiki/md-graph.ts'
+
+export type GraphMount = {
+    /** route + card id: /graph/<id>, instance graph:<id> */
+    id: string
+    /** card text and tool label, e.g. `wiki graph`, `<repo> wiki` */
+    label: string
+    /** graph page title */
+    title: string
+    load: () => MdGraph
+    /** null = someone else owns this graph's lint (a repo-owned provider, or a
+     *  wiki living in another repo): the card links, it never judges */
+    lint: { root: string; index?: string } | null
+    /** parenthesized on the CARD only, never in the terminal banner: why this
+     *  graph carries no verdict here */
+    note?: string
+}