@codedology/code-forge 0.1.0

package/src/install/wizard/answers.mjs

@@ -0,0 +1,389 @@
+/**
+ * The wizard's answers (plan §2, block B13a): what each of the nine steps proposes, from the
+ * project on disk and the machine, then an existing `.code-forge.yml` on top (so a re-run
+ * proposes what is already there — the idempotent diff), then the flags on top of that.
+ * `sources[key]` records where each answer came from: `default`, `existing` or `flag`.
+ * Pure apart from the reads in {@link gatherContext}.
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { defaultsForProvider } from '../../config/defaults/index.mjs';
+import { detectGates } from '../../gates/detect.mjs';
+import { detectAgentEnv } from '../agent-env.mjs';
+import { detectAll } from '../detect.mjs';
+import { ANSWER_FLAGS, PROVIDERS } from './flags.mjs';
+
+/** Harnesses that expose a subagent tool (§5.1: Claude Code's `Agent`, [A13]). */
+export const SUBAGENT_HARNESSES = Object.freeze(['claude']);
+
+/**
+ * `copy_untracked` proposed per stack (§2 step 8, C5). Laravel is any PHP project (`composer.json`)
+ * with an `artisan` file, whatever test runner it uses; a PHP project without one gets the plain
+ * `.env`.
+ */
+export const COPY_UNTRACKED = Object.freeze({
+  laravel: ['.env', '.env.testing'],
+  php: ['.env'],
+  node: ['.env', '.env.test'],
+  python: ['.env'],
+});
+
+/** `link_dirs` per stack: the dependency directories an export links instead of copying. */
+const LINK_DIRS = Object.freeze({
+  laravel: ['vendor', 'node_modules'],
+  php: ['vendor'],
+  node: ['node_modules'],
+  python: ['.venv'],
+  rust: ['target'],
+  go: [],
+  unknown: ['vendor', 'node_modules'],
+});
+
+/** High-risk paths per stack (v1 §2 step 8: migrations, policies, money, auth/middleware, webhooks). */
+const HIGH_PATHS = Object.freeze({
+  laravel: ['database/migrations/**', 'app/Policies/**', 'app/Http/Middleware/**', '**/*Money*', '**/*Webhook*'],
+  php: ['**/*Money*', '**/*Webhook*', '**/Auth/**'],
+  node: ['**/migrations/**', '**/auth/**', '**/*money*', '**/*webhook*'],
+  python: ['**/migrations/**', '**/auth/**', '**/*money*', '**/*webhook*'],
+  rust: ['**/auth/**', '**/*money*'],
+  go: ['**/auth/**', '**/*money*'],
+  unknown: [],
+});
+
+/**
+ * The proof profile is decided from the project, not from the gate detector's stack name alone:
+ * `detectGates` (B5) names only `php-pest`, so a Laravel app on PHPUnit reaches here as `node`
+ * (its Vite `package.json`) or `unknown` — `composer.json` + `artisan` is Laravel either way.
+ * @param {string} stack - `detectGates().stack`
+ * @param {string} cwd
+ * @returns {string} the proof profile: `laravel`, `php`, `node`, `python`, `rust`, `go` or `unknown`.
+ */
+export function proofProfile(stack, cwd) {
+  const composer = existsSync(path.join(cwd, 'composer.json'));
+  const php = stack.startsWith('php') || composer;
+  if (php && existsSync(path.join(cwd, 'artisan'))) return 'laravel';
+  if (stack.startsWith('php')) return 'php';
+  // a detected non-PHP stack keeps its word; only an undetected project falls back on composer.json
+  if (stack !== 'unknown' && Object.hasOwn(LINK_DIRS, stack)) return stack;
+  return composer ? 'php' : 'unknown';
+}
+
+/**
+ * The provider a level runs on: its own `provider` override (R5), else the default provider.
+ * @param {{provider: string, levels: Record<string, any>}} values
+ * @param {'L0'|'L1'|'L2'|'L3'} level
+ * @returns {string}
+ */
+export function effectiveProvider(values, level) {
+  const own = values.levels?.[level]?.provider;
+  return typeof own === 'string' && own.length > 0 ? own : values.provider;
+}
+
+/**
+ * Consensus review (§4.4) needs three families: reviewer 1 (the effective L2), reviewer 2
+ * (`second_provider`) and a judge (the effective L3) that shares a provider with neither
+ * (validator rule 7, `judge-family-collision`). With three providers in the catalog the judge's
+ * provider is therefore determined once both reviewers are known.
+ * @param {{provider: string, levels: Record<string, any>, multimodel: boolean, second_provider: string|null}} values
+ * @returns {{judge: string, reviewers: string[], third: string|null} | null} the collision, with
+ *   the one provider left for the judge; null when multimodel is off, the second reviewer is not
+ *   chosen yet, or the judge already differs from both reviewers.
+ */
+export function judgeCollision(values) {
+  if (values.multimodel !== true || !values.second_provider) return null;
+  const reviewers = [effectiveProvider(values, 'L2'), values.second_provider];
+  const judge = effectiveProvider(values, 'L3');
+  if (!reviewers.includes(judge)) return null;
+  return { judge, reviewers, third: PROVIDERS.find((p) => !reviewers.includes(p)) ?? null };
+}
+
+/**
+ * The judge the wizard proposes: `provider`'s shipped default L3, pinned to that provider.
+ * @param {string} provider
+ * @returns {{model: string, effort?: string, provider: string}}
+ */
+export function proposeJudge(provider) {
+  const levels = /** @type {Record<string, any>} */ (defaultsForProvider(provider)?.levels ?? {});
+  return { ...levels.L3, provider };
+}
+
+/**
+ * Step 8's proposal for a stack.
+ * @param {string} profile
+ * @returns {{high: string[], isolation: 'export', link_dirs: string[], copy_untracked: string[]}}
+ */
+export function proposeProof(profile) {
+  return {
+    high: [...(HIGH_PATHS[profile] ?? [])],
+    isolation: 'export',
+    link_dirs: [...(LINK_DIRS[profile] ?? LINK_DIRS.unknown)],
+    copy_untracked: [...(COPY_UNTRACKED[profile] ?? [])],
+  };
+}
+
+/**
+ * Variables the Codex CLI sets in the environment of the commands it runs. Source: the strings of
+ * the installed Codex CLI 0.155.1 binary on this machine (read-only `grep`, 2026-09-25), which
+ * contains `CODEX_SANDBOX` and `CODEX_SANDBOX_NETWORK_DISABLED`. User-config variables
+ * (`CODEX_HOME`, `CODEX_API_KEY`) are deliberately not here.
+ */
+export const CODEX_SESSION_VARS = Object.freeze(['CODEX_SANDBOX', 'CODEX_SANDBOX_NETWORK_DISABLED']);
+
+/**
+ * The harness the wizard runs under, from the agent env vars. Codex is recognised only by the
+ * variables it sets for its own sessions ({@link CODEX_SESSION_VARS}), never by `CODEX_HOME` or
+ * `CODEX_API_KEY`, which people set in their normal shells.
+ * @param {NodeJS.ProcessEnv} env
+ * @returns {{agent: boolean, harness: string|null}}
+ */
+export function currentHarness(env) {
+  const { source } = detectAgentEnv(env);
+  if (source === 'CLAUDECODE' || source === 'CLAUDE_CODE') return { agent: true, harness: 'claude' };
+  if (source === 'CURSOR_AGENT') return { agent: true, harness: 'cursor' };
+  if (CODEX_SESSION_VARS.some((k) => typeof env[k] === 'string' && env[k].length > 0)) return { agent: true, harness: 'codex' };
+  if (source === 'AI_AGENT') return { agent: true, harness: 'unknown' };
+  return { agent: false, harness: null };
+}
+
+/**
+ * Solo is present when `SOLO_MCP_PATH` is set or `~/.claude.json` declares an MCP server whose
+ * name contains `solo`.
+ * @param {NodeJS.ProcessEnv} env @param {string} home
+ * @returns {boolean}
+ */
+export function soloPresent(env, home) {
+  if (typeof env.SOLO_MCP_PATH === 'string' && env.SOLO_MCP_PATH.length > 0) return true;
+  try {
+    const parsed = JSON.parse(readFileSync(path.join(home, '.claude.json'), 'utf8'));
+    const servers = parsed?.mcpServers && typeof parsed.mcpServers === 'object' ? Object.keys(parsed.mcpServers) : [];
+    return servers.some((name) => /solo/i.test(name));
+  } catch {
+    return false;
+  }
+}
+
+/** @param {string} dir @returns {boolean} `dir` or an ancestor holds `.git`. */
+function insideGitRepo(dir) {
+  let cur = path.resolve(dir);
+  for (;;) {
+    if (existsSync(path.join(cur, '.git'))) return true;
+    const parent = path.dirname(cur);
+    if (parent === cur) return false;
+    cur = parent;
+  }
+}
+
+/** @param {string} name @returns {string} */
+function slugify(name) {
+  const slug = name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+  return slug.length > 0 ? slug : 'project';
+}
+
+/**
+ * Project name: `package.json` name, else the last segment of `composer.json`'s name, else the
+ * directory name.
+ * @param {string} cwd
+ * @returns {{name: string, slug: string}}
+ */
+export function projectIdentity(cwd) {
+  for (const [file, pick] of /** @type {Array<[string, (v: any) => unknown]>} */ ([
+    ['package.json', (v) => v?.name],
+    ['composer.json', (v) => (typeof v?.name === 'string' ? v.name.split('/').pop() : undefined)],
+  ])) {
+    try {
+      const name = pick(JSON.parse(readFileSync(path.join(cwd, file), 'utf8')));
+      if (typeof name === 'string' && name.length > 0) {
+        const bare = name.startsWith('@') ? name.split('/').pop() : name;
+        return { name: bare, slug: slugify(bare) };
+      }
+    } catch {
+      // absent or not JSON: next source
+    }
+  }
+  const base = path.basename(path.resolve(cwd));
+  return { name: base, slug: slugify(base) };
+}
+
+/**
+ * @typedef {object} WizardContext
+ * @property {string} cwd
+ * @property {string} home
+ * @property {NodeJS.ProcessEnv} env
+ * @property {ReturnType<typeof detectGates>} detected
+ * @property {string} profile
+ * @property {boolean} gitRepo
+ * @property {string[]} detectedHarnesses
+ * @property {{agent: boolean, harness: string|null}} current
+ * @property {boolean} solo
+ * @property {{name: string, slug: string}} project
+ */
+
+/**
+ * @param {{cwd: string, home: string, env: NodeJS.ProcessEnv}} opts
+ * @returns {Promise<WizardContext>}
+ */
+export async function gatherContext({ cwd, home, env }) {
+  const detected = detectGates(cwd);
+  const found = await detectAll({ home, pathEnv: env.PATH ?? '' });
+  return {
+    cwd,
+    home,
+    env,
+    detected,
+    profile: proofProfile(detected.stack, cwd),
+    gitRepo: insideGitRepo(cwd),
+    detectedHarnesses: found.filter((d) => d.detected).map((d) => d.id),
+    current: currentHarness(env),
+    solo: soloPresent(env, home),
+    project: projectIdentity(cwd),
+  };
+}
+
+/** @param {unknown} v @returns {any} a deep plain copy */
+function clone(v) {
+  return v === undefined ? undefined : JSON.parse(JSON.stringify(v));
+}
+
+/** @param {unknown} gate @returns {string[]|null} a schema-valid argv (a `{argv}` descriptor keeps its argv). */
+function gateArgv(gate) {
+  if (Array.isArray(gate)) return [...gate];
+  if (gate && typeof gate === 'object' && Array.isArray(/** @type {any} */ (gate).argv)) return [.../** @type {any} */ (gate).argv];
+  return null;
+}
+
+/**
+ * @typedef {object} Answers
+ * @property {'current'|'recommended'} tools
+ * @property {string[]} yes_tools
+ * @property {string[]} harnesses
+ * @property {'project'|'global'} scope
+ * @property {'symlink'|'copy'} method
+ * @property {string} provider
+ * @property {Record<string, any>} levels
+ * @property {boolean} refresh_models
+ * @property {boolean} multimodel
+ * @property {string|null} second_provider
+ * @property {{mode: 'auto'} | {mode: 'ref', ref: string} | {mode: 'none'}} jev
+ * @property {string} engine
+ * @property {number|null} solo_project
+ * @property {{test: string[]|null, lint: string[]|null, types: string[]|null, format: string[]|null}} gates
+ * @property {{high: string[], isolation: string, link_dirs: string[], copy_untracked: string[]}} proof
+ * @property {boolean} doctor
+ */
+
+/** The answer keys in step order. */
+export const ANSWER_KEYS = Object.freeze([
+  'tools', 'yes_tools', 'harnesses', 'scope', 'method', 'provider', 'levels', 'refresh_models',
+  'multimodel', 'second_provider', 'jev', 'engine', 'solo_project', 'gates', 'proof', 'doctor',
+]);
+
+/**
+ * @param {WizardContext} ctx
+ * @param {Record<string, any>|null} existing - the current `.code-forge.yml`, when there is one.
+ * @param {Record<string, any>|null} user - the current user-level config (`~/.code-forge/`).
+ * @param {Array<{flag: string, value: any}>} given - parsed answer flags.
+ * @returns {{values: Answers, sources: Record<string, 'default'|'existing'|'flag'>}}
+ */
+export function resolveAnswers(ctx, existing, user, given) {
+  /** @type {Record<string, 'default'|'existing'|'flag'>} */
+  const sources = {};
+  const ex = existing ?? {};
+  /** @type {any} */
+  const v = {};
+  /** @param {string} key @param {unknown} fromExisting @param {() => unknown} fallback */
+  const set = (key, fromExisting, fallback) => {
+    if (fromExisting !== undefined && fromExisting !== null) {
+      v[key] = clone(fromExisting);
+      sources[key] = 'existing';
+    } else {
+      v[key] = fallback();
+      sources[key] = 'default';
+    }
+  };
+  const flagsFor = (/** @type {string} */ key) => given.filter((g) => ANSWER_FLAGS[g.flag] === key);
+  const lastFlag = (/** @type {string} */ key) => flagsFor(key).at(-1);
+  const override = (/** @type {string} */ key, /** @type {unknown} */ value) => {
+    v[key] = value;
+    sources[key] = 'flag';
+  };
+
+  set('tools', user?.tools, () => 'current');
+  if (lastFlag('tools')) override('tools', lastFlag('tools').value);
+  set('yes_tools', undefined, () => []);
+  if (flagsFor('yes_tools').length > 0) override('yes_tools', [...new Set(flagsFor('yes_tools').map((g) => g.value))]);
+
+  set('harnesses', ex.harnesses, () =>
+    v.tools === 'current' && ctx.current.harness && ctx.current.harness !== 'unknown' ? [ctx.current.harness] : [...ctx.detectedHarnesses],
+  );
+  if (lastFlag('harnesses')) override('harnesses', lastFlag('harnesses').value);
+  set('scope', undefined, () => (ctx.gitRepo ? 'project' : 'global'));
+  if (lastFlag('scope')) override('scope', lastFlag('scope').value);
+  set('method', undefined, () => 'symlink');
+  if (lastFlag('method')) override('method', lastFlag('method').value);
+
+  set('provider', ex.provider, () => 'anthropic');
+  if (lastFlag('provider')) override('provider', lastFlag('provider').value);
+  const providerDefaults = defaultsForProvider(v.provider);
+  set('levels', ex.provider === v.provider ? ex.levels : undefined, () => clone(providerDefaults.levels));
+  if (flagsFor('levels').length > 0) {
+    const levels = clone(v.levels);
+    for (const g of flagsFor('levels')) levels[g.value.level] = { ...g.value.spec };
+    override('levels', levels);
+  }
+  set('refresh_models', undefined, () => false);
+  if (lastFlag('refresh_models')) override('refresh_models', true);
+
+  set('multimodel', ex.review?.multimodel, () => false);
+  if (lastFlag('multimodel')) override('multimodel', lastFlag('multimodel').value);
+  set('second_provider', ex.review?.second_provider, () => null);
+  if (lastFlag('second_provider')) override('second_provider', lastFlag('second_provider').value);
+
+  const exJev = typeof ex.keys?.jev === 'string' ? { mode: 'ref', ref: ex.keys.jev } : existing ? { mode: 'none' } : undefined;
+  set('jev', exJev, () => ({ mode: 'auto' }));
+  const jevFlag = lastFlag('jev');
+  if (jevFlag) {
+    if (jevFlag.flag === '--no-jev') override('jev', { mode: 'none' });
+    else override('jev', { mode: 'ref', ref: jevFlag.flag === '--jev-env' ? `env:${jevFlag.value}` : jevFlag.value });
+  }
+
+  set('engine', ex.engine, () => 'auto');
+  if (lastFlag('engine')) override('engine', lastFlag('engine').value);
+  set('solo_project', user?.solo?.project_id, () => null);
+  if (lastFlag('solo_project')) override('solo_project', lastFlag('solo_project').value);
+
+  const detectedGates = {
+    test: gateArgv(ctx.detected.test),
+    lint: gateArgv(ctx.detected.lint),
+    types: gateArgv(ctx.detected.types),
+    format: gateArgv(ctx.detected.format),
+  };
+  const exGates = ex.gates && typeof ex.gates === 'object' ? ex.gates : undefined;
+  set('gates', exGates ? { ...detectedGates, ...exGates } : undefined, () => detectedGates);
+  if (flagsFor('gates').length > 0) {
+    const gates = clone(v.gates);
+    for (const g of flagsFor('gates')) gates[g.value.name] = g.value.argv;
+    override('gates', gates);
+  }
+
+  const proposal = proposeProof(ctx.profile);
+  const exProof = ex.proof && typeof ex.proof === 'object'
+    ? {
+        high: ex.proof.tiers?.high?.paths ?? proposal.high,
+        isolation: ex.proof.isolation ?? proposal.isolation,
+        link_dirs: ex.proof.export?.link_dirs ?? proposal.link_dirs,
+        copy_untracked: ex.proof.export?.copy_untracked ?? proposal.copy_untracked,
+      }
+    : undefined;
+  set('proof', exProof, () => proposal);
+  if (flagsFor('proof').length > 0) {
+    const proof = clone(v.proof);
+    for (const g of flagsFor('proof')) proof[g.value.key] = g.value.value;
+    override('proof', proof);
+  }
+
+  set('doctor', undefined, () => true);
+  if (lastFlag('doctor')) override('doctor', false);
+
+  return { values: v, sources };
+}

package/src/install/wizard/flags.mjs

@@ -0,0 +1,248 @@
+/**
+ * `code-forge init` flags (plan §2 table, block B13a). Every answer flag overrides exactly one
+ * wizard answer (`ANSWER_FLAGS` maps flag -> answer key); `--no-interaction` is a mode switch and
+ * overrides no answer.
+ *
+ * **Q16 = cut (Ricardo, 2026-09-25):** step 8 asks no mutation-tool or nightly question, so the
+ * v1.2 `--no-nightly` flag is gone and `--proof` takes only the keys the schema still has
+ * (`isolation`, `high`, `link_dirs`, `copy_untracked`). With `-g` and `-p` counted as two flags
+ * (two tokens that each set the scope answer) there are 19 answer flags.
+ *
+ * Parsing is strict: an unknown flag, a missing value, a repeated single-value flag or a bad value
+ * is a usage error. Error messages name the flag, never the value given (a user can paste a key
+ * into any flag by mistake).
+ */
+
+import { isOpRef } from '../../keys/onepassword.mjs';
+import { HARNESSES } from '../harnesses.mjs';
+
+export const PROVIDERS = Object.freeze(['anthropic', 'openai', 'xai']);
+/** The engines the wizard offers. `subprocess` is never proposed (R2): a power user types it. */
+export const ENGINE_CHOICES = Object.freeze(['auto', 'solo', 'harness']);
+export const GATE_NAMES = Object.freeze(['test', 'lint', 'types', 'format']);
+export const PROOF_KEYS = Object.freeze(['isolation', 'high', 'link_dirs', 'copy_untracked']);
+/** Tools step 1 knows how to detect (and, for some, install after a per-tool yes). */
+export const TOOL_IDS = Object.freeze(['solo', 'codex', 'grok', 'gemini', 'op']);
+
+/** flag (as typed) -> the one answer key it overrides. */
+export const ANSWER_FLAGS = Object.freeze({
+  '--tools': 'tools',
+  '--yes-tool': 'yes_tools',
+  '--harness': 'harnesses',
+  '-g': 'scope',
+  '-p': 'scope',
+  '--copy': 'method',
+  '--provider': 'provider',
+  '--level': 'levels',
+  '--refresh-models': 'refresh_models',
+  '--multimodel': 'multimodel',
+  '--second-provider': 'second_provider',
+  '--jev-ref': 'jev',
+  '--jev-env': 'jev',
+  '--no-jev': 'jev',
+  '--engine': 'engine',
+  '--solo-project': 'solo_project',
+  '--gate': 'gates',
+  '--proof': 'proof',
+  '--skip-doctor': 'doctor',
+});
+
+const BOOLEAN_FLAGS = new Set(['-g', '-p', '--copy', '--refresh-models', '--no-jev', '--skip-doctor', '--no-interaction']);
+const REPEATABLE = new Set(['--yes-tool', '--level', '--gate', '--proof']);
+const LEVEL_NAMES = new Set(['L0', 'L1', 'L2', 'L3']);
+const ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+export class UsageError extends Error {}
+
+/**
+ * Split a gate command into argv the way a shell would split words (single/double quotes,
+ * backslash escapes) — without ever running a shell.
+ * @param {string} text
+ * @returns {string[]}
+ */
+export function shellWords(text) {
+  const words = [];
+  let current = '';
+  let has = false;
+  /** @type {string|null} */
+  let quote = null;
+  for (let i = 0; i < text.length; i += 1) {
+    const ch = text[i];
+    if (quote === "'") {
+      if (ch === "'") quote = null;
+      else current += ch;
+    } else if (ch === '\\' && i + 1 < text.length && quote !== "'") {
+      i += 1;
+      current += text[i];
+      has = true;
+    } else if (quote === '"') {
+      if (ch === '"') quote = null;
+      else current += ch;
+    } else if (ch === '"' || ch === "'") {
+      quote = ch;
+      has = true;
+    } else if (/\s/.test(ch)) {
+      if (has) words.push(current);
+      current = '';
+      has = false;
+    } else {
+      current += ch;
+      has = true;
+    }
+  }
+  if (quote !== null) throw new UsageError('--gate: unterminated quote');
+  if (has) words.push(current);
+  return words;
+}
+
+/** @param {string} flag @param {string} value @returns {[string, string]} */
+function keyValue(flag, value) {
+  const eq = value.indexOf('=');
+  if (eq <= 0) throw new UsageError(`${flag} expects <key>=<value>`);
+  return [value.slice(0, eq), value.slice(eq + 1)];
+}
+
+/** @param {string} value @returns {string[]} */
+function csv(value) {
+  return value.split(',').map((s) => s.trim()).filter((s) => s.length > 0);
+}
+
+/**
+ * `L1=model[:effort][@provider]`
+ * @param {string} value
+ * @returns {{level: string, spec: {model: string, effort?: string, provider?: string}}}
+ */
+export function parseLevel(value) {
+  const [level, rest] = keyValue('--level', value);
+  if (!LEVEL_NAMES.has(level)) throw new UsageError('--level: level must be L0, L1, L2 or L3');
+  let body = rest;
+  /** @type {{model: string, effort?: string, provider?: string}} */
+  const spec = { model: '' };
+  const at = body.lastIndexOf('@');
+  if (at >= 0) {
+    const provider = body.slice(at + 1);
+    if (!PROVIDERS.includes(provider)) throw new UsageError('--level: unknown provider');
+    spec.provider = provider;
+    body = body.slice(0, at);
+  }
+  const colon = body.lastIndexOf(':');
+  if (colon >= 0) {
+    const effort = body.slice(colon + 1);
+    if (effort.length === 0) throw new UsageError('--level: empty effort');
+    spec.effort = effort;
+    body = body.slice(0, colon);
+  }
+  if (body.length === 0) throw new UsageError('--level: empty model');
+  spec.model = body;
+  // key order model, effort, provider — the order the schema documents
+  return { level, spec: { model: spec.model, ...(spec.effort ? { effort: spec.effort } : {}), ...(spec.provider ? { provider: spec.provider } : {}) } };
+}
+
+/**
+ * @param {string} flag @param {string} value
+ * @returns {unknown} the typed value for that flag
+ */
+function convert(flag, value) {
+  switch (flag) {
+    case '--tools':
+      if (value !== 'recommended' && value !== 'current') throw new UsageError('--tools must be recommended or current');
+      return value;
+    case '--yes-tool':
+      if (!TOOL_IDS.includes(value)) throw new UsageError(`--yes-tool must be one of ${TOOL_IDS.join(', ')}`);
+      return value;
+    case '--harness': {
+      const ids = csv(value);
+      const known = HARNESSES.map((h) => h.id);
+      if (ids.length === 0 || ids.some((id) => !known.includes(id))) throw new UsageError(`--harness takes a comma list of ${known.join(', ')}`);
+      return [...new Set(ids)];
+    }
+    case '--provider':
+    case '--second-provider':
+      if (!PROVIDERS.includes(value)) throw new UsageError(`${flag} must be one of ${PROVIDERS.join(', ')}`);
+      return value;
+    case '--level':
+      return parseLevel(value);
+    case '--multimodel':
+      if (value !== 'on' && value !== 'off') throw new UsageError('--multimodel must be on or off');
+      return value === 'on';
+    case '--jev-ref':
+      if (!isOpRef(value)) throw new UsageError('--jev-ref must be an op://vault/item/field reference');
+      return value;
+    case '--jev-env':
+      if (!ENV_NAME.test(value)) throw new UsageError('--jev-env must be an environment variable name');
+      return value;
+    case '--engine':
+      if (value === 'subprocess') {
+        throw new UsageError('--engine: init never selects subprocess (R2); type "engine: subprocess" into .code-forge.yml yourself');
+      }
+      if (!ENGINE_CHOICES.includes(value)) throw new UsageError(`--engine must be one of ${ENGINE_CHOICES.join(', ')}`);
+      return value;
+    case '--solo-project':
+      if (!/^[1-9]\d{0,9}$/.test(value)) throw new UsageError('--solo-project must be a positive integer');
+      return Number(value);
+    case '--gate': {
+      const [name, cmd] = keyValue('--gate', value);
+      if (!GATE_NAMES.includes(name)) throw new UsageError(`--gate: gate must be one of ${GATE_NAMES.join(', ')}`);
+      if (cmd === 'none' || cmd === 'null') return { name, argv: null };
+      const argv = shellWords(cmd);
+      if (argv.length === 0) throw new UsageError('--gate: empty command');
+      return { name, argv };
+    }
+    case '--proof': {
+      const [key, raw] = keyValue('--proof', value);
+      if (!PROOF_KEYS.includes(key)) throw new UsageError(`--proof: key must be one of ${PROOF_KEYS.join(', ')}`);
+      if (key === 'isolation') {
+        if (raw !== 'export' && raw !== 'lock') throw new UsageError('--proof isolation must be export or lock');
+        return { key, value: raw };
+      }
+      return { key, value: csv(raw) };
+    }
+    default:
+      throw new UsageError(`unknown flag ${flag}`);
+  }
+}
+
+/**
+ * @typedef {object} ParsedFlags
+ * @property {boolean} noInteraction
+ * @property {Array<{flag: string, value: unknown}>} given - answer flags in the order typed.
+ */
+
+/**
+ * @param {string[]} args
+ * @returns {ParsedFlags}
+ * @throws {UsageError}
+ */
+export function parseInitArgs(args) {
+  /** @type {ParsedFlags} */
+  const out = { noInteraction: false, given: [] };
+  const seen = new Set();
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    const eq = arg.startsWith('--') ? arg.indexOf('=') : -1;
+    const flag = eq > 0 ? arg.slice(0, eq) : arg;
+    if (flag !== '--no-interaction' && !Object.hasOwn(ANSWER_FLAGS, flag)) {
+      throw new UsageError(arg.startsWith('-') ? `unknown flag ${flag}` : 'init takes no positional argument');
+    }
+    if (seen.has(flag) && !REPEATABLE.has(flag)) throw new UsageError(`${flag} given more than once`);
+    seen.add(flag);
+    if (BOOLEAN_FLAGS.has(flag)) {
+      if (eq > 0) throw new UsageError(`${flag} takes no value`);
+      if (flag === '--no-interaction') out.noInteraction = true;
+      else out.given.push({ flag, value: flag === '--copy' ? 'copy' : flag === '-g' ? 'global' : flag === '-p' ? 'project' : true });
+      continue;
+    }
+    let value;
+    if (eq > 0) value = arg.slice(eq + 1);
+    else {
+      value = args[i + 1];
+      i += 1;
+    }
+    if (typeof value !== 'string' || value.length === 0 || (eq < 0 && value.startsWith('-'))) throw new UsageError(`${flag} needs a value`);
+    out.given.push({ flag, value: convert(flag, value) });
+  }
+  if (seen.has('-g') && seen.has('-p')) throw new UsageError('-g and -p are exclusive');
+  const jev = ['--jev-ref', '--jev-env', '--no-jev'].filter((f) => seen.has(f));
+  if (jev.length > 1) throw new UsageError(`${jev.join(' and ')} are exclusive`);
+  return out;
+}