@skitterbyte/skitterspec 18.0.0 → 20.0.0

package/src/init.js

@@ -5,6 +5,7 @@ const path = require('path')
 const crypto = require('crypto')
 
 const { ensureWorktreeDirTrusted } = require('./env/trust.js')
+const { ensureReviewGateHook } = require('./env/hooks.js')
 const { repoInfo, expandTokens } = require('./env/resolve.js')
 
 const ASSETS = path.join(__dirname, '..', 'assets')
@@ -38,6 +39,20 @@ function listCommands() {
   }
 }
 
+// Hook scripts shipped as `assets/hooks/*.js`, installed to `.claude/hooks/`.
+// Discovered from the bundled tree like everything else, so a distribution
+// installs precisely what it ships and a hook can be retired by deleting it.
+function listHooks() {
+  try {
+    return fs
+      .readdirSync(path.join(ASSETS, 'hooks'))
+      .filter((f) => f.endsWith('.js'))
+      .sort()
+  } catch {
+    return [] // a distribution may ship no hooks
+  }
+}
+
 function listRules() {
   return fs
     .readdirSync(path.join(ASSETS, 'rules'))
@@ -61,6 +76,8 @@ const COMMANDS = listCommands()
 
 const RULES = listRules()
 
+const HOOKS = listHooks()
+
 const SPEC_FOLDERS = ['.core', 'backlog', 'in-progress', 'complete', 'cancelled']
 
 // Opt-in config templates, scaffolded into specs/.core/ (the base ships the
@@ -153,7 +170,7 @@ function assertComposedAssets() {
 const SPEC_MARKER_START = '<!-- skitterspec:start -->'
 const SPEC_MARKER_END = '<!-- skitterspec:end -->'
 
-const report = { created: [], updated: [], skipped: [], removed: [], customized: [], healed: [], warnings: [] }
+const report = { created: [], updated: [], skipped: [], refused: [], removed: [], customized: [], healed: [], warnings: [] }
 
 function resetReport() {
   for (const k of Object.keys(report)) report[k].length = 0
@@ -209,6 +226,7 @@ function managedTargets(dir) {
   for (const name of COMMANDS)
     add(path.join('commands', name), path.join(dir, '.claude', 'commands', name), renderCommand)
   for (const name of RULES) add(path.join('rules', name), path.join(dir, '.claude', 'rules', name))
+  for (const name of HOOKS) add(path.join('hooks', name), path.join(dir, '.claude', 'hooks', name))
   for (const asset of CORE_FILES) add(asset, path.join(dir, 'specs', '.core', path.basename(asset)))
   return out
 }
@@ -293,6 +311,25 @@ function writeFile(dir, target, content, { force }) {
   if (link && link.isSymbolicLink() && !fs.existsSync(target)) {
     fs.unlinkSync(target)
   }
+  // A LIVE symlink is the opposite case, and `--force` is what makes it
+  // dangerous: `writeFileSync` follows the link, so forcing would write composed
+  // content — seam markers resolved, provider text spliced in — straight through
+  // it and into whatever it points at. In a checkout that dogfoods its own
+  // assets that is `packages/*/assets`, i.e. the SOURCE the link exists to keep
+  // live. Refuse: the staleness `--force` was reached for is a smaller problem
+  // than corrupting the file it would overwrite.
+  //
+  // WHAT WOULD MAKE THIS LIE: a HARD link. It has no distinguishing lstat — it
+  // simply is the file — so it takes the same corrupting path and nothing here
+  // can see it. Out of scope deliberately, and said out loud rather than left to
+  // be discovered; nothing in this project's install creates one.
+  //
+  // It cannot fire in an ordinary consumer install, because nothing there is
+  // linked — `skitterspec update` writes copies by design.
+  if (force && link && link.isSymbolicLink() && fs.existsSync(target)) {
+    report.refused.push(rel(dir, target))
+    return
+  }
   if (fs.existsSync(target)) {
     if (!force) {
       report.skipped.push(rel(dir, target))
@@ -353,6 +390,40 @@ function installRule(dir, opts) {
   }
 }
 
+// Register the review-gate hook in the project's committed settings, so a
+// phase that owes a verdict is enforced one level below the skills. Best-effort
+// in exactly the way `trustWorktreeRoot` is: a settings file we cannot parse is
+// 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)'
+  let res
+  try {
+    res = ensureReviewGateHook(dir)
+  } catch {
+    report.warnings.push('could not write .claude/settings.json — review-gate hook not registered')
+    return
+  }
+  if (res.reason === 'malformed') {
+    report.warnings.push(
+      '.claude/settings.json is not valid JSON — did not register the review-gate hook',
+    )
+  } else if (res.reason === 'created') {
+    report.created.push(label)
+  } else if (res.reason === 'added') {
+    report.updated.push(label)
+  } else {
+    report.skipped.push('.claude/settings.json (review-gate hook already registered)')
+  }
+}
+
+function installHooks(dir, opts) {
+  for (const name of HOOKS) {
+    copyAsset(dir, path.join('hooks', name), path.join(dir, '.claude', 'hooks', name), opts)
+  }
+  registerReviewGateHook(dir)
+}
+
 function installFolders(dir) {
   for (const folder of SPEC_FOLDERS) {
     const abs = path.join(dir, 'specs', folder)
@@ -499,6 +570,67 @@ function trustWorktreeRoot(dir) {
   }
 }
 
+// Is the CLAUDE.md section this project has installed the one we ship?
+//
+// THREE answers, not two. `differs` deliberately does NOT mean "stale": the
+// block is a COPY, so a difference is either an out-of-date copy or the user's
+// own edit, and from here those read identically. Rule 4 of
+// `.claude/rules/negative-checks.md` — route the unknown case to the harmless
+// branch, which here means reporting a difference and naming the fix rather
+// than accusing them of being behind.
+//
+// WHAT WOULD FOOL THIS: absent markers mean the section was never installed, OR
+// that someone stripped it deliberately (`stripClaudeMdSection` exists and is
+// reachable from `reset`). Neither is a fault, so both answer `not installed`
+// and neither is reported as a problem.
+function claudeMdSectionState(dir) {
+  const target = path.join(dir, 'CLAUDE.md')
+  if (!fs.existsSync(target)) return 'not installed'
+  const existing = fs.readFileSync(target, 'utf8')
+  if (!existing.includes(SPEC_MARKER_START) || !existing.includes(SPEC_MARKER_END)) {
+    return 'not installed'
+  }
+  const shipped = fs.readFileSync(path.join(ASSETS, 'claude-md-section.md'), 'utf8').trim()
+  const start = existing.indexOf(SPEC_MARKER_START) + SPEC_MARKER_START.length
+  const installed = existing.slice(start, existing.indexOf(SPEC_MARKER_END)).trim()
+  return installed === shipped ? 'fresh' : 'differs'
+}
+
+// `update --check`: say what `update` would change, write nothing, exit 0.
+// It reports; `update` without the flag stays the only thing that touches a
+// file. This exists because the section is a copy and a copy goes quietly out
+// of date — this repo's own was a whole spec behind the template it ships,
+// through a spec about that template, with every test green.
+function checkSync(dir, { claudeMd = true, log = console.log } = {}) {
+  if (!fs.existsSync(dir)) throw new Error(`target dir does not exist: ${dir}`)
+  const manifest = readManifest(dir)
+  const rows = []
+  // Mirror `resyncManagedFile`'s decision exactly rather than re-deriving it:
+  // missing → it would create; customized → it would KEEP yours and say so;
+  // pristine → it would write only when the shipped content actually differs.
+  for (const { relPath, abs, bundled } of managedTargets(dir)) {
+    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 (fs.readFileSync(abs, 'utf8') !== bundled) rows.push([relPath, 'out of date — would be updated'])
+  }
+  const section = claudeMd ? claudeMdSectionState(dir) : 'fresh'
+  // A healthy area says NOTHING. A report that lists what is already fine is a
+  // report people learn to skim, and then the one line that mattered is missed.
+  if (section === 'differs') {
+    rows.push([
+      'CLAUDE.md (spec workflow section)',
+      'differs from the shipped one — `update` would replace it (it is a copy, so this is either your edit or an out-of-date one)',
+    ])
+  }
+  if (!rows.length) log('skitterspec update --check: everything is up to date.')
+  else {
+    log('skitterspec update --check: `skitterspec update` would:')
+    for (const [name, why] of rows) log(`  ${name} — ${why}`)
+  }
+  return { rows, section }
+}
+
 function installClaudeMd(dir, { mode }) {
   const section = fs.readFileSync(path.join(ASSETS, 'claude-md-section.md'), 'utf8').trim()
   const block = `${SPEC_MARKER_START}\n${section}\n${SPEC_MARKER_END}\n`
@@ -657,6 +789,7 @@ function reset(dir, { claudeMd = true } = {}) {
   installSkills(dir, { force: true })
   installCommands(dir, { force: true })
   installRule(dir, { force: true })
+  installHooks(dir, { force: true })
   installFolders(dir)
   removeRetiredFiles(dir)
   installCore(dir, { force: true })
@@ -681,6 +814,15 @@ function printReport(dir, mode, { diff = false } = {}) {
   )
   line('manifest repaired', report.healed)
   line('unchanged', report.skipped)
+  if (report.refused.length) {
+    process.stdout.write('\nrefused (a symlink — writing would overwrite what it points at):\n')
+    for (const it of report.refused) process.stdout.write(`  ${it}\n`)
+    process.stdout.write(
+      '  These are links into the shipped assets. --force would follow them and\n' +
+        '  write composed content into the source. Unlink one to take the copy\n' +
+        '  (rm <path>, then re-run), or leave it linked and edit the asset.\n',
+    )
+  }
   if (report.warnings.length) {
     process.stdout.write('\nwarnings:\n')
     for (const w of report.warnings) process.stdout.write(`  ! ${w}\n`)
@@ -747,6 +889,7 @@ async function init({ dir, force, claudeMd, mode, isolation, workspaceMode, gati
   installSkills(dir, { force })
   installCommands(dir, { force })
   installRule(dir, { force })
+  installHooks(dir, { force })
   installFolders(dir)
   removeRetiredFiles(dir)
   installCore(dir, { force })
@@ -764,6 +907,10 @@ async function init({ dir, force, claudeMd, mode, isolation, workspaceMode, gati
 
 module.exports = {
   init,
+  // A snapshot of the last run's report, for tests that need to assert on what a
+  // run DECIDED rather than only on what it left on disk. Copied, so a caller
+  // cannot mutate the live report between phases of a run.
+  lastReport: () => JSON.parse(JSON.stringify(report)),
   SKILLS,
   COMMANDS,
   RULES,
@@ -774,6 +921,8 @@ module.exports = {
   writeManifest,
   managedTargets,
   managedState,
+  claudeMdSectionState,
+  checkSync,
   isExistingSetup,
   resync,
   reset,

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2026 Reuben Greaves
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.