rvlib-shipkit 0.27.0 → 0.28.0

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.28.0
+
+- **The `.claude/` policy files are OPT-IN.** 0.27.0 wrote a pre-approved shell allowlist (`curl *`, `git push*`, `./deploy.sh`) and an attribution silencer into every started repo, gitignored and therefore invisible to review. Those are decisions about what an agent can do in a repo and what its git history says, so they now require the caller to declare a house (`claudePolicy`, which `start` enables when it seeds CLAUDE.md include lines), and the grant prints once by name when it lands. The verify skill still lands for everyone.
+- **The scaffolded verify skill points at `shipkit ci`.** It shipped a gate of `bunx tsc && bun test && bun run build`: scripts a started repo does not have, contradicting the coding page written beside it.
+- **The `.gitignore` baseline is appended line by line, by ONE writer.** It was written only when the file was absent, so a dir arriving with any `.gitignore` at all (a downloaded template, one stray line) skipped it: the install then wrote `node_modules/` and the first commit refused over thousands of staged files. A `.env` in a started dir is now ignored rather than blocking the commit outright, so the secret stays out AND the work gets backed up.
+- **A scaffold write error no longer aborts the start.** It is wrapped like every other step, warns, and the chain still commits and pushes.
+- **Smaller repairs**: an unparseable `package.json` warns instead of silently skipping the scripts · files the scaffold SKIPPED are reported, because on a half-built dir the skipped one is the interesting one · delivered templates get their "copy me somewhere" comment blocks stripped, true on the page they twin and nonsense in the repo they land in · the hub port in `tasks.json` derives from the package name, matching what `init` writes into `repo.config.ts`.
+
 ## 0.27.0
 
 - **`shipkit start` writes the whole day-one shape, not just a repo.** A started dir was a repo you still had to furnish: no tsconfig, no editor tasks, no agent wiki behind CLAUDE.md's own include, no verify skill, no attribution silencer, and two baseline scripts the rules then warned about. One scaffold pass now writes all of it (`src/scaffold/project-scaffold.ts`), installs the toolchain, and the result passes its OWN `shipkit ci` with nothing left but the identity assets a human has to choose. Every file is CREATE-ONLY, so running it over a half-built dir never destroys work.

package/package.json

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

@@ -9,7 +9,7 @@ export class StartCommand extends Command {
 
     static override usage = Command.Usage({
         category: 'Setup',
-        description: 'create (or enter) ~/dev/<name> from ANY cwd, READY to work in: ensures the dir, seeds CLAUDE.md include lines, scaffolds a minimal package.json + src/index.ts + the rvlib-shipkit dev dep on any dir with no commit history (loose files ride in the first commit), wires shipkit (repo.config.ts via init), then runs the whole bootstrap chain: git init, first commit, PRIVATE github repo, push. Only a repo with real history is left as it is. Prints the dir on stdout so a shell alias can cd there. cwd-only sibling: `shipkit init`',
+        description: 'create (or enter) ~/dev/<name> from ANY cwd, READY to work in. On any dir with no commit history it writes the day-one shape (package.json + src/index.ts + lint/fmt/typecheck, tsconfig, .vscode tasks + settings, the verify skill, an agent/ wiki, .rv-reflections), installs the toolchain, wires shipkit (repo.config.ts via init), and runs the whole bootstrap chain: git init, first commit, PRIVATE github repo, push. Loose files ride in that first commit, and only a repo with real history is left as it is. Writes are create-only for files, additive for package.json scripts and .gitignore. Seeding CLAUDE.md include lines also opts the repo into the .claude/ policy files (a pre-approved shell allowlist + the attribution silencer). Prints the dir on stdout so a shell alias can cd there. cwd-only sibling: `shipkit init`',
         examples: [
             ['create or enter ~/dev/pong: dir, package.json, shipkit wiring, git, first commit, private github repo, push', 'shipkit start pong'],
             ['seed CLAUDE.md includes', "shipkit start pong --include '@~/wiki/index.md' --include '@./agent/index.md'"],

package/src/git-bootstrap.ts

@@ -14,7 +14,7 @@
 // identity), it never touches a history that already has commits, and every
 // unverifiable path (no gh, not authenticated, offline) is a WARN that
 // leaves the local repo wired and names the next move.
-import { existsSync, realpathSync } from 'fs'
+import { existsSync, readFileSync, realpathSync, writeFileSync } from 'fs'
 import { tmpdir } from 'os'
 import { basename, join } from 'path'
 import { spawnWithTimeout } from './core/spawn-timeout.ts'
@@ -261,13 +261,15 @@ async function firstCommit(root: string, git: Run, p: (line: string) => void): P
         p('skip: first commit — nothing in this dir yet')
         return false
     }
-    // a repo with no .gitignore at all gets the baseline: the very first
-    // commit is the one nobody reviews, and it is the one that ships a .env
-    // to github. A repo that HAS one keeps its own answer, whatever it says.
-    // rule SK004 stays the only writer of its managed block, with the repo's
-    // real config: rewriting it from a synthetic one here DELETED the lines
-    // repo.config.ts contributed, seconds before staging what they covered
-    if (!existsSync(join(root, '.gitignore'))) await Bun.write(join(root, '.gitignore'), `${IGNORE_BASELINE.join('\n')}\n`)
+    // the baseline lands before the very first commit, the one nobody
+    // reviews and the one that ships a .env to github. Every MISSING line is
+    // appended, because a repo that arrived with a one-line .gitignore is
+    // exactly as exposed as one with none. Repo-owned lines are never
+    // touched, and rule SK004 stays the only writer of its managed block,
+    // with the repo's real config: rewriting it from a synthetic one here
+    // DELETED the lines repo.config.ts contributed, seconds before staging
+    // what they covered
+    ensureIgnoreBaseline(root)
     const status = await git(['status', '--porcelain', '-uall'])
     if (status.code !== 0) {
         p(`WARN no first commit: ${firstGhLine(status.out)}`)
@@ -300,6 +302,19 @@ async function firstCommit(root: string, git: Run, p: (line: string) => void): P
     return true
 }
 
+/** append whichever baseline lines this repo's .gitignore does not already
+ *  carry. ONE writer of this fact, called by the first commit and by the
+ *  start scaffold (which runs before the dep install, so node_modules can
+ *  never reach the staging area) */
+export function ensureIgnoreBaseline(root: string): void {
+    const path = join(root, '.gitignore')
+    const cur = existsSync(path) ? readFileSync(path, 'utf8') : ''
+    const have = new Set(cur.split('\n').map((l) => l.trim()))
+    const missing = IGNORE_BASELINE.filter((l) => !have.has(l))
+    if (missing.length === 0) return
+    writeFileSync(path, `${cur}${cur === '' || cur.endsWith('\n') ? '' : '\n'}${missing.join('\n')}\n`)
+}
+
 /** never in a first commit, wherever it sits in the tree. `.env.example` and
  *  friends are documentation and belong in the repo */
 function isRisky(f: string): boolean {

package/src/scaffold/files/tsconfig.json

@@ -38,5 +38,11 @@
       "incremental": true,
       "tsBuildInfoFile": "node_modules/.cache/tsbuildinfo.json"
    },
-   "include": ["src", "scripts", "*.ts"]
+   // NO root `*.ts` glob: it picks up a config file like repo.config.ts,
+   // and a dependency imported from there whose package points at raw .ts
+   // (rvlib-shipkit does) gets walked and typechecked in full, since
+   // skipLibCheck covers .d.ts only. The repo then fails on code its owner
+   // cannot edit. List a root file BY NAME when it earns checking, the way
+   // a vite repo lists vite.config.ts
+   "include": ["src", "scripts"]
 }

package/src/scaffold/files/verify-skill.md

@@ -16,10 +16,11 @@ description: Prove a change in THIS project actually works — drive the real fl
 - Verify as the end user would: drive the real flow, observe the real signal.
 
 ## This project
-- Dev server: `bun run dev` → http://localhost:<PORT> (check it's not already
-  running first: `curl -s localhost:<PORT> >/dev/null && echo up`)
-- Full gate: `bunx tsc --noEmit && bun test && bun run build`
-- Live URL after deploy: https://<project>.pages.dev (curl 200 + drive the flow)
+- Full gate: `shipkit ci` — THE command, never the linter, the typechecker
+  and the tests one at a time.
+- TODO, fill these in once the stack exists: the dev server command and its
+  port (check it is not already running: `curl -s localhost:PORT >/dev/null
+  && echo up`), and the live URL after deploy (curl 200 + drive the flow).
 
 ## Browser verification (only when a browser is truly needed)
 Playwright with explicit `executablePath`, `deviceScaleFactor: 2`, localStorage

package/src/scaffold/project-scaffold.ts

@@ -3,8 +3,11 @@
 // an agent lands on a wiki that routes it, and `shipkit ci` is green with no
 // warning a machine could have cleared.
 //
-// Every file is CREATE-ONLY: a path that exists is left exactly as it is, so
-// the scaffold can run over a half-built dir without ever destroying work.
+// Writes are CREATE-ONLY for files (a path that exists is left exactly as it
+// is) and ADDITIVE for package.json scripts and .gitignore (a free key or a
+// missing line is filled, an existing one is never touched), so the scaffold
+// can run over a half-built dir without ever destroying work. Note that the
+// package.json rewrite reformats the file it edits.
 // Templates live beside this file in files/ and ship in the npm tarball, so
 // none of them may name a machine-local tool or a private path.
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs'
@@ -20,6 +23,12 @@ export type ScaffoldOpts = {
     print?: (line: string) => void
     /** the changelog's first dated entry — injected so callers stay testable */
     today?: string
+    /** write the .claude/ POLICY files: a pre-approved permission list and an
+     *  attribution silencer. Both are decisions about what agents may do in
+     *  someone's repo and what its git history says, so they are opt-in: only
+     *  a caller that declares a house (start seeds include lines) turns them
+     *  on, and the grant is printed the one time it lands */
+    claudePolicy?: boolean
 }
 
 /** every dep the house toolchain needs for the scripts below to run */
@@ -38,10 +47,47 @@ const SCRIPTS: Record<string, string> = {
  *  fixer never rewrites them */
 const IGNORE_EXTRA = ['backups/', '.claude/settings.local.json']
 
+/** a line telling a READER to copy this file somewhere. True in the wiki page
+ *  the template is a twin of, nonsense in the repo it just landed in */
+const COPY_INSTRUCTION = /copy (?:as-is|to|this)|merge into|^\s*<!-- Template:/i
+
 const template = (file: string, vars: Record<string, string>): string => {
     let out = readFileSync(join(FILES, file), 'utf8')
     for (const [k, v] of Object.entries(vars)) out = out.replaceAll(`{{${k}}}`, v)
-    return out
+    return stripCopyInstructions(out)
+}
+
+/** drop whole COMMENT BLOCKS that address a copier, never a structural line:
+ *  a template's own "copy me somewhere" line is true on the wiki page it
+ *  twins and nonsense in the repo it just landed in. Comments explaining the
+ *  CONTENT are the point of these files and stay */
+export function stripCopyInstructions(body: string): string {
+    const lines = body.split('\n')
+    const drop = new Set<number>()
+    const blockSpeaksToACopier = (from: number, to: number): boolean => COPY_INSTRUCTION.test(lines.slice(from, to + 1).join('\n'))
+    for (let i = 0; i < lines.length; i++) {
+        if (drop.has(i)) continue
+        const line = lines[i]!
+        // an html comment block, possibly spanning lines
+        if (/^\s*<!--/.test(line)) {
+            let end = i
+            while (end < lines.length && !/-->/.test(lines[end]!)) end++
+            if (end < lines.length && blockSpeaksToACopier(i, end)) for (let k = i; k <= end; k++) drop.add(k)
+            i = end
+            continue
+        }
+        // a run of consecutive // lines is one block
+        if (/^\s*\/\//.test(line)) {
+            let end = i
+            while (end + 1 < lines.length && /^\s*\/\//.test(lines[end + 1]!)) end++
+            if (blockSpeaksToACopier(i, end)) for (let k = i; k <= end; k++) drop.add(k)
+            i = end
+        }
+    }
+    if (drop.size === 0) return body
+    const kept = lines.filter((_, i) => !drop.has(i))
+    while (kept.length > 0 && kept[0]!.trim() === '') kept.shift()
+    return kept.join('\n')
 }
 
 /** write only when the path is free. Returns whether it wrote */
@@ -55,29 +101,35 @@ function put(root: string, rel: string, body: string): boolean {
 
 export function scaffoldProject(root: string, opts: ScaffoldOpts): string[] {
     const p = opts.print ?? console.log
+    // the hub resolves its port from the CONFIG name, which init takes from
+    // package.json — a dir whose folder name differs would otherwise get a
+    // tasks.json advertising a port nothing listens on
+    const configName = packageName(root) ?? opts.name
     const vars = {
         NAME: opts.name,
-        PORT: String(defaultHubPort(opts.name)),
+        PORT: String(defaultHubPort(configName)),
         DATE: opts.today ?? new Date().toISOString().slice(0, 10),
     }
     const written: string[] = []
-    const write = (rel: string, body: string): void => { if (put(root, rel, body)) written.push(rel) }
+    const skipped: string[] = []
+    const write = (rel: string, body: string): void => { (put(root, rel, body) ? written : skipped).push(rel) }
 
     write('src/index.ts', 'export {}\n')
-    // the reference says to adjust include to the repo's own dirs, and a
-    // fresh repo has exactly one. Its root `*.ts` glob must NOT ship: that
-    // glob picks up repo.config.ts, whose `rvlib-shipkit` import is raw .ts,
-    // so tsc walks into the dependency and typechecks the whole library
-    // (skipLibCheck covers .d.ts only). Add a root file back by name, the
-    // way a vite repo lists vite.config.ts
-    write('tsconfig.json', template('tsconfig.json', vars).replace(/"include":.*$/m, '"include": ["src"]'))
+    write('tsconfig.json', template('tsconfig.json', vars))
     write('.vscode/settings.json', template('vscode-settings.json', vars))
     write('.vscode/tasks.json', template('vscode-tasks.json', vars))
-    // the harness must never write an assistant trailer into this repo's
-    // history, and the setting only counts from the FIRST commit on
-    write('.claude/settings.json', template('claude-settings.json', vars))
-    write('.claude/settings.local.json', template('claude-settings-local.json', vars))
     write('.claude/skills/verify/SKILL.md', template('verify-skill.md', vars))
+    // a permission grant and a git-history policy are decisions about someone
+    // else's repo, so they land only for a caller that declared a house, and
+    // the grant is named out loud the one time it is written
+    if (opts.claudePolicy === true) {
+        write('.claude/settings.json', template('claude-settings.json', vars))
+        write('.claude/settings.local.json', template('claude-settings-local.json', vars))
+        if (written.includes('.claude/settings.local.json')) p(`ok: .claude/ policy written — agents are pre-approved for ${grantSummary()} in this repo, and the harness writes no attribution trailer`)
+    }
+    // the project's own docs wiki. A repo whose CLAUDE.md routes at
+    // agent/index.md (rule SK003) needs the file to exist, and a repo with no
+    // CLAUDE.md at all still gets a place for its docs to live
     write('agent/index.md', template('agent-index.md', vars))
     write('agent/coding.md', template('agent-coding.md', vars))
     write('agent/changelog.md', template('agent-changelog.md', vars))
@@ -85,13 +137,28 @@ export function scaffoldProject(root: string, opts: ScaffoldOpts): string[] {
     // friction with the toolchain finds the place to write it down
     write('.rv-reflections/README.md', REFLECTIONS_README)
 
-    addScripts(root, written)
+    addScripts(root, written, p)
     addIgnoreLines(root, written)
 
     if (written.length > 0) p(`ok: scaffolded ${written.length} file(s): ${written.slice(0, 6).join(', ')}${written.length > 6 ? `, +${written.length - 6} more` : ''}`)
+    // the skips are the interesting half on a half-built dir: a pre-existing
+    // .claude/settings.json means no attribution silencer, and that one only
+    // counts from the first commit on
+    if (skipped.length > 0) p(`skip: ${skipped.length} file(s) already present, left untouched: ${skipped.join(', ')}`)
     return written
 }
 
+/** what the pre-approved permission list actually allows, in one phrase */
+function grantSummary(): string {
+    try {
+        const s = JSON.parse(readFileSync(join(FILES, 'claude-settings-local.json'), 'utf8')) as { permissions?: { allow?: string[] } }
+        const allow = s.permissions?.allow ?? []
+        return `${allow.length} shell patterns incl. ${allow.filter((a) => /curl|push|deploy/.test(a)).join(', ') || 'none network-facing'}`
+    } catch {
+        return 'a shell allowlist'
+    }
+}
+
 const REFLECTIONS_README = `# .rv-reflections
 
 One file per friction with the shared toolchain: \`YYYYMMDD-<slug>.md\`.
@@ -100,12 +167,13 @@ transient by design: it is harvested, then deleted.
 `
 
 /** the three baseline scripts, added only where the key is free */
-function addScripts(root: string, written: string[]): void {
+function addScripts(root: string, written: string[], p: (line: string) => void): void {
     const path = join(root, 'package.json')
-    if (!existsSync(path)) return
+    if (!existsSync(path)) return void p('WARN no package.json here — the lint/fmt/typecheck scripts were not written')
     const raw = readFileSync(path, 'utf8')
     let pkg: { scripts?: Record<string, string> }
-    try { pkg = JSON.parse(raw) as { scripts?: Record<string, string> } } catch { return }
+    try { pkg = JSON.parse(raw) as { scripts?: Record<string, string> } }
+    catch (e) { return void p(`WARN package.json is unparseable (${String(e).slice(0, 80)}) — the lint/fmt/typecheck scripts were not written, repair it then re-run`) }
     pkg.scripts ??= {}
     let added = 0
     for (const [k, v] of Object.entries(SCRIPTS)) if (pkg.scripts[k] == null) { pkg.scripts[k] = v; added++ }
@@ -115,6 +183,14 @@ function addScripts(root: string, written: string[]): void {
     written.push(`package.json (${added} script(s))`)
 }
 
+function packageName(root: string): string | null {
+    try {
+        return (JSON.parse(readFileSync(join(root, 'package.json'), 'utf8')) as { name?: string }).name ?? null
+    } catch {
+        return null
+    }
+}
+
 function addIgnoreLines(root: string, written: string[]): void {
     const path = join(root, '.gitignore')
     const cur = existsSync(path) ? readFileSync(path, 'utf8') : ''

package/src/start-repo.ts

@@ -7,7 +7,7 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs'
 import { homedir } from 'os'
 import { join } from 'path'
-import { ensureGitRepo, firstGhLine, IGNORE_BASELINE, isScratch, publishRepo, runner, type Run } from './git-bootstrap.ts'
+import { ensureGitRepo, ensureIgnoreBaseline, firstGhLine, isScratch, publishRepo, runner, type Run } from './git-bootstrap.ts'
 import { initRepo } from './init-repo.ts'
 import { scaffoldProject, TOOLCHAIN } from './scaffold/project-scaffold.ts'
 
@@ -101,16 +101,22 @@ export async function startRepo(name: string, opts: StartOpts = {}): Promise<num
                 writeFileSync(join(dir, 'package.json'), JSON.stringify(pkg, null, 4) + '\n')
                 console.error('ok: package.json created (private, type module)')
             }
-            // the baseline ignore goes FIRST, before anything else can create
-            // a .gitignore: the install below writes node_modules/ and
-            // neither SK004's block nor the scaffold's own lines carry it, so
-            // a file that already exists silently skips the baseline and the
-            // first commit refuses on 7000 staged dep files
-            if (!existsSync(join(dir, '.gitignore'))) writeFileSync(join(dir, '.gitignore'), `${IGNORE_BASELINE.join('\n')}\n`)
+            // the baseline ignore goes FIRST, before anything else creates a
+            // .gitignore, and every MISSING line is appended rather than the
+            // file being written only when absent: the install below writes
+            // node_modules/, neither SK004's block nor the scaffold's own
+            // lines carry it, and a dir that arrived with any .gitignore at
+            // all (a downloaded template, one stray line) otherwise skipped
+            // the baseline and refused the first commit over 7000 dep files
+            ensureIgnoreBaseline(dir)
             // the day-one shape: tsconfig, vscode tasks, the agent wiki, the
-            // verify skill, the attribution silencer. Create-only, so a dir
-            // that already holds any of them keeps its own
-            scaffoldProject(dir, { name, print })
+            // verify skill. Create-only, so a dir that already holds any of
+            // them keeps its own. The .claude/ policy files ride on the
+            // include lines: a caller that declares a house gets the house
+            // defaults, a bare `shipkit start` never has its agent
+            // permissions widened by a scaffold
+            try { scaffoldProject(dir, { name, print, claudePolicy: (opts.include ?? []).length > 0 }) }
+            catch (e) { console.error(`WARN scaffold incomplete in ${dir}: ${e instanceof Error ? e.message : String(e)} — the dir is still yours`) }
             // the wired scripts call node_modules binaries, so a scaffold
             // whose scripts exit 127 is not a started repo. Skips mirror the
             // github half's guards: an injected runner wins, the env switch