@skitterbyte/skitterspec 22.3.2 → 22.4.0

package/assets/core/env.config.md

@@ -90,7 +90,17 @@ through to a documented conservative default; see the field notes below.
     "projectNamePattern": "{repoSlug}_{slug}", // → COMPOSE_PROJECT_NAME
     "portBase": 3000,          // first port of slot 0's block
     "portsPerSpec": 10,        // block width; slot n → portBase + n*portsPerSpec
-    "envFile": ".env",         // written into the worktree
+    // Written into the worktree, and passed to compose as `--env-file`. A
+    // Docker spec's worktree steps run in this order: seedFiles, this env file
+    // (COMPOSE_PROJECT_NAME and PORT_OFFSET appended only where missing, so a
+    // value `setup` or you put there is kept), `setup`, then
+    // `docker compose … up -d` — all from inside the worktree, so the stack
+    // reads this spec's values and not the primary checkout's.
+    // It must be a file of its OWN: if it is also in `seedFiles` as a symlink,
+    // the write is refused rather than send this spec's port block into the
+    // primary checkout's file. Name a different file here (".worktree.env")
+    // and have your compose file read the values from it.
+    "envFile": ".env",
     "backupCommand": ""        // optional pre-teardown backup (e.g. pg_dump);
                               // empty = no backup, volumes dropped directly.
   },
@@ -116,6 +126,8 @@ through to a documented conservative default; see the field notes below.
   // `local.settings.json`, `config/local.yml`.
   // Seeded files are gitignored, so they never make the worktree "dirty" and
   // never block teardown; they vanish with the worktree at `spec-env down`.
+  // On a Docker project, do not seed `docker.envFile` as a symlink — the env
+  // file step refuses to write through one (see `envFile` above).
   // [] (or absent) = seed nothing (current behaviour).
   "seedFiles": {
     "mode": "symlink",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skitterbyte/skitterspec",
-  "version": "22.3.2",
+  "version": "22.4.0",
   "description": "Spec-driven development for Claude Code \u2014 a tracker-free filesystem workflow: lifecycle skills and per-spec isolation. For Linear sync, install @skitterbyte/skitterspec-linear instead.",
   "keywords": [
     "claude",

package/src/cli.js

@@ -1097,21 +1097,20 @@ function specEnvUp(dir, config, specArg, flags = {}) {
   out.push('')
   out.push('  to provision, run:')
   for (const cmd of plan.commands) out.push(`    ${cmd}`)
-  // Seed files first (setup may depend on them), then the setup commands —
-  // both run in the worktree, under one heading.
-  const worktreeSteps = [...plan.seedCommands, ...plan.setupCommands]
+  // Everything after the fork runs in the worktree, under one heading, in the
+  // order each step depends on the last: seeds (the env file may be one), the
+  // env file, setup (which may derive values into it), and only then the stack.
+  const worktreeSteps = [
+    ...plan.seedCommands,
+    ...(plan.envCommands || []),
+    ...plan.setupCommands,
+    ...(plan.dockerCommands || []),
+  ]
   if (worktreeSteps.length) {
     out.push('')
     out.push('  then, in the worktree, run:')
     for (const cmd of worktreeSteps) out.push(`    ${cmd}`)
   }
-  if (plan.envContents) {
-    out.push('')
-    out.push(`  write ${config.docker.envFile} in the worktree:`)
-    for (const line of plan.envContents.replace(/\n$/, '').split('\n')) {
-      out.push(`    ${line}`)
-    }
-  }
   process.stdout.write(out.join('\n') + '\n')
 }
 

package/src/env/provision.js

@@ -4,8 +4,8 @@
  * Pure provisioning planner for `spec-env up`.
  *
  * 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`) and the rendered `.env` contents — but performs no side
+ * side-effecting commands the `/spec-env` skill runs (`git worktree add`, the
+ * env file, `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.
@@ -73,6 +73,50 @@ function seedCommandFor(file, mode) {
 }
 
 
+// Single-quote a value for POSIX sh: the only character that needs escaping
+// inside single quotes is the single quote itself.
+function shq(value) {
+  return `'${String(value).replace(/'/g, `'\\''`)}'`
+}
+
+/**
+ * Build one idempotent POSIX-sh command that writes the spec's env file in the
+ * current worktree (the cwd when the skill runs it).
+ *
+ * It was prose once — "write <envFile> in the worktree:" — which left the write
+ * to whoever read the plan, and a secrets guard that blocks any tool call naming
+ * `.env` refused it. As a command it is one more step the plan runs.
+ *
+ * Idempotent and additive: it `touch`es the file and appends each key only when
+ * no line already sets it, so a re-run changes nothing and a file `setup` has
+ * already written to keeps every value it holds — including a deliberate
+ * `PORT_OFFSET` of its own.
+ *
+ * A SYMLINK IS REFUSED, loudly. Seeding links gitignored files from the primary
+ * checkout, so a seeded env file is the primary checkout's own; appending
+ * through it would write this spec's port block into the main stack's
+ * configuration. It runs after the seeds precisely so that collision is caught
+ * rather than hidden. The fix is a `docker.envFile` naming a file of its own.
+ */
+function envFileCommandFor(envFile, projectName, offset) {
+  const f = shq(envFile)
+  const ensure = (key, value) =>
+    `{ grep -q '^${key}=' ${f} || echo ${shq(`${key}=${value}`)} >> ${f}; }`
+  return (
+    `if [ -L ${f} ]; then echo ${shq(
+      `env file ${envFile} 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",
+    )} >&2; exit 1; fi; ` +
+    `touch ${f} && ` +
+    // A file without a trailing newline would glue the first appended key onto
+    // its last line.
+    `{ [ ! -s ${f} ] || [ -z "$(tail -c 1 ${f})" ] || echo >> ${f}; } && ` +
+    `${ensure('COMPOSE_PROJECT_NAME', projectName)} && ` +
+    `${ensure('PORT_OFFSET', offset)} && ` +
+    `echo ${shq(`env file ${envFile}: ready`)}`
+  )
+}
+
 // Cap a path list in a message: enough to recognise, not a wall of text.
 function listPaths(paths) {
   const shown = paths.slice(0, 5).join(', ')
@@ -294,8 +338,10 @@ function resolveStack(spec, config, { docs = false, composeFilePresent } = {}) {
  * @param {object} config normalised env config.
  * @param {object} opts  { docs } — documents mode (see below). Optional.
  * @returns {object} { worktreePath, branch, projectName, slot, portOffset,
- *                     envContents, commands, seedCommands,
- *                     setupCommands, docs, attached }
+ *                     envContents, commands, seedCommands, envCommands,
+ *                     setupCommands, dockerCommands, docs, attached }
+ *
+ * The worktree steps run in that order: seeds, env file, setup, compose.
  */
 function planUp(spec, alloc, config, ctx, opts = {}) {
   const { slot, attached } = alloc
@@ -367,12 +413,24 @@ function planUp(spec, alloc, config, ctx, opts = {}) {
       ? `git worktree add ${spec.worktreePath} ${spec.branch}`
       : `git worktree add ${spec.worktreePath} -b ${spec.branch}${forkPoint}`,
   )
-  if (wantsDocker) {
-    commands.push(
-      `docker compose${composeFileArg(config, ctx ? ctx.composeFilePresent : undefined)}` +
-        ` --project-name ${spec.projectName} up -d`,
-    )
-  }
+  // The stack comes up LAST, in the worktree: after the seeds, after the env
+  // file, after `setup` — which may derive values into that file. It once ran
+  // from the primary checkout before the worktree existed, so compose read the
+  // primary checkout's env file, fell back to its defaults and collided with the
+  // main stack. `--env-file` is always passed: with the default `.env` it is what
+  // compose would have found anyway, and with any other name it is the only way
+  // compose finds it.
+  const envFile = (config.docker && config.docker.envFile) || '.env'
+  const envCommands = wantsDocker
+    ? [`${guard}; ${envFileCommandFor(envFile, spec.projectName, offset)}`]
+    : []
+  const dockerCommands = wantsDocker
+    ? [
+        `${guard}; docker compose` +
+          composeFileArg(config, ctx ? ctx.composeFilePresent : undefined) +
+          ` --env-file ${shq(envFile)} --project-name ${spec.projectName} up -d`,
+      ]
+    : []
 
   // The tree gate. A worktree forks from the base branch's tree, so an
   // uncommitted spec would produce a branch missing the spec it is for — this is
@@ -398,11 +456,13 @@ function planUp(spec, alloc, config, ctx, opts = {}) {
     envContents,
     commands: gate.blocked ? [] : [...gate.commands, ...commands],
     seedCommands: gate.blocked ? [] : seedCommands,
+    envCommands: gate.blocked ? [] : envCommands,
     // Documents mode drops these, and keeps the seed commands above. The two are
     // not the same kind of thing: seeding links the gitignored files a worktree
     // has none of — cheap, and a spec author may well want `.env` present —
     // while `setup` is the expensive half that exists to make the tree run.
     setupCommands: gate.blocked || docs ? [] : setupCommands,
+    dockerCommands: gate.blocked ? [] : dockerCommands,
     // Reported so a caller reading `--json` can tell a documents worktree from a
     // full one POSITIVELY, rather than inferring it from what is missing. An
     // empty `setupCommands` also describes a project that configured no setup
@@ -481,6 +541,7 @@ module.exports = {
   planCheckoutUp,
   planSpecCommit,
   seedCommandFor,
+  envFileCommandFor,
   worktreeCd,
   resolveStack,
   composeFileArg,

package/src/env/teardown.js

@@ -94,6 +94,10 @@ function planDown(spec, config, flags, ctx) {
   }
 
   // --- docker compose down (drop volumes unless kept) ---
+  // Run from the primary checkout with no `--env-file`, unlike `up`, and on
+  // purpose: compose finds the stack's containers, networks and volumes by the
+  // project label `--project-name` gives it, so it needs nothing from the env
+  // file — which may already be gone with a half-removed worktree.
   if (wantsDocker) {
     const base =
       `docker compose${composeFileArg(config, ctx ? ctx.composeFilePresent : undefined)}` +