@skitterbyte/skitterspec 12.0.0 → 14.0.0

package/src/env/hotfix.js

@@ -0,0 +1,133 @@
+'use strict'
+
+/**
+ * Pure landing planner for `spec-env hotfix land`.
+ *
+ * A hotfix is built on an old release tag (its `Base version`), so it can't be
+ * fast-forwarded onto `main` like an ordinary spec (that's `integrate.js`).
+ * Instead `planHotfixLand` emits the exact side-effect-free, **never-pushing**
+ * commands to:
+ *   1. tag the hotfix branch head with the patch-bumped base tag (the prod deploy
+ *      tag — the branch head already is baseRef + the fix);
+ *   2. for each extra target tag, cherry-pick the fix onto a throwaway worktree at
+ *      that tag and re-tag it with its own patch bump (test/demo release lines);
+ *   3. cherry-pick the fix onto the base branch (main) for the next release.
+ *
+ * It performs no side effects — the caller (the CLI) probes git for `dirty` /
+ * `aheadOfBase` / `existingTags` / `mainRepoPath` and supplies them, keeping this
+ * deterministic and unit-testable with no live git. Conflict handling lives in the
+ * skill (run a cherry-pick, abort on non-zero exit, hand back), mirroring
+ * `integrate.js` — the planner never reasons about conflicts.
+ */
+
+const path = require('node:path')
+
+/**
+ * Parse a semver-ish tag and return it with its PATCH bumped by one. Preserves any
+ * non-digit prefix (e.g. `v` → `v33.16.5`) and drops any pre-release/build suffix
+ * (`-rc1`, `+build`). Throws on a tag with no `MAJOR.MINOR.PATCH` core.
+ */
+function bumpPatch(tag) {
+  const m = /^(\D*)(\d+)\.(\d+)\.(\d+)(?:.*)$/.exec(String(tag || '').trim())
+  if (!m) {
+    throw new Error(
+      `hotfix: cannot bump a patch version from tag "${tag}" — need <prefix>MAJOR.MINOR.PATCH`,
+    )
+  }
+  const [, prefix, major, minor, patch] = m
+  return `${prefix}${major}.${minor}.${Number(patch) + 1}`
+}
+
+// A filesystem/branch-safe slug derived from a tag (`v30.2.1` → `v30-2-1`).
+function tagSlug(tag) {
+  return String(tag)
+    .replace(/[^a-zA-Z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+}
+
+/**
+ * @param {object} spec  resolved hotfix spec: { slug, branch, worktreePath, baseRef, ... }
+ * @param {object} config normalised env config (reads `config.hotfix`).
+ * @param {object} ctx   { worktreeState:{dirty}, aheadOfBase, fixRange, mainRepoPath,
+ *                          base, extraTargets: string[], existingTags: string[] }
+ * @returns {object} { blocked, noop, reason, commands, prodTag, targets, branch, base }
+ */
+function planHotfixLand(spec, config, ctx) {
+  const c = ctx || {}
+  const branch = spec.branch
+  const baseRef = spec.baseRef
+  const hotfixCfg = (config && config.hotfix) || { cherryPickMain: true, targets: [] }
+  const result = {
+    blocked: false,
+    noop: false,
+    reason: null,
+    commands: [],
+    prodTag: null,
+    targets: [],
+    branch,
+    base: c.base,
+  }
+  const block = (reason) => ({ ...result, blocked: true, reason })
+
+  // A hotfix must carry the tag it forked from — everything below bumps from it.
+  if (!baseRef) {
+    return block('spec has no Base version — not a hotfix, or the header is missing')
+  }
+  // The completion edits (status flip, git mv) must be committed before landing.
+  if (c.worktreeState && c.worktreeState.dirty) {
+    return block('worktree has uncommitted changes — commit the completion first')
+  }
+  // Nothing on the branch beyond the base tag → nothing to land.
+  if (!c.aheadOfBase) {
+    return { ...result, noop: true, reason: `no commits on ${branch} beyond ${baseRef} — nothing to land` }
+  }
+
+  // Track tags we'd create so we never plan a collision (with an existing tag, or
+  // between the prod tag and a target tag).
+  const taken = new Set(c.existingTags || [])
+  const fixRange = c.fixRange
+  const commands = []
+  const targets = []
+
+  // 1. Prod line: tag the hotfix branch head (already baseRef + fix). No push.
+  const prodTag = bumpPatch(baseRef)
+  if (taken.has(prodTag)) {
+    return block(`tag ${prodTag} already exists — bump the base version or delete the stale tag`)
+  }
+  taken.add(prodTag)
+  commands.push(`git -C ${spec.worktreePath} tag ${prodTag}`)
+  targets.push({ kind: 'prod', base: baseRef, tag: prodTag })
+
+  // 2. Extra targets: cherry-pick the fix onto a throwaway worktree at each tag,
+  //    re-tag with its own patch bump, then remove the worktree + temp branch (the
+  //    commits survive under the new tag, so `-D` is safe for the throwaway branch).
+  const wtRoot = path.dirname(spec.worktreePath)
+  for (const t of c.extraTargets || []) {
+    const tag = bumpPatch(t)
+    if (taken.has(tag)) {
+      return block(`tag ${tag} (for target ${t}) already exists — resolve it before landing`)
+    }
+    taken.add(tag)
+    const slug = `${spec.slug}-onto-${tagSlug(t)}`
+    const tmpBranch = `hotfix/${slug}`
+    const tmpPath = path.join(wtRoot, slug)
+    commands.push(
+      `git worktree add ${tmpPath} -b ${tmpBranch} ${t}`,
+      `git -C ${tmpPath} cherry-pick ${fixRange}`,
+      `git -C ${tmpPath} tag ${tag}`,
+      `git worktree remove ${tmpPath}`,
+      `git branch -D ${tmpBranch}`,
+    )
+    targets.push({ kind: 'extra', base: t, tag, worktreePath: tmpPath })
+  }
+
+  // 3. Cherry-pick the fix onto the base branch (main) for the next release.
+  if (hotfixCfg.cherryPickMain !== false) {
+    commands.push(`git -C ${c.mainRepoPath} cherry-pick ${fixRange}`)
+    targets.push({ kind: 'main', base: c.base })
+  }
+
+  return { ...result, commands, prodTag, targets, fixRange }
+}
+
+module.exports = { bumpPatch, tagSlug, planHotfixLand }

package/src/env/live.js

@@ -179,21 +179,30 @@ function planTake(spec, config, ctx) {
   if (!c.worktreeExists) {
     return block(`${spec.folder} has no worktree — run \`/spec-go ${spec.folder}\` first`)
   }
-  // 4. v1 is code-only: refuse a stateful spec (Stack: worktree + docker)…
+  // 4. A hotfix is built on an old release tag; checking its branch out under the
+  //    running dev server risks schema/DB drift breaking the shared instance.
+  //    Always refuse, regardless of Stack — test it in isolation via /spec-connect.
+  if (spec.type === 'hotfix') {
+    return block(
+      `${spec.folder} is a hotfix (built on an old release tag) — live overlay ` +
+        'could break the running instance; use `/spec-connect` to test it in isolation',
+    )
+  }
+  // 5. v1 is code-only: refuse a stateful spec (Stack: worktree + docker)…
   if (spec.stack === 'docker') {
     return block(
       `${spec.folder} is stateful (Stack: worktree + docker) — live overlay is ` +
         'code-only; use `/spec-connect` for a Docker-backed spec',
     )
   }
-  // 5. …and refuse a branch that changes migrations (would mutate the shared DB).
+  // 6. …and refuse a branch that changes migrations (would mutate the shared DB).
   if (c.migrationsHit) {
     return block(
       `${spec.folder}'s branch changes migrations — live overlay is code-only; ` +
         'use `/spec-connect`',
     )
   }
-  // 6. Verify-only: a dev server must be listening to hot-reload the switch.
+  // 7. Verify-only: a dev server must be listening to hot-reload the switch.
   if (c.serverUp === false) {
     return block(
       `no dev server listening on canonical port(s) ${(c.canonicalPorts || []).join(', ')} — ` +

package/src/env/provision.js

@@ -94,10 +94,14 @@ function planUp(spec, alloc, config) {
 
   const commands = []
   // Fresh branch → -b; attach an existing branch/slot → plain form (never clobber).
+  // A hotfix forks its fresh branch from a release tag (`spec.baseRef`, e.g.
+  // `v33.16.4`) instead of base HEAD — so the fix is built on the exact commit
+  // line prod runs. Attaching an existing branch ignores baseRef (already forked).
+  const forkPoint = !attached && spec.baseRef ? ` ${spec.baseRef}` : ''
   commands.push(
     attached
       ? `git worktree add ${spec.worktreePath} ${spec.branch}`
-      : `git worktree add ${spec.worktreePath} -b ${spec.branch}`,
+      : `git worktree add ${spec.worktreePath} -b ${spec.branch}${forkPoint}`,
   )
   if (wantsDocker) {
     commands.push(`docker compose --project-name ${spec.projectName} up -d`)

package/src/env/prune.js

@@ -0,0 +1,119 @@
+'use strict'
+
+/**
+ * Pure planner for `spec-env prune` — the orphaned-test-DB reaper.
+ *
+ * Per-spec isolation gives each Docker-escalated spec its own compose stack
+ * namespaced by `{repoSlug}_{slug}`; the DB storage is a Docker named volume
+ * (`{repoSlug}_{slug}_<volname>`). Those volumes only ever get dropped by an
+ * explicit single-spec `spec-env down`, so they leak whenever that path is
+ * skipped (declined/guard-aborted teardown, manual `git worktree remove`,
+ * `--keep-volumes`). This planner reconciles the live namespace volumes against
+ * the specs that are still live and returns the `docker volume rm` commands for
+ * the orphans.
+ *
+ * **Liveness = an existing worktree, NOT the slot registry.** The registry is
+ * exactly what goes stale (a declined teardown leaves both the slot and the
+ * volume behind), so the caller derives `liveSlugs` from real worktrees and the
+ * registry is only reconciled afterwards. See the spec Decisions.
+ *
+ * We never parse a slug out of an orphan. Instead we build a protected-prefix
+ * set from the live slugs (`{repoSlug}_{slug}_`) and keep any volume matching
+ * one — everything else in the `{repoSlug}_` namespace is an orphan. The
+ * trailing `_` makes the slug match exact: slugs are kebab-case (`[a-z0-9-]`)
+ * and `_` is the compose project/volume separator, so `add` never protects
+ * `add-widget`.
+ *
+ * Side-effect free and deterministic: no `Date.now()` — the caller supplies
+ * `now` (and per-volume `createdAt`) when age-gating.
+ */
+
+const { splitPrefix } = require('./resolve.js')
+
+/**
+ * @param {Array<string|{name:string,createdAt?:number|null}>} volumes
+ *   live Docker volume names (or objects carrying `createdAt` epoch-ms for age
+ *   gating). Plain strings are treated as unknown-age.
+ * @param {Iterable<string>} liveSlugs  slugs of specs that still have a worktree.
+ * @param {object} opts { repoSlug, olderThanDays?, now? }
+ *   `repoSlug` (required) is the namespace prefix. `olderThanDays` (optional)
+ *   keeps only orphans strictly older than the cutoff; when set, `now`
+ *   (epoch-ms) is required and volumes of unknown age are conservatively kept.
+ * @returns {{ orphans: Array<{name:string,createdAt:number|null}>, commands: string[] }}
+ */
+function planPrune(volumes, liveSlugs, opts = {}) {
+  const { repoSlug, olderThanDays = null, now = null } = opts
+  if (!repoSlug) throw new Error('planPrune: opts.repoSlug is required')
+
+  const namespace = `${repoSlug}_`
+  const live = liveSlugs instanceof Set ? liveSlugs : new Set(liveSlugs || [])
+  const protectedPrefixes = [...live].map((slug) => `${repoSlug}_${slug}_`)
+
+  let orphans = (volumes || [])
+    .map((v) => (typeof v === 'string' ? { name: v, createdAt: null } : v))
+    .filter((v) => {
+      const name = v && v.name
+      if (!name || !name.startsWith(namespace)) return false
+      return !protectedPrefixes.some((p) => name.startsWith(p))
+    })
+    .map((v) => ({ name: v.name, createdAt: v.createdAt == null ? null : v.createdAt }))
+
+  if (olderThanDays != null) {
+    if (now == null) throw new Error('planPrune: olderThanDays requires opts.now')
+    const cutoff = now - olderThanDays * 24 * 60 * 60 * 1000
+    // Unknown age (createdAt == null) is kept — never drop what we can't date.
+    orphans = orphans.filter((v) => v.createdAt != null && v.createdAt <= cutoff)
+  }
+
+  const commands = orphans.map((v) => `docker volume rm ${v.name}`)
+  return { orphans, commands }
+}
+
+/**
+ * Derive the set of live spec slugs from the specs that still have a git
+ * worktree. The **worktree is the liveness signal** (see module header): the
+ * registry is not consulted here. Pure — the caller supplies the spec list and
+ * the set of live worktree paths (both gathered via IO).
+ *
+ * @param {Array<{slug:string, worktreePath:string}>} specs
+ * @param {Set<string>|Iterable<string>} liveWorktreePaths  absolute paths.
+ * @returns {Set<string>} slugs whose worktree currently exists.
+ */
+function liveSlugsForSpecs(specs, liveWorktreePaths) {
+  const live = liveWorktreePaths instanceof Set ? liveWorktreePaths : new Set(liveWorktreePaths || [])
+  const slugs = new Set()
+  for (const spec of specs || []) {
+    if (spec && spec.worktreePath && live.has(spec.worktreePath)) slugs.add(spec.slug)
+  }
+  return slugs
+}
+
+/**
+ * Reconcile the slot registry against the volumes we're about to reap. A stale
+ * slot is one whose spec's DB volume is an orphan — freeing it converges the
+ * registry back to what actually exists (the registry is keyed by spec *folder*,
+ * so we split each folder's prefix to get its slug and match it to a reaped
+ * volume by the same `{repoSlug}_{slug}_` prefix used for orphan detection).
+ * Pure: returns a new registry object plus the folders freed; never mutates.
+ *
+ * @param {{slots: Object<string,number>}} registry
+ * @param {Array<{name:string}>} orphans  the volumes planPrune decided to reap.
+ * @param {string} repoSlug
+ * @returns {{ registry: {slots: Object<string,number>}, freed: string[] }}
+ */
+function reconcileRegistry(registry, orphans, repoSlug) {
+  const slots = { ...((registry && registry.slots) || {}) }
+  const reaped = (orphans || []).map((o) => o.name)
+  const freed = []
+  for (const folder of Object.keys(slots)) {
+    const { slug } = splitPrefix(folder)
+    const prefix = `${repoSlug}_${slug}_`
+    if (reaped.some((name) => name.startsWith(prefix))) {
+      delete slots[folder]
+      freed.push(folder)
+    }
+  }
+  return { registry: { slots }, freed }
+}
+
+module.exports = { planPrune, liveSlugsForSpecs, reconcileRegistry }

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
@@ -207,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)
@@ -239,4 +262,5 @@ module.exports = {
   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 }