create-agentic-workspace 0.0.0 → 0.2.2

package/src/argv.mjs

@@ -0,0 +1,67 @@
+// argv.mjs — the argv parser. Its accepted long-flag set is derived from the question table AND
+// FROM NO SECOND LIST (AC-BCL-2). --help is rendered one line per table record.
+import { RefusalError } from './util.mjs';
+
+/** Parse argv against `table` (defaults to QUESTION_TABLE at call sites). Returns
+ * { values: {id: value}, provided: Set<id> }. Throws RefusalError on an unknown flag, a missing
+ * value, or an out-of-`choices` value — writing nothing is the caller's responsibility (this
+ * function performs no I/O). */
+export function parseArgv(argv, table) {
+  const byFlag = new Map(table.map((r) => [r.flag, r]));
+  const values = {};
+  const provided = new Set();
+
+  for (let i = 0; i < argv.length; i++) {
+    const tok = argv[i];
+    if (!tok.startsWith('--')) {
+      throw new RefusalError(`unexpected positional argument: ${tok}`);
+    }
+    let name = tok.slice(2);
+    let inline = null;
+    const eq = name.indexOf('=');
+    if (eq !== -1) {
+      inline = name.slice(eq + 1);
+      name = name.slice(0, eq);
+    }
+    const rec = byFlag.get(name);
+    if (!rec) {
+      throw new RefusalError(`unknown flag: --${name}`, name);
+    }
+    if (rec.type === 'boolean') {
+      values[rec.id] = inline === null ? true : inline === 'true';
+    } else {
+      let v = inline;
+      if (v === null) {
+        const next = argv[i + 1];
+        if (next === undefined || (next.startsWith('--') && next.length > 2)) {
+          throw new RefusalError(`--${rec.flag} needs a value`, rec.flag);
+        }
+        v = next;
+        i++;
+      }
+      if (rec.choices && !rec.choices.includes(v)) {
+        throw new RefusalError(
+          `--${rec.flag} must be one of: ${rec.choices.join(', ')} (got ${JSON.stringify(v)})`,
+          rec.flag,
+        );
+      }
+      values[rec.id] = v;
+    }
+    provided.add(rec.id);
+  }
+  return { values, provided };
+}
+
+/** Render one `--help` line per table record — the third leg of the flag/prompt/help bijection. */
+export function renderHelp(table, { programName = 'create-agentic-workspace' } = {}) {
+  const lines = [`Usage: ${programName} [options]`, ''];
+  for (const rec of table) {
+    const flagCol = rec.type === 'boolean' ? `--${rec.flag}` : `--${rec.flag} <value>`;
+    const req = rec.required ? ' (required)' : rec.default !== undefined && rec.default !== '' ? ` (default: ${rec.default})` : '';
+    const choices = rec.choices ? ` [choices: ${rec.choices.join('|')}]` : '';
+    lines.push(`  ${flagCol.padEnd(24)} ${rec.prompt}${choices}${req}`);
+  }
+  lines.push('');
+  lines.push('This CLI collects and transmits nothing: no telemetry.');
+  return lines.join('\n');
+}

package/src/identity.mjs

@@ -0,0 +1,155 @@
+// identity.mjs — the out-of-session identity half (AC-BCL-7), proved differentially equal to
+// `scripts/foundry-bootstrap.sh`. Every git-config write goes through `git config` in an argv
+// position — never composed/templated text — so git's own writer, quoting and locking apply, and
+// the CLI's output is byte-identical to the shell script's for the same inputs.
+import { execFileSync, execFile as execFileCb } from 'node:child_process';
+import { promisify } from 'node:util';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { RefusalError, physicalResolve } from './util.mjs';
+
+const execFileAsync = promisify(execFileCb);
+
+const SLUG_RE = /^[A-Za-z0-9._-]+$/;
+
+/** Validate a --gh-account value against the closed charset, refusing '.'/'..' (AC-BCL-7). */
+export function validateSlug(raw) {
+  if (raw === '.' || raw === '..' || !SLUG_RE.test(raw)) {
+    throw new RefusalError(
+      `invalid --gh-account slug (need ^[A-Za-z0-9._-]+$, not '.'/'..'): ${raw}`,
+      'gh-account',
+    );
+  }
+  return raw;
+}
+
+const STRIPPED_ENV_VARS = ['GH_TOKEN', 'GITHUB_TOKEN', 'GH_ENTERPRISE_TOKEN', 'GITHUB_ENTERPRISE_TOKEN', 'GH_HOST'];
+
+/** At most ONE `gh api user` invocation, timeout-bounded, jailed under its own GH_CONFIG_DIR, with
+ * the five higher-precedence token/host variables stripped from the child environment. Compares
+ * the returned `.login` against the declared slug (ASCII case-insensitive) and discards the probe
+ * WHOLE on any mismatch, parse failure, timeout, or absent `gh` — never a partial adopt. No probe
+ * output (in whole or in part) is ever written to a file, logged, or printed by this function. */
+export async function probeGhIdentity(slug, { homeDir, timeoutMs = 5000, env = process.env } = {}) {
+  // A STRING LITERAL, never an env-supplied name (PR #61 security review Risk 1). This previously
+  // read `env.FOUNDRY_TEST_GH_BIN || 'gh'`, which made the spec's "the child-process set is closed
+  // to {git, gh}, so `claude` is never spawned" literally false: anything able to set that variable
+  // — a direnv .envrc in a freshly cloned repo, an exported var, CI — chose the binary this line
+  // spawns, `claude` included. It was also DEAD: the only reference in the tree was its own
+  // definition, since the test suites inject their `gh` stub via PATH. Removed rather than guarded;
+  // an unused escape hatch is all cost.
+  const gh = 'gh';
+  const jail = path.join(homeDir, '.config', `gh-${slug}`);
+  fs.mkdirSync(jail, { recursive: true });
+  const childEnv = { ...env, GH_CONFIG_DIR: jail };
+  for (const v of STRIPPED_ENV_VARS) delete childEnv[v];
+
+  let stdout;
+  try {
+    const result = await execFileAsync(gh, ['api', 'user'], { env: childEnv, timeout: timeoutMs });
+    stdout = result.stdout;
+  } catch {
+    return null; // absent gh, non-zero exit, or timeout — degrade, no further network call
+  }
+  let data;
+  try {
+    data = JSON.parse(stdout);
+  } catch {
+    return null;
+  }
+  const login = typeof data.login === 'string' ? data.login : '';
+  if (login.toLowerCase() !== slug.toLowerCase()) return null; // whole discard, never partial
+  const name = typeof data.name === 'string' ? data.name : '';
+  const email = typeof data.email === 'string' ? data.email : '';
+  if (!name || !email) return null;
+  return { name, email };
+}
+
+function parseGitAuthor(raw) {
+  const m = /^(.*) <([^<>]+)>$/.exec(raw);
+  if (!m) {
+    throw new RefusalError(`malformed --git-author (expected 'Name <email>'): ${raw}`, 'git-author');
+  }
+  return { name: m[1], email: m[2] };
+}
+
+/** Resolve the declared "Name <email>" (AC-BCL-7 order): (1) --git-author, (2) the bounded gh
+ * probe, (3) an interactive TTY prompt, (4) fail closed. */
+export async function resolveIdentity(slug, { gitAuthor, homeDir, isTTY, promptFn } = {}) {
+  if (gitAuthor) {
+    return parseGitAuthor(gitAuthor);
+  }
+  const probed = await probeGhIdentity(slug, { homeDir });
+  if (probed) return probed;
+  if (isTTY && promptFn) {
+    const name = (await promptFn(`commit-identity name for account ${slug}: `)).trim();
+    const email = (await promptFn(`commit-identity email for account ${slug}: `)).trim();
+    if (name && email) return { name, email };
+  }
+  throw new RefusalError(
+    `could not resolve a commit identity for '${slug}' (give --git-author 'Name <email>', authenticate gh, or run interactively)`,
+    'git-author',
+  );
+}
+
+function validateIdentityValue(kind, val) {
+  if (!val) throw new RefusalError(`commit-identity ${kind} is empty (refusing to write a fabricated identity)`);
+  if (val.includes('\n')) throw new RefusalError(`commit-identity ${kind} is not single-line (refusing to write)`);
+  if (kind === 'email' && !val.includes('@')) {
+    throw new RefusalError(`commit-identity email lacks '@': ${val} (refusing to write)`);
+  }
+}
+
+/** Physically-resolved target root with a trailing separator (the <canon> Terminology term). Works
+ * even when the target does not yet exist (preview time), by resolving the longest existing
+ * ancestor and appending the missing segments (see util.physicalResolve). */
+export function canonicalTargetWithSlash(targetRoot) {
+  const real = physicalResolve(targetRoot);
+  return real.endsWith(path.sep) ? real : real + path.sep;
+}
+
+/** Describe (never execute) the three machine-scope writes wireIdentity would make — used by the
+ * preview/dry-run path (AC-BCL-3), which SHALL spawn zero child processes. */
+export function plannedMachineScopeWrites({ slug, targetRoot, homeDir }) {
+  const canon = canonicalTargetWithSlash(targetRoot);
+  const matchPrefix = os.platform() === 'darwin' ? 'gitdir/i:' : 'gitdir:';
+  const inc = path.join(homeDir, '.config', 'git', `identity-${slug}`);
+  return [
+    { scope: 'global git config (machine-wide)', description: `includeIf.${matchPrefix}${canon}.git.path -> ${inc}` },
+    { scope: 'global git config (machine-wide)', description: `includeIf.${matchPrefix}${canon}.git/.path -> ${inc}` },
+    { scope: 'per-account include file (machine-wide)', description: inc },
+  ];
+}
+
+/** Wire the three machine-scope artifacts + the repo-local useConfigOnly + the .claude/gh-identity
+ * marker, EXACTLY as `scripts/foundry-bootstrap.sh`'s seed_commit_identity/seed_gh_identity do:
+ * every git-config write goes through `git config` in an argv position (AC-BCL-7). Returns the
+ * paths written, for the caller's machine-scope-write accounting (AC-BCL-9). */
+export function wireIdentity({ slug, name, email, targetRoot, homeDir }) {
+  validateIdentityValue('name', name);
+  validateIdentityValue('email', email);
+
+  const inc = path.join(homeDir, '.config', 'git', `identity-${slug}`);
+  fs.mkdirSync(path.dirname(inc), { recursive: true });
+  execFileSync('git', ['config', '--file', inc, 'user.name', name]);
+  execFileSync('git', ['config', '--file', inc, 'user.email', email]);
+
+  const canon = canonicalTargetWithSlash(targetRoot);
+  const matchPrefix = os.platform() === 'darwin' ? 'gitdir/i:' : 'gitdir:';
+  const narrow1 = `${matchPrefix}${canon}.git`;
+  const narrow2 = `${matchPrefix}${canon}.git/`;
+  const gitConfigEnv = { ...process.env, HOME: homeDir };
+  execFileSync('git', ['config', '--global', `includeIf.${narrow1}.path`, inc], { env: gitConfigEnv });
+  execFileSync('git', ['config', '--global', `includeIf.${narrow2}.path`, inc], { env: gitConfigEnv });
+
+  const dotGitConfig = path.join(targetRoot, '.git', 'config');
+  execFileSync('git', ['config', '--file', dotGitConfig, 'user.useConfigOnly', 'true']);
+
+  const claudeDir = path.join(targetRoot, '.claude');
+  fs.mkdirSync(claudeDir, { recursive: true });
+  const marker = path.join(claudeDir, 'gh-identity');
+  fs.writeFileSync(marker, `${slug}\n`);
+
+  return { includeFile: inc, narrow1, narrow2, dotGitConfig, marker };
+}

package/src/permissionFloor.mjs

@@ -0,0 +1,179 @@
+// permissionFloor.mjs — loads the bundled map, builds the written settings.json object (a
+// verbatim declaration, never a grant — AC-BCL-4), renders the capability preview, and classifies
+// drift between the map and a target's effective settings using the AC-DPF-8 vocabulary
+// (AC-BCL-8). `covers()` agrees with tests/test_permission_floor_map.py::_subsumes on the shared
+// 8-row table by construction (same prefix-subsumption rule).
+import fs from 'node:fs';
+
+export function loadMap(mapPath) {
+  const text = fs.readFileSync(mapPath, 'utf-8');
+  return JSON.parse(text);
+}
+
+const RULE_RE = /^([A-Za-z0-9_-]+)\((.*)\)$/s;
+
+export function ruleBody(rule) {
+  const m = RULE_RE.exec(rule);
+  if (!m) return null;
+  return m[2];
+}
+
+export function ruleTool(rule) {
+  const m = RULE_RE.exec(rule);
+  return m ? m[1] : null;
+}
+
+/** covers(A, B): true if the broad rule A's reach (a `:*`-terminated prefix) subsumes rule B's
+ * body. Mirrors tests/test_permission_floor_map.py::_subsumes exactly (same prefix rule). */
+export function covers(ruleA, ruleB) {
+  const bodyA = ruleBody(ruleA);
+  if (bodyA === null || !bodyA.endsWith(':*')) return false;
+  const sA = bodyA.slice(0, -2);
+  const bodyB = ruleBody(ruleB);
+  if (bodyB === null) return false;
+  const sB = bodyB.endsWith(':*') ? bodyB.slice(0, -2) : bodyB;
+  return sB.startsWith(sA);
+}
+
+const BLANKET_BODIES = new Set(['*', 'python3 *', 'python3:*']);
+
+/** A blanket effective allow rule: one whose reach swallows the whole map (AC-DPF-3(a)'s named
+ * spellings this atom's own controls (g)(h)(i) exercise: `Bash(*)`, `Bash(python3 *)`,
+ * `Bash(python3:*)`). */
+export function isBlanketAllow(rule) {
+  const body = ruleBody(rule);
+  if (body === null) return false;
+  const stripped = body.endsWith(':*') ? body.slice(0, -2) : body;
+  return BLANKET_BODIES.has(body) || stripped === '' || stripped === '*';
+}
+
+const SCRIPTS_BASENAME_RE = /scripts\/([A-Za-z0-9_.-]+)/;
+
+/** A "ceremony" map entry (AC-DPF-8 rank 2): tier `ask` and its rule body names a scripts/
+ * basename — derived structurally, no second source of truth. */
+export function isCeremonyEntry(entry) {
+  return entry.tier === 'ask' && SCRIPTS_BASENAME_RE.test(ruleBody(entry.rule) || '');
+}
+
+export const DRIFT_CLASSES = Object.freeze([
+  'blanket-allow',
+  'ask-shadowed-ceremony',
+  'ask-shadowed',
+  'deny-missing',
+  'settings-unreadable',
+  'stale-plugin-path',
+  'allow-absent',
+  'unclassified',
+]);
+
+/** Build the settings.json object the CLI writes, verbatim from the bundled map plus the
+ * marketplace/plugin pins (AC-BCL-4). */
+export function buildSettings(map, pins) {
+  const byTier = { allow: [], ask: [], deny: [] };
+  for (const e of map.entries) {
+    byTier[e.tier].push(e.rule);
+  }
+  // THE PINNED LITERAL (AC-BCL-4(b), contract v1.2 — PR #61 security review Block 1). `ref` is
+  // load-bearing, not decoration: without it the adopter's FIRST marketplace resolution floats to
+  // whatever the default branch points at, and because the floor's allow rules are
+  // version-wildcarded (`cache/*/foundry/*/scripts/...`), the operator's single trust acceptance
+  // becomes a standing grant over whatever code that resolution delivered. That is the same
+  // floating-pin defect `autoUpdate: false` guards the LATER fetches against, left open on the
+  // first one — and strictly weaker than the manual path docs/QUICKSTART.md documents
+  // (the documented `marketplace add …#<tag>` install line). Single-sourced from
+  // the `foundry` pin block, so it cannot drift from the marketplace manifest.
+  const marketplaceEntry = {
+    source: { source: 'github', repo: pins.marketplace_repo, ref: `v${pins.plugin_version}` },
+    autoUpdate: false,
+  };
+  return {
+    permissions: { allow: byTier.allow, ask: byTier.ask, deny: byTier.deny },
+    extraKnownMarketplaces: { [pins.marketplace_name]: marketplaceEntry },
+    enabledPlugins: { [`${pins.plugin_name}@${pins.marketplace_name}`]: true },
+  };
+}
+
+/** One capability-preview line per bundled-map entry, grouped by tier, carrying rule/tier/
+ * rationale (AC-BCL-3). */
+export function renderCapabilityLines(map) {
+  const lines = [];
+  for (const tier of ['allow', 'ask', 'deny']) {
+    const entries = map.entries.filter((e) => e.tier === tier);
+    if (entries.length === 0) continue;
+    lines.push(`  [${tier}] (${entries.length} rules)`);
+    for (const e of entries) {
+      lines.push(`    - ${e.rule}  — ${e.rationale}`);
+    }
+  }
+  return lines;
+}
+
+/** Classify drift between the bundled map and a target's effective permission configuration.
+ * `effective` is { allow: [{rule, origin, tierKey}], ask: [...], deny: [...] } drawn from
+ * settings.json unioned with settings.local.json (origin-tracked, AC-BCL-8). `readable` names
+ * whether each origin file that exists parsed successfully. `pluginRootExpansion` is the list of
+ * directories `plugin_root_glob` expanded to on disk (empty => stale-plugin-path). Returns an
+ * array of finding objects `{class, ...}` using exactly the AC-DPF-8 vocabulary — no other class
+ * name is ever emitted. */
+export function classifyDrift(map, effective, { pluginRootExpansion = [], unreadableOrigins = [] } = {}) {
+  const findings = [];
+
+  for (const origin of unreadableOrigins) {
+    findings.push({ class: 'settings-unreadable', origin });
+  }
+
+  const shadowedByBlanket = new Set();
+  for (const a of effective.allow) {
+    if (isBlanketAllow(a.rule)) {
+      const swallowed = map.entries.filter((e) => e.tier !== 'allow');
+      findings.push({
+        class: 'blanket-allow',
+        rule: a.rule,
+        origin: a.origin,
+        swallows: swallowed.map((e) => e.rule),
+      });
+      for (const e of swallowed) shadowedByBlanket.add(e.rule);
+    }
+  }
+
+  for (const entry of map.entries.filter((e) => e.tier === 'ask')) {
+    if (shadowedByBlanket.has(entry.rule)) continue;
+    const coveringAllow = effective.allow.filter((a) => covers(a.rule, entry.rule));
+    if (coveringAllow.length > 0) {
+      findings.push({
+        class: isCeremonyEntry(entry) ? 'ask-shadowed-ceremony' : 'ask-shadowed',
+        rule: entry.rule,
+        coveredBy: coveringAllow.map((a) => ({ rule: a.rule, origin: a.origin, tierKey: a.tierKey })),
+      });
+    }
+  }
+
+  for (const entry of map.entries.filter((e) => e.tier === 'deny')) {
+    const coveringDeny = effective.deny.filter((d) => covers(d.rule, entry.rule) || d.rule === entry.rule);
+    if (coveringDeny.length === 0) {
+      findings.push({ class: 'deny-missing', rule: entry.rule });
+    }
+  }
+
+  if (pluginRootExpansion.length === 0) {
+    findings.push({ class: 'stale-plugin-path', glob: map.plugin_root_glob });
+  }
+
+  for (const entry of map.entries.filter((e) => e.tier === 'allow')) {
+    const coveringAllow = effective.allow.filter((a) => covers(a.rule, entry.rule) || a.rule === entry.rule);
+    if (coveringAllow.length === 0) {
+      findings.push({ class: 'allow-absent', rule: entry.rule });
+    }
+  }
+
+  for (const tierKey of ['allow', 'ask', 'deny']) {
+    for (const eff of effective[tierKey]) {
+      if (ruleBody(eff.rule) === null) {
+        const prefix = (eff.rule.split('(')[0] || '?').replace(/[^A-Za-z0-9_-]/g, '') || '?';
+        findings.push({ class: 'unclassified', toolPrefix: prefix.slice(0, 32), origin: eff.origin, tierKey });
+      }
+    }
+  }
+
+  return findings;
+}

package/src/preview.mjs

@@ -0,0 +1,55 @@
+// preview.mjs — the full preview (AC-BCL-3): every managed path + action, every machine-scope
+// write, and every capability the CLI will declare, before the first byte lands.
+import { renderCapabilityLines } from './permissionFloor.mjs';
+
+export function renderPreview({ plan, machineScopeWrites, map }) {
+  const lines = [];
+  lines.push('The following paths will be written or reconciled under the target root:');
+  for (const f of plan) {
+    lines.push(`  [${f.action}] ${f.relPath}`);
+  }
+  lines.push('');
+  if (machineScopeWrites.length > 0) {
+    lines.push('The following machine-scope writes will be made (outside the target root):');
+    for (const w of machineScopeWrites) {
+      lines.push(`  [${w.scope}] ${w.description}`);
+    }
+  } else {
+    lines.push('No machine-scope writes (no --gh-account given).');
+  }
+  lines.push('');
+  lines.push('The following capabilities will be declared (never granted — the workspace trust dialog decides):');
+  lines.push(...renderCapabilityLines(map));
+  return lines.join('\n');
+}
+
+// `isGitRepo` is computed by the CALLER and passed in, so this module stays pure (it renders text;
+// it does not probe the filesystem).
+//
+// WHY THE GIT STEP IS PRINTED AND NOT PERFORMED. A workspace that is not a git repository is a
+// dead end: the factory's whole discipline is branch-per-atom → PR → merge floor, and the setup
+// path tells the reader to apply branch protection a few steps later — which needs a repo AND a
+// remote. This CLI ALREADY writes a `.gitignore`, which means nothing without one.
+//
+// It is still printed rather than run. This CLI's contract is that it writes exactly the files it
+// previewed and nothing else; `git init` would be an un-previewed side effect, and the choice of
+// remote is genuinely the reader's. `create-vite` prints its next steps the same way, for the same
+// reason. Telling keeps the promise; doing would quietly break it.
+export const TRUST_HANDOFF_TEXT = (dir, { isGitRepo = true } = {}) => `
+The workspace has been written. The permission floor above is a declaration, not a grant: the
+platform's trust dialog is the consent ceremony, and the \`allow\` rules take effect only after
+you accept it — the dialog lists them.
+
+  cd ${dir}${isGitRepo ? '' : `
+  git init && git add -A && git commit -m 'workspace seed'
+  # ^ this directory is NOT a git repository yet. The factory works through
+  #   branch-per-atom → PR → the merge floor, so it needs a repo and a remote.
+  #   Create the remote too (e.g. \`gh repo create <you>/<project>-handbook --private --source=. --push\`)
+  #   before you reach the branch-protection step.`}
+  claude
+  > (accept the trust dialog when prompted)
+  > /foundry:init
+
+Once the session is open, run \`/foundry:doctor\` — it compares this written floor against the
+installed plugin's own copy of the map, the one independent check that did not travel through npm.
+`;

package/src/questions.mjs

@@ -0,0 +1,77 @@
+// questions.mjs — THE single question table (AC-BCL-2). Every accepted long flag, every --help
+// line and every interactive prompt are derived from this table and from no second list.
+//
+// Record shape: { id, flag, type: 'string'|'boolean', prompt, default? , required?, choices?,
+//                 interactive } — `default` XOR `required: true` (never both, never neither).
+
+export const QUESTION_TABLE = [
+  {
+    id: 'dir',
+    flag: 'dir',
+    type: 'string',
+    prompt: 'Workspace directory to create',
+    required: true,
+    interactive: true,
+  },
+  {
+    id: 'existing',
+    flag: 'existing',
+    type: 'boolean',
+    prompt: 'Target directory already exists and is non-empty (scaffold into it; never clobbers)',
+    default: false,
+    interactive: true,
+  },
+  {
+    id: 'stageMode',
+    flag: 'stage-mode',
+    type: 'string',
+    prompt: 'Stage mode',
+    default: 'lean',
+    choices: ['lean', 'scale'],
+    interactive: true,
+  },
+  {
+    id: 'ghAccount',
+    flag: 'gh-account',
+    type: 'string',
+    prompt: 'GitHub account slug for commit-identity isolation (blank to skip)',
+    default: '',
+    interactive: true,
+  },
+  {
+    id: 'gitAuthor',
+    flag: 'git-author',
+    type: 'string',
+    prompt: 'Git author "Name <email>" (blank: try gh, then prompt, then fail closed — only used with --gh-account)',
+    default: '',
+    interactive: true,
+  },
+  {
+    id: 'yes',
+    flag: 'yes',
+    type: 'boolean',
+    prompt: 'Accept every default and the write-phase confirmation without prompting',
+    default: false,
+    interactive: false,
+  },
+  {
+    id: 'dryRun',
+    flag: 'dry-run',
+    type: 'boolean',
+    prompt: 'Print the preview only; make no write and no side effect',
+    default: false,
+    interactive: false,
+  },
+  {
+    id: 'help',
+    flag: 'help',
+    type: 'boolean',
+    prompt: 'Show this help and exit',
+    default: false,
+    interactive: false,
+  },
+];
+
+export function tableFlags(table = QUESTION_TABLE) {
+  return table.map((r) => r.flag);
+}

package/src/reconcile.mjs

@@ -0,0 +1,47 @@
+// reconcile.mjs — the ONE write path: terraform-init reconcile shape, shared by a greenfield
+// create, an --existing scaffold-into, and an idempotent re-run (AC-BCL-8/AC-BCL-9). A managed
+// path that is absent is created; one that exists and matches is left untouched (no write
+// syscall at all — bytes/inode/mtime survive); one that exists and differs is reported `drifted`
+// and NEVER written, on any path, in any mode (never-clobber is unconditional).
+import { ensureDirFor, fileBytesEqual } from './util.mjs';
+import fs from 'node:fs';
+
+/** Compute the action for each managed file WITHOUT writing anything. */
+export function planManagedFiles(managedFiles) {
+  return managedFiles.map((f) => {
+    const { present, equal, notRegular } = fileBytesEqual(f.absPath, f.bytes);
+    let action;
+    if (!present) action = 'create';
+    else if (notRegular) action = 'drifted';
+    else action = equal ? 'unchanged' : 'drifted';
+    return { ...f, action };
+  });
+}
+
+/** Apply a plan: writes ONLY the `create` rows. `unchanged`/`drifted` rows are never touched —
+ * this is what makes never-clobber unconditional and re-runs byte/inode/mtime-stable. */
+export function applyPlan(plan) {
+  for (const f of plan) {
+    if (f.action !== 'create') continue;
+    ensureDirFor(f.absPath);
+    // O_EXCL ('wx'), not a plain write (PR #61 security review Block 2, defence in depth). The
+    // plan already refuses to emit `create` for any path that exists — including a dangling
+    // symlink, since fileBytesEqual lstats rather than existsSync's. 'wx' makes the WRITE itself
+    // refuse a target that came into existence between plan and apply, so the never-clobber
+    // guarantee does not rest on the plan/apply window being atomic. A plain write would follow a
+    // symlink planted in that window; this one fails with EEXIST instead.
+    const fd = fs.openSync(f.absPath, 'wx');
+    try {
+      fs.writeFileSync(fd, f.bytes);
+    } finally {
+      fs.closeSync(fd);
+    }
+  }
+  return plan;
+}
+
+/** The total exit-code matrix (AC-BCL-8): 0 unless >=1 row is `drifted`, in which case 2. Refusals
+ * are a distinct path (exit 1) handled by the caller before any plan is computed. */
+export function exitCodeForPlan(plan) {
+  return plan.some((f) => f.action === 'drifted') ? 2 : 0;
+}