@skitterbyte/skitterspec 22.4.0 → 23.0.0

package/src/cli.js

@@ -29,6 +29,7 @@ const ENV_CONFIG_LABEL = 'env.config.json'
 // their own lines below.
 const SPEC_ENV_VERBS = Object.freeze([
   'up',
+  'bootstrap',
   'down',
   'prune',
   'dev',
@@ -94,6 +95,9 @@ const {
   reviewUrlPath,
   reviewPublishPath,
   readReviewUrl,
+  readRemoteAllow,
+  writeRemoteAllow,
+  withSpecRemote,
   publishedPageNotice,
   reviewServerNotice,
   renderReviewFragment,
@@ -144,7 +148,8 @@ const {
   cacheHit,
   asCached,
 } = require('./env/reviewers.js')
-const { planUp, planCheckoutUp, worktreeCd, resolveStack } = require('./env/provision.js')
+const { planUp, planCheckoutUp, resolveStack, worktreeSteps } = require('./env/provision.js')
+const { runBootstrap, describeStep } = require('./env/bootstrap.js')
 const { classifyDirtyTree, dirtyPaths, specDocsIn } = require('./env/classify.js')
 const { isGitCommit } = require('./env/commitcmd.js')
 const { planDown, planDownCheckout } = require('./env/teardown.js')
@@ -210,6 +215,10 @@ Usage:
                                                   Docker stack (prints commands; creates nothing)
                                                   --docs: a tree to write documents in — no
                                                   setup commands, no Docker
+                                bootstrap [spec]  run the worktree's seeds, env file, setup
+                                                  and stack itself, in the worktree — after
+                                                  \`up\`'s worktree add (--docs: seeds only;
+                                                  --plan: describe, run nothing; --json)
                                 nospec <name>     record a branch with no spec document
                                                   (/no-spec work) and print its plan
                                 main <check|allow|status>
@@ -666,8 +675,17 @@ function specEnvMain(dir, config, positional, flags = {}, present = true, invoke
     // checkout before it runs, so asking `dir` whether it is the primary
     // checkout always answers yes — and the guard would fire on a write inside
     // somebody's worktree, which is the one place it must never fire.
+    //
+    // `--path` is the file being written, and where it is given it decides: a
+    // write outside the primary checkout is none of this guard's business,
+    // whichever directory the session happens to be standing in.
     const from = invokedFrom || dir
-    const verdict = checkMainWrite(from, config, gitReader(from), { sessionId, present })
+    const verdict = checkMainWrite(from, config, gitReader(from), {
+      sessionId,
+      present,
+      target: flags.path ? path.resolve(from, flags.path) : null,
+      gitAt: gitReader,
+    })
     if (!verdict.refuse) return
     process.stdout.write(`spec-env main: ${verdict.reason}\n`)
     process.exitCode = 1
@@ -802,9 +820,6 @@ function specEnvNospec(dir, config, name, flags = {}) {
   const trust = ensureWorktreeDirTrusted(dir, worktreeRootAbs)
   const attached = fs.existsSync(spec.worktreePath)
 
-  const guard = worktreeCd(spec.worktreePath)
-  const setupCommands = (config.setup || []).map((cmd) => `${guard}; ${cmd}`)
-
   const out = [
     `spec-env nospec: ${name} ` +
       (attached ? '(plan — worktree exists; will attach)' : '(plan — nothing created yet)'),
@@ -832,11 +847,7 @@ function specEnvNospec(dir, config, name, flags = {}) {
       ? `    git worktree add ${spec.worktreePath} ${spec.branch}`
       : `    git worktree add ${spec.worktreePath} -b ${spec.branch}`,
   )
-  if (setupCommands.length) {
-    out.push('')
-    out.push('  then, in the worktree, run:')
-    for (const cmd of setupCommands) out.push(`    ${cmd}`)
-  }
+  if ((config.setup || []).length) out.push(...bootstrapLines(name))
   if (flags.json) {
     process.stdout.write(
       JSON.stringify(
@@ -1097,21 +1108,189 @@ function specEnvUp(dir, config, specArg, flags = {}) {
   out.push('')
   out.push('  to provision, run:')
   for (const cmd of plan.commands) out.push(`    ${cmd}`)
-  // 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 || []),
+  // Everything after the fork runs in the worktree, and the engine runs it: one
+  // line naming the verb, never the steps as shell (see `specEnvBootstrap`).
+  if (plan.steps.length) out.push(...bootstrapLines(spec.folder, { docs }))
+  process.stdout.write(out.join('\n') + '\n')
+}
+
+/**
+ * `spec-env bootstrap [<spec>]` — bring a provisioned worktree to ready.
+ *
+ * Runs the steps `up` once printed as shell for the caller to copy —
+ * seeds, the env file, `setup`, the stack — itself, with the worktree as cwd.
+ * The caller's command line is `skitterspec spec-env bootstrap <name>` and
+ * nothing more, so no `.env` path ever appears in it: there is nothing for a
+ * secrets hook to refuse, and nothing for an agent to rewrite on the way.
+ *
+ * IT DOES NOT FORK. `git worktree add` and the spec's own commit stay `up`'s,
+ * printed and run as before; this verb starts where they finish, so re-running
+ * one step later — `setup` after a lockfile change — costs no re-plan.
+ *
+ * Refuses BEFORE ACTING, non-zero, when there is nothing to bootstrap yet: no
+ * worktree on disk, or a docker spec with no registry slot (its port block
+ * would be derived from nothing). Both name `spec-env up`.
+ *
+ * Specless (`/no-spec`) work runs `setup` only — `nospec` has never seeded and
+ * still does not. Checkout mode has no worktree and says so, exit 0: the
+ * primary checkout already has its dependencies.
+ */
+function specEnvBootstrap(dir, config, specArg, flags = {}) {
+  const docs = flags.docs === true
+  const json = flags.json === true
+  const say = (line) => process.stdout.write(line + '\n')
+  const refuse = (msg) => {
+    if (json) say(JSON.stringify({ ok: false, refused: msg }, null, 2))
+    else say(`spec-env bootstrap: ${msg}`)
+    process.exitCode = 1
+  }
+
+  if (config.mode === 'checkout') {
+    say(
+      'spec-env bootstrap: checkout mode has no worktree to bootstrap — the primary ' +
+        'checkout already has its dependencies.',
+    )
+    return
+  }
+
+  const spec = resolveSpecWithWorktree(dir, config, specArg)
+  const name = spec.folder
+
+  if (!fs.existsSync(spec.worktreePath)) {
+    refuse(
+      `no worktree at ${spec.worktreePath} — run \`skitterspec spec-env up ${name}\` ` +
+        'and the worktree add it prints first.',
+    )
+    return
+  }
+  // The primary checkout answering as the worktree would seed every file onto
+  // itself and report `exists — skipped`, indistinguishable from a healthy
+  // re-run, while `setup` ran against the base branch.
+  if (sameDir(spec.worktreePath, dir)) {
+    refuse(`${spec.worktreePath} is the primary checkout, not ${name}'s worktree.`)
+    return
+  }
+
+  let steps
+  // A `/no-spec` record — not the authoring record `up --docs` writes for a
+  // spec not yet on disk, which is a spec and plans like one.
+  if (spec.specless && !spec.unwritten) {
+    steps = docs ? [] : (config.setup || []).map((command) => ({ kind: 'setup', command }))
+  } else {
+    const compose = composeFilePresent(dir, config)
+    const { wantsDocker } = resolveStack(spec, config, { docs, composeFilePresent: compose })
+    let offset = null
+    if (wantsDocker) {
+      const slots = readRegistry(dir, config).slots || {}
+      if (!Object.prototype.hasOwnProperty.call(slots, name)) {
+        refuse(
+          `${name} wants a Docker stack and has no slot yet — run ` +
+            `\`skitterspec spec-env up ${name}\` first.`,
+        )
+        return
+      }
+      offset = portOffset(slots[name], config)
+    }
+    steps = worktreeSteps(spec, offset, config, {
+      docs,
+      wantsDocker,
+      composeFilePresent: compose,
+    })
+  }
+
+  if (flags.plan) {
+    if (json) {
+      say(
+        JSON.stringify(
+          { spec: name, worktree: spec.worktreePath, docs, planned: true, steps },
+          null,
+          2,
+        ),
+      )
+      return
+    }
+    say(`spec-env bootstrap: ${name} (plan — nothing run)`)
+    say('')
+    say(`  worktree:  ${spec.worktreePath}`)
+    if (!steps.length) say('  steps:     none — nothing configured to run')
+    else steps.forEach((st, i) => say(`  ${i + 1}. ${describeStep(st)}`))
+    return
+  }
+
+  if (!json) {
+    say(`spec-env bootstrap: ${name}`)
+    say(`  worktree:  ${spec.worktreePath}`)
+  }
+  const result = runBootstrap(steps, {
+    cwd: spec.worktreePath,
+    mainRoot: dir,
+    // Report lines go to stdout as plain text; under --json they are carried in
+    // the payload instead, and spawned output is moved to stderr with them.
+    write: json ? () => {} : (line) => say(`  ${line}`),
+    childStdout: json ? process.stderr : 'inherit',
+  })
+
+  if (json) {
+    say(
+      JSON.stringify(
+        {
+          spec: name,
+          worktree: spec.worktreePath,
+          docs,
+          planned: false,
+          ok: result.ok,
+          failedAt: result.failedAt,
+          steps: result.results.map((r) => ({ ...r.step, outcome: r.outcome, line: r.line })),
+          remaining: steps.slice(result.results.length),
+        },
+        null,
+        2,
+      ),
+    )
+  } else if (result.ok) {
+    say(
+      steps.length
+        ? `spec-env bootstrap: ${name} ready (${steps.length} step${steps.length === 1 ? '' : 's'})`
+        : `spec-env bootstrap: ${name} — nothing to do (no seedFiles, setup or stack configured)`,
+    )
+  } else {
+    const failed = result.results[result.results.length - 1]
+    process.stderr.write(`  ${failed.line}\n`)
+    say(
+      `spec-env bootstrap: stopped at step ${result.failedAt} of ${steps.length} ` +
+        `(${describeStep(failed.step)}) — nothing after it ran.`,
+    )
+  }
+  if (!result.ok) process.exitCode = 1
+}
+
+/**
+ * The hand-off from a planner to `spec-env bootstrap`: the one command a caller
+ * runs once the worktree exists.
+ *
+ * ONE LINE, AND NO SHELL. The worktree steps used to be printed here as
+ * POSIX-sh one-liners, and an agent copying them rewrote them — merged two seeds
+ * into a loop, reworded the echo text — at which point a consumer's secrets hook
+ * refused the `.env` paths in the rewrite. This line names no file at all, so it
+ * has nothing to rewrite and nothing to refuse. `bootstrap --plan` is where the
+ * steps can still be read.
+ */
+function bootstrapLines(name, { docs = false } = {}) {
+  return [
+    '',
+    '  then, run:',
+    `    skitterspec spec-env bootstrap ${name}${docs ? ' --docs' : ''}`,
   ]
-  if (worktreeSteps.length) {
-    out.push('')
-    out.push('  then, in the worktree, run:')
-    for (const cmd of worktreeSteps) out.push(`    ${cmd}`)
+}
+
+// Two spellings of one directory — `/tmp` and `/private/tmp` on macOS — are
+// the same directory. Cannot-tell (either missing) is "not the same".
+function sameDir(a, b) {
+  try {
+    return fs.realpathSync(a) === fs.realpathSync(b)
+  } catch {
+    return false
   }
-  process.stdout.write(out.join('\n') + '\n')
 }
 
 /**
@@ -1732,7 +1911,8 @@ function specEnvIntegrate(dir, config, specArg) {
     }
     if (cplan.noop) {
       process.stdout.write(
-        `spec-env integrate: ${spec.folder} already landed on ${base} — nothing to integrate.\n`,
+        `spec-env integrate: ${spec.folder} already landed on ${base} — nothing to integrate.\n` +
+          afterLandSection(cplan.afterLand),
       )
       return
     }
@@ -1740,7 +1920,7 @@ function specEnvIntegrate(dir, config, specArg) {
                   `  base:      ${base}`, `  branch:    ${cplan.branch}`, '',
                   '  run these (abort the rebase on conflict):']
     for (const cmd of cplan.commands) cout.push(`    ${cmd}`)
-    process.stdout.write(cout.join('\n') + '\n')
+    process.stdout.write(cout.join('\n') + '\n' + afterLandSection(cplan.afterLand))
     return
   }
 
@@ -1829,7 +2009,8 @@ function specEnvIntegrate(dir, config, specArg) {
   }
   if (plan.noop) {
     process.stdout.write(
-      `spec-env integrate: ${spec.folder} already landed on ${base} — nothing to integrate.\n`,
+      `spec-env integrate: ${spec.folder} already landed on ${base} — nothing to integrate.\n` +
+        afterLandSection(plan.afterLand),
     )
     return
   }
@@ -1843,7 +2024,17 @@ function specEnvIntegrate(dir, config, specArg) {
   out.push('')
   out.push('  run these (abort the rebase on conflict):')
   for (const cmd of plan.commands) out.push(`    ${cmd}`)
-  process.stdout.write(out.join('\n') + '\n')
+  process.stdout.write(out.join('\n') + '\n' + afterLandSection(plan.afterLand))
+}
+
+// The `afterLand` commands, as a section printed after a land plan — or after
+// integrate's already-landed line. Empty string when none apply, so a project
+// without the key sees exactly the output it always has.
+function afterLandSection(afterLand) {
+  if (!afterLand || !afterLand.commands || afterLand.commands.length === 0) return ''
+  const out = ['', `  then, in the primary checkout (${afterLand.cwd}), run (stop at the first failure):`]
+  for (const cmd of afterLand.commands) out.push(`    ${cmd}`)
+  return out.join('\n') + '\n'
 }
 
 // Land a hotfix: tag the branch with the patch-bumped base tag (the prod deploy
@@ -1931,7 +2122,7 @@ function specEnvHotfix(dir, config, positional, flags) {
   for (const cmd of plan.commands) out.push(`    ${cmd}`)
   out.push('')
   out.push(`  then push the deploy tag yourself:  git push origin ${plan.prodTag}`)
-  process.stdout.write(out.join('\n') + '\n')
+  process.stdout.write(out.join('\n') + '\n' + afterLandSection(plan.afterLand))
 }
 
 // What the primary checkout has GAINED right now, by content. `dir` is already
@@ -2526,24 +2717,32 @@ function specEnvReviewGate(dir, config, specArg, flags, invokedFrom = dir) {
 }
 
 /**
- * `review allow <network|remote> [--off]` — permit or withdraw a review tier.
+ * `review allow <network|remote> [<spec>] [--off | --set <on|off|>] [--project]`
+ * — permit or withdraw a review tier.
  *
- * THE FIRST THING IN THIS ENGINE TO WRITE `env.config.json`, and that is why it
- * is narrow: it reads, sets one key under `review`, and writes back with the
- * indent the file already uses. It never reorders, never adds a key nobody
- * asked for, and never touches another section.
+ * TWO SCOPES, because the two tiers are different kinds of decision.
+ *
+ * `network` is a BIND, and one server binds for every spec at once — so it is a
+ * project setting and lives in the committed `env.config.json`.
  *
- * WHAT WOULD FOOL THIS: a config written with comments. `loadEnvConfig` parses
- * it with `JSON.parse`, so such a file already fails to load and there is no
- * comment-preserving case to protect — but a file indented with anything other
- * than two spaces IS reformatted, which is cosmetic and worth knowing before it
- * shows up in someone's diff.
+ * `remote` PERMITS PUBLISHING, which sends one spec's diff to a third party. It
+ * was project-wide too, and that was bug-remote-review-toggle: typed from a
+ * worktree with a review waiting, it dirtied the base branch's committed config
+ * and permitted every other spec in the repo to publish as well. So it is now
+ * PER SPEC — a sidecar in the gitignored review store, layered over the
+ * committed key by `withSpecRemote`. `--project` keeps the committed write for
+ * a team that wants it everywhere.
  *
- * IT EDITS A COMMITTED FILE. Turning network reviews on for yourself turns them
- * on for everyone who pulls, so the output says so rather than leaving it to be
- * discovered by a colleague's render.
+ * THE COMMITTED WRITE IS NARROW: it reads, sets one key under `review`, and
+ * writes back with two-space indent. It never reorders, never adds a key nobody
+ * asked for, and never touches another section.
+ *
+ * WHAT WOULD FOOL THIS: a config indented with anything other than two spaces
+ * IS reformatted by the committed write — cosmetic, but worth knowing before it
+ * shows up in someone's diff. A config with comments already fails to load, so
+ * there is no comment-preserving case to protect.
  */
-function specEnvReviewAllow(dir, config, tier, flags) {
+function specEnvReviewAllow(dir, config, tier, specArg, flags) {
   const TIERS = { network: 'allowNetwork', remote: 'allowRemote' }
   const key = TIERS[String(tier || '').trim()]
   if (!key) {
@@ -2556,39 +2755,63 @@ function specEnvReviewAllow(dir, config, tier, flags) {
     process.exitCode = 1
     return
   }
-  // THREE WAYS TO SAY WHAT THE TIER SHOULD BE, and only the third is new.
-  // Bare `allow <tier>` turns it ON and `--off` turns it off, exactly as they
-  // always have — every existing caller and test reads those.
-  //
-  // `--set` exists because a SLASH COMMAND can only make one static
-  // substitution: `/spec-remote-review on` has to reach the engine as the word
-  // the person typed, not as a flag the command file worked out. An EMPTY value
-  // is the bare form of that command, and it toggles — which is the common case,
-  // because a reader flipping a tier is looking at the line that says which way
-  // it currently is.
+
+  // WHICH SPEC, for the per-spec scope — resolved before anything is read, so a
+  // refusal changes nothing. An unknown name throws rather than falling back:
+  // permitting the wrong spec to publish looks exactly like permitting the
+  // right one.
+  const perSpec = key === 'allowRemote' && !flags.project
+  let spec = null
+  let out = null
+  if (perSpec) {
+    try {
+      spec = resolveSpecWithWorktree(dir, config, specArg)
+    } catch (err) {
+      process.stdout.write(
+        `spec-env review allow: ${err.message}\n` +
+          '  remote is permitted per spec — name it, or run this from its worktree.\n' +
+          '  --project permits every spec instead (writes the committed env.config.json).\n' +
+          '  Nothing changed.\n',
+      )
+      process.exitCode = 1
+      return
+    }
+    out = reviewOutPath(dir, spec.folder, null)
+  }
+
+  // What the tier is now, through the same precedence the render uses — so a
+  // toggle means "the other thing the render showed".
+  const file = path.resolve(dir, 'specs/.core/env.config.json')
+  const committed = () => {
+    try {
+      const now = JSON.parse(fs.readFileSync(file, 'utf8'))
+      return now.review && now.review[key] !== undefined ? now.review[key] : config.review[key]
+    } catch {
+      return config.review[key]
+    }
+  }
+  const current = () => {
+    if (perSpec) {
+      const own = readRemoteAllow(out)
+      if (own !== null) return own
+    }
+    return Boolean(committed())
+  }
+
+  // THREE WAYS TO SAY WHAT THE TIER SHOULD BE. Bare `allow <tier>` turns it ON
+  // and `--off` turns it off, exactly as they always have. `--set` exists
+  // because a SLASH COMMAND can only make one static substitution: the word the
+  // person typed reaches the engine as a word. An EMPTY value toggles.
   let on = !flags.off
   if (flags.set !== undefined) {
     const said = String(flags.set).trim().toLowerCase()
     if (said === '') {
-      // Toggle. Read through the same precedence the report below uses, so
-      // "turn it to the other thing" means the other thing the render showed.
-      const current = Boolean(
-        (() => {
-          try {
-            const now = JSON.parse(fs.readFileSync(path.resolve(dir, 'specs/.core/env.config.json'), 'utf8'))
-            return now.review && now.review[key] !== undefined ? now.review[key] : config.review[key]
-          } catch {
-            return config.review[key]
-          }
-        })(),
-      )
-      on = !current
+      on = !current()
     } else if (said === 'on' || said === 'off') {
       on = said === 'on'
     } else {
-      // Refused by name, like an unknown tier. A misspelt state coerced to a
-      // default is the one outcome worth more than a round trip — and the
-      // wrong default here opens a port or permits a publish.
+      // Refused by name, like an unknown tier. The wrong default here opens a
+      // port or permits a publish.
       process.stdout.write(
         `spec-env review allow: ${JSON.stringify(String(flags.set))} is not a state — ` +
           'one of on, off, or nothing at all to toggle. Nothing changed.\n',
@@ -2597,58 +2820,77 @@ function specEnvReviewAllow(dir, config, tier, flags) {
       return
     }
   }
-  const file = path.resolve(dir, 'specs/.core/env.config.json')
-  let parsed
-  try {
-    parsed = JSON.parse(fs.readFileSync(file, 'utf8'))
-  } catch (err) {
-    // Cannot tell what is in there, so write nothing. Overwriting a config we
-    // could not read is unrecoverable, and the alternative costs one message.
-    //
-    // NARROWER THAN IT LOOKS: `loadEnvConfig` already refuses the whole
-    // `spec-env` command on an unparseable config, naming the file and the
-    // parse position — so this branch is reachable only if the file changes
-    // between that load and this write. It is kept for that race rather than
-    // deleted as dead, and the upstream refusal is what the test asserts.
-    process.stdout.write(
-      `spec-env review allow: ${file} could not be read as JSON (${err.message}) — ` +
-        'nothing changed.\n',
-    )
-    process.exitCode = 1
-    return
+
+  const before = current()
+  let wrote
+  if (perSpec) {
+    wrote = writeRemoteAllow(out, on)
+  } else {
+    let parsed
+    try {
+      parsed = JSON.parse(fs.readFileSync(file, 'utf8'))
+    } catch (err) {
+      // Cannot tell what is in there, so write nothing. Reachable only if the
+      // file changes between `loadEnvConfig` and here — that load already
+      // refuses an unparseable config.
+      process.stdout.write(
+        `spec-env review allow: ${file} could not be read as JSON (${err.message}) — ` +
+          'nothing changed.\n',
+      )
+      process.exitCode = 1
+      return
+    }
+    parsed.review = { ...(parsed.review || {}), [key]: on }
+    fs.writeFileSync(file, JSON.stringify(parsed, null, 2) + '\n')
+    wrote = file
   }
-  const before = Boolean(
-    parsed.review && parsed.review[key] !== undefined ? parsed.review[key] : config.review[key],
-  )
-  parsed.review = { ...(parsed.review || {}), [key]: on }
-  fs.writeFileSync(file, JSON.stringify(parsed, null, 2) + '\n')
 
   const lines = [
-    `spec-env review allow: ${tier} reviews are now ${on ? 'ON' : 'OFF'}` +
+    `spec-env review allow: ${tier} reviews${spec ? ` for ${spec.folder}` : ''} are now ${on ? 'ON' : 'OFF'}` +
       (before === on ? ' (unchanged)' : ''),
-    // THE ABSOLUTE PATH, not one relative to `dir`. `dir` is re-anchored to the
-    // primary checkout, so run from inside a worktree this writes a file in a
-    // DIFFERENT TREE — and a relative path reads as the tree you are standing
-    // in. Found by running it from a worktree and reverting the surprise.
-    `  wrote: ${file}`,
-    '  that is the primary checkout, whichever tree you ran this from, and the file is',
-    '  COMMITTED — so it changes for everyone who pulls, and leaves that tree dirty.',
+    // THE ABSOLUTE PATH. `dir` is re-anchored to the primary checkout, so run
+    // from a worktree this writes in a different tree — and a relative path
+    // reads as the tree you are standing in.
+    `  wrote: ${wrote}`,
   ]
+  if (perSpec) {
+    lines.push('  this spec only, in the gitignored review store — the committed config is untouched.')
+  } else {
+    lines.push(
+      '  that is the primary checkout, whichever tree you ran this from, and the file is',
+      '  COMMITTED — so it changes for everyone who pulls, and leaves that tree dirty.',
+    )
+  }
   if (key === 'allowNetwork') {
     lines.push(
       on
         ? '  the next render binds every interface, so the page opens on your phone.'
         : '  the next render binds 127.0.0.1 only, reachable from this machine.',
     )
+  } else if (!on) {
+    lines.push(
+      '  publishing is no longer permitted; any page already published stays up.\n' +
+        '  turn it back on with: /spec-remote-review',
+    )
   } else {
     lines.push(
-      on
-        ? '  this PERMITS publishing; it publishes nothing. A published page cannot be\n' +
-          '  deleted by skitterspec, and a verdict there needs /spec-reviewed.\n' +
-          '  turn it back off with: /spec-remote-review'
-        : '  publishing is no longer permitted; any page already published stays up.\n' +
-          '  turn it back on with: /spec-remote-review',
+      '  a published page cannot be deleted by skitterspec,\n' +
+        '  and a verdict there needs /spec-reviewed.\n' +
+        '  turn it back off with: /spec-remote-review',
     )
+    // THE REVIEW IT WAS TYPED FOR. The banner names this command beside a page
+    // the reader cannot reach, so turning remote on is the ask to publish THAT
+    // page — and saying nothing about it left the reader with no link at all.
+    // A page on disk is the positive signal; with none there is nothing to
+    // publish, and nothing is named.
+    if (spec && fs.existsSync(out)) {
+      lines.push(
+        `  review:   ${spec.folder} has a page — publish it and re-show the stack`,
+        `  publish:  skitterspec spec-env review ${spec.folder} --publish-copy`,
+      )
+    } else {
+      lines.push('  this PERMITS publishing; it publishes nothing.')
+    }
   }
   process.stdout.write(lines.join('\n') + '\n')
 }
@@ -2761,6 +3003,9 @@ async function specEnvReview(dir, config, specArg, flags, invokedFrom = dir) {
   // CHECKOUT, keyed by the spec's folder name; not one byte of it comes from
   // the worktree. `--out` moves the page and its sidecars together.
   const out = reviewOutPath(dir, spec.folder, flags.out)
+  // This spec's own remote permission over the project default — a
+  // per-worktree decision, never the committed config (bug-remote-review-toggle).
+  config = withSpecRemote(config, out)
 
   // The other half of a confirmation: a pass the operator says is not theirs.
   // Left in the store it is reported on every render until they stop reading the
@@ -5064,6 +5309,7 @@ async function specEnv(rest) {
     else if (args[i] === '--stop') flags.stop = true
     else if (args[i] === '--rotate-token') flags.rotateToken = true
     else if (args[i] === '--off') flags.off = true
+    else if (args[i] === '--project') flags.project = true
     else if (args[i] === '--status') flags.status = true
     else if (args[i] === '--port') flags.port = args[++i]
     else if (args[i] === '--host') flags.host = args[++i]
@@ -5094,8 +5340,10 @@ async function specEnv(rest) {
     else if (args[i] === '--phase') flags.phase = args[++i]
     else if (args[i] === '--record-primary') flags.recordPrimary = true
     else if (args[i] === '--docs') flags.docs = true
+    else if (args[i] === '--plan') flags.plan = true
     else if (args[i] === '--from') flags.from = args[++i]
     else if (args[i] === '--session') flags.session = args[++i]
+    else if (args[i] === '--path') flags.path = args[++i]
     else if (args[i] === '--assert-primary-clean') flags.assertPrimaryClean = true
     else positional.push(args[i])
   }
@@ -5168,6 +5416,9 @@ async function specEnv(rest) {
     case 'up':
       specEnvUp(dir, config, positional[0], flags)
       break
+    case 'bootstrap':
+      specEnvBootstrap(dir, config, positional[0], flags)
+      break
     case 'nospec':
       specEnvNospec(dir, config, positional[0], flags)
       break
@@ -5229,7 +5480,7 @@ async function specEnv(rest) {
         break
       }
       if (positional[0] === 'allow') {
-        specEnvReviewAllow(dir, config, positional[1], flags)
+        specEnvReviewAllow(dir, config, positional[1], positional[2], flags)
         break
       }
       if (positional[0] === 'skip') {
@@ -5249,7 +5500,8 @@ async function specEnv(rest) {
         `Usage: skitterspec spec-env <${SPEC_ENV_VERBS.join('|')}> [spec] [--keep-volumes] [--force] [--also <tag>] [--older-than <days>] [--branch] [--out <file>] [--review <json>] [--run-reviewers] [--notes <json>] [--verdict <word>] [--resolve <json>] [--outcome <text>] [--claim <code>] [--drop <code>] [--buttons <set>] [--json] [--record-primary] [--assert-primary-clean]\n` +
         '  review serve [--port <n>] [--host <addr>] [--stop] [--status]  serve every diff locally\n' +
         '  review serve --rotate-token    mint a new URL token; every handed-out link dies\n' +
-        '  review allow <network|remote> [--off]  permit a review tier (writes env.config.json)\n' +
+        '  review allow <network|remote> [<spec>] [--off] [--project]  permit a review tier\n' +
+        '                                   (network: env.config.json; remote: this spec only)\n' +
           '  review arm [spec] [--phase <n>]        a phase ended — its diff now owes a verdict\n' +
           '  review gate [spec] [--check] [--json]  is one owed? --check exits non-zero if so\n' +
           '       [--for-command <cmdline>]         ...but only when that command is a git commit\n' +