rvlib-shipkit 0.8.0 → 0.9.0

package/CHANGELOG.md

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

package/package.json

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

@@ -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,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
+}