rvlib-shipkit 0.9.0 → 0.10.0

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # 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:

package/package.json

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

@@ -12,14 +12,14 @@ export class StartCommand extends Command {
         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'"],
+            ['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.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' })
+    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> {

package/src/start-repo.ts

@@ -1,8 +1,9 @@
-// `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).
+// `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'
@@ -10,16 +11,14 @@ 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 */
+    /** 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 the include */
+    /** repo names that never get includes */
     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`)
@@ -30,18 +29,29 @@ export function startRepo(name: string, opts: StartOpts = {}): number {
         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`)
+    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, `${opts.include}\n`)
-            console.error('ok: CLAUDE.md created with the include')
+            writeFileSync(claudeMd, `${want.join('\n')}\n`)
+            console.error(`ok: CLAUDE.md created with ${want.length} include line(s)`)
         } 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')
+            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`)
             }
         }
     }

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
         }