rvlib-shipkit 0.8.0 → 0.10.0

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # Changelog
 
+## 0.10.0 — 2026-07-22
+
+New:
+
+- `shipkit start`: `--include` is now repeatable — every given line is
+  ensured in CLAUDE.md, in order, inserted after any leading include lines
+  already present (never double-added; `--also-ok` satisfies the first
+  include).
+
+Fixed:
+
+- md graph scanner: a backticked/arrow token carrying the scan root's own
+  dir name (`agent/architecture.md` while scanning `agent/`) now resolves —
+  routing tables written repo-root-relative finally produce edges.
+
+## 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:

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "rvlib-shipkit",
-    "version": "0.8.0",
+    "version": "0.10.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/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 includes', "shipkit start pong --include '@~/wiki/index.md' --include '@./agent/index.md'"],
+        ],
+    })
+
+    name = Option.String()
+    root = Option.String('--root', { description: 'parent dir for repos (default ~/dev)' })
+    include = Option.Array('--include', { description: 'line CLAUDE.md must carry, repeatable, order kept; omitted = only ensure the dir' })
+    alsoOk = Option.Array('--also-ok', { description: 'alternative lines satisfying the first --include — 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

@@ -12,6 +12,7 @@ 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'
 
@@ -45,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/start-repo.ts

@@ -0,0 +1,60 @@
+// `shipkit start` — ensure <root>/<name> exists and, when --include lines
+// are given, that CLAUDE.md carries them (in order, at the top). 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
+    /** lines CLAUDE.md must carry, in order; omitted = only ensure the dir */
+    include?: string[]
+    /** alternative lines that satisfy the FIRST include — never double-add */
+    alsoOk?: string[]
+    /** repo names that never get includes */
+    skip?: string[]
+}
+
+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}`)
+    }
+    const want = opts.include ?? []
+    if (want.length === 0 || (opts.skip ?? []).includes(name)) {
+        if (want.length > 0) console.error(`skip: ${name} is include-exempt — CLAUDE.md untouched`)
+    } else {
+        const claudeMd = join(dir, 'CLAUDE.md')
+        if (!existsSync(claudeMd)) {
+            writeFileSync(claudeMd, `${want.join('\n')}\n`)
+            console.error(`ok: CLAUDE.md created with ${want.length} include line(s)`)
+        } else {
+            const cur = readFileSync(claudeMd, 'utf8')
+            const lineSet = new Set(cur.split('\n'))
+            const alt = opts.alsoOk ?? []
+            const satisfied = (w: string): boolean => lineSet.has(w) || (w === want[0] && alt.some((a) => lineSet.has(a)))
+            const missing = want.filter((w) => !satisfied(w))
+            if (missing.length > 0) {
+                // insert after any leading include/alt lines so order survives
+                const lines = cur.split('\n')
+                const known = new Set([...want, ...alt])
+                let at = 0
+                while (at < lines.length && known.has(lines[at]!)) at++
+                lines.splice(at, 0, ...missing)
+                writeFileSync(claudeMd, lines.join('\n'))
+                console.error(`ok: ${missing.length} missing include line(s) inserted into CLAUDE.md`)
+            }
+        }
+    }
+    console.log(dir)
+    return 0
+}

package/src/wiki/scan-md.ts

@@ -8,7 +8,7 @@
 // unreachable files stay in the graph with no depth (lint-md.ts turns those,
 // plus dangling refs, into failures — the graph itself is a viewer).
 import { existsSync, readdirSync, readFileSync, statSync } from 'fs'
-import { dirname, join, relative, resolve } from 'path'
+import { basename, dirname, join, relative, resolve } from 'path'
 import type { MdEdge, MdGraph, MdNode } from 'rvlib-shipkit/src/wiki/md-graph.ts'
 
 export type ScanMdConfig = {
@@ -43,8 +43,13 @@ export function scanMd(cfg: ScanMdConfig): MdScan {
     files.sort()
     const inGraph = new Set(files)
 
+    // writers inside a scanned dir often name paths from the REPO root
+    // ("agent/architecture.md" while scanning agent/) — accept that form too
+    const rootBase = `${basename(cfg.root)}/`
     const resolveRef = (fromRel: string, token: string): string | null => {
-        for (const cand of [resolve(join(cfg.root, dirname(fromRel)), token), resolve(cfg.root, token)]) {
+        const cands = [resolve(join(cfg.root, dirname(fromRel)), token), resolve(cfg.root, token)]
+        if (token.startsWith(rootBase)) cands.push(resolve(cfg.root, token.slice(rootBase.length)))
+        for (const cand of cands) {
             const rel = relative(cfg.root, cand)
             if (!rel.startsWith('..') && inGraph.has(rel)) return rel
         }