@skitterbyte/skitterspec-linear 12.0.0 → 13.0.0

package/src/env/building.js

@@ -0,0 +1,143 @@
+'use strict'
+
+/**
+ * The primary-checkout leak guard.
+ *
+ * A phase can be built in a worktree from a session standing somewhere else —
+ * every write an absolute path, every command `cd`-prefixed. That works;
+ * `spec-env review` already reads a worktree exactly that way. What it cannot do
+ * is *prove* it worked: one relative path and the edit lands in the primary
+ * checkout, on the base branch, silently.
+ *
+ * So record what the primary checkout looked like before the build
+ * (`--record-primary`) and compare after it (`--assert-primary-clean`).
+ *
+ * The baseline is the whole point. `negative-checks.md` rule 1 asks for a
+ * positive signal rather than an absence, and "these were the dirty paths at a
+ * known moment" is one; a bare "the primary must be clean" check would accuse
+ * anyone who left an unrelated edit open in another window. Rule 4 supplies the
+ * third state: when the baseline is missing, or is for another spec, the check
+ * cannot tell — and cannot-tell reports and exits 0 rather than accusing.
+ */
+
+const path = require('node:path')
+
+// The state dir sits beside the registry file, e.g. `.spec-env` — the same
+// convention `dev.js` uses for logs and pids.
+function stateDir(config) {
+  return path.posix.dirname(config.registry) || '.spec-env'
+}
+
+/** Where the baseline lives. Gitignored with the rest of `.spec-env/`. */
+function baselinePath(dir, config) {
+  return path.join(dir, stateDir(config), 'building.json')
+}
+
+/**
+ * Merge one or more newline-separated git path listings into a sorted, deduped
+ * array. Blank lines are dropped; nothing is parsed out of the line.
+ *
+ * DELIBERATELY NOT `git status --porcelain`, for two reasons, both found by
+ * running this against a real worktree:
+ *
+ *   1. Porcelain puts the path behind two fixed status columns and a space, and
+ *      the repo's `gitReader` TRIMS its stdout — so the first line loses its
+ *      leading space and a fixed `slice(3)` eats the first character of the
+ *      first path. A guard that renames the file it is accusing you of is worse
+ *      than no guard.
+ *   2. Porcelain reports stat-dirty entries: a file whose mtime moved but whose
+ *      content is identical to HEAD. One was observed here, reported as ` M`
+ *      with an empty `git diff`. Accusing someone of leaking a file they never
+ *      changed is exactly the false accusation `negative-checks.md` exists to
+ *      prevent.
+ *
+ * `git diff --name-only HEAD` compares CONTENT, and
+ * `git ls-files --others --exclude-standard` lists genuinely new files. Between
+ * them they answer "what did this tree gain?" without a column to miscount.
+ */
+function mergePaths(...listings) {
+  const out = new Set()
+  for (const listing of listings) {
+    for (const line of String(listing || '').split('\n')) {
+      const p = line.replace(/\r$/, '').trim()
+      if (p !== '') out.add(p)
+    }
+  }
+  return [...out].sort()
+}
+
+/** Are these two paths the same tree? */
+function sameTree(a, b) {
+  return path.resolve(a) === path.resolve(b)
+}
+
+/** The record written by `--record-primary`. Pure. */
+function buildBaseline({ spec, worktreePath, primary, paths }) {
+  return { spec, worktreePath, primary, paths: [...paths].sort() }
+}
+
+/**
+ * Compare a recorded baseline against the primary checkout's current state.
+ *
+ * Three verdicts, never two (`negative-checks.md` rule 4):
+ *   - `clean`   — nothing new appeared; say nothing and exit 0.
+ *   - `leaked`  — these paths appeared since; name them and exit non-zero.
+ *   - `unknown` — the check cannot tell; say why and exit 0.
+ *
+ * Pure: every input is supplied, nothing is read from disk or git.
+ *
+ * WHAT WOULD FOOL THIS CHECK, deliberately unhandled:
+ *   - Work the build COMMITTED in the primary checkout. A commit empties the
+ *     porcelain, so a leak that was tidied away looks identical to no leak. The
+ *     guard is aimed at the actual failure mode — writes going astray mid-build,
+ *     while nothing has been committed yet — and runs before the phase commit
+ *     for that reason.
+ *   - A write to a GITIGNORED path in the primary (`.spec-env/` itself, build
+ *     output, `node_modules`). `git status` cannot see it, by design, and the
+ *     baseline file lives in exactly such a path so that recording it is not
+ *     itself a change the next comparison trips over.
+ *   - A path dirty at record time and then edited FURTHER by the build. It is in
+ *     the baseline, so it stays silent. That is the deliberate trade: silence
+ *     there costs a missed edit to a file someone was already working on, and
+ *     the opposite default accuses every healthy concurrent edit.
+ */
+function compare(baseline, currentPaths, { spec, worktreePath, primary }) {
+  if (sameTree(primary, worktreePath)) {
+    return {
+      verdict: 'unknown',
+      paths: [],
+      reason: 'the worktree IS the primary checkout — there is no second tree to leak into',
+    }
+  }
+  if (!baseline) {
+    return { verdict: 'unknown', paths: [], reason: 'no baseline recorded' }
+  }
+  if (baseline.spec !== spec) {
+    return {
+      verdict: 'unknown',
+      paths: [],
+      reason: `the baseline was recorded for ${baseline.spec}, not ${spec}`,
+    }
+  }
+  if (!sameTree(baseline.worktreePath, worktreePath)) {
+    return {
+      verdict: 'unknown',
+      paths: [],
+      reason: 'the baseline records a different worktree for this spec',
+    }
+  }
+  const before = new Set(baseline.paths || [])
+  const appeared = [...currentPaths].filter((p) => !before.has(p)).sort()
+  return appeared.length === 0
+    ? { verdict: 'clean', paths: [], reason: null }
+    : { verdict: 'leaked', paths: appeared, reason: null }
+}
+
+module.exports = {
+  stateDir,
+  baselinePath,
+  mergePaths,
+  sameTree,
+  buildBaseline,
+  compare,
+}

package/src/env/config.js

@@ -27,7 +27,6 @@
  *     dev:      [ { name, command, portVar, health?, frontPort? } ],  // host dev
  *               // servers started on the spec's port block (empty = none)
  *     proxy:    { enabled, host },  // bundled front-door proxy (spec-env connect)
- *     open:     { command },   // optional, editor/terminal-agnostic opener
  *     registry: ".spec-env/registry.json",
  *     branch:   { pattern, identifierField },  // git branch naming (provider-neutral)
  *     spec:     { companionPaths: [ "path", ... ] },  // paths that belong to a
@@ -86,7 +85,6 @@ const DEFAULT_CONFIG = Object.freeze({
   // Front-door proxy (`spec-env connect`): a bundled Node reverse proxy that
   // exposes one connected spec's frontPort processes on the canonical ports.
   proxy: Object.freeze({ enabled: true, host: '127.0.0.1' }),
-  open: Object.freeze({ command: '' }),
   registry: '.spec-env/registry.json',
   // Git branch naming, provider-neutral. `pattern` expands {type}/{slug} and,
   // when a tracker provider is linked, {identifier}; `identifierField` names the
@@ -104,11 +102,31 @@ const DEFAULT_CONFIG = Object.freeze({
   baseBranch: '',
   guards: Object.freeze({ refuseTeardownIfDirty: true, refuseTeardownIfUnpushed: true }),
   // Teardown cleanup beyond this machine. `deleteRemoteBranch` decides what
-  // `spec-env down` does about the branch `/spec-start` pushed: "prompt" (default)
+  // `spec-env down` does about a branch the USER published by hand — nothing
+  // publishes one at provisioning, so there is often no remote ref at all and
+  // the plan then says nothing: "prompt" (default)
   // plans the delete in its own confirm-first section for the skill to ask about,
   // "never" omits it, "always" folds it into the run-blind command list. Only ever
   // planned for a LANDED branch — see teardown.js.
   teardown: Object.freeze({ deleteRemoteBranch: 'prompt' }),
+
+  // `reader` decides how a diff's location is worded, and — via
+  // `serveOnRemote` — whether the engine stands the local server up so a remote
+  // reader gets a link that opens. It never decides to PUBLISH: publishing
+  // leaves a page this tooling cannot remove, so it stays an explicit ask.
+  // `detect` sniffs; `local`/`remote` are the operator's own answer and are
+  // believed without sniffing, because they know where they are reading and no
+  // signal can outrank that.
+  // `commitWith` names the skill a COMMITTING verdict hands off to. `/commit`
+  // ships with skittership, a different package — so it may not be installed,
+  // and skitterspec must never vendor a copy of it.
+  //
+  // There is no off switch, and that is deliberate: `"none"` existed and was
+  // removed, because it produced the one thing a review page must not have —
+  // a verdict that records itself and does nothing. A review is the guard in
+  // front of an action; recording an approval for SOMEONE ELSE to act on is a
+  // different mechanism, not a value of this key.
+  review: Object.freeze({ reader: 'detect', servePort: 7777, serveOnRemote: true, commitWith: '/commit' }),
   // Live overlay (`spec-env live`). `migrations` is a list of globs marking
   // migration files; a branch that changes any of them is treated as stateful and
   // `live take` refuses it (code-only v1). Default: none (nothing is stateful).
@@ -135,13 +153,13 @@ function defaults() {
     setup: [],
     dev: [],
     proxy: { ...DEFAULT_CONFIG.proxy },
-    open: { ...DEFAULT_CONFIG.open },
     registry: DEFAULT_CONFIG.registry,
     branch: { ...DEFAULT_CONFIG.branch },
     spec: { companionPaths: [] },
     baseBranch: DEFAULT_CONFIG.baseBranch,
     guards: { ...DEFAULT_CONFIG.guards },
     teardown: { ...DEFAULT_CONFIG.teardown },
+    review: { ...DEFAULT_CONFIG.review },
     live: { migrations: [] },
     hotfix: { ...DEFAULT_CONFIG.hotfix, targets: [] },
   }
@@ -269,11 +287,6 @@ function mergeConfig(base, parsed) {
     assign(base.proxy, parsed.proxy, 'host', 'string')
   }
 
-  if (isObject(parsed.open)) {
-    // command may be intentionally empty (no auto-open)
-    assign(base.open, parsed.open, 'command', 'string?')
-  }
-
   if (isObject(parsed.branch)) {
     assign(base.branch, parsed.branch, 'pattern', 'string')
     assign(base.branch, parsed.branch, 'identifierField', 'string')
@@ -307,6 +320,26 @@ function mergeConfig(base, parsed) {
     }
   }
 
+  // An unrecognised reader falls through to `detect`, which is the state that
+  // claims least: it can answer "unknown", and unknown is wired to today's
+  // behaviour. A typo must never become a confident `local`, because a confident
+  // `local` is exactly the dead `file://` link this key exists to prevent.
+  if (isObject(parsed.review)) {
+    const reader = parsed.review.reader
+    if (reader === 'local' || reader === 'remote' || reader === 'detect') {
+      base.review.reader = reader
+    }
+    assign(base.review, parsed.review, 'servePort', 'number')
+    // Opting OUT is the only thing this key can do — a non-boolean leaves the
+    // default in place rather than being read as a refusal, so a typo cannot
+    // quietly restore the dead `file://` link on a remote reader.
+    assign(base.review, parsed.review, 'serveOnRemote', 'boolean')
+    // An empty string leaves `/commit` standing, like every other string key
+    // here. There is nothing it could mean instead: the hand-off has no off
+    // switch, so a blank value is a typo rather than an instruction.
+    assign(base.review, parsed.review, 'commitWith', 'string')
+  }
+
   if (isObject(parsed.spec) && Array.isArray(parsed.spec.companionPaths)) {
     base.spec.companionPaths = normalizeFileList(parsed.spec.companionPaths)
   }

package/src/env/provision.js

@@ -5,15 +5,15 @@
  *
  * Given a resolved spec and its allocated slot, `planUp` returns the exact
  * side-effecting commands the `/spec-env` skill runs (`git worktree add`,
- * `docker compose up`), the rendered `.env` contents, and the expanded opener —
- * but performs no side effects itself. The caller (the CLI) reads/allocates the
+ * `docker compose up`) and the rendered `.env` contents — but performs no side
+ * effects itself. The caller (the CLI) reads/allocates the
  * registry and passes the slot; this stays deterministic and unit-testable with
  * no live git/docker.
  */
 
 const { classifyDirtyTree } = require('./classify.js')
 const { portOffset } = require('./registry.js')
-const { renderEnvFile, expandOpenCommand } = require('./render.js')
+const { renderEnvFile } = require('./render.js')
 const { expandTokens } = require('./resolve.js')
 
 /**
@@ -114,11 +114,20 @@ function listPaths(paths) {
  * tell (an unreadable git, or a hotfix, which forks from a tag predating its own
  * spec), and routes to carrying on, never to refusing.
  *
+ * FOREIGN DIRT IS THE SAME ASYMMETRY, for the same reason. Another spec's
+ * uncommitted work refuses in checkout mode, where `git switch -c` would carry
+ * it onto the new branch, and does not in worktree mode, where nothing carries
+ * anywhere. Refusing there fired on the commonest tree this workflow produces —
+ * author spec B while spec A is still uncommitted, then start B — and prevented
+ * nothing, since the only write to the primary checkout is a pathspec-limited
+ * commit of this spec's own paths. It is reported instead, on `foreign`.
+ *
  * ctx: { dirtyPaths?, clean?, specOnFork?, specFoundOn?, forkRef?, specUntracked? }
- * @returns {{blocked: boolean, reason: string|null, commands: string[]}}
+ * @returns {{blocked: boolean, reason: string|null, commands: string[],
+ *            owned: string[], foreign: string[]}}
  */
 function planSpecCommit(spec, ctx, config, { carriesChanges = false } = {}) {
-  const ok = { blocked: false, reason: null, commands: [], owned: [], verb: null }
+  const ok = { blocked: false, reason: null, commands: [], owned: [], verb: null, foreign: [] }
   const c = ctx || {}
 
   if (!Array.isArray(c.dirtyPaths)) {
@@ -140,15 +149,30 @@ function planSpecCommit(spec, ctx, config, { carriesChanges = false } = {}) {
 
   const { owned, foreign } = classifyDirtyTree(spec, c.dirtyPaths, config)
 
-  if (foreign.length) {
+  // FOREIGN DIRT REFUSES ONLY WHERE IT CAN REACH THE BRANCH, which is checkout
+  // mode and nowhere else. `git switch -c` carries the working tree onto the new
+  // branch, silently, so there it is someone else's work being moved without
+  // them asking. `git worktree add` carries nothing and forks from a commit, so
+  // in worktree mode the same tree is simply none of this run's business.
+  //
+  // WHAT WOULD MAKE THIS UNSAFE AGAIN: an unbounded commit. The only thing this
+  // run does to the primary checkout is the spec commit below, and it is safe to
+  // leave a colleague's files sitting beside it only because that commit is
+  // pathspec-limited on BOTH halves (`git add --`, `git commit … --`) and so
+  // cannot reach a path it does not own — not even one another session has
+  // already staged into the shared index. Drop the `--` and this stops being a
+  // false guard and starts being a missing one.
+  if (foreign.length && carriesChanges) {
     return {
       blocked: true,
       reason:
         `the primary checkout has uncommitted changes that are not ${spec.folder}'s — ` +
-        'commit or stash them first' +
-        (carriesChanges ? ' (switching would carry them onto the new branch)' : '') +
+        'commit or stash them first (switching would carry them onto the new branch)' +
         `: ${listPaths(foreign)}`,
       commands: [],
+      owned: [],
+      verb: null,
+      foreign,
     }
   }
 
@@ -165,20 +189,34 @@ function planSpecCommit(spec, ctx, config, { carriesChanges = false } = {}) {
         ? c.specUntracked
         : owned.includes(`specs/${spec.bucket}/${spec.folder}`)
     const verb = isNew ? 'add' : 'update'
+    // BOTH HALVES ARE PATHSPEC-LIMITED, and they answer different failures.
+    // `add` is what makes a path git has never seen committable at all — every
+    // brand-new spec folder is untracked. The `--` on the COMMIT is what bounds
+    // what lands: a checkout has one `.git/index` and every session standing in
+    // it shares that index, so a bare `git commit` takes whatever another
+    // session has already staged, however exactly this one named its own paths.
+    // Dropping the `--` would leave the naming above as decoration.
+    const paths = owned.map((p) => `"${p}"`).join(' ')
     return {
       blocked: false,
       reason: null,
       owned,
       verb,
+      foreign,
       commands: [
-        `git add ${owned.map((p) => `"${p}"`).join(' ')}`,
-        `git commit -m "chore(spec): ${verb} ${spec.folder}"`,
+        `git add -- ${paths}`,
+        `git commit -m "chore(spec): ${verb} ${spec.folder}" -- ${paths}`,
       ],
     }
   }
 
   // Tree is clean. The spec must already be in the base branch's tree, or the
   // worktree forks without it.
+  // Nothing of this spec's is uncommitted, but somebody else's may be — say so
+  // rather than returning the bare `ok`, or the caller has no way to report what
+  // it left alone.
+  if (foreign.length && c.specOnFork !== false) return { ...ok, foreign }
+
   if (c.specOnFork === false) {
     return {
       blocked: true,
@@ -201,7 +239,7 @@ function planSpecCommit(spec, ctx, config, { carriesChanges = false } = {}) {
  *                       existed in the registry (re-run → attach, don't clobber).
  * @param {object} config normalised env config.
  * @returns {object} { worktreePath, branch, projectName, slot, portOffset,
- *                     envContents, openCommand, commands, seedCommands,
+ *                     envContents, commands, seedCommands,
  *                     setupCommands, attached }
  */
 function planUp(spec, alloc, config, ctx) {
@@ -228,7 +266,6 @@ function planUp(spec, alloc, config, ctx) {
     portOffset: offset === null ? '' : String(offset),
   }
 
-  const openCommand = expandOpenCommand(config.open.command, tokens)
 
   // File seeding runs *in the worktree* after `git worktree add`, before the
   // setup commands (which may depend on the seeded .env). Each entry becomes an
@@ -276,13 +313,16 @@ function planUp(spec, alloc, config, ctx) {
     blocked: gate.blocked,
     reason: gate.reason,
     specCommit: gate.owned && gate.owned.length ? { paths: gate.owned, verb: gate.verb } : null,
+    // What this run deliberately did not touch. Carried out rather than dropped
+    // because "provisioned, and left four of your files alone" is a different
+    // report from "provisioned", and the caller cannot reconstruct it.
+    untouched: gate.foreign || [],
     worktreePath: spec.worktreePath,
     branch: spec.branch,
     projectName: spec.projectName,
     slot: wantsDocker ? slot : null,
     portOffset: offset,
     envContents,
-    openCommand,
     commands: gate.blocked ? [] : [...gate.commands, ...commands],
     seedCommands: gate.blocked ? [] : seedCommands,
     setupCommands: gate.blocked ? [] : setupCommands,
@@ -306,8 +346,7 @@ function planUp(spec, alloc, config, ctx) {
  *    about someone else's unfinished spec. Being on THIS spec's branch is not a
  *    refusal — it is the re-run, and the answer is "already attached".
  *
- * There is no bootstrap and no opener: the primary checkout already has its
- * dependencies, and no new session is being opened.
+ * There is no bootstrap: the primary checkout already has its dependencies.
  */
 function planCheckoutUp(spec, ctx, config) {
   const base = ctx.base || (config && config.baseBranch) || 'main'

package/src/env/proxy.js

@@ -141,7 +141,40 @@ async function waitListening(
   return false
 }
 
-module.exports = { renderRoutes, createRouteServer, startProxy, portsInUse, waitListening }
+
+/**
+ * Ask whether `port` is free on EVERY host it will need, one host at a time.
+ *
+ * SEQUENTIAL IS THE WHOLE POINT, and it is not a style choice. The probe works
+ * by binding, so two probes of the same port running concurrently contend with
+ * each other — and on Linux a wildcard bind and a loopback bind of one port are
+ * mutually exclusive, so the pair reports a completely free port as busy. The
+ * review server then refused to start on every Linux machine, which is to say
+ * on CI, while every macOS run stayed green because BSD lets the two coexist.
+ *
+ * Probing one host at a time asks the question that was always intended — is
+ * anything ELSE holding this port — instead of racing the caller against
+ * itself. Verified on node:24-alpine: parallel reports busy on a free port,
+ * sequential does not; both still refuse a real squatter on either address.
+ *
+ * `probe` is injectable so the concurrency can be asserted without sockets.
+ */
+async function portsInUseOn(port, hosts, probe = portsInUse) {
+  const busy = []
+  for (const host of [...new Set(hosts)]) {
+    busy.push(...(await probe([port], host)))
+  }
+  return [...new Set(busy)]
+}
+
+module.exports = {
+  renderRoutes,
+  createRouteServer,
+  startProxy,
+  portsInUse,
+  portsInUseOn,
+  waitListening,
+}
 
 // Entry point: run as a detached process by the CLI. Reads its routes from a
 // file so a re-`connect` just rewrites the file and restarts this (tiny) process.

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 }