rvlib-shipkit 0.20.0 → 0.20.1

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.20.1
+
+- **Fix: `start --skip` means shipkit never touches the repo.** 0.20.0's adoption block ran after the skip branch, so `ship <job-repo>` would have scaffolded `repo.config.ts` into a repo on the never-wire list (caught by review in a sandbox). The whole wiring block sits behind the skip list now, frozen by test.
+- **Fix: a failed adoption never breaks the cd contract.** A broken `package.json` in the target repo downgrades wiring to a WARN on stderr, and `start` still prints the dir. `initRepo` gained a `print` sink, so `start` reports on stderr without touching the console global.
+- **Fix: arming only ever happens at the work-tree ROOT.** `armHooks` in a subdirectory used to set the PARENT repo's `core.hooksPath` onto a dir that does not exist there, disarming the parent's gates. It compares `git rev-parse --show-toplevel` now and declines with a named state.
+- **Fix: arming never rewrites existing hook bodies.** A repo with `core.hooksPath=hooks` and both hook files present is `current`, whatever its bodies say: arming means making dark gates live, not normalizing another repo's `--bin` choice. `hooks install` with no `--bin` now defaults to the same resolution as arming (the repo's own node_modules copy first), one invocation policy instead of two.
+- A failure to arm prints as a WARN, never as a skip, and a successful arm says to commit the `hooks/` dir.
+
 ## 0.20.0
 
 - **Commit gates arm themselves.** An interactive `shipkit ci` run now installs the git hooks whenever the repo has a `repo.config.ts` and `core.hooksPath` is unset or already `hooks`: hook bodies written, leak-guard keyword starter seeded, `core.hooksPath` set, idempotent. The field case: a whole drill session committed with dark gates because init was treated as "create repo.config.ts". A FOREIGN `core.hooksPath` (husky and friends) is respected and named, never taken. Hook bodies prefer the repo's own `node_modules/rvlib-shipkit` copy over the cli that happens to be running, so a repo keeps its pinned version. Scoped to the interactive gate on purpose: CI verify mode, `bump` and `release` gate runs never mutate the tree they are about to ship, and arming reports on its own line, never as a fixer rewrite.

package/package.json

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

@@ -1,7 +1,7 @@
 // shipkit hooks, install the git hooks, run their gates, or list what
 // blocks a commit. Thin clipanion surface; logic in hooks/run-hooks.ts.
 import { Command, Option } from 'clipanion'
-import { installHooks, listGates, runCommitMsg, runPreCommit, type GateOutcome } from '../hooks/run-hooks.ts'
+import { hookBinInvocation, installHooks, listGates, runCommitMsg, runPreCommit, type GateOutcome } from '../hooks/run-hooks.ts'
 import { loadRepoConfig } from '../repo-config.ts'
 
 const report = (out: GateOutcome[], write: (s: string) => void): number => {
@@ -17,11 +17,11 @@ export class HooksInstallCommand extends Command {
         examples: [['wire the hooks', 'shipkit hooks install']],
     })
 
-    bin = Option.String('--bin', 'bunx rvlib-shipkit', { description: 'how the hook body invokes shipkit (in-repo consumers pass `bun <path to cli.ts>`)' })
+    bin = Option.String('--bin', { description: 'how the hook body invokes shipkit (default: the repo\'s own node_modules copy, else the running cli — in-repo consumers pass `bun <path to cli.ts>`)' })
 
     async execute(): Promise<number> {
         const config = await loadRepoConfig(process.cwd()).catch(() => null)
-        const r = installHooks(process.cwd(), this.bin, config?.hooks?.keywordFile)
+        const r = installHooks(process.cwd(), this.bin ?? hookBinInvocation(process.cwd()), config?.hooks?.keywordFile)
         for (const w of r.written) this.context.stdout.write(`ok: wrote ${w}\n`)
         if (r.written.length === 0) this.context.stdout.write('ok: hook bodies already current\n')
         this.context.stdout.write(`${r.note.startsWith('WARN') ? r.note : `ok: ${r.note}`}\n`)

package/src/cli/cmd_Start.ts

@@ -21,7 +21,7 @@ export class StartCommand extends Command {
     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 means 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' })
+    skip = Option.Array('--skip', { description: 'repo names shipkit never touches: no CLAUDE.md include, no wiring' })
 
     async execute(): Promise<number> {
         return startRepo(this.name, { root: this.root, include: this.include, alsoOk: this.alsoOk, skip: this.skip })

package/src/core/run-fixers.ts

@@ -131,8 +131,9 @@ export async function runFixPass(root: string, config: RepoConfig, o: FixPassOpt
     // its own reported concern, never counted as a fixer rewrite.
     if (o.armHooks === true && !verify) {
         const armed = armHooks(root, config)
-        if (armed.state === 'armed') o.print(`ok: hooks armed (${armed.detail})`)
-        else if (armed.state === 'foreign') o.print(`skip: hooks (${armed.detail})`)
+        if (armed.state === 'armed') o.print(`ok: hooks armed (${armed.detail}), commit the hooks/ dir`)
+        else if (armed.state === 'foreign' || armed.state === 'not-root') o.print(`skip: hooks (${armed.detail})`)
+        else if (armed.state === 'failed') o.print(`WARN hooks could not arm: ${armed.detail}`)
     }
     const { slots, unfilled, disabled } = resolveFixers(root, config)
     for (const u of unfilled) o.print(`skip: ${u.id} (${u.reason})`)

package/src/hooks/run-hooks.ts

@@ -3,7 +3,7 @@
 // hand-rolled hooks are invisible to `shipkit check`: a repo reports green
 // while its next commit is already doomed, and nothing can enumerate what
 // the hooks enforce. `shipkit hooks list` answers that without reading shell.
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs'
+import { existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from 'fs'
 import { dirname, join } from 'path'
 import { fileURLToPath } from 'url'
 import { commitMessageOffenses } from './commit-message.ts'
@@ -47,20 +47,30 @@ export function hookBinInvocation(root: string): string {
     return running.startsWith(prefix) ? `bun ${running.slice(prefix.length)}` : `bun ${running}`
 }
 
-export type ArmHooksResult = { state: 'armed' | 'current' | 'foreign' | 'no-git'; detail: string }
+export type ArmHooksResult = { state: 'armed' | 'current' | 'foreign' | 'no-git' | 'not-root' | 'failed'; detail: string }
 
 /** self-arming: a repo.config with dark commit gates is the half-wired state
- *  that let a whole drill session commit ungated (2026-08-04). Idempotent,
- *  and a FOREIGN core.hooksPath is respected and named, never taken. */
+ *  that let a whole drill session commit ungated (2026-08-04). Arming means
+ *  making DARK gates live: hooks that already exist under an armed hooksPath
+ *  are never rewritten (the repo's own --bin choice stands). A FOREIGN
+ *  core.hooksPath is respected and named, and only the work-tree ROOT may
+ *  arm (a subdir would set the parent's hooksPath onto a dir that does not
+ *  exist there, disarming the parent's gates). */
 export function armHooks(root: string, config: RepoConfig): ArmHooksResult {
-    const inRepo = Bun.spawnSync(['git', 'rev-parse', '--is-inside-work-tree'], { cwd: root })
-    if (inRepo.exitCode !== 0) return { state: 'no-git', detail: 'not a git repo' }
+    const top = Bun.spawnSync(['git', 'rev-parse', '--show-toplevel'], { cwd: root })
+    if (top.exitCode !== 0) return { state: 'no-git', detail: 'not a git repo' }
+    const topDir = top.stdout.toString().trim()
+    try {
+        if (realpathSync(topDir) !== realpathSync(root)) return { state: 'not-root', detail: `work tree root is ${topDir}, not here` }
+    } catch {
+        return { state: 'no-git', detail: 'work tree root unresolvable' }
+    }
     const p = Bun.spawnSync(['git', 'config', 'core.hooksPath'], { cwd: root })
     const current = p.exitCode === 0 ? p.stdout.toString().trim() : ''
     if (current !== '' && current !== HOOK_DIR) return { state: 'foreign', detail: `core.hooksPath=${current}, foreign, left alone` }
+    if (current === HOOK_DIR && HOOKS.every((h) => existsSync(join(root, HOOK_DIR, h)))) return { state: 'current', detail: 'hooks already armed' }
     const r = installHooks(root, hookBinInvocation(root), config.hooks?.keywordFile)
-    if (r.note.startsWith('WARN')) return { state: 'foreign', detail: r.note }
-    if (r.written.length === 0 && current === HOOK_DIR) return { state: 'current', detail: 'hooks already armed' }
+    if (r.note.startsWith('WARN')) return { state: 'failed', detail: r.note }
     return { state: 'armed', detail: `wrote ${r.written.join(', ') || 'nothing'}, ${r.note}` }
 }
 

package/src/init-repo.ts

@@ -35,20 +35,24 @@ export default defineRepo({
 export type InitOpts = {
     /** in-repo-source consumers: path to shipkit's cli.ts — scripts become `bun <path> <cmd>` instead of `shipkit <cmd>` */
     bin?: string
+    /** report sink, default console.log (startRepo passes console.error: its
+     *  stdout contract is the resolved dir alone) */
+    print?: (line: string) => void
 }
 
 export async function initRepo(root: string, opts: InitOpts = {}): Promise<number> {
+    const p = opts.print ?? console.log
     const configPath = join(root, 'repo.config.ts')
     if (existsSync(configPath)) {
-        console.log(`skip: repo.config.ts already exists`)
+        p(`skip: repo.config.ts already exists`)
         // adoption path: re-running init on an existing repo still converges
         // its .gitignore policy block (same fixer as `check --fix SK004`),
         // with the repo's own contributed lines honored
         const cfg = await loadRepoConfig(root)
         const g = await gitignorePolicy.fix!({ root, config: cfg })
-        console.log(`ok: .gitignore policy block ${g.changed ? 'written' : 'already current'}`)
+        p(`ok: .gitignore policy block ${g.changed ? 'written' : 'already current'}`)
         const mh = reportToMotherhome(root, cfg)
-        if (mh.note != null) console.log(mh.note)
+        if (mh.note != null) p(mh.note)
         return 0
     }
     const pkgPath = join(root, 'package.json')
@@ -57,7 +61,7 @@ export async function initRepo(root: string, opts: InitOpts = {}): Promise<numbe
     const pkg = JSON.parse(pkgRaw) as { name?: string; scripts?: Record<string, string> }
     const name = pkg.name ?? 'my-repo'
     writeFileSync(configPath, CONFIG_TEMPLATE(name))
-    console.log('ok: repo.config.ts created')
+    p('ok: repo.config.ts created')
     const indent = pkgRaw.match(/^(\s+)"/m)?.[1] ?? '  '
     pkg.scripts ??= {}
     let added = 0
@@ -69,32 +73,32 @@ export async function initRepo(root: string, opts: InitOpts = {}): Promise<numbe
     for (const [k, v] of Object.entries(canonicalBodies({ bin: opts.bin }))) {
         if (k === 'test' && !hasTestFiles(root)) continue
         if (pkg.scripts[k] == null) { pkg.scripts[k] = v; added++ }
-        else if (pkg.scripts[k] !== v) console.log(`skip: package.json script '${k}' exists — left untouched`)
+        else if (pkg.scripts[k] !== v) p(`skip: package.json script '${k}' exists — left untouched`)
     }
     if (added > 0) {
         writeFileSync(pkgPath, JSON.stringify(pkg, null, indent) + '\n')
-        console.log(`ok: ${added} package.json script(s) added`)
+        p(`ok: ${added} package.json script(s) added`)
     }
     // the .gitignore policy block (contract git policy) — same fixer as
     // `shipkit check --fix SK004`, one code path
     const g = await gitignorePolicy.fix!({ root, config: defineRepo({ name }) })
-    console.log(`ok: .gitignore policy block ${g.changed ? 'written' : 'already current'}`)
+    p(`ok: .gitignore policy block ${g.changed ? 'written' : 'already current'}`)
     // show what the gate actually is — a thin floor must be seen at init
     // time, not discovered after a bad commit slipped through
     const floor = resolveFloor(defineRepo({ name }), root)
-    for (const t of floor.tasks) console.log(`ok: floor ${t.id} ← ${floor.sources[t.id] ?? 'unknown'}`)
-    for (const u of floor.unfilled) console.log(`skip: ${u.id} (${u.reason})`)
+    for (const t of floor.tasks) p(`ok: floor ${t.id} ← ${floor.sources[t.id] ?? 'unknown'}`)
+    for (const u of floor.unfilled) p(`skip: ${u.id} (${u.reason})`)
     // every verb comes from the `shipkit` bin — dead on arrival unless the
     // package is actually installed (bunx runs without adding the dep)
     if (opts.bin == null) {
         try {
             Bun.resolveSync('rvlib-shipkit', root)
         } catch {
-            console.log('WARN rvlib-shipkit not installed here — the scripts above call its bin and will exit 127')
-            console.log('      fix: bun add -d rvlib-shipkit')
+            p('WARN rvlib-shipkit not installed here — the scripts above call its bin and will exit 127')
+            p('      fix: bun add -d rvlib-shipkit')
         }
     }
-    console.log('next: fill venues/social in repo.config.ts, then `shipkit ci`')
-    console.log('next: identity+assets — mint .rv-identity/brand.ts + .rv-assets/kit.ts, `shipkit assets identity` (the identity contract expects public/ favicon+og+logo)')
+    p('next: fill venues/social in repo.config.ts, then `shipkit ci`')
+    p('next: identity+assets — mint .rv-identity/brand.ts + .rv-assets/kit.ts, `shipkit assets identity` (the identity contract expects public/ favicon+og+logo)')
     return 0
 }

package/src/start-repo.ts

@@ -60,13 +60,13 @@ export async function startRepo(name: string, opts: StartOpts = {}): Promise<num
     // (package.json) gets wired on the spot, so a pre-existing repo goes
     // 0 → shipkit'd with the one command. init itself stays cwd-only, like
     // git init. A brand-new empty dir cannot be wired yet, say what is next.
-    if (!existsSync(join(dir, 'repo.config.ts'))) {
+    // --skip means shipkit NEVER TOUCHES that repo (his job repo lives on
+    // this list), not just no CLAUDE.md. And the cd contract survives a
+    // failed adoption: the dir always prints, wiring trouble is a WARN.
+    if (!(opts.skip ?? []).includes(name) && !existsSync(join(dir, 'repo.config.ts'))) {
         if (existsSync(join(dir, 'package.json'))) {
-            // initRepo reports on stdout, but start's stdout contract is THE
-            // DIR ONLY (a sourced alias cd's to it) — reroute to stderr here
-            const realLog = console.log
-            console.log = ((...a: unknown[]) => console.error(...a)) as typeof console.log
-            try { await initRepo(dir, {}) } finally { console.log = realLog }
+            try { await initRepo(dir, { print: (l) => console.error(l) }) }
+            catch (e) { console.error(`WARN could not wire ${dir}: ${e instanceof Error ? e.message : String(e)} — the dir is still yours`) }
         } else {
             console.error(`next: scaffold the app in ${dir} (package.json), then \`shipkit init\` inside it — the commit gates arm on the first ci run`)
         }