@skitterbyte/skitterspec 22.4.0 → 23.0.0

package/src/env/bootstrap.js

@@ -0,0 +1,188 @@
+'use strict'
+
+/**
+ * Run a worktree's bootstrap steps — the engine half of `spec-env bootstrap`.
+ *
+ * `planUp` decides WHAT a fresh worktree needs (`worktreeSteps`); this module
+ * does it. Seeds and the env file are plain filesystem work, done here with
+ * `fs` and no shell at all. `setup` commands and the stack are spawned with the
+ * worktree as their cwd.
+ *
+ * WHY THE ENGINE RUNS THEM. These steps used to be printed as shell for the
+ * agent to run, and an agent does not copy shell faithfully. A consumer's
+ * secrets hook refuses any Bash call naming a `.env` file, with one exception
+ * for the exact printed shape — so every rewrite was refused, and the retry was
+ * refused again by auto mode as a workaround. The call that replaces them,
+ * `skitterspec spec-env bootstrap <name>`, names no file at all.
+ *
+ * Behaviour is the printed commands' behaviour, kept exactly: idempotent, one
+ * `seeded …` / `… — skipped` line per seed, a seed missing from the primary
+ * checkout is skipped rather than failed, a symlinked env file is refused before
+ * anything is written through it, and the run stops at the first failing step.
+ *
+ * Every side effect goes through `io`, so the tests drive it with a real temp
+ * directory and a fake spawn — no docker, no package manager.
+ */
+
+const realFs = require('node:fs')
+const path = require('node:path')
+const { spawnSync } = require('node:child_process')
+
+/** One line describing a step, for `--plan` and for the failure report. */
+function describeStep(step) {
+  switch (step.kind) {
+    case 'seed':
+      return `seed ${step.file} (${step.mode} from the primary checkout)`
+    case 'envFile':
+      return `env file ${step.file} (COMPOSE_PROJECT_NAME, PORT_OFFSET)`
+    case 'setup':
+      return `setup: ${step.command}`
+    case 'docker':
+      return `docker: ${step.argv.join(' ')}`
+    default:
+      return `unknown step ${step.kind}`
+  }
+}
+
+// `lstat` that answers null for a missing path rather than throwing.
+function lstatOrNull(fs, p) {
+  try {
+    return fs.lstatSync(p)
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Seed one gitignored file from the primary checkout.
+ *
+ * The source is tested with `existsSync`, which follows links — a dangling
+ * link in the primary checkout is "not in main", exactly as `[ -e ]` read it.
+ * The target is tested with `lstat`, which does not: an existing link, even a
+ * dangling one, is somebody's deliberate state and is left alone.
+ */
+function runSeed(step, { cwd, mainRoot, fs }) {
+  const src = path.join(mainRoot, step.file)
+  const dst = path.join(cwd, step.file)
+  if (!fs.existsSync(src)) {
+    return { outcome: 'skipped', line: `seed ${step.file}: not in main — skipped` }
+  }
+  if (lstatOrNull(fs, dst)) {
+    return { outcome: 'skipped', line: `seed ${step.file}: exists — skipped` }
+  }
+  fs.mkdirSync(path.dirname(dst), { recursive: true })
+  if (step.mode === 'copy') fs.copyFileSync(src, dst)
+  else fs.symlinkSync(src, dst)
+  return { outcome: 'seeded', line: `seeded ${step.file} → ${src}` }
+}
+
+/**
+ * Make sure the spec's env file sets its project name and port block.
+ *
+ * Additive: a key is appended only when no line already sets it, so a re-run
+ * writes nothing and a file `setup` already wrote to keeps every value it holds
+ * — a deliberate `PORT_OFFSET` of its own included.
+ *
+ * A SYMLINK IS REFUSED, before anything is written. Seeding links gitignored
+ * files from the primary checkout, so a seeded env file IS the primary
+ * checkout's own, and appending through it would write this spec's port block
+ * into the main stack's configuration. The fix is a `docker.envFile` naming a
+ * file of its own.
+ */
+function runEnvFile(step, { cwd, fs }) {
+  const p = path.join(cwd, step.file)
+  const st = lstatOrNull(fs, p)
+  if (st && st.isSymbolicLink()) {
+    return {
+      outcome: 'refused',
+      line:
+        `env file ${step.file} is a symlink — docker.envFile must name a file of its own, ` +
+        "not a seeded one; refusing to write this spec's port block through it",
+    }
+  }
+  const before = st ? fs.readFileSync(p, 'utf8') : ''
+  let add = ''
+  // A file without a trailing newline would glue the first appended key onto
+  // its last line.
+  const sep = before.length && !before.endsWith('\n') ? '\n' : ''
+  for (const [key, value] of [
+    ['COMPOSE_PROJECT_NAME', step.projectName],
+    ['PORT_OFFSET', step.offset],
+  ]) {
+    if (!new RegExp(`^${key}=`, 'm').test(before)) add += `${key}=${value}\n`
+  }
+  if (!st || add) {
+    fs.mkdirSync(path.dirname(p), { recursive: true })
+    fs.writeFileSync(p, before + (add ? sep + add : ''))
+  }
+  return { outcome: add ? 'written' : 'skipped', line: `env file ${step.file}: ready` }
+}
+
+/**
+ * Spawn a setup command (through the shell — it is the project's own command
+ * line) or the stack (an argv, no shell).
+ *
+ * `stdout` is where the child's own output goes: inherited normally, so an
+ * install streams as it runs, and moved to stderr under `--json` so the payload
+ * on stdout stays parseable.
+ */
+function runSpawned(step, { cwd, spawn, childStdout }) {
+  const stdio = ['ignore', childStdout, 'inherit']
+  const res =
+    step.kind === 'setup'
+      ? spawn(step.command, { cwd, shell: true, stdio })
+      : spawn(step.argv[0], step.argv.slice(1), { cwd, stdio })
+  if (res.error) {
+    return { outcome: 'failed', line: `${describeStep(step)} — ${res.error.message}` }
+  }
+  if (res.status !== 0) {
+    const why = res.status === null ? `killed by ${res.signal || 'a signal'}` : `exit ${res.status}`
+    return { outcome: 'failed', line: `${describeStep(step)} — ${why}` }
+  }
+  return { outcome: 'ran', line: null }
+}
+
+/**
+ * Run `steps` in order in `cwd`, stopping at the first that fails.
+ *
+ * io: { cwd, mainRoot, fs?, spawn?, write?, childStdout? }
+ *   - `write(line)` receives every report line as it happens
+ *   - `childStdout` is the stdio slot for spawned output ('inherit' default)
+ *
+ * Returns { ok, results: [{ step, outcome, line }], failedAt } — `failedAt` is
+ * the 1-based index of the step that stopped the run, or null.
+ */
+function runBootstrap(steps, io) {
+  const ctx = {
+    cwd: io.cwd,
+    mainRoot: io.mainRoot,
+    fs: io.fs || realFs,
+    spawn: io.spawn || spawnSync,
+    childStdout: io.childStdout || 'inherit',
+  }
+  const write = io.write || (() => {})
+  const results = []
+  for (let i = 0; i < steps.length; i++) {
+    const step = steps[i]
+    // A spawned step announces itself BEFORE it runs, so the streamed output
+    // that follows has a heading.
+    if (step.kind === 'setup' || step.kind === 'docker') write(describeStep(step))
+    let r
+    try {
+      if (step.kind === 'seed') r = runSeed(step, ctx)
+      else if (step.kind === 'envFile') r = runEnvFile(step, ctx)
+      else if (step.kind === 'setup' || step.kind === 'docker') r = runSpawned(step, ctx)
+      else r = { outcome: 'failed', line: describeStep(step) }
+    } catch (err) {
+      r = { outcome: 'failed', line: `${describeStep(step)} — ${err.message}` }
+    }
+    results.push({ step, ...r })
+    if (r.line && r.outcome !== 'failed' && r.outcome !== 'refused') write(r.line)
+    if (r.outcome === 'failed' || r.outcome === 'refused') {
+      return { ok: false, results, failedAt: i + 1 }
+    }
+  }
+  return { ok: true, results, failedAt: null }
+}
+
+module.exports = { runBootstrap, describeStep }

package/src/env/config.js

@@ -24,6 +24,9 @@
  *               // setup runs (mode: "symlink" default | "copy"); empty = none
  *     setup:    [ "cmd", ... ],  // bootstrap commands run in the worktree right
  *               // after `git worktree add` (e.g. install deps); empty = none
+ *     afterLand:[ "cmd", ... ],  // commands run in the PRIMARY checkout after a
+ *               // land (integrate's ff, hotfix land's main cherry-pick), e.g. a
+ *               // data migration; literal, no token expansion; empty = none
  *     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)
@@ -166,6 +169,12 @@ const DEFAULT_CONFIG = Object.freeze({
   // `git worktree add` (before Docker/dev), on every provision. Array of shell
   // strings (e.g. "pnpm install"); {slug}/{branch}/… expand. Default: none.
   setup: Object.freeze([]),
+  // Commands run in the primary checkout after a land, printed by `spec-env
+  // integrate` (including its already-landed no-op) and by `hotfix land` when
+  // it cherry-picks onto the base branch. The skill runs them; the engine only
+  // plans. Literal strings — no {slug}/{port} tokens, since they run on the base
+  // branch where a spec's tokens mean nothing. Default: none.
+  afterLand: Object.freeze([]),
   // Host dev servers started on the spec's port block by `spec-env dev up`.
   // Each: { name, command, portVar, health?, frontPort? }. Default: none.
   dev: Object.freeze([]),
@@ -332,6 +341,7 @@ function defaults() {
     docker: { ...DEFAULT_CONFIG.docker },
     seedFiles: { mode: DEFAULT_CONFIG.seedFiles.mode, files: [] },
     setup: [],
+    afterLand: [],
     dev: [],
     proxy: { ...DEFAULT_CONFIG.proxy },
     registry: DEFAULT_CONFIG.registry,
@@ -542,6 +552,11 @@ function mergeConfig(base, parsed) {
     base.setup = normalizeSetup(parsed.setup)
   }
 
+  // Same rule as `setup`: a stray entry is dropped, never thrown on.
+  if (Array.isArray(parsed.afterLand)) {
+    base.afterLand = normalizeSetup(parsed.afterLand)
+  }
+
   if (Array.isArray(parsed.dev)) {
     base.dev = normalizeDev(parsed.dev)
   }

package/src/env/hotfix.js

@@ -21,6 +21,7 @@
  */
 
 const path = require('node:path')
+const { afterLandFor } = require('./integrate.js')
 
 /**
  * Parse a semver-ish tag and return it with its PATCH bumped by one. Preserves any
@@ -50,7 +51,7 @@ function tagSlug(tag) {
  * @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 }
+ * @returns {object} { blocked, noop, reason, commands, afterLand, prodTag, targets, branch, base }
  */
 function planHotfixLand(spec, config, ctx) {
   const c = ctx || {}
@@ -62,6 +63,7 @@ function planHotfixLand(spec, config, ctx) {
     noop: false,
     reason: null,
     commands: [],
+    afterLand: afterLandFor(null),
     prodTag: null,
     targets: [],
     branch,
@@ -122,12 +124,16 @@ function planHotfixLand(spec, config, ctx) {
   }
 
   // 3. Cherry-pick the fix onto the base branch (main) for the next release.
+  //    Only then does the primary checkout gain anything, so only then do the
+  //    after-land commands apply — a prod-only land leaves main untouched.
+  let afterLand = result.afterLand
   if (hotfixCfg.cherryPickMain !== false) {
     commands.push(`git -C ${c.mainRepoPath} cherry-pick ${fixRange}`)
     targets.push({ kind: 'main', base: c.base })
+    afterLand = afterLandFor(config, c.mainRepoPath)
   }
 
-  return { ...result, commands, prodTag, targets, fixRange }
+  return { ...result, commands, afterLand, prodTag, targets, fixRange }
 }
 
 module.exports = { bumpPatch, tagSlug, planHotfixLand }

package/src/env/integrate.js

@@ -15,28 +15,32 @@
  * hands back — so the planner never needs to reason about conflicts.
  *
  * @param {object} spec  resolved spec: { branch, worktreePath, folder, ... }
- * @param {object} config normalised env config (unused today; kept for symmetry).
+ * @param {object} config normalised env config (reads `afterLand`).
  * In CHECKOUT mode there is no worktree: the branch is already checked out in the
  * primary checkout, so landing is a rebase in place, a switch to base, and the
  * fast-forward. `planIntegrateCheckout` below covers that; the shape of what it
  * returns is identical so callers need no second code path.
  *
  * @param {object} ctx   { worktreeState: { dirty }, base, aheadOfBase, mainRepoPath }
- * @returns {object} { blocked, noop, reason, commands, base, branch }
+ * @returns {object} { blocked, noop, reason, commands, afterLand, base, branch }
  */
 function planIntegrate(spec, config, ctx) {
   const { worktreeState = {}, base, aheadOfBase, mainRepoPath } = ctx || {}
   const branch = spec.branch
-  const result = { blocked: false, noop: false, reason: null, commands: [], base, branch }
+  const result = {
+    blocked: false, noop: false, reason: null, commands: [], afterLand: noAfterLand(), base, branch,
+  }
 
   // The completion edits must be committed first — never rebase a dirty tree.
   if (worktreeState.dirty) {
     return { ...result, blocked: true, reason: 'worktree has uncommitted changes — commit the completion first' }
   }
 
-  // Nothing on the branch that isn't already on base → already landed.
+  // Nothing on the branch that isn't already on base → already landed. The
+  // after-land commands still apply: the land may have happened on another
+  // machine or in an earlier session, leaving them pending in THIS checkout.
   if (!aheadOfBase) {
-    return { ...result, noop: true }
+    return { ...result, noop: true, afterLand: afterLandFor(config, mainRepoPath) }
   }
 
   return {
@@ -45,6 +49,7 @@ function planIntegrate(spec, config, ctx) {
       `git -C ${spec.worktreePath} rebase ${base}`,
       `git -C ${mainRepoPath} merge --ff-only ${branch}`,
     ],
+    afterLand: afterLandFor(config, mainRepoPath),
   }
 }
 
@@ -65,7 +70,9 @@ function planIntegrate(spec, config, ctx) {
 function planIntegrateCheckout(spec, config, ctx) {
   const { dirty, base, aheadOfBase, checkoutPath, onBranch } = ctx || {}
   const branch = spec.branch
-  const result = { blocked: false, noop: false, reason: null, commands: [], base, branch }
+  const result = {
+    blocked: false, noop: false, reason: null, commands: [], afterLand: noAfterLand(), base, branch,
+  }
 
   // "Already landed" is answered FIRST, before any refusal. A landed spec needs
   // no action wherever the checkout happens to be standing — and after a
@@ -73,7 +80,7 @@ function planIntegrateCheckout(spec, config, ctx) {
   // would refuse the very spec this just finished landing. /spec-complete calls
   // integrate again on exactly that state.
   if (!aheadOfBase) {
-    return { ...result, noop: true }
+    return { ...result, noop: true, afterLand: afterLandFor(config, checkoutPath) }
   }
   if (dirty) {
     return {
@@ -100,7 +107,20 @@ function planIntegrateCheckout(spec, config, ctx) {
       `git -C ${checkoutPath} switch ${base}`,
       `git -C ${checkoutPath} merge --ff-only ${branch}`,
     ],
+    afterLand: afterLandFor(config, checkoutPath),
   }
 }
 
-module.exports = { planIntegrate, planIntegrateCheckout }
+// The after-land half of a plan: `config.afterLand`, to run in `cwd` (the
+// primary checkout, standing on base) once the land commands have succeeded.
+// A blocked plan carries the empty form — nothing landed, so nothing follows.
+function afterLandFor(config, cwd) {
+  const commands = (config && Array.isArray(config.afterLand)) ? [...config.afterLand] : []
+  return { cwd: commands.length ? cwd : null, commands }
+}
+
+function noAfterLand() {
+  return { cwd: null, commands: [] }
+}
+
+module.exports = { planIntegrate, planIntegrateCheckout, afterLandFor }

package/src/env/mainguard.js

@@ -139,12 +139,61 @@ function judgeMainWrite(ctx) {
   }
 }
 
+/**
+ * The checkout a path lives in: the `--show-toplevel` of its nearest existing
+ * ancestor, or null when that is in no git repo at all.
+ *
+ * NEAREST EXISTING ANCESTOR, because a `Write` usually creates its file and
+ * often its folder too — `git -C` on a directory that does not exist yet fails,
+ * and reading that failure as "not in a repo" would wave through exactly the
+ * new file the guard exists for.
+ */
+function checkoutOf(target, gitAt) {
+  let at = path.resolve(target)
+  while (!fs.existsSync(at)) {
+    const up = path.dirname(at)
+    if (up === at) return null
+    at = up
+  }
+  if (!fs.statSync(at).isDirectory()) at = path.dirname(at)
+  return gitAt(at)(['rev-parse', '--show-toplevel'])
+}
+
+// Two spellings of one directory — `/tmp` and `/private/tmp` on macOS — are
+// the same directory. Cannot-tell is "not the same", the branch that allows.
+function sameDir(a, b) {
+  try {
+    return fs.realpathSync(a) === fs.realpathSync(b)
+  } catch {
+    return false
+  }
+}
+
+const ALLOWS = { refuse: false, reason: null, branch: null, baseBranch: null }
+
 /**
  * Gather the facts and judge. The only IO in the module's hot path.
  *
  * `git` is an injected reader, as everywhere in this package: the caller owns
  * the child-process boundary, which is what keeps `judgeMainWrite` testable
  * without one.
+ *
+ * `opts.target` is the path being written, and when it is given IT decides
+ * where the write lands — not `dir`, which is only where the session stands.
+ * Judging the session's directory refused every write a session on the base
+ * branch made anywhere, its own scratchpad under /tmp included, while a session
+ * standing in a worktree could write into the primary checkout unseen
+ * (bug-main-guard-judges-cwd). `opts.gitAt(dir)` makes a reader for another
+ * directory; it is required alongside `target`.
+ *
+ * This reads the write's LOCATION, never its name, so it is not the exception
+ * list `judgeMainWrite` refuses to grow: a path inside the primary checkout is
+ * judged exactly as before, whatever it is called.
+ *
+ * WHAT WOULD FOOL THIS: a target in ANOTHER configured repo is judged against
+ * this session's repo, so it is allowed — that repo's guard is its own sessions'
+ * business. And without `target` (an older hook, a tool with no path) the
+ * session's directory is judged as it always was.
  */
 function checkMainWrite(dir, config, git, opts = {}) {
   // `present` from `loadEnvConfig` — the caller has it and this module must not
@@ -159,27 +208,37 @@ function checkMainWrite(dir, config, git, opts = {}) {
   // looking for the absence of a worktree marker.
   let isPrimary = false
   let primary = null
+  // Which checkout's HEAD decides "on the base branch". With a target that is
+  // the primary checkout's own, wherever the session is standing.
+  let branchGit = git
   try {
     primary = resolvePrimaryCheckout(dir, git)
-    isPrimary = Boolean(primary) && path.resolve(primary) === path.resolve(dir)
+    if (opts.target && typeof opts.gitAt === 'function') {
+      const top = checkoutOf(opts.target, opts.gitAt)
+      isPrimary = Boolean(top) && Boolean(primary) && sameDir(top, primary)
+      if (!isPrimary) return ALLOWS
+      branchGit = opts.gitAt(primary)
+    } else {
+      isPrimary = Boolean(primary) && path.resolve(primary) === path.resolve(dir)
+    }
   } catch {
     // Not a git repo, or git unreadable. Cannot tell → allow.
-    return { refuse: false, reason: null, branch: null, baseBranch: null }
+    return ALLOWS
   }
 
   let onBase = false
   let branch = null
   let baseBranch = null
   try {
-    const state = assertPrimaryOnMain(config, git)
+    const state = assertPrimaryOnMain(config, branchGit)
     onBase = state.onBase
     branch = state.branch
     baseBranch = state.baseBranch
   } catch {
-    return { refuse: false, reason: null, branch: null, baseBranch: null }
+    return ALLOWS
   }
 
-  const root = isPrimary ? dir : primary || dir
+  const root = primary || dir
   const verdict = judgeMainWrite({
     configured,
     enabled,