@skitterbyte/skitterspec 17.0.0 → 19.0.0

package/src/env/render.js

@@ -3,24 +3,15 @@
 /**
  * Pure renderers for per-spec isolation artifacts.
  *
- * `renderEnvFile` produces the worktree's `.env` body (the only file the engine
- * writes). `expandOpenCommand` expands the optional, editor/terminal-agnostic
- * `open.command` template. No side effects — unit-testable in isolation.
+ * `renderEnvFile` produces the worktree's `.env` body — the only file the engine
+ * writes. No side effects — unit-testable in isolation.
  */
 
-const { expandTokens } = require('./resolve.js')
-
 // 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`
 }
 
-// Expand the opener template with the provided tokens. An empty/whitespace-only
-// template means "no auto-open" → returns null.
-function expandOpenCommand(template, tokens) {
-  if (typeof template !== 'string' || !template.trim()) return null
-  return expandTokens(template, tokens)
-}
 
-module.exports = { renderEnvFile, expandOpenCommand }
+module.exports = { renderEnvFile }

package/src/env/resolve.js

@@ -20,12 +20,19 @@ const BUCKETS = ['backlog', 'in-progress', 'complete', 'cancelled']
 
 // Find the spec folder under specs/<bucket>/<name>. `specArg` may be a bare
 // folder name or a path — only its basename is matched against the buckets.
-// Searches `dir` first, then any `extraDirs` in order — so a caller (e.g.
-// `spec-env integrate`) can fall back to a worktree checkout for a spec that
-// was authored on its branch and never committed to the primary checkout.
-function findSpecFolder(specArg, dir, extraDirs = []) {
+//
+// Search order is `preferDirs`, then `dir`, then `extraDirs`:
+//   - `preferDirs` is the checkout the CALLER is standing in. A spec's bucket
+//     and its `Stack:` / `Base version:` headers are properties of the branch,
+//     not of the repo — `/spec-start` moves a spec to `in-progress` on the
+//     spec's own branch, so the primary checkout keeps showing `backlog`.
+//   - `dir` is the primary checkout, and stays the fallback (and the sole
+//     source of repo identity — see `resolveSpec`).
+//   - `extraDirs` lets a caller (e.g. `spec-env integrate`) reach a spec that
+//     was authored on a branch and never committed to the primary checkout.
+function findSpecFolder(specArg, dir, extraDirs = [], preferDirs = []) {
   const name = path.basename(specArg)
-  for (const root of [dir, ...extraDirs]) {
+  for (const root of [...preferDirs, dir, ...extraDirs]) {
     for (const bucket of BUCKETS) {
       const abs = path.join(root, 'specs', bucket, name)
       if (fs.existsSync(abs) && fs.statSync(abs).isDirectory()) {
@@ -36,6 +43,209 @@ function findSpecFolder(specArg, dir, extraDirs = []) {
   return null
 }
 
+/**
+ * A spec's phases, as the review page needs them. Never throws.
+ *
+ * WHAT IT ANSWERS: is there a phase left for `/spec-next` to build? That is the
+ * question a `Commit & Continue` button needs, and it is simply `done < total` —
+ * `/spec-next` acts on the FIRST UNFINISHED phase, so a spec sitting mid-way
+ * through its last phase still has one to build, while a spec whose phases are
+ * all done has none whether it was finished a minute ago or a month ago.
+ *
+ * THREE OUTCOMES. `null` means cannot tell — a legacy bare `<name>.md`, an
+ * overview carrying its phases inline, a folder this cannot see. The caller
+ * must route that to leaving things as they are: an absence is not evidence
+ * that a spec has no phases (`.claude/rules/negative-checks.md` rules 1 and 4).
+ *
+ * WHAT WOULD FOOL THIS: a spec whose phase files exist but whose statuses were
+ * never updated reads as unfinished, so the button stays offered — the harmless
+ * direction. The opposite error, reading a live spec as finished, would take a
+ * file claiming Done that is not, which is a lie in the repo rather than a gap
+ * in this reader.
+ */
+function readPhases(specDir, { overviewFile = '00-overview.md' } = {}) {
+  let entries
+  try {
+    entries = fs.readdirSync(specDir, { withFileTypes: true })
+  } catch {
+    return null
+  }
+  const files = entries
+    .filter((e) => e.isFile() && /^\d\d-.+\.md$/.test(e.name) && e.name !== overviewFile)
+    .map((e) => e.name)
+    .sort()
+  // No phase files is not "no phases" — it is a legacy layout whose phases live
+  // inline in the overview, and this reader cannot see them.
+  if (!files.length) return null
+
+  let done = 0
+  for (const name of files) {
+    let text
+    try {
+      text = fs.readFileSync(path.join(specDir, name), 'utf8')
+    } catch {
+      return null
+    }
+    if (phaseIsDone(text)) done++
+  }
+  return { total: files.length, done, hasNextPhase: done < files.length, live: livePhase(specDir, files) }
+}
+
+/**
+ * The phase this diff is about — its number, title, goal and tasks.
+ *
+ * WHICH PHASE. The one in progress, else the last one done. A goal shown beside
+ * a diff that predates it is worse than no goal at all, and those two are the
+ * only phases a diff can plausibly be about: work in flight, or work just
+ * finished and not yet committed.
+ *
+ * `null` throughout rather than a half-filled object — a phase file this cannot
+ * parse is a phase with nothing to say, and the page omits the section rather
+ * than rendering an empty one.
+ */
+function livePhase(specDir, files) {
+  let inProgress = null
+  let lastDone = null
+  for (const name of files) {
+    let text
+    try {
+      text = fs.readFileSync(path.join(specDir, name), 'utf8')
+    } catch {
+      continue
+    }
+    const parsed = parsePhase(text, name)
+    if (!parsed) continue
+    if (phaseIsDone(text)) lastDone = parsed
+    else if (phaseIsStarted(text)) inProgress = inProgress || parsed
+  }
+  return inProgress || lastDone
+}
+
+/** Is this phase under way? The status line wins, for `phaseIsDone`'s reason. */
+function phaseIsStarted(text) {
+  const status = /^>.*\*\*Status:\*\*\s*(.+)$/m.exec(text)
+  if (status) return /^in progress\b/i.test(status[1].trim())
+  return /^#\s.*🔄\s*$/m.test(text)
+}
+
+/**
+ * One phase file's readable parts. Pure, and tolerant: every field but `n` is
+ * optional, because a phase file someone wrote by hand is still a phase file.
+ */
+function parsePhase(text, name) {
+  const num = /^(\d\d)-/.exec(name)
+  if (!num) return null
+  const heading = /^#\s+(.+?)\s*$/m.exec(text)
+  // `# Phase 1 — The engine reads the phase index ✅` → the title between the
+  // dash and the status emoji, which is the half a reader wants.
+  let title = heading ? heading[1] : ''
+  title = title.replace(/^Phase\s+\d+\s*[—–-]\s*/i, '').replace(/\s*[⬜🔄✅]\s*$/u, '').trim()
+  const goal = /^\*\*Goal:\*\*\s*([\s\S]*?)(?:\n\n|\n##)/m.exec(text)
+  // LINE BY LINE, not one regex. A task wraps across lines with the
+  // continuation indented, and an `$` under `/m` matches at every line end — so
+  // the obvious regex silently truncates every wrapped task at its first line.
+  // It looked right on the short ones, which is why this is done the long way.
+  const tasks = []
+  for (const line of text.split('\n')) {
+    const start = /^- \[([ xX])\]\s*(.*)$/.exec(line)
+    if (start) {
+      tasks.push({ done: start[1].toLowerCase() === 'x', text: start[2].trim() })
+      continue
+    }
+    // An indented non-empty line continues the task above it. Anything else —
+    // a blank line, a heading, an unindented paragraph — ends the list.
+    if (!tasks.length) continue
+    if (/^\s+\S/.test(line)) tasks[tasks.length - 1].text += ' ' + line.trim()
+    else if (line.trim()) break
+  }
+  return {
+    n: Number(num[1]),
+    title,
+    goal: goal ? goal[1].replace(/\s+/g, ' ').trim() : null,
+    tasks,
+  }
+}
+
+/**
+ * The spec's own `## Problem` and `## Impact`, for the page's header.
+ *
+ * WHAT WOULD FOOL THIS: a spec that renames those headings, or a legacy bare
+ * `<name>.md` with no overview at all. Both yield `null`, which the caller
+ * routes to omitting the header — the page rendered without one yesterday and
+ * still does (`.claude/rules/negative-checks.md` rule 4).
+ */
+function readOverview(specDir, { overviewFile = '00-overview.md' } = {}) {
+  let text
+  try {
+    text = fs.readFileSync(path.join(specDir, overviewFile), 'utf8')
+  } catch {
+    return null
+  }
+  const problem = sectionOf(text, 'Problem') || sectionOf(text, 'Symptom')
+  const impact = impactRows(sectionOf(text, 'Impact'))
+  if (!problem && !impact) return null
+  return {
+    ...(problem ? { problem } : {}),
+    ...(impact ? { impact } : {}),
+  }
+}
+
+/**
+ * The body under one `## Heading`, up to the next one. Trimmed, or null.
+ *
+ * SLICED, not lookahead-matched. The obvious regex ends with
+ * `(?=^##\s|\Z)` — and JS has no `\Z`, so that alternative is a literal
+ * `Z` and every section at the END of a file returns nothing. It passed on the
+ * spec used to write it, whose Problem happened to be followed by another
+ * heading, and failed on a bug spec's Symptom and on any Impact table written
+ * last.
+ */
+function sectionOf(text, heading) {
+  const open = new RegExp(`^##\\s+${heading}\\s*$`, 'm').exec(text)
+  if (!open) return null
+  const from = open.index + open[0].length
+  const next = /^##\s/m.exec(text.slice(from))
+  const body = (next ? text.slice(from, from + next.index) : text.slice(from)).trim()
+  return body || null
+}
+
+/**
+ * The Impact table's rows. The heading is always present in a spec, and the
+ * table is not — a spec touching no external surface writes a one-line sentence
+ * instead, which is a real answer and is returned as prose.
+ */
+function impactRows(section) {
+  if (!section) return null
+  const rows = []
+  for (const line of section.split('\n')) {
+    if (!line.trim().startsWith('|')) continue
+    const cells = line.split('|').slice(1, -1).map((c) => c.trim())
+    if (cells.length < 3) continue
+    // The header and its `|---|` separator, dropped by shape rather than by
+    // position — a spec that omits either still yields its rows.
+    if (/^-{2,}$/.test(cells[0].replace(/:/g, ''))) continue
+    if (/^surface$/i.test(cells[0]) && /^change$/i.test(cells[1])) continue
+    rows.push({ surface: cells[0], change: cells[1], detail: cells[2] })
+  }
+  if (rows.length) return { rows }
+  const prose = section.split('\n').map((l) => l.trim()).filter(Boolean).join(' ').replace(/^_|_$/g, '')
+  return prose ? { prose } : null
+}
+
+/**
+ * Is one phase file finished? Pure.
+ *
+ * THE STATUS LINE WINS over the heading's emoji. Both are written by the
+ * lifecycle skills and both are kept in step, but a hand edit that fixes one
+ * and forgets the other far more often leaves a stale emoji than stale prose —
+ * and the emoji is the half a reader's eye skips.
+ */
+function phaseIsDone(text) {
+  const status = /^>.*\*\*Status:\*\*\s*(.+)$/m.exec(text)
+  if (status) return /^done\b/i.test(status[1].trim())
+  return /^#\s.*✅\s*$/m.test(text)
+}
+
 // Split a `feat-`/`bug-`/`hotfix-` prefix. Unknown prefix → type defaults to
 // `feat` and the whole folder name is the slug.
 function splitPrefix(folder) {
@@ -212,18 +422,28 @@ function assertPrimaryOnMain(config, git) {
  * Resolve a spec argument to its identity + isolation coordinates.
  * Throws a clear Error when the spec folder can't be found.
  *
+ * `opts.preferDirs` are checkout roots searched BEFORE `dir` — the checkout the
+ * caller is standing in, so the spec's bucket and headers come from the branch
+ * they are on rather than from the base branch's stale copy.
  * `opts.searchDirs` adds fallback checkout roots to look under (after `dir`) when
- * locating the spec folder; identity/coordinate tokens still expand against `dir`
- * (the primary checkout), so a worktree-only spec resolves to the right base.
+ * locating the spec folder.
+ *
+ * **Identity/coordinate tokens still expand against `dir`** (the primary
+ * checkout) in every case — `{repo}`, the worktree path, the docker project name
+ * and the registry are repo-level facts that must be identical from anywhere.
+ * That is `bug-spec-env-cwd-anchor`'s fix and it is deliberately untouched here;
+ * only which *file* is read moves.
  */
 function resolveSpec(specArg, dir, config, opts = {}) {
   const searchDirs = opts.searchDirs || []
-  const found = findSpecFolder(specArg, dir, searchDirs)
+  const preferDirs = opts.preferDirs || []
+  const found = findSpecFolder(specArg, dir, searchDirs, preferDirs)
   if (!found) {
     // Name the roots we looked under: the usual cause is a spec that only exists
     // on its own branch, and the message should say where we didn't find it.
     throw new Error(
-      `spec not found under specs/**: ${specArg} (searched: ${[dir, ...searchDirs].join(', ')})`,
+      `spec not found under specs/**: ${specArg} ` +
+        `(searched: ${[...preferDirs, dir, ...searchDirs].join(', ')})`,
     )
   }
 
@@ -255,9 +475,70 @@ function resolveSpec(specArg, dir, config, opts = {}) {
   }
 }
 
+/**
+ * Every worktree git knows about, as absolute paths — the primary checkout
+ * included, since `git worktree list` reports it as one.
+ *
+ * `git` is an injected reader, as everywhere else in this file: the caller owns
+ * the child-process boundary, which is what keeps this module testable without
+ * one.
+ */
+function liveWorktreePaths(git) {
+  const out = git(['worktree', 'list', '--porcelain'])
+  const paths = new Set()
+  if (out == null) return paths
+  for (const line of out.split('\n')) {
+    if (line.startsWith('worktree ')) {
+      paths.add(path.resolve(line.slice('worktree '.length).trim()))
+    }
+  }
+  return paths
+}
+
+// An in-progress spec lives on its *worktree branch*, not the primary checkout,
+// so we must scan the worktrees too — otherwise a live spec's DB looks orphaned.
+function collectSpecFolders(roots) {
+  const folders = new Set()
+  for (const root of roots) {
+    for (const bucket of BUCKETS) {
+      let entries
+      try {
+        entries = fs.readdirSync(path.join(root, 'specs', bucket), { withFileTypes: true })
+      } catch {
+        continue
+      }
+      for (const entry of entries) if (entry.isDirectory()) folders.add(entry.name)
+    }
+  }
+  return folders
+}
+
+/**
+ * Resolve every spec folder (found in the primary checkout OR any worktree) to
+ * `{ folder, slug, worktreePath }`. `searchDirs` lets `resolveSpec` locate a
+ * spec that was authored on its branch and never committed to the primary
+ * checkout.
+ */
+function allSpecs(dir, config, worktreePaths) {
+  const searchDirs = [...worktreePaths]
+  const specs = []
+  for (const folder of collectSpecFolders([dir, ...searchDirs])) {
+    try {
+      const spec = resolveSpec(folder, dir, config, { searchDirs })
+      specs.push({ folder: spec.folder, slug: spec.slug, worktreePath: spec.worktreePath })
+    } catch {
+      // Unresolvable folder (not a real spec) — skip.
+    }
+  }
+  return specs
+}
+
 module.exports = {
   BUCKETS,
   resolveSpec,
+  liveWorktreePaths,
+  collectSpecFolders,
+  allSpecs,
   resolveBaseBranch,
   resolvePrimaryCheckout,
   currentBranch,
@@ -267,6 +548,12 @@ module.exports = {
   repoInfo,
   expandTokens,
   findSpecFolder,
+  readPhases,
+  phaseIsDone,
+  phaseIsStarted,
+  parsePhase,
+  readOverview,
+  readFrontmatterField,
   readStackField,
   readBaseVersionField,
 }