rvlib-shipkit 0.7.0 → 0.9.0

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # Changelog
 
+## 0.9.0 — 2026-07-22
+
+New:
+
+- `shipkit start <name>`: ensure `<root>/<name>` exists (`--root`, default
+  `~/dev`) and, with `--include <line>`, that CLAUDE.md starts with that
+  include (`--also-ok <line>` variants count as already wired and are never
+  double-added; `--skip <name>` repos never get the include). Stdout is
+  ONLY the resolved dir: a sourced shell alias can
+  `cd "$(shipkit start <name> …)"`, the one thing a child process can't do
+  for its parent shell.
+
+## 0.8.0 — 2026-07-22
+
+New:
+
+- `shipkit mv <old.md> <new.md>` in every repo: rename an md page + its
+  sibling asset dir + `<name>.check.ts`, sweeping every tracked file for
+  refs (full path, docs-root id, check filename, boundary-guarded so
+  lookalikes survive). Dry by default, `--write` applies, `--commit` adds
+  one conventional commit behind the repo's pre-commit gate. A repo
+  `mv:after` script (NOT `postmv`, bun npm-compat auto-runs post* names)
+  runs after the moves for repo-specific re-stamps. `movePage` exported.
+  `init` scaffolds the `mv` script; the package.json probe requires it.
+  Upgraders: re-run `shipkit init` (idempotent, only adds the gap).
+- the hub detects its own staleness: lib version read at boot vs on disk
+  per attention load. A mismatched running process shows a red line telling
+  you to restart the task (field bug: a morning process served old studio
+  code all day and a pick looked broken).
+
 ## 0.7.0 — 2026-07-22
 
 New (the hub becomes THE dashboard; autonomy over nagging):

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "rvlib-shipkit",
-    "version": "0.7.0",
+    "version": "0.9.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/assets/run-assets.ts

@@ -184,7 +184,7 @@ export const runAssetsCheck = (root: string, io: AssetsIo): Promise<number> =>
         else if (idn.state === 'rendered') io.print(`ok: identity re-rendered (brand.ts changed) — ${idn.detail}`)
         else if (idn.state === 'blocked') { io.print(`FAIL: identity blocked — ${idn.detail}`); bad++ }
         // manual assets: no rolls = nothing to ship = RED (the missing list
-        // is the shopping list — build/audio doctrine); rolls-but-no-pick = WARN
+        // is the shopping list — build/game-audio doctrine); rolls-but-no-pick = WARN
         const manuals = allAssets(kit).filter((f) => f.kind.generate.backend === 'manual')
         let manualBad = 0
         for (const f of manuals) {

package/src/cli/cmd_Mv.ts

@@ -0,0 +1,34 @@
+// shipkit mv — md-page rename with repo-wide ref sweep. Thin clipanion
+// surface; logic in mv/mv-md.ts.
+import { Command, Option } from 'clipanion'
+import { movePage } from '../mv/mv-md.ts'
+
+export class MvCommand extends Command {
+    static override paths = [['mv']]
+
+    static override usage = Command.Usage({
+        category: 'Wiki',
+        description: 'rename an md page + sibling dir + check.ts, sweeping every tracked ref; renames must be CHEAP',
+        examples: [
+            ['dry run (default): show what would change', 'shipkit mv docs/old-name.md docs/new-name.md'],
+            ['apply + one conventional commit', 'shipkit mv docs/old-name.md docs/new-name.md --commit'],
+        ],
+    })
+
+    oldPath = Option.String()
+    newPath = Option.String()
+    write = Option.Boolean('--write', false, { description: 'apply (default is a dry run)' })
+    commit = Option.Boolean('--commit', false, { description: 'apply + git commit (pre-commit hook is the gate)' })
+
+    async execute(): Promise<number> {
+        try {
+            return movePage(process.cwd(), this.oldPath, this.newPath, {
+                print: (l) => this.context.stdout.write(`${l}\n`),
+                printErr: (l) => this.context.stderr.write(`${l}\n`),
+            }, { write: this.write, commit: this.commit })
+        } catch (e) {
+            this.context.stderr.write(`FAIL: ${e instanceof Error ? e.message : String(e)}\n`)
+            return 1
+        }
+    }
+}

package/src/cli/cmd_Start.ts

@@ -0,0 +1,28 @@
+// shipkit start — ensure <root>/<name> exists (+ a CLAUDE.md include),
+// printing the dir on stdout so a shell alias can cd there (a child process
+// can't cd its parent). Thin clipanion surface; logic in start-repo.ts.
+import { Command, Option } from 'clipanion'
+import { startRepo } from '../start-repo.ts'
+
+export class StartCommand extends Command {
+    static override paths = [['start']]
+
+    static override usage = Command.Usage({
+        category: 'Setup',
+        description: 'ensure <root>/<name> exists, optionally with a CLAUDE.md include line; prints the dir on stdout so a shell alias can cd there',
+        examples: [
+            ['start (or enter) a repo', 'shipkit start pong'],
+            ['seed CLAUDE.md line 1', "shipkit start pong --include '@~/wiki/index.md'"],
+        ],
+    })
+
+    name = Option.String()
+    root = Option.String('--root', { description: 'parent dir for repos (default ~/dev)' })
+    include = Option.String('--include', { description: 'line CLAUDE.md must start with; omitted = only ensure the dir' })
+    alsoOk = Option.Array('--also-ok', { description: 'alternative lines that already count as wired — never double-add' })
+    skip = Option.Array('--skip', { description: 'repo names that never get the include' })
+
+    async execute(): Promise<number> {
+        return startRepo(this.name, { root: this.root, include: this.include, alsoOk: this.alsoOk, skip: this.skip })
+    }
+}

package/src/cli.ts

@@ -10,7 +10,9 @@ 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 { MvCommand } from './cli/cmd_Mv.ts'
 import { ServeCommand } from './cli/cmd_Serve.ts'
+import { StartCommand } from './cli/cmd_Start.ts'
 import { TuiCommand } from './cli/cmd_Tui.ts'
 import { WikiLintCommand, WikiServeCommand } from './cli/cmd_Wiki.ts'
 
@@ -27,6 +29,7 @@ const cli = new Cli({
 cli.register(Builtins.HelpCommand)
 cli.register(Builtins.VersionCommand)
 cli.register(CiCommand)
+cli.register(MvCommand)
 cli.register(CheckCommand)
 cli.register(TuiCommand)
 cli.register(ServeCommand)
@@ -43,5 +46,6 @@ cli.register(AssetsGenCommand)
 cli.register(AssetsIdentityCommand)
 cli.register(AssetsCheckCommand)
 cli.register(InitCommand)
+cli.register(StartCommand)
 
 cli.runExit(process.argv.slice(2))

package/src/contracts/manifests/discord.contract.ts

@@ -5,7 +5,7 @@ import { defineContract, dirExists, md, png } from 'rvlib-shipkit/src/contracts/
 export default defineContract({
     venue: 'discord',
     dir: '.rv-discord',
-    owner: 'distribute/social.md',
+    owner: 'distribute/post-publicly.md',
     appliesTo: 'declared',
     detect: [dirExists('.rv-discord')],
     artifacts: [

package/src/contracts/manifests/identity.contract.ts

@@ -6,7 +6,7 @@ import { defineContract, file, glob, png } from 'rvlib-shipkit/src/contracts/con
 export default defineContract({
     venue: 'identity',
     dir: '.rv-identity',
-    owner: 'build/assets.md',
+    owner: 'build/generate-assets.md',
     appliesTo: 'always',
     gate: 'public-surface',
     detect: [],

package/src/contracts/manifests/social.contract.ts

@@ -5,7 +5,7 @@ import { custom, defineContract, dirExists } from 'rvlib-shipkit/src/contracts/c
 export default defineContract({
     venue: 'social',
     dir: '.rv-social',
-    owner: 'distribute/social.md',
+    owner: 'distribute/post-publicly.md',
     appliesTo: 'declared',
     detect: [dirExists('.rv-social')],
     artifacts: [

package/src/core/package-json-check.ts

@@ -68,6 +68,7 @@ export async function evaluatePackageJson(t: CheckCtx, root: string, c: RepoConf
         { name: 'contracts', why: 'shipkit repo' },
         { name: 'tui', why: 'shipkit repo' },
         { name: 'hub', why: 'shipkit repo' },
+        { name: 'mv', why: 'shipkit repo' },
     ]
     if (existsSync(join(root, '.rv-assets/kit.ts'))) required.push({ name: 'assets', why: '.rv-assets/kit.ts exists' })
     if (existsSync(join(root, '.rv-identity/brand.ts'))) required.push({ name: 'assets:identity', why: '.rv-identity/brand.ts exists' })

package/src/init-repo.ts

@@ -42,7 +42,7 @@ export async function initRepo(root: string, opts: InitOpts = {}): Promise<numbe
     let added = 0
     // canonical script NAME → shipkit command (hub runs `shipkit serve`) —
     // vocabulary owned by meta/rv-conventions/package-json.md
-    const CANONICAL = { ci: 'ci', check: 'check', contracts: 'contracts', tui: 'tui', hub: 'serve' } as const
+    const CANONICAL = { ci: 'ci', check: 'check', contracts: 'contracts', tui: 'tui', hub: 'serve', mv: 'mv' } as const
     for (const [k, cmd] of Object.entries(CANONICAL)) {
         const v = run(cmd)
         if (pkg.scripts[k] == null) { pkg.scripts[k] = v; added++ }

package/src/mv/mv-md.ts

@@ -0,0 +1,90 @@
+// shipkit mv — rename an md page the AGILE way: one command moves the .md,
+// its sibling asset dir and <name>.check.ts, then sweeps EVERY tracked text
+// file for refs (full path, docs-root-relative id, check filename). Dry by
+// default; --write applies; --commit adds one conventional commit (the
+// repo's pre-commit hook is the gate). If package.json has a `mv:after`
+// script it runs after the moves (repo-specific re-stamps). TS module moves
+// are a different concern (a TS-aware renamer owns import graphs).
+import { execSync } from 'child_process'
+import { existsSync, readFileSync, writeFileSync } from 'fs'
+import { basename, dirname, join } from 'path'
+
+export type MvIo = { print: (l: string) => void; printErr: (l: string) => void }
+export type MvOpts = { write?: boolean; commit?: boolean }
+
+const sh = (cmd: string, cwd: string): string => execSync(cmd, { cwd }).toString()
+
+export function movePage(root: string, oldRel: string, newRel: string, io: MvIo, o: MvOpts = {}): number {
+    const die = (m: string): number => { io.printErr(`FAIL: ${m}`); return 1 }
+    if (!oldRel.endsWith('.md') || !newRel.endsWith('.md')) return die('both paths must be .md (TS moves are not this tool\'s job)')
+    if (!existsSync(join(root, oldRel))) return die(`${oldRel} does not exist`)
+    if (existsSync(join(root, newRel))) return die(`${newRel} already exists`)
+    if (dirname(oldRel) !== dirname(newRel)) return die('cross-directory moves not supported yet, same dir only')
+
+    const write = o.write === true || o.commit === true
+    const oldName = basename(oldRel, '.md')
+    const newName = basename(newRel, '.md')
+    const oldBase = oldRel.slice(0, -3) // full path sans .md — the sibling dir
+    const newBase = newRel.slice(0, -3)
+    // docs-root-relative id: refs inside a wiki usually omit the top dir
+    // (`build/state`, not `wiki/build/state`) — sweep both forms
+    const tail = (p: string): string | null => { const seg = p.split('/'); return seg.length >= 3 ? seg.slice(1).join('/') : null }
+    const oldId = tail(oldBase)
+    const newId = tail(newBase)
+
+    // longest-first so `wiki/x/state.md` beats `x/state` beats bare tokens
+    const pairs: [string, string][] = [
+        [`${oldBase}.md`, `${newBase}.md`],
+        ...(oldId != null ? [[`${oldId}.md`, `${newId}.md`] as [string, string]] : []),
+        // probe file is named after its page; DIR-qualified so another
+        // page's same-named check.ts in a different dir never gets rewritten
+        [`${oldBase}/${oldName}.check.ts`, `${newBase}/${newName}.check.ts`],
+        ...(oldId != null ? [[`${oldId}/${oldName}.check.ts`, `${newId}/${newName}.check.ts`] as [string, string]] : []),
+        [`${oldBase}/`, `${newBase}/`],
+        ...(oldId != null ? [[`${oldId}/`, `${newId}/`] as [string, string]] : []),
+        [oldBase, newBase],
+        ...(oldId != null ? [[oldId, newId!] as [string, string]] : []),
+    ]
+    const bound = (t: string): RegExp =>
+        new RegExp('(?<![\\w-])' + t.replace(/[.*+?^${}()|[\]\\]/g, '\\$&') + (/[/.]$/.test(t) || t.endsWith('.ts') ? '' : '(?![\\w-])'), 'g')
+
+    const tracked = sh('git ls-files', root).split('\n').filter(Boolean)
+        .filter((f) => !/\.(png|jpe?g|gif|webp|ico|woff2?|ttf|zip|gz|lockb|lock)$/i.test(f))
+    let touched = 0
+    for (const f of tracked) {
+        const p = join(root, f)
+        if (!existsSync(p)) continue
+        const before = readFileSync(p, 'utf8')
+        let after = before
+        for (const [oldTok, newTok] of pairs) after = after.replace(bound(oldTok), newTok)
+        if (after !== before) {
+            io.print(`  ${f}`)
+            if (write) writeFileSync(p, after)
+            touched++
+        }
+    }
+    io.print(`${write ? 'renamed' : 'DRY RUN'}: ${oldBase} → ${newBase}, refs in ${touched} file(s)`)
+    if (!write) { io.print('re-run with --write (or --commit) to apply'); return 0 }
+
+    // moves AFTER the sweep (the sweep rewrote files at their old paths)
+    sh(`git mv ${JSON.stringify(oldRel)} ${JSON.stringify(newRel)}`, root)
+    if (existsSync(join(root, oldBase))) {
+        sh(`git mv ${JSON.stringify(oldBase)} ${JSON.stringify(newBase)}`, root)
+        const oldCheck = join(newBase, `${oldName}.check.ts`)
+        if (existsSync(join(root, oldCheck))) sh(`git mv ${JSON.stringify(oldCheck)} ${JSON.stringify(join(newBase, `${newName}.check.ts`))}`, root)
+    }
+
+    // repo-specific re-stamps (e.g. wiki depth frontmatter) — loud on failure
+    const pkg = existsSync(join(root, 'package.json')) ? (JSON.parse(readFileSync(join(root, 'package.json'), 'utf8')) as { scripts?: Record<string, string> }) : {}
+    if (pkg.scripts?.['mv:after'] != null) {
+        try { execSync('bun run mv:after', { cwd: root, stdio: 'inherit' }) } catch { return die('mv:after failed, fix before committing') }
+    }
+    if (o.commit === true) {
+        sh('git add -A', root)
+        try {
+            execSync(`git commit -m ${JSON.stringify(`docs: rename ${oldBase} → ${newBase}`)}`, { cwd: root, stdio: 'inherit' })
+        } catch { return die('commit failed (pre-commit gate?). The rename is applied, fix and commit yourself') }
+    }
+    io.print(`ok: ${oldBase} → ${newBase}${o.commit === true ? ' (committed)' : ''}`)
+    return 0
+}

package/src/serve/run-serve.ts

@@ -5,7 +5,7 @@
 // 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, readdirSync, statSync } from 'fs'
+import { existsSync, readdirSync, readFileSync, statSync } from 'fs'
 import { join } from 'path'
 import { fileURLToPath } from 'url'
 import { loadKit, allAssets, type ResolvedKit } from '../assets/kit-config.ts'
@@ -63,6 +63,15 @@ export async function resolveHubDeps(root: string, c: RepoConfig, io: ServeIo, o
     }
 }
 
+// the hub must KNOW when it is outdated (field bug 2026-07-22: a morning
+// process served stale code all day, picks looked broken): version read at
+// boot vs on disk per attention load; mismatch = red line telling him to
+// restart the task
+const libVersion = (): string => {
+    try { return (JSON.parse(readFileSync(fileURLToPath(new URL('../../package.json', import.meta.url)), 'utf8')) as { version?: string }).version ?? '?' } catch { return '?' }
+}
+const BOOT_VERSION = libVersion()
+
 // ── the / dashboard's data: everything red, one collector per source, each
 //    failure-isolated (a broken source reports itself, never blanks the page)
 export function attentionCollector(root: string, c: RepoConfig, kit: ResolvedKit | null): () => Promise<AttentionSection[]> {
@@ -71,6 +80,11 @@ export function attentionCollector(root: string, c: RepoConfig, kit: ResolvedKit
     }
     return async () => {
         const sections = await Promise.all([
+            guard('hub process', 'red', async () => {
+                const now = libVersion()
+                if (now === BOOT_VERSION) return []
+                return [{ text: `hub is running shipkit ${BOOT_VERSION} but ${now} is on disk (stale process, stale pages, old studio code). Restart the 🚀 shipkit task` }]
+            }),
             guard('failing checks', 'red', async () => {
                 const p = join(root, 'STATUS.md')
                 if (!existsSync(p)) return []

package/src/shipkit.ts

@@ -58,3 +58,5 @@ export { lintMd } from './wiki/lint-md.ts'
 export { serveMdGraph } from './wiki/serve-graph.ts'
 export { graphHtml } from './wiki/graph-page.ts'
 export type { MdGraph, MdNode, MdEdge } from './wiki/md-graph.ts'
+export { movePage } from './mv/mv-md.ts'
+export type { MvIo, MvOpts } from './mv/mv-md.ts'

package/src/start-repo.ts

@@ -0,0 +1,50 @@
+// `shipkit start` — ensure <root>/<name> exists and, when --include is
+// given, that CLAUDE.md carries that include line. Plain module behind
+// cmd_Start. Status lines go to STDERR — the ONLY stdout output is the
+// resolved dir, so a sourced shell alias can `cd "$(shipkit start <name>)"`
+// (the one thing a child process can't do for its parent shell).
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs'
+import { homedir } from 'os'
+import { join } from 'path'
+
+export type StartOpts = {
+    /** parent dir for repos — default ~/dev */
+    root?: string
+    /** line CLAUDE.md must start with; omitted = only ensure the dir */
+    include?: string
+    /** alternative lines that already count as wired — never double-add */
+    alsoOk?: string[]
+    /** repo names that never get the include */
+    skip?: string[]
+}
+
+const escapeRe = (s: string): string => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+
+export function startRepo(name: string, opts: StartOpts = {}): number {
+    if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(name)) {
+        console.error(`FAIL: bad repo name '${name}' — letters/digits/._- only, no leading dot, no slashes`)
+        return 2
+    }
+    const dir = join(opts.root ?? join(homedir(), 'dev'), name)
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true })
+        console.error(`ok: created ${dir}`)
+    }
+    if (opts.include == null || (opts.skip ?? []).includes(name)) {
+        if (opts.include != null) console.error(`skip: ${name} is include-exempt — CLAUDE.md untouched`)
+    } else {
+        const claudeMd = join(dir, 'CLAUDE.md')
+        if (!existsSync(claudeMd)) {
+            writeFileSync(claudeMd, `${opts.include}\n`)
+            console.error('ok: CLAUDE.md created with the include')
+        } else {
+            const wiredRe = new RegExp([opts.include, ...(opts.alsoOk ?? [])].map((l) => `^${escapeRe(l)}$`).join('|'), 'm')
+            if (!wiredRe.test(readFileSync(claudeMd, 'utf8'))) {
+                writeFileSync(claudeMd, `${opts.include}\n\n${readFileSync(claudeMd, 'utf8')}`)
+                console.error('ok: include prepended to CLAUDE.md')
+            }
+        }
+    }
+    console.log(dir)
+    return 0
+}

package/src/tui/run-tui.ts

@@ -13,7 +13,7 @@ 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
+    // playbook (build/mobx-mechanics): 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' })

package/src/tui/tui-store.ts

@@ -1,4 +1,4 @@
-// TUI state — MobX per the house playbook (build/state + build/mobx):
+// TUI state — MobX per the house playbook (build/app-state-tree + build/mobx-mechanics):
 // `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(),