@skitterbyte/skitterspec 12.0.0 → 13.0.0

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 }