@skitterbyte/skitterspec 11.0.0 → 13.0.0

package/src/env/resolve.js

@@ -36,10 +36,10 @@ function findSpecFolder(specArg, dir, extraDirs = []) {
   return null
 }
 
-// Split a `feat-`/`bug-` prefix. Unknown prefix → type defaults to `feat` and
-// the whole folder name is the slug.
+// Split a `feat-`/`bug-`/`hotfix-` prefix. Unknown prefix → type defaults to
+// `feat` and the whole folder name is the slug.
 function splitPrefix(folder) {
-  const m = /^(feat|bug)-(.+)$/.exec(folder)
+  const m = /^(feat|bug|hotfix)-(.+)$/.exec(folder)
   if (m) return { type: m[1], slug: m[2] }
   return { type: 'feat', slug: folder }
 }
@@ -104,6 +104,26 @@ function readStackField(specPath, config) {
   return config.docker && config.docker.enabled ? 'docker' : 'worktree'
 }
 
+/**
+ * Read a spec's `> **Base version:** <tag>` blockquote field from 00-overview.md.
+ * This is the release tag a hotfix forks its worktree from (e.g. `v33.16.4`),
+ * authored by the `/spec-hotfix` skill. Returns the trimmed tag, or null when the
+ * field / file is absent — so a non-hotfix spec resolves to `baseRef: null` and
+ * provisioning forks from base HEAD as before.
+ */
+function readBaseVersionField(specPath) {
+  const overview = path.join(specPath, '00-overview.md')
+  let raw
+  try {
+    raw = fs.readFileSync(overview, 'utf-8')
+  } catch {
+    return null
+  }
+  const m = /^>\s*\*\*Base version:\*\*\s*(.+)$/m.exec(raw)
+  if (!m) return null
+  return m[1].trim().replace(/^["'`]|["'`]$/g, '') || null
+}
+
 /**
  * Derive the git branch for a spec from the provider-neutral `branch.pattern`
  * (`{type}`, `{slug}`, and optionally `{identifier}`). When the pattern uses
@@ -165,6 +185,29 @@ function resolvePrimaryCheckout(dir, git) {
   return common ? path.dirname(path.resolve(dir, common)) : dir
 }
 
+/**
+ * The current branch of a checkout, or `null` when detached (or not a repo).
+ * `git` is a reader bound to the target checkout — for the live-overlay guard the
+ * CLI binds it to the primary checkout. (`symbolic-ref --short HEAD` exits
+ * non-zero on a detached HEAD, which the reader maps to `null`.)
+ */
+function currentBranch(git) {
+  return git(['symbolic-ref', '--short', 'HEAD'])
+}
+
+/**
+ * The live-overlay guard: is the primary checkout on the integration base branch
+ * (free) or on a feature branch (a spec is in control)? Returns
+ * `{ onBase, branch, baseBranch }` — a structured result, never a throw, so each
+ * caller phrases its own refusal. `git` must be bound to the primary checkout.
+ * `onBase` is false on a detached HEAD (`branch === null`), which is not the base.
+ */
+function assertPrimaryOnMain(config, git) {
+  const baseBranch = resolveBaseBranch(config, git)
+  const branch = currentBranch(git)
+  return { onBase: branch === baseBranch, branch, baseBranch }
+}
+
 /**
  * Resolve a spec argument to its identity + isolation coordinates.
  * Throws a clear Error when the spec folder can't be found.
@@ -184,7 +227,10 @@ function resolveSpec(specArg, dir, config, opts = {}) {
   const tokens = { repo, repoSlug, slug }
 
   const stack = readStackField(found.path, config)
-  const spec = { folder: found.folder, bucket: found.bucket, path: found.path, type, slug, stack }
+  // A hotfix forks its worktree from a release tag (its `Base version`) instead
+  // of base HEAD; every other type resolves to baseRef:null (fork from HEAD).
+  const baseRef = type === 'hotfix' ? readBaseVersionField(found.path) : null
+  const spec = { folder: found.folder, bucket: found.bucket, path: found.path, type, slug, stack, baseRef }
   const branch = branchFor(spec, config)
 
   const worktreeRoot = expandTokens(config.worktree.root, tokens)
@@ -208,10 +254,13 @@ module.exports = {
   resolveSpec,
   resolveBaseBranch,
   resolvePrimaryCheckout,
+  currentBranch,
+  assertPrimaryOnMain,
   branchFor,
   splitPrefix,
   repoInfo,
   expandTokens,
   findSpecFolder,
   readStackField,
+  readBaseVersionField,
 }

package/src/env/teardown.js

@@ -21,7 +21,7 @@ const { expandTokens } = require('./resolve.js')
  * @param {object} spec  resolved spec: { slug, branch, worktreePath, projectName, ... }
  * @param {object} config normalised env config.
  * @param {object} flags { keepVolumes, force }
- * @param {object} ctx   { worktreeState: { dirty, unpushed, merged }, timestamp }
+ * @param {object} ctx   { worktreeState: { dirty, unpushed, merged, reachableFromTag }, timestamp }
  * @returns {object} { blocked, reason, commands, backupCommand, backupPath,
  *                     volumesDropped }
  */
@@ -30,20 +30,22 @@ function planDown(spec, config, flags, ctx) {
   const force = Boolean(flags && flags.force)
   const keepVolumes = Boolean(flags && flags.keepVolumes)
 
+  // A hotfix lands by tag + cherry-pick, so its branch is never an ancestor of
+  // base — but once its head is captured by a tag (the deploy tag from
+  // `hotfix land`), the commits are recoverable and the branch is safe to drop.
+  // Treat "reachable from a tag" as landed, alongside merged.
+  const landed = Boolean(worktreeState.merged || worktreeState.reachableFromTag)
+
   // --- guards (overridable with --force) ---
   if (!force) {
     if (config.guards.refuseTeardownIfDirty && worktreeState.dirty) {
       return blocked('worktree has uncommitted changes')
     }
     // Unpushed commits are only unsafe when they aren't already integrated into
-    // the base branch. A branch merged into base carries nothing to lose even
-    // with no remote — so /spec-complete's local land-then-teardown needs no
-    // --force. Block only when the commits are both unpushed AND unmerged.
-    if (
-      config.guards.refuseTeardownIfUnpushed &&
-      worktreeState.unpushed &&
-      !worktreeState.merged
-    ) {
+    // the base branch (or captured by a tag). A landed branch carries nothing to
+    // lose even with no remote — so /spec-complete's local land-then-teardown
+    // needs no --force. Block only when unpushed AND not landed.
+    if (config.guards.refuseTeardownIfUnpushed && worktreeState.unpushed && !landed) {
       return blocked('worktree has unpushed commits not yet merged into the base branch')
     }
   }
@@ -85,11 +87,16 @@ function planDown(spec, config, flags, ctx) {
       : `git worktree remove ${spec.worktreePath}`,
   )
 
-  // --- delete the branch (safe: -d refuses an unmerged branch, never -D) ---
-  // Runs after the worktree remove frees the branch. On a forced teardown of an
-  // unmerged branch this fails loudly; the skill relays it rather than -D-ing.
+  // --- delete the branch ---
+  // Runs after the worktree remove frees the branch. Normally `-d` (safe: refuses
+  // an unmerged branch, never -D). A tag-landed hotfix branch is intentionally NOT
+  // an ancestor of base, so `-d` would refuse it — but its commits are captured by
+  // the deploy tag, so `-D` is safe *only* in that case. Everything else stays `-d`;
+  // on a forced teardown of a genuinely unmerged branch it fails loudly and the
+  // skill relays it rather than -D-ing.
   if (spec.branch) {
-    commands.push(`git branch -d ${spec.branch}`)
+    const tagLanded = Boolean(worktreeState.reachableFromTag && !worktreeState.merged)
+    commands.push(`git branch ${tagLanded ? '-D' : '-d'} ${spec.branch}`)
   }
 
   return { blocked: false, reason: null, commands, backupCommand, backupPath, volumesDropped }

package/src/init.js

@@ -2,6 +2,7 @@
 
 const fs = require('fs')
 const path = require('path')
+const crypto = require('crypto')
 
 const { ensureWorktreeDirTrusted } = require('./env/trust.js')
 const { repoInfo, expandTokens } = require('./env/resolve.js')
@@ -52,7 +53,12 @@ const CORE_FILES = listCoreTemplates()
 const SPEC_MARKER_START = '<!-- skitterspec:start -->'
 const SPEC_MARKER_END = '<!-- skitterspec:end -->'
 
-const report = { created: [], updated: [], skipped: [], removed: [], warnings: [] }
+const report = { created: [], updated: [], skipped: [], removed: [], customized: [], warnings: [] }
+
+function resetReport() {
+  for (const k of Object.keys(report)) report[k].length = 0
+  for (const k of Object.keys(writtenHashes)) delete writtenHashes[k]
+}
 
 // Folder index files scaffolded by earlier versions, now retired. `init`/`update`
 // deletes any left behind so upgrading projects don't keep stale caches.
@@ -69,7 +75,109 @@ function ensureDir(p) {
   if (!fs.existsSync(p)) fs.mkdirSync(p, { recursive: true })
 }
 
+// --- install manifest (safe re-run baseline) --------------------------------
+//
+// specs/.core/.skitterspec-manifest.json records, per managed file, the sha1 of
+// the content we last wrote. It's the baseline that lets a later resync tell "an
+// old version we own" (safe to update) from "a file the user edited" (keep). It
+// lists only managed FILES (skills, rules, .core templates) — never user content.
+
+const MANIFEST_FILE = path.join('specs', '.core', '.skitterspec-manifest.json')
+const MANIFEST_VERSION = 1
+
+// Hashes of files actually written in the current run (populated by writeFile),
+// reset each init() alongside `report`.
+const writtenHashes = {}
+
+function sha1(content) {
+  return crypto.createHash('sha1').update(content).digest('hex')
+}
+
+// The full managed set for a target dir: repo-relative path, absolute path, and
+// the bundled content that ships in this distribution's assets.
+function managedTargets(dir) {
+  const out = []
+  const add = (assetRel, targetAbs) =>
+    out.push({
+      relPath: rel(dir, targetAbs),
+      abs: targetAbs,
+      bundled: fs.readFileSync(path.join(ASSETS, assetRel), 'utf8'),
+    })
+  for (const name of SKILLS) add(path.join('skills', name, 'SKILL.md'), path.join(dir, '.claude', 'skills', name, 'SKILL.md'))
+  for (const name of RULES) add(path.join('rules', name), path.join(dir, '.claude', 'rules', name))
+  for (const asset of CORE_FILES) add(asset, path.join(dir, 'specs', '.core', path.basename(asset)))
+  return out
+}
+
+// Read the manifest (tolerant: missing/malformed → an empty baseline).
+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 }
+    }
+  } catch {
+    /* missing or malformed → empty baseline */
+  }
+  return { version: MANIFEST_VERSION, files: {} }
+}
+
+function writeManifest(dir, files) {
+  const target = path.join(dir, MANIFEST_FILE)
+  ensureDir(path.dirname(target))
+  const sorted = {}
+  for (const k of Object.keys(files).sort()) sorted[k] = files[k]
+  fs.writeFileSync(target, JSON.stringify({ version: MANIFEST_VERSION, files: sorted }, null, 2) + '\n')
+}
+
+// Classify a managed file against the manifest baseline.
+//   missing    — not on disk
+//   pristine   — on disk and matches the hash we recorded (ours to update)
+//   customized — on disk but differs (or unknown) — a user edit; keep it
+function managedState(dir, relPath, manifest) {
+  const abs = path.join(dir, relPath)
+  if (!fs.existsSync(abs)) return 'missing'
+  const known = manifest.files[relPath]
+  return known && sha1(fs.readFileSync(abs, 'utf8')) === known ? 'pristine' : 'customized'
+}
+
+// Reconcile and persist the manifest after an install/resync run: keep prior
+// entries, apply files written this run, seed any pre-existing managed file that
+// has no entry yet from its bundled hash (migration for repos predating the
+// manifest), and prune entries whose file is gone.
+function flushManifest(dir) {
+  // Only managed files belong in the manifest — never live user config (e.g. an
+  // env.config.json that installIsolation happens to write through writeFile).
+  const managed = managedTargets(dir)
+  const managedRel = new Set(managed.map((t) => t.relPath))
+  const merged = { ...readManifest(dir).files, ...writtenHashes }
+  const next = {}
+  for (const [relPath, hash] of Object.entries(merged)) {
+    if (managedRel.has(relPath)) next[relPath] = hash
+  }
+  for (const { relPath, abs, bundled } of managed) {
+    if (!next[relPath] && fs.existsSync(abs)) next[relPath] = sha1(bundled) // migration seed
+  }
+  for (const relPath of Object.keys(next)) {
+    if (!fs.existsSync(path.join(dir, relPath))) delete next[relPath] // prune gone
+  }
+  writeManifest(dir, next)
+}
+
 function writeFile(dir, target, content, { force }) {
+  // A dangling symlink (its target no longer exists) is invisible to existsSync,
+  // which follows the link — but the link itself is still on disk, so a plain
+  // writeFileSync would follow it into a missing directory and throw ENOENT.
+  // Drop the broken link and write a real file in its place.
+  let link = null
+  try {
+    link = fs.lstatSync(target)
+  } catch {
+    /* no such path — nothing to clean up */
+  }
+  if (link && link.isSymbolicLink() && !fs.existsSync(target)) {
+    fs.unlinkSync(target)
+  }
   if (fs.existsSync(target)) {
     if (!force) {
       report.skipped.push(rel(dir, target))
@@ -77,15 +185,19 @@ function writeFile(dir, target, content, { force }) {
     }
     const existing = fs.readFileSync(target, 'utf8')
     if (existing === content) {
+      // Already the content we'd write — record it as ours (pristine).
+      writtenHashes[rel(dir, target)] = sha1(content)
       report.skipped.push(rel(dir, target))
       return
     }
     fs.writeFileSync(target, content)
+    writtenHashes[rel(dir, target)] = sha1(content)
     report.updated.push(rel(dir, target))
     return
   }
   ensureDir(path.dirname(target))
   fs.writeFileSync(target, content)
+  writtenHashes[rel(dir, target)] = sha1(content)
   report.created.push(rel(dir, target))
 }
 
@@ -253,6 +365,118 @@ function installClaudeMd(dir, { mode }) {
   report.updated.push('CLAUDE.md (appended spec workflow section)')
 }
 
+// --- detection, resync, reset (safe re-run) ---------------------------------
+
+// True when the repo looks already set up: any managed file present, any spec
+// lifecycle folder, or the CLAUDE.md spec marker (Decision 1 — detect eagerly).
+function isExistingSetup(dir) {
+  if (managedTargets(dir).some((t) => fs.existsSync(t.abs))) return true
+  if (SPEC_FOLDERS.some((f) => fs.existsSync(path.join(dir, 'specs', f)))) return true
+  const claude = path.join(dir, 'CLAUDE.md')
+  return fs.existsSync(claude) && fs.readFileSync(claude, 'utf8').includes(SPEC_MARKER_START)
+}
+
+// RESYNC: bring managed files to the latest bundled version WITHOUT clobbering
+// user edits. Per file: missing → create; pristine (matches the manifest) →
+// update; customized (edited) → keep + report, unless `force`.
+function resyncManagedFile(dir, target, manifest, force) {
+  const { relPath, abs, bundled } = target
+  const state = managedState(dir, relPath, manifest)
+  const write = (bucket) => {
+    ensureDir(path.dirname(abs))
+    fs.writeFileSync(abs, bundled)
+    writtenHashes[relPath] = sha1(bundled)
+    report[bucket].push(relPath)
+  }
+  if (state === 'missing') return write('created')
+  if (state === 'customized') {
+    if (force) return write('updated')
+    writtenHashes[relPath] = manifest.files[relPath] || writtenHashes[relPath] // keep baseline
+    return report.customized.push(relPath)
+  }
+  // pristine — update only if the bundled content actually changed
+  if (fs.readFileSync(abs, 'utf8') === bundled) {
+    writtenHashes[relPath] = sha1(bundled)
+    return report.skipped.push(relPath)
+  }
+  write('updated')
+}
+
+function resync(dir, { force = false, claudeMd = true } = {}) {
+  if (!fs.existsSync(dir)) throw new Error(`target dir does not exist: ${dir}`)
+  resetReport()
+  const manifest = readManifest(dir)
+  for (const t of managedTargets(dir)) resyncManagedFile(dir, t, manifest, force)
+  installFolders(dir)
+  removeRetiredFiles(dir)
+  if (claudeMd) installClaudeMd(dir, { mode: 'update' })
+  flushManifest(dir)
+  printReport(dir, 'resync')
+}
+
+// The never-touch set: START AGAIN may only delete a known managed file, and may
+// never delete spec content or active config (defense-in-depth — the manifest
+// never lists these, but a tampered/foreign entry must still be refused).
+const PROTECTED_SPEC_BUCKETS = ['backlog', 'in-progress', 'complete', 'cancelled']
+const PROTECTED_CONFIG = ['env.config.json', 'linear.config.json']
+const PROTECTED_DIRS = ['linear-base', 'linear-backups']
+
+function assertSafeToDelete(relPath, managedSet) {
+  const norm = relPath.split(path.sep).join('/')
+  for (const b of PROTECTED_SPEC_BUCKETS) {
+    if (norm.startsWith(`specs/${b}/`)) throw new Error(`refusing to delete spec content: ${relPath}`)
+  }
+  if (PROTECTED_CONFIG.includes(path.posix.basename(norm))) {
+    throw new Error(`refusing to delete active config: ${relPath}`)
+  }
+  for (const d of PROTECTED_DIRS) {
+    if (norm.includes(`/${d}/`)) throw new Error(`refusing to delete sync state: ${relPath}`)
+  }
+  if (!managedSet.has(norm)) throw new Error(`refusing to delete a non-managed path: ${relPath}`)
+}
+
+// Remove the marked spec-workflow block from CLAUDE.md (leaves the rest intact).
+function stripClaudeMdSection(dir) {
+  const target = path.join(dir, 'CLAUDE.md')
+  if (!fs.existsSync(target)) return
+  const existing = fs.readFileSync(target, 'utf8')
+  const next = existing.replace(
+    new RegExp(`\\n?${SPEC_MARKER_START}[\\s\\S]*?${SPEC_MARKER_END}\\n?`),
+    '\n',
+  )
+  if (next !== existing) {
+    fs.writeFileSync(target, next)
+    report.removed.push('CLAUDE.md (spec workflow section)')
+  }
+}
+
+// START AGAIN: delete exactly the manifest-listed managed files (each guarded),
+// strip the CLAUDE.md marked section, then reinstall fresh. Never touches a
+// non-manifest path. Destructive by design for managed files (that's the point).
+function reset(dir, { claudeMd = true } = {}) {
+  if (!fs.existsSync(dir)) throw new Error(`target dir does not exist: ${dir}`)
+  resetReport()
+  const manifest = readManifest(dir)
+  const managedSet = new Set(managedTargets(dir).map((t) => t.relPath.split(path.sep).join('/')))
+  for (const relPath of Object.keys(manifest.files)) {
+    assertSafeToDelete(relPath, managedSet)
+    const abs = path.join(dir, relPath)
+    if (fs.existsSync(abs)) {
+      fs.unlinkSync(abs)
+      report.removed.push(relPath)
+    }
+  }
+  if (claudeMd) stripClaudeMdSection(dir)
+  installSkills(dir, { force: true })
+  installRule(dir, { force: true })
+  installFolders(dir)
+  removeRetiredFiles(dir)
+  installCore(dir, { force: true })
+  if (claudeMd) installClaudeMd(dir, { mode: 'init' })
+  flushManifest(dir)
+  printReport(dir, 'reset')
+}
+
 function printReport(dir, mode) {
   const line = (label, items) => {
     if (!items.length) return
@@ -263,6 +487,7 @@ function printReport(dir, mode) {
   line('created', report.created)
   line('updated', report.updated)
   line('removed', report.removed)
+  line('customized (kept)', report.customized)
   line('unchanged', report.skipped)
   if (report.warnings.length) {
     process.stdout.write('\nwarnings:\n')
@@ -285,11 +510,7 @@ function printReport(dir, mode) {
 
 async function init({ dir, force, claudeMd, mode, isolation }) {
   if (!fs.existsSync(dir)) throw new Error(`target dir does not exist: ${dir}`)
-  report.created.length = 0
-  report.updated.length = 0
-  report.skipped.length = 0
-  report.removed.length = 0
-  report.warnings.length = 0
+  resetReport()
 
   installSkills(dir, { force })
   installRule(dir, { force })
@@ -300,6 +521,10 @@ async function init({ dir, force, claudeMd, mode, isolation }) {
   if (mode !== 'update') installIsolation(dir, { enabled: isolation }, { force })
   if (claudeMd) installClaudeMd(dir, { mode })
 
+  // Record what we wrote (and migrate a pre-manifest repo) so a later resync can
+  // tell our files from the user's.
+  flushManifest(dir)
+
   printReport(dir, mode)
 }
 
@@ -308,4 +533,14 @@ module.exports = {
   SKILLS,
   RULES,
   SPEC_FOLDERS,
+  MANIFEST_FILE,
+  sha1,
+  readManifest,
+  writeManifest,
+  managedTargets,
+  managedState,
+  isExistingSetup,
+  resync,
+  reset,
+  assertSafeToDelete,
 }

package/src/prompts.js

@@ -53,4 +53,40 @@ async function confirmRemoveReleaseTooling() {
   return Boolean(ans.remove)
 }
 
-module.exports = { promptSetup, confirmRemoveReleaseTooling }
+/**
+ * Interactive choice when `init` finds an already-set-up repo. Returns one of
+ * `leave` | `resync` | `reset`. Defaults to (and cancels to) `leave` — the safe
+ * no-op — and asks a second confirm before `reset` (destructive to managed files).
+ */
+async function promptExistingSetup() {
+  const prompts = require('prompts')
+  const { action } = await prompts(
+    {
+      type: 'select',
+      name: 'action',
+      message: 'This project already has skitterspec set up. What would you like to do?',
+      initial: 0,
+      choices: [
+        { title: 'Leave alone — make no changes', value: 'leave' },
+        { title: 'Resync — update managed files to the latest, keep my edits', value: 'resync' },
+        { title: 'Start again — reset the scaffolding (your specs & config are kept)', value: 'reset' },
+      ],
+    },
+    { onCancel: () => {} },
+  )
+  if (action === 'reset') {
+    const { confirm } = await prompts(
+      {
+        type: 'confirm',
+        name: 'confirm',
+        message: 'Start again overwrites managed skills/rules. Your specs and config are untouched. Continue?',
+        initial: false,
+      },
+      { onCancel: () => false },
+    )
+    if (!confirm) return 'leave'
+  }
+  return action || 'leave'
+}
+
+module.exports = { promptSetup, confirmRemoveReleaseTooling, promptExistingSetup }