@skitterbyte/skitterspec 21.0.0 → 22.1.0

package/src/env/teardown.js

@@ -22,6 +22,7 @@
  */
 
 const { expandTokens } = require('./resolve.js')
+const { composeFileArg } = require('./provision.js')
 
 /**
  * @param {object} spec  resolved spec: { slug, branch, worktreePath, projectName, ... }
@@ -64,6 +65,14 @@ function planDown(spec, config, flags, ctx) {
   // (Stack: worktree) has no stack/volumes even when the project master switch is
   // on — tearing it down is just removing the worktree. A spec resolved without an
   // explicit stack (legacy/tests) follows the master switch (pre-`Stack` behaviour).
+  //
+  // DELIBERATELY NOT GATED ON THE COMPOSE FILE, where `planUp` is. The two
+  // directions are not symmetric: bringing a stack up without evidence there is
+  // one to bring costs a failed provision, while skipping a `down` costs an
+  // orphaned stack and its volumes, still running, that nothing will come back
+  // for. So `up` needs a positive signal and `down` errs toward cleaning up —
+  // a `down` for a stack that was never started is a no-op (rule 4, pointing
+  // the other way because the harmless branch is the other branch).
   const stack = spec.stack || (config.docker.enabled ? 'docker' : 'worktree')
   const wantsDocker = stack === 'docker' && config.docker.enabled
 
@@ -86,7 +95,9 @@ function planDown(spec, config, flags, ctx) {
 
   // --- docker compose down (drop volumes unless kept) ---
   if (wantsDocker) {
-    const base = `docker compose --project-name ${spec.projectName} down`
+    const base =
+      `docker compose${composeFileArg(config, ctx ? ctx.composeFilePresent : undefined)}` +
+      ` --project-name ${spec.projectName} down`
     commands.push(volumesDropped ? `${base} --volumes` : base)
   }
 

package/src/init.js

@@ -5,7 +5,7 @@ const path = require('path')
 const crypto = require('crypto')
 
 const { ensureWorktreeDirTrusted } = require('./env/trust.js')
-const { ensureReviewGateHook } = require('./env/hooks.js')
+const { ensureHooks } = require('./env/hooks.js')
 const { repoInfo, expandTokens } = require('./env/resolve.js')
 
 const ASSETS = path.join(__dirname, '..', 'assets')
@@ -93,14 +93,20 @@ const SPEC_FOLDERS = ['.core', 'backlog', 'in-progress', 'complete', 'cancelled'
 // env.config isolation templates; a provider superset also ships its own).
 const CORE_FILES = listCoreTemplates()
 
-// The CLI is a local devDependency and never on PATH, so a command file that
-// pre-executes it must carry a literal, working invocation. Detect the runner
-// from the lockfile and bake it in at write time.
+// A command file pre-executes the CLI, so it must carry a literal invocation
+// that actually resolves in THIS project. Three installs are possible — local
+// dependency, global, or none — and the runner differs for each.
 //
-// The lockfile is a POSITIVE signal — a file that must be present for the answer
-// to be yes — rather than an absence. When none is found we do not guess a
-// package manager we have no evidence for; `npx` is the fallback because it is
-// the one runner that works across all three installs.
+// A LOCKFILE DOES NOT ANSWER THIS QUESTION. It says which runner would be used
+// *if* the CLI were installed here, which is a different thing, and reading it
+// as evidence of an install is inferring from an absence
+// (`.claude/rules/negative-checks.md` rule 1). It cost the non-Node case
+// outright: a project with no lockfile got `npx skitterspec` baked into every
+// command file, and the unscoped name `skitterspec` does not exist on npm, so
+// all four 404'd.
+//
+// So the lockfile keeps the job it is good at — picking the runner once a local
+// install is established — and a ladder decides whether there is one.
 const PACKAGE_MANAGERS = [
   ['pnpm-lock.yaml', 'pnpm exec'],
   ['yarn.lock', 'yarn'],
@@ -108,6 +114,8 @@ const PACKAGE_MANAGERS = [
   ['bun.lockb', 'bunx'],
 ]
 
+// Which runner would reach a LOCAL install here? Rung 1's answer only — it says
+// nothing about whether the CLI is present, which is `detectRunner`'s job.
 function detectPackageManager(dir) {
   for (const [lockfile, exec] of PACKAGE_MANAGERS) {
     if (fs.existsSync(path.join(dir, lockfile))) return exec
@@ -115,12 +123,97 @@ function detectPackageManager(dir) {
   return 'npx'
 }
 
+// The bin names a distribution may expose. A provider superset ships its own
+// name alongside `skitterspec`, and either proves the engine is reachable.
+const ENGINE_BINS = ['skitterspec', 'skitterspec-linear']
+
+function binNames() {
+  return process.platform === 'win32'
+    ? ENGINE_BINS.flatMap((n) => [n, `${n}.cmd`, `${n}.exe`])
+    : ENGINE_BINS
+}
+
+// Rung 1 — a local install, found by walking up. Bounded at 6 levels, matching
+// the hooks' own `findEngine`: a git worktree's checkout has its own
+// `node_modules`, and a monorepo package hoists to the root.
+function hasLocalInstall(dir) {
+  let at = path.resolve(dir)
+  for (let i = 0; i < 6; i++) {
+    for (const name of binNames()) {
+      if (fs.existsSync(path.join(at, 'node_modules', '.bin', name))) return true
+    }
+    const up = path.dirname(at)
+    if (up === at) break
+    at = up
+  }
+  return false
+}
+
+// An npx cache bin directory. Matched on the path SEGMENT, so a project that
+// happens to live under a directory called `_npxtools` is not mistaken for one.
+const NPX_CACHE_RE = /[\\/]_npx[\\/]/
+
+// Rung 2 — a global install, found on PATH.
+//
+// WHAT WOULD FOOL THIS, and why the filter is not optional: `npx` PREPENDS its
+// own cache bin directory to PATH for the processes it spawns. Verified, not
+// assumed. So running `npx @skitterbyte/skitterspec init` puts a `skitterspec`
+// on PATH that exists only for the duration of that one command — and probing
+// for it here would bake a bare `skitterspec …` into four COMMITTED files that
+// stop working the moment init exits. Excluding `_npx` entries is what makes
+// this rung evidence of an install rather than evidence of the install running.
+function hasPathInstall(env = process.env) {
+  const raw = env.PATH || env.Path || ''
+  if (!raw) return false
+  for (const entry of raw.split(path.delimiter)) {
+    if (!entry || NPX_CACHE_RE.test(entry)) continue
+    for (const name of binNames()) {
+      if (fs.existsSync(path.join(entry, name))) return true
+    }
+  }
+  return false
+}
+
+/**
+ * How should a command file invoke the CLI here?
+ *
+ * A positive-signal ladder: each rung asserts something that must be PRESENT,
+ * and only the last is a fallback.
+ *
+ *   local — a local install; the lockfile picks the runner
+ *   path  — a global install; no runner at all, the bin is invoked bare
+ *   none  — neither could be found. `npx` is written as before, and the caller
+ *           warns, because this is the cannot-tell case rather than a third
+ *           kind of install (rule 4: the unknown routes to the harmless branch,
+ *           which here is "write what we always wrote and say so").
+ *
+ * PROJECT-VISIBLE SIGNALS OUTRANK MACHINE-VISIBLE ONES, which is why `local` is
+ * checked first. `.claude/commands/*.md` is committed and `renderCommand` feeds
+ * `managedTargets`, so a render that varies by machine makes the file flip
+ * between pristine and updatable as different people run `update`. A lockfile
+ * is committed and answers the same everywhere; PATH is one machine's business.
+ */
+function detectRunner(dir, env = process.env) {
+  if (hasLocalInstall(dir)) return { runner: detectPackageManager(dir), rung: 'local' }
+  if (hasPathInstall(env)) return { runner: '', rung: 'path' }
+  return { runner: 'npx', rung: 'none' }
+}
+
 // Fill a command file's `{{exec}}` placeholders. Kept a pure function of
 // (content, dir) so `managedTargets` can compare against exactly what
 // `installCommands` would write — otherwise every install would hash as
 // customized on the next run.
+//
+// The token is consumed WITH its trailing space, so an empty runner leaves
+// `Bash(skitterspec …)` rather than `Bash( skitterspec …)`. The second pass
+// catches a bare `{{exec}}` in case a template ever lands without one.
 function renderCommand(content, dir) {
-  return content.split('{{exec}}').join(detectPackageManager(dir))
+  const { runner } = detectRunner(dir)
+  return content
+    .split('{{exec}} ')
+    .join(runner ? `${runner} ` : '')
+    .split('{{exec}}')
+    .join(runner)
 }
 
 // --- composed-assets guard -------------------------------------------------
@@ -179,7 +272,7 @@ function assertComposedAssets() {
 const SPEC_MARKER_START = '<!-- skitterspec:start -->'
 const SPEC_MARKER_END = '<!-- skitterspec:end -->'
 
-const report = { created: [], updated: [], skipped: [], refused: [], removed: [], customized: [], healed: [], warnings: [] }
+const report = { created: [], updated: [], skipped: [], refused: [], removed: [], customized: [], adopted: [], healed: [], warnings: [] }
 
 function resetReport() {
   for (const k of Object.keys(report)) report[k].length = 0
@@ -241,16 +334,31 @@ function managedTargets(dir) {
 }
 
 // Read the manifest (tolerant: missing/malformed → an empty baseline).
+// `baselined` answers a question `files` cannot: could this manifest have SEEN
+// a path? It is true only when the file parsed into the expected shape AND
+// records at least one entry — a POSITIVE signal, not an absence, which is what
+// lets `managedState` read a path's absence from it as evidence of anything
+// (`.claude/rules/negative-checks.md` rule 1).
+//
+// WHAT WOULD FOOL IT: nothing silently. A missing manifest and a malformed one
+// both fall into the same empty baseline below — correct for reading hashes,
+// and useless for reasoning about absence, since on a repo with no manifest yet
+// EVERY path is absent. Both answer `baselined: false`, so the one conclusion
+// that depends on it is simply not drawn.
 function readManifest(dir) {
   try {
     const parsed = JSON.parse(fs.readFileSync(path.join(dir, MANIFEST_FILE), 'utf8'))
     if (parsed && typeof parsed === 'object' && parsed.files && typeof parsed.files === 'object') {
-      return { version: parsed.version || MANIFEST_VERSION, files: parsed.files }
+      return {
+        version: parsed.version || MANIFEST_VERSION,
+        files: parsed.files,
+        baselined: Object.keys(parsed.files).length > 0,
+      }
     }
   } catch {
     /* missing or malformed → empty baseline */
   }
-  return { version: MANIFEST_VERSION, files: {} }
+  return { version: MANIFEST_VERSION, files: {}, baselined: false }
 }
 
 function writeManifest(dir, files) {
@@ -265,6 +373,29 @@ function writeManifest(dir, files) {
 //   missing    — not on disk
 //   pristine   — ours to update: it matches the package asset, or the hash we recorded
 //   customized — on disk but differs from both — a user edit; keep it
+//   adopted    — a path this version has NEWLY CLAIMED, where the project
+//                already had a file: it differs from what we ship, and the
+//                manifest that could have named it does not. Keep it too — the
+//                two states differ only in what the report CLAIMS about it.
+//
+// The split exists because `customized` made a false statement about the second
+// case. "Your edit — kept" describes our file at a path upstream had not
+// claimed, and the reader acts on it: v21 renamed the commit hook to
+// `review-gate.cjs`, which is the same name anyone would have picked to work
+// around v20's ESM crash — so their shim was kept, the real hook was never
+// installed, and `review-gate.js` was pruned out from under it. The shim fails
+// open, so the gate went silently absent under a report that said success.
+//
+// WHAT WOULD FOOL THIS, and why neither does:
+//   - A repo with no manifest (or an unreadable one) has EVERY path absent.
+//     `baselined` is the positive signal that gates the conclusion, so those
+//     fall back to `customized` — which keeps the file either way
+//     (`.claude/rules/negative-checks.md` rules 1 and 4).
+//   - The signal is ONE-SHOT. `flushManifest`'s migration seed gives any
+//     present managed file an entry on the very next run, so an adopted path
+//     reads `customized` from then on. Anyone who already upgraded has spent
+//     it — which is why the `.cjs` trap is also written into MIGRATION.md,
+//     where that reader is actually looking.
 //
 // `bundled` (the current package asset) is optional but decisive: a file whose
 // CONTENT equals what we ship is not customized, whatever the manifest says.
@@ -280,7 +411,8 @@ function managedState(dir, relPath, manifest, bundled) {
   const onDisk = fs.readFileSync(abs, 'utf8')
   if (bundled !== undefined && onDisk === bundled) return 'pristine'
   const known = manifest.files[relPath]
-  return known && sha1(onDisk) === known ? 'pristine' : 'customized'
+  if (known) return sha1(onDisk) === known ? 'pristine' : 'customized'
+  return manifest.baselined ? 'adopted' : 'customized'
 }
 
 // Reconcile and persist the manifest after an install/resync run: keep prior
@@ -386,6 +518,19 @@ function installCommands(dir, opts) {
     )
     writeFile(dir, path.join(dir, '.claude', 'commands', name), content, opts)
   }
+
+  // ONLY on the cannot-tell rung, and it warns rather than refusing: `init` has
+  // real work to do either way — skills, rules, folders — and none of it needs
+  // the CLI reachable later. Silence here is what let a project install cleanly
+  // and hand back four commands that 404 on first use.
+  if (COMMANDS.length && detectRunner(dir).rung === 'none') {
+    report.warnings.push(
+      `the skitterspec CLI could not be found here, so the ${COMMANDS.length} slash ` +
+        'command(s) were written to call `npx skitterspec`, which will fail — ' +
+        'install it (npm i -g @skitterbyte/skitterspec, or add it as a dev ' +
+        'dependency) and re-run `skitterspec update` to rewrite them',
+    )
+  }
 }
 
 function installRule(dir, opts) {
@@ -405,17 +550,20 @@ function installRule(dir, opts) {
 // reported and left alone, never rewritten, and never fatal — the hook is an
 // extra layer, and the engine and `/spec-next` hold the gate without it.
 function registerReviewGateHook(dir) {
-  const label = '.claude/settings.json (review-gate hook)'
+  // "hooks", plural, because two ship now — the review gate and the main guard.
+  // The label names the file and the subject rather than one script, so adding a
+  // third does not leave a report that undercounts what it wrote.
+  const label = '.claude/settings.json (skitterspec hooks)'
   let res
   try {
-    res = ensureReviewGateHook(dir)
+    res = ensureHooks(dir)
   } catch {
-    report.warnings.push('could not write .claude/settings.json — review-gate hook not registered')
+    report.warnings.push('could not write .claude/settings.json — skitterspec hooks not registered')
     return
   }
   if (res.reason === 'malformed') {
     report.warnings.push(
-      '.claude/settings.json is not valid JSON — did not register the review-gate hook',
+      '.claude/settings.json is not valid JSON — did not register the skitterspec hooks',
     )
   } else if (res.reason === 'created') {
     report.created.push(label)
@@ -426,9 +574,9 @@ function registerReviewGateHook(dir) {
     // that: rewriting the registered path and then reporting "already
     // registered" — a run that acts and says it did not, which is the shape of
     // the bug this whole change exists to fix.
-    report.updated.push('.claude/settings.json (review-gate hook repointed at the renamed script)')
+    report.updated.push('.claude/settings.json (skitterspec hooks repointed at the renamed script)')
   } else {
-    report.skipped.push('.claude/settings.json (review-gate hook already registered)')
+    report.skipped.push('.claude/settings.json (skitterspec hooks already registered)')
   }
 }
 
@@ -627,6 +775,8 @@ function checkSync(dir, { claudeMd = true, log = console.log } = {}) {
     const state = managedState(dir, relPath, manifest, bundled)
     if (state === 'missing') rows.push([relPath, 'missing — would be created'])
     else if (state === 'customized') rows.push([relPath, 'your edit — kept (--force overwrites)'])
+    else if (state === 'adopted')
+      rows.push([relPath, 'adopted upstream — yours kept, theirs not installed (--force takes theirs)'])
     else if (fs.readFileSync(abs, 'utf8') !== bundled) rows.push([relPath, 'out of date — would be updated'])
   }
   const section = claudeMd ? claudeMdSectionState(dir) : 'fresh'
@@ -714,14 +864,16 @@ function resyncManagedFile(dir, target, manifest, force) {
     report[bucket].push(relPath)
   }
   if (state === 'missing') return write('created')
-  if (state === 'customized') {
+  // `adopted` writes exactly as `customized` does — keep unless forced. Only the
+  // bucket differs, because only the REPORT was ever wrong about it.
+  if (state === 'customized' || state === 'adopted') {
     if (force) return write('updated')
     writtenHashes[relPath] = manifest.files[relPath] || writtenHashes[relPath] // keep baseline
     // Carry the change the user just DECLINED. A bare filename tells them a
     // decision was made on their behalf but not what it was, which leaves
     // "clobber and re-apply my edits by hand" as the only safe way to upgrade.
     const { added, removed, hunks } = linesDiff(fs.readFileSync(abs, 'utf8'), bundled)
-    return report.customized.push({ relPath, added, removed, hunks })
+    return report[state].push({ relPath, added, removed, hunks })
   }
   // pristine — update only if the bundled content actually changed
   if (fs.readFileSync(abs, 'utf8') === bundled) {
@@ -836,6 +988,10 @@ function printReport(dir, mode, { diff = false } = {}) {
     'customized (kept)',
     report.customized.map((c) => `${c.relPath}  +${c.added} \u2212${c.removed}`),
   )
+  line(
+    'adopted upstream (kept — ours was never installed)',
+    report.adopted.map((c) => `${c.relPath}  +${c.added} \u2212${c.removed}`),
+  )
   line('manifest repaired', report.healed)
   line('unchanged', report.skipped)
   if (report.refused.length) {
@@ -851,13 +1007,17 @@ function printReport(dir, mode, { diff = false } = {}) {
     process.stdout.write('\nwarnings:\n')
     for (const w of report.warnings) process.stdout.write(`  ! ${w}\n`)
   }
+  const declined = [
+    ...report.customized.map((c) => [c, 'kept — this is what you declined']),
+    ...report.adopted.map((c) => [c, 'kept — this is what was not installed']),
+  ]
   if (diff) {
-    for (const c of report.customized) {
+    for (const [c, why] of declined) {
       if (!c.hunks.length) continue
-      process.stdout.write(`\n--- ${c.relPath} (kept — this is what you declined)\n`)
+      process.stdout.write(`\n--- ${c.relPath} (${why})\n`)
       for (const h of c.hunks) process.stdout.write(`${h}\n`)
     }
-  } else if (report.customized.length) {
+  } else if (declined.length) {
     process.stdout.write('\nRe-run with --diff to see the changes those files declined.\n')
   }
   const isolationOn = fs.existsSync(path.join(dir, 'specs', '.core', 'env.config.json'))
@@ -953,5 +1113,6 @@ module.exports = {
   assertSafeToDelete,
   assertComposedAssets,
   detectPackageManager,
+  detectRunner,
   renderCommand,
 }