@codedology/code-forge 0.1.0

package/src/install/wizard/steps.mjs

@@ -0,0 +1,201 @@
+/**
+ * The interactive half of `code-forge init` (plan §2, block B13a): one question per answer that
+ * no flag already fixed, default on Enter. `ui` has `@clack/prompts`' shape (`select`,
+ * `multiselect`, `text`, `confirm`, `password`, `isCancel`), so the real module is passed in
+ * production and a scripted fake in tests. Step 5's key question lives in {@link askJevSource}
+ * because it is asked only when the chain resolves nothing.
+ */
+
+import { isOpRef } from '../../keys/onepassword.mjs';
+import { HARNESSES } from '../harnesses.mjs';
+import { effectiveProvider, judgeCollision, proposeJudge } from './answers.mjs';
+import { ENGINE_CHOICES, GATE_NAMES, PROVIDERS, parseLevel, shellWords, UsageError } from './flags.mjs';
+
+export class CancelledError extends Error {}
+
+/**
+ * @typedef {object} Ui
+ * @property {(o: {message: string, options: Array<{value: any, label?: string}>, initialValue?: any}) => Promise<any>} select
+ * @property {(o: {message: string, options: Array<{value: any, label?: string}>, initialValues?: any[], required?: boolean}) => Promise<any>} multiselect
+ * @property {(o: {message: string, initialValue?: string, placeholder?: string}) => Promise<any>} text
+ * @property {(o: {message: string, initialValue?: boolean}) => Promise<any>} confirm
+ * @property {(o: {message: string}) => Promise<any>} password
+ * @property {(v: unknown) => boolean} isCancel
+ */
+
+/** @param {Ui} ui @param {Promise<any>} pending @returns {Promise<any>} */
+async function answer(ui, pending) {
+  const value = await pending;
+  if (ui.isCancel(value)) throw new CancelledError('cancelled — nothing written');
+  return value;
+}
+
+/**
+ * A comma list split only at brace depth 0, so a glob like `app/**\/*.{php,vue}` stays one item
+ * and Enter on a pre-filled list gives the list back unchanged.
+ * @param {string} text @returns {string[]}
+ */
+function csv(text) {
+  const items = [];
+  let current = '';
+  let depth = 0;
+  for (const ch of String(text ?? '')) {
+    if (ch === '{') depth += 1;
+    else if (ch === '}' && depth > 0) depth -= 1;
+    if (ch === ',' && depth === 0) {
+      items.push(current);
+      current = '';
+    } else {
+      current += ch;
+    }
+  }
+  items.push(current);
+  return items.map((s) => s.trim()).filter((s) => s.length > 0);
+}
+
+/**
+ * The `model[:effort][@provider]` text a level is pre-filled with — the exact form `parseLevel`
+ * reads back, so Enter keeps the level unchanged (provider override included).
+ * @param {{model: string, effort?: string, provider?: string}} level @returns {string}
+ */
+export function levelText(level) {
+  return `${level.model}${level.effort ? `:${level.effort}` : ''}${level.provider ? `@${level.provider}` : ''}`;
+}
+
+/**
+ * Asks every answer whose source is not `flag`, in step order. Mutates and returns `values`.
+ * @param {import('./answers.mjs').Answers} values
+ * @param {Record<string, string>} sources
+ * @param {import('./answers.mjs').WizardContext} ctx
+ * @param {Ui} ui
+ * @returns {Promise<import('./answers.mjs').Answers>}
+ */
+export async function askAnswers(values, sources, ctx, ui) {
+  const open = (/** @type {string} */ key) => sources[key] !== 'flag';
+
+  if (open('tools')) {
+    values.tools = await answer(ui, ui.select({
+      message: 'Install the recommended tools, or use only the current harness?',
+      options: [{ value: 'current', label: 'current harness' }, { value: 'recommended', label: 'recommended tools' }],
+      initialValue: values.tools,
+    }));
+  }
+  if (open('harnesses')) {
+    values.harnesses = await answer(ui, ui.multiselect({
+      message: 'Install the skill into:',
+      options: HARNESSES.map((h) => ({ value: h.id, label: `${h.label}${ctx.detectedHarnesses.includes(h.id) ? ' (detected)' : ''}` })),
+      initialValues: values.harnesses,
+      required: false,
+    }));
+  }
+  if (open('scope')) {
+    values.scope = await answer(ui, ui.select({ message: 'Scope', options: [{ value: 'project' }, { value: 'global' }], initialValue: values.scope }));
+  }
+  if (open('method')) {
+    values.method = await answer(ui, ui.select({ message: 'Method', options: [{ value: 'symlink' }, { value: 'copy' }], initialValue: values.method }));
+  }
+  if (open('provider')) {
+    values.provider = await answer(ui, ui.select({ message: 'Default provider', options: PROVIDERS.map((p) => ({ value: p })), initialValue: values.provider }));
+  }
+  if (open('levels')) {
+    const summary = ['L0', 'L1', 'L2', 'L3'].map((l) => `${l}=${levelText(values.levels[l])}`).join(' ');
+    const keep = await answer(ui, ui.confirm({ message: `Keep the level matrix? ${summary}`, initialValue: true }));
+    if (!keep) {
+      for (const level of ['L0', 'L1', 'L2', 'L3']) {
+        const shown = levelText(values.levels[level]);
+        const typed = await answer(ui, ui.text({ message: `${level} model[:effort][@provider]`, initialValue: shown }));
+        // Enter (unchanged text) keeps the level object as it is, `fallback` included
+        if (String(typed).trim() !== shown) values.levels[level] = parseLevel(`${level}=${String(typed).trim()}`).spec;
+      }
+    }
+  }
+  if (open('refresh_models')) {
+    values.refresh_models = await answer(ui, ui.confirm({ message: 'Read model ids from the Codex/Grok CLI caches on this machine?', initialValue: false }));
+  }
+  if (open('multimodel')) {
+    values.multimodel = await answer(ui, ui.confirm({ message: 'Multimodel review (consensus)?', initialValue: values.multimodel }));
+  }
+  if (values.multimodel && open('second_provider')) {
+    // R5: the second reviewer must differ from the provider L2 actually runs on, not the default one
+    const reviewer1 = effectiveProvider(values, 'L2');
+    const others = PROVIDERS.filter((p) => p !== reviewer1);
+    values.second_provider = await answer(ui, ui.select({
+      message: `Second provider (must differ from the effective L2 provider, ${reviewer1})`,
+      options: others.map((p) => ({ value: p })),
+      initialValue: others.includes(values.second_provider) ? values.second_provider : others[0],
+    }));
+  }
+  // Consensus judge (§4.4, validator rule 7): the effective L3 must share a provider with neither
+  // reviewer. Proposes the third provider's default L3; asked again until the answer differs. Not
+  // asked when a flag-supplied second provider equals the effective L2 — `runInit` refuses that.
+  const reviewersDiffer = values.second_provider !== effectiveProvider(values, 'L2');
+  for (let collision = reviewersDiffer ? judgeCollision(values) : null; collision; collision = judgeCollision(values)) {
+    const proposal = collision.third ? levelText(proposeJudge(collision.third)) : '';
+    const typed = await answer(ui, ui.text({
+      message: `L3 judge — must come from a third provider (reviewers: ${collision.reviewers.join(', ')}); model[:effort][@provider]`,
+      initialValue: proposal,
+    }));
+    values.levels.L3 = parseLevel(`L3=${String(typed).trim()}`).spec;
+  }
+  // `subprocess` is never offered (R2); an existing `engine: subprocess` is kept, not asked.
+  if (open('engine') && values.engine !== 'subprocess') {
+    values.engine = await answer(ui, ui.select({ message: 'Engine', options: ENGINE_CHOICES.map((e) => ({ value: e })), initialValue: values.engine }));
+  }
+  if (open('solo_project') && ctx.solo && values.engine !== 'harness') {
+    const typed = await answer(ui, ui.text({ message: 'Solo project id (blank: none)', initialValue: values.solo_project === null ? '' : String(values.solo_project) }));
+    values.solo_project = /^[1-9]\d{0,9}$/.test(String(typed).trim()) ? Number(String(typed).trim()) : null;
+  }
+  if (open('gates')) {
+    for (const name of GATE_NAMES) {
+      const current = values.gates[name];
+      const typed = await answer(ui, ui.text({ message: `Gate ${name} (blank or "none": no gate)`, initialValue: current ? current.join(' ') : '' }));
+      const text = String(typed ?? '').trim();
+      values.gates[name] = text === '' || text === 'none' ? null : shellWords(text);
+    }
+  }
+  if (open('proof')) {
+    values.proof.high = csv(await answer(ui, ui.text({ message: 'High-risk paths (comma list of globs)', initialValue: values.proof.high.join(',') })));
+    values.proof.isolation = await answer(ui, ui.select({ message: 'Proof isolation', options: [{ value: 'export' }, { value: 'lock' }], initialValue: values.proof.isolation }));
+    values.proof.link_dirs = csv(await answer(ui, ui.text({ message: 'Export: directories to link', initialValue: values.proof.link_dirs.join(',') })));
+    values.proof.copy_untracked = csv(await answer(ui, ui.text({ message: 'Export: untracked files to copy', initialValue: values.proof.copy_untracked.join(',') })));
+  }
+  return values;
+}
+
+/**
+ * Step 5 when the chain resolved nothing: where is the Jev key? A pasted key is read with hidden
+ * input and handed straight to `store`; it is never returned, echoed or logged.
+ * @param {Ui} ui
+ * @param {() => Promise<{put: (name: string, value: string, meta: {source: string, exp: number|null}) => Promise<void>}>} getStore
+ * @returns {Promise<{ref: string|null, source: string}>}
+ */
+export async function askJevSource(ui, getStore) {
+  const choice = await answer(ui, ui.select({
+    message: 'Where is the Jev key?',
+    options: [
+      { value: 'op', label: '1Password reference' },
+      { value: 'env', label: 'environment variable name' },
+      { value: 'paste', label: 'paste now (hidden)' },
+      { value: 'skip', label: 'skip (rules-only System 1)' },
+    ],
+    initialValue: 'skip',
+  }));
+  if (choice === 'op') {
+    const ref = String(await answer(ui, ui.text({ message: '1Password reference (op://vault/item/field)' }))).trim();
+    if (!isOpRef(ref)) throw new UsageError('not an op://vault/item/field reference');
+    return { ref, source: 'op' };
+  }
+  if (choice === 'env') {
+    const name = String(await answer(ui, ui.text({ message: 'Environment variable name' }))).trim();
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) throw new UsageError('not an environment variable name');
+    return { ref: `env:${name}`, source: 'env' };
+  }
+  if (choice === 'paste') {
+    const typed = await answer(ui, ui.password({ message: 'Jev key (input hidden)' }));
+    if (typeof typed !== 'string' || typed.length === 0) return { ref: null, source: 'none' };
+    const store = await getStore();
+    await store.put('jev', typed, { source: 'user', exp: null });
+    return { ref: 'user', source: 'keychain' };
+  }
+  return { ref: null, source: 'none' };
+}

package/src/keys/backends/constants.mjs

@@ -0,0 +1,7 @@
+/**
+ * Constants shared by the keychain backends. No imports on purpose: `security-cli.mjs` must stay
+ * loadable when `@napi-rs/keyring` (and anything that touches it) cannot load.
+ */
+
+/** Keychain service name; the account is the key name. */
+export const SERVICE = 'code-forge';

package/src/keys/backends/file.mjs

@@ -0,0 +1,99 @@
+/**
+ * Last-resort backend: one file per key under `~/.code-forge/store/`, file mode 0600, directory
+ * mode 0700 (plan §1.2, §8.1). Selecting it makes `doctor` WARN (see `../store.mjs`).
+ *
+ * A secret is never written into an existing file: `writePrivateFile` creates a NEW temp file
+ * with `O_CREAT|O_EXCL` at mode 0600 (so a pre-planted file or symlink is never opened), writes,
+ * then renames it over the target. A key file with a loose mode, or a symlink planted at the
+ * key's path, is replaced, never written through. The rename is also what makes the write atomic.
+ *
+ * Values are stored verbatim; on read one trailing newline (a hand-edited file) is dropped and
+ * an empty file reads as absent.
+ *
+ * @typedef {import('../store.mjs').Backend} Backend
+ */
+
+import { randomBytes } from 'node:crypto';
+import { chmod, mkdir, open, readFile, rename, rm } from 'node:fs/promises';
+import path from 'node:path';
+
+export const FILE_MODE = 0o600;
+export const DIR_MODE = 0o700;
+
+/**
+ * Write `content` to `file` so it only ever exists at mode 0600: temp file created exclusively
+ * at 0600 in the same directory, then renamed over the target.
+ * @param {string} file
+ * @param {string} content
+ */
+export async function writePrivateFile(file, content) {
+  const dir = path.dirname(file);
+  await mkdir(dir, { recursive: true, mode: DIR_MODE });
+  await chmod(dir, DIR_MODE);
+  const tmp = path.join(dir, `.${path.basename(file)}.${process.pid}.${randomBytes(6).toString('hex')}.tmp`);
+  const handle = await open(tmp, 'wx', FILE_MODE);
+  try {
+    // The umask can only remove bits from 0600, never add them; this makes the mode exact.
+    await handle.chmod(FILE_MODE);
+    await handle.writeFile(content, 'utf8');
+    await handle.sync();
+  } catch (err) {
+    await handle.close();
+    await rm(tmp, { force: true });
+    throw err;
+  }
+  await handle.close();
+  await rename(tmp, file);
+}
+
+/**
+ * @param {object} opts
+ * @param {string} opts.dir - e.g. `~/.code-forge/store`.
+ * @returns {Backend}
+ */
+export function createFileBackend({ dir }) {
+  const root = path.resolve(dir);
+  /** @param {string} name */
+  const fileFor = (name) => {
+    const file = path.resolve(root, `${name}.key`);
+    if (typeof name !== 'string' || name.length === 0 || /[/\\]/.test(name) || name.startsWith('.') || path.dirname(file) !== root) {
+      throw new TypeError('file backend: key name must be a plain file name inside the store');
+    }
+    return file;
+  };
+
+  return {
+    name: 'file',
+    writable: true,
+    async available() {
+      return true;
+    },
+    async get(name) {
+      const file = fileFor(name);
+      try {
+        const raw = (await readFile(file, 'utf8')).replace(/\n$/, '');
+        return raw.length > 0 ? raw : null;
+      } catch (err) {
+        if (err?.code === 'ENOENT') {
+          return null;
+        }
+        throw err;
+      }
+    },
+    async set(name, value) {
+      await writePrivateFile(fileFor(name), value);
+    },
+    async delete(name) {
+      const file = fileFor(name);
+      try {
+        await rm(file);
+        return true;
+      } catch (err) {
+        if (err?.code === 'ENOENT') {
+          return false;
+        }
+        throw err;
+      }
+    },
+  };
+}

package/src/keys/backends/keychain.mjs

@@ -0,0 +1,81 @@
+/**
+ * OS keychain backend over `@napi-rs/keyring` (an optionalDependency, plan §1.1 / §8.1).
+ *
+ * The module is loaded dynamically, and `available()` proves the keychain is USABLE, not only
+ * importable: it reads a probe entry that never exists. A binding that loads on a machine with
+ * no usable store (headless Linux without Secret Service, a denied keychain, a CI container)
+ * throws there, `available()` resolves `false`, and the store falls back to the macOS `security`
+ * CLI, then the 0600 file (see `../store.mjs`).
+ *
+ * Every entry lives under service `code-forge`, account = key name — the same pair the
+ * `security` CLI backend reads.
+ *
+ * @typedef {import('../store.mjs').Backend} Backend
+ */
+
+import { SERVICE } from './constants.mjs';
+
+export { SERVICE };
+
+/** An account name no key can have (key names start with a lowercase letter). */
+export const PROBE_ACCOUNT = '__code-forge-probe__';
+
+/** @returns {Promise<any>} the `@napi-rs/keyring` module namespace. */
+async function importKeyring() {
+  return import('@napi-rs/keyring');
+}
+
+/**
+ * @param {object} [opts]
+ * @param {() => Promise<any>} [opts.loadModule] - injected in tests; never the real keyring there.
+ * @param {string} [opts.service]
+ * @returns {Backend}
+ */
+export function createKeychainBackend({ loadModule = importKeyring, service = SERVICE } = {}) {
+  /** @type {Promise<any> | undefined} */
+  let loading;
+  const load = () => {
+    loading ??= loadModule().then(
+      (mod) => {
+        const Entry = mod?.Entry ?? mod?.default?.Entry ?? null;
+        if (!Entry) {
+          return null;
+        }
+        try {
+          new Entry(service, PROBE_ACCOUNT).getPassword();
+          return Entry;
+        } catch {
+          return null;
+        }
+      },
+      () => null,
+    );
+    return loading;
+  };
+  /** @param {string} name */
+  const entry = async (name) => {
+    const Entry = await load();
+    if (!Entry) {
+      throw new Error('keychain: @napi-rs/keyring is not available');
+    }
+    return new Entry(service, name);
+  };
+
+  return {
+    name: 'keychain',
+    writable: true,
+    async available() {
+      return (await load()) !== null;
+    },
+    async get(name) {
+      const value = (await entry(name)).getPassword();
+      return typeof value === 'string' && value.length > 0 ? value : null;
+    },
+    async set(name, value) {
+      (await entry(name)).setPassword(value);
+    },
+    async delete(name) {
+      return Boolean((await entry(name)).deletePassword());
+    },
+  };
+}

package/src/keys/backends/security-cli.mjs

@@ -0,0 +1,105 @@
+/**
+ * macOS `security` CLI backend — the fallback when `@napi-rs/keyring` cannot load (plan §8.1).
+ *
+ * Read, write and delete. A write never puts the secret in argv (where any process listing
+ * would show it): `add-generic-password … -w` with `-w` as the LAST option and no value makes
+ * `security` prompt for the password, and since `exec` spawns the child in a new session with
+ * no controlling terminal, the prompt reads from stdin. The value is piped there twice (password,
+ * then the "retype" confirmation), one per line, via B0.1 `exec`'s `input` (B2.1). A value that
+ * contains a line break cannot be sent that way and is refused before anything spawns. After the
+ * write the item is read back; a stored value that differs (truncated, empty) is deleted and
+ * the write fails.
+ *
+ * It imports nothing from `keychain.mjs`, so it loads even when the keyring binding cannot.
+ * The binary is called by absolute path so a `security` earlier on PATH cannot intercept it
+ * (`bin` exists only so tests can point it at a fake).
+ *
+ * Values: code-forge stores printable JSON text, which `-w` prints as-is. An item holding
+ * non-printable bytes is printed by `security` as hex; such items are not code-forge's and are
+ * returned as that text (documented limitation). An empty password reads as absent.
+ *
+ * @typedef {import('../store.mjs').Backend} Backend
+ */
+
+import { exec as realExec } from '../../util/exec.mjs';
+import { SERVICE } from './constants.mjs';
+
+export const SECURITY_BIN = '/usr/bin/security';
+
+/** `security` exits 44 when no matching item exists. */
+export const NOT_FOUND_EXIT = 44;
+
+const TIMEOUT_MS = 10_000;
+
+/**
+ * @param {object} [opts]
+ * @param {typeof realExec} [opts.exec]
+ * @param {string} [opts.platform]
+ * @param {string} [opts.service]
+ * @param {string} [opts.bin] - path of the `security` binary (default {@link SECURITY_BIN}).
+ * @returns {Backend}
+ */
+export function createSecurityCliBackend({
+  exec = realExec,
+  platform = process.platform,
+  service = SERVICE,
+  bin = SECURITY_BIN,
+} = {}) {
+  /** @type {Backend} */
+  const backend = {
+    name: 'security-cli',
+    writable: true,
+    async available() {
+      if (platform !== 'darwin') {
+        return false;
+      }
+      const res = await exec([bin, 'help'], { timeoutMs: TIMEOUT_MS, okExitCodes: [0, 1] });
+      return res.result === 'ok';
+    },
+    async get(name) {
+      const res = await exec([bin, 'find-generic-password', '-s', service, '-a', name, '-w'], {
+        timeoutMs: TIMEOUT_MS,
+        okExitCodes: [0, NOT_FOUND_EXIT],
+      });
+      if (res.result !== 'ok') {
+        throw new Error(`security-cli: find-generic-password failed (exit ${res.code})`);
+      }
+      if (res.code === NOT_FOUND_EXIT) {
+        return null;
+      }
+      const value = res.stdout.replace(/\n$/, '');
+      return value.length > 0 ? value : null;
+    },
+    async set(name, value) {
+      if (/[\r\n]/.test(value)) {
+        throw new TypeError('security-cli: a value containing a line break cannot be written through stdin');
+      }
+      // `-U` updates an existing item; `-w` must stay last so `security` reads the value from stdin.
+      const res = await exec([bin, 'add-generic-password', '-U', '-s', service, '-a', name, '-w'], {
+        timeoutMs: TIMEOUT_MS,
+        input: `${value}\n${value}\n`,
+      });
+      if (res.result !== 'ok') {
+        throw new Error(`security-cli: add-generic-password failed (exit ${res.code})`);
+      }
+      // A clean exit is not proof: the prompt (getpass/readpassphrase) can truncate long input
+      // or store an empty value and still exit 0. Read the item back and compare.
+      if ((await backend.get(name)) !== value) {
+        // Best effort: drop the bad item so a truncated secret is never served later.
+        await backend.delete(name).catch(() => false);
+        throw new Error('security-cli: add-generic-password stored value mismatch');
+      }
+    },
+    async delete(name) {
+      const res = await exec([bin, 'delete-generic-password', '-s', service, '-a', name], {
+        timeoutMs: TIMEOUT_MS,
+        okExitCodes: [0, NOT_FOUND_EXIT],
+      });
+      if (res.result !== 'ok') {
+        throw new Error(`security-cli: delete-generic-password failed (exit ${res.code})`);
+      }
+      return res.code === 0;
+    },
+  };
+  return backend;
+}

package/src/keys/onepassword.mjs

@@ -0,0 +1,46 @@
+/**
+ * 1Password source: `op read <op://ref>` (plan §8.1). Retried exactly once, and only when the
+ * FIRST call timed out (a cold `op` waiting on biometric unlock is the common case); any other
+ * failure is final. The value is read from stdout and never logged; a failure message carries
+ * the exit code only, never stdout/stderr.
+ */
+
+import { exec as realExec } from '../util/exec.mjs';
+
+export const OP_TIMEOUT_MS = 20_000;
+
+/**
+ * @param {string} ref
+ * @returns {boolean}
+ */
+export function isOpRef(ref) {
+  // Three non-empty segments; spaces are allowed (vault/item names have them, and argv needs no
+  // quoting). No line breaks.
+  return typeof ref === 'string' && /^op:\/\/[^/\r\n]+\/[^/\r\n]+\/[^\r\n]+$/.test(ref);
+}
+
+/**
+ * @param {string} ref - an `op://vault/item/field` reference.
+ * @param {object} [opts]
+ * @param {typeof realExec} [opts.exec]
+ * @param {number} [opts.timeoutMs]
+ * @returns {Promise<{value: string|null, attempts: number, error?: string}>}
+ */
+export async function opRead(ref, { exec = realExec, timeoutMs = OP_TIMEOUT_MS } = {}) {
+  if (!isOpRef(ref)) {
+    throw new TypeError('opRead: reference must look like op://vault/item/field');
+  }
+  let attempts = 0;
+  let res;
+  do {
+    attempts += 1;
+    res = await exec(['op', 'read', ref], { timeoutMs });
+  } while (res.result !== 'ok' && res.timedOut && attempts === 1);
+
+  if (res.result !== 'ok') {
+    const why = res.timedOut ? 'timed out' : res.code !== null ? `exit ${res.code}` : res.signal ? `signal ${res.signal}` : 'failed';
+    return { value: null, attempts, error: `op read failed (${why})` };
+  }
+  const value = res.stdout.replace(/\r?\n$/, '');
+  return value.length > 0 ? { value, attempts } : { value: null, attempts, error: 'op read returned nothing' };
+}