@skitterbyte/skitterspec-jira 0.0.0-stage → 2.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/registry.js

@@ -0,0 +1,159 @@
+'use strict'
+
+/**
+ * Slot registry for per-spec isolation — the single source of truth for which
+ * spec owns which slot index. It lives at the **primary checkout root** (shared
+ * by all worktrees, machine-local, gitignored) at the config-driven `registry`
+ * path (default `.spec-env/registry.json`).
+ *
+ * Slot `n` → a reserved port block: `portOffset = portBase + n * portsPerSpec`.
+ *
+ * The allocation helpers are pure transforms on a registry object so they can be
+ * unit-tested with no filesystem; `readRegistry`/`writeRegistry` are the only IO
+ * and are the seam the CLI drives. No `Date.now()`/`Math.random()` — determinism
+ * matters (callers pass timestamps when needed).
+ */
+
+const fs = require('node:fs')
+const path = require('node:path')
+
+function isObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+}
+
+// Absolute path to the registry file, resolved against the primary checkout root.
+function registryPath(rootDir, config) {
+  return path.resolve(rootDir, config.registry)
+}
+
+// Read the registry from disk. Missing file → an empty registry (never throws
+// on absence). Malformed JSON → a clear Error.
+function readRegistry(rootDir, config) {
+  const file = registryPath(rootDir, config)
+  let raw
+  try {
+    raw = fs.readFileSync(file, 'utf-8')
+  } catch (error) {
+    if (error.code === 'ENOENT') return { slots: {}, specless: {} }
+    throw error
+  }
+  let parsed
+  try {
+    parsed = JSON.parse(raw)
+  } catch (error) {
+    throw new Error(`Invalid registry ${config.registry}: ${error.message}`)
+  }
+  return {
+    slots: isObject(parsed.slots) ? { ...parsed.slots } : {},
+    specless: isObject(parsed.specless) ? { ...parsed.specless } : {},
+  }
+}
+
+// Persist the registry, creating its parent dir as needed.
+function writeRegistry(rootDir, config, registry) {
+  const file = registryPath(rootDir, config)
+  fs.mkdirSync(path.dirname(file), { recursive: true })
+  // `specless` is written only when it holds something, so a project that never
+  // ran `/no-spec` keeps a registry file byte-identical to the one it had
+  // before this key existed.
+  const payload = { slots: registry.slots }
+  if (registry.specless && Object.keys(registry.specless).length) {
+    payload.specless = registry.specless
+  }
+  fs.writeFileSync(file, JSON.stringify(payload, null, 2) + '\n')
+}
+
+/**
+ * Allocate the lowest free slot index to `name`. Idempotent: if `name` already
+ * holds a slot, that slot is returned and the registry is unchanged. Returns a
+ * new registry object (does not mutate the input).
+ */
+function allocateSlot(registry, name) {
+  const slots = { ...registry.slots }
+  // CARRIED THROUGH, NOT REBUILT. Every one of these helpers returns a whole
+  // registry, so a helper that forgets a key silently deletes it on the next
+  // write — which is how a `/no-spec` branch would have become unresolvable the
+  // moment any Docker spec was provisioned beside it.
+  const specless = { ...(registry.specless || {}) }
+  if (Object.prototype.hasOwnProperty.call(slots, name)) {
+    return { registry: { slots, specless }, slot: slots[name] }
+  }
+  const used = new Set(Object.values(slots))
+  let slot = 0
+  while (used.has(slot)) slot++
+  slots[name] = slot
+  return { registry: { slots, specless }, slot }
+}
+
+/**
+ * Free `name`'s slot. Idempotent: freeing an absent spec is a clean no-op.
+ * Returns a new registry object (does not mutate the input).
+ */
+function freeSlot(registry, name) {
+  const slots = { ...registry.slots }
+  delete slots[name]
+  return { slots, specless: { ...(registry.specless || {}) } }
+}
+
+// Port block base for a slot.
+function portOffset(slot, config) {
+  return config.docker.portBase + slot * config.docker.portsPerSpec
+}
+
+/**
+ * Record a SPECLESS branch — `/no-spec` work, which has a worktree and a branch
+ * and no spec document anywhere.
+ *
+ * A SEPARATE KEY RATHER THAN A SLOT, and that is the whole design of it. A slot
+ * means a reserved port block, which mechanical work does not want; and every
+ * consumer of `slots` reads an entry there as "this spec runs a Docker stack".
+ * Sharing the map would have made `/no-spec` allocate ports it never binds and
+ * appear as a stateful spec in `status`.
+ *
+ * It is what makes a specless name RESOLVABLE. Without a record, "no spec folder
+ * for this name" is indistinguishable from a typo — and `resolve.js` would have
+ * to treat every unknown name as possibly-specless, which is exactly the
+ * absence-as-evidence this codebase refuses (`.claude/rules/negative-checks.md`
+ * rule 1). This is the positive signal: the engine wrote this name down.
+ *
+ * Idempotent, and pure — returns a new registry object.
+ */
+function recordSpecless(registry, name, entry = {}) {
+  const specless = { ...(registry.specless || {}) }
+  specless[name] = { ...(specless[name] || {}), ...entry }
+  return { slots: { ...registry.slots }, specless }
+}
+
+/**
+ * Forget a specless branch. Idempotent: forgetting an absent one is a clean
+ * no-op, which is what lets teardown call it without looking first.
+ */
+function forgetSpecless(registry, name) {
+  const specless = { ...(registry.specless || {}) }
+  delete specless[name]
+  return { slots: { ...registry.slots }, specless }
+}
+
+// Is this name a recorded specless branch? Pure, and the positive signal
+// `resolve.js` asks for before it will resolve a name with no spec folder.
+function isSpecless(registry, name) {
+  return Object.prototype.hasOwnProperty.call((registry && registry.specless) || {}, name)
+}
+
+// Every recorded specless name, sorted so output is stable. Pure.
+function speclessNames(registry) {
+  return Object.keys((registry && registry.specless) || {}).sort()
+}
+
+module.exports = {
+  registryPath,
+  readRegistry,
+  writeRegistry,
+  allocateSlot,
+  freeSlot,
+  portOffset,
+  recordSpecless,
+  forgetSpecless,
+  isSpecless,
+  speclessNames,
+}

package/src/env/render.js

@@ -0,0 +1,17 @@
+'use strict'
+
+/**
+ * Pure renderers for per-spec isolation artifacts.
+ *
+ * `renderEnvFile` produces the worktree's `.env` body — the only file the engine
+ * writes. No side effects — unit-testable in isolation.
+ */
+
+// The worktree `.env`: COMPOSE_PROJECT_NAME namespaces the Docker stack and its
+// named volumes; PORT_OFFSET shifts the spec's reserved port block.
+function renderEnvFile({ projectName, portOffset }) {
+  return `COMPOSE_PROJECT_NAME=${projectName}\nPORT_OFFSET=${portOffset}\n`
+}
+
+
+module.exports = { renderEnvFile }