@codedology/code-forge 0.2.0 → 0.2.2

package/src/install/tools.mjs

@@ -0,0 +1,163 @@
+/**
+ * The recommended tools (block B26): ONE table shared by `code-forge tools`, `init` step 1 and
+ * `doctor`. Each row says how to detect the tool and how to install it on this OS:
+ *  - an npm package installs with `npm install -g <pkg>` when `npm` is on PATH, else it is manual;
+ *  - a Homebrew formula/cask installs with `brew install …` on macOS when `brew` is on PATH
+ *    ("install Homebrew first" when it is not), and is manual (a vendor link) on other systems;
+ *  - Solo is always manual (a desktop app, then its MCP entry).
+ * Detection never spawns a process: `commandOnPath` scans PATH, and Solo's app bundle is a plain
+ * existence check. Installs are argv arrays only — the caller runs them through B0 `exec`.
+ */
+
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { commandOnPath } from './detect.mjs';
+
+/**
+ * @typedef {object} ToolRow
+ * @property {string} id
+ * @property {string} command - the binary looked up on PATH (and asked for `--version`).
+ * @property {string|null} npm - the npm package, installed globally.
+ * @property {ReadonlyArray<string>|null} brew - the args after `brew install` (macOS only).
+ * @property {string|null} manual - the link (or text) when there is no automatic install.
+ * @property {string|null} app - a macOS app bundle name that also counts as installed.
+ * @property {string|null} note - printed next to the tool when it is installed.
+ */
+
+/** @type {ReadonlyArray<Readonly<ToolRow>>} */
+export const TOOLS = Object.freeze([
+  Object.freeze({ id: 'claude', command: 'claude', npm: '@anthropic-ai/claude-code', brew: null, manual: null, app: null, note: null }),
+  Object.freeze({ id: 'codex', command: 'codex', npm: '@openai/codex', brew: null, manual: null, app: null, note: null }),
+  Object.freeze({ id: 'gemini', command: 'gemini', npm: '@google/gemini-cli', brew: null, manual: null, app: null, note: null }),
+  Object.freeze({ id: 'grok', command: 'grok', npm: null, brew: Object.freeze(['--cask', 'grok-build']), manual: 'https://x.ai/build', app: null, note: null }),
+  Object.freeze({
+    id: 'op',
+    command: 'op',
+    npm: null,
+    brew: Object.freeze(['1password-cli']),
+    manual: 'https://developer.1password.com/docs/cli/get-started/',
+    app: null,
+    note: 'turn on 1Password app → Settings → Developer → "Integrate with 1Password CLI"',
+  }),
+  Object.freeze({
+    id: 'solo',
+    command: 'solo',
+    npm: null,
+    brew: null,
+    manual: 'https://soloterm.com (desktop app, then add its MCP entry)',
+    app: 'Solo.app',
+    note: null,
+  }),
+]);
+
+/** Every tool id, in table order. */
+export const TOOL_IDS = Object.freeze(TOOLS.map((t) => t.id));
+
+/** The hint when a brew install is due but `brew` is not on PATH. */
+export const NO_BREW_HINT = 'install Homebrew first: https://brew.sh';
+
+/** The version timeout (`<cmd> --version`). */
+export const VERSION_TIMEOUT_MS = 10_000;
+
+/**
+ * @typedef {object} ToolEnv
+ * @property {string} [pathEnv] - a PATH-shaped string (default `process.env.PATH`).
+ * @property {NodeJS.Platform} [platform] - default `process.platform`.
+ * @property {string} [home] - for `~/Applications` (default `process.env.HOME`).
+ * @property {(p: string) => boolean} [exists] - default `existsSync` (tests: a fake).
+ */
+
+/** @param {string} id @returns {Readonly<ToolRow>|undefined} */
+export function toolById(id) {
+  return TOOLS.find((t) => t.id === id);
+}
+
+/**
+ * Whether a tool is installed: its command on PATH, or (macOS) its app bundle in `/Applications`
+ * or `~/Applications`.
+ * @param {Readonly<ToolRow>} tool @param {ToolEnv} [opts]
+ * @returns {Promise<boolean>}
+ */
+export async function detectTool(tool, opts = {}) {
+  const platform = opts.platform ?? process.platform;
+  if (await commandOnPath(tool.command, { pathEnv: opts.pathEnv ?? process.env.PATH ?? '', platform })) return true;
+  if (tool.app === null || platform !== 'darwin') return false;
+  const exists = opts.exists ?? existsSync;
+  const home = opts.home ?? process.env.HOME ?? '';
+  const places = [path.join('/Applications', tool.app), ...(home ? [path.join(home, 'Applications', tool.app)] : [])];
+  return places.some((p) => exists(p));
+}
+
+/**
+ * @typedef {{kind: 'run', argv: string[]} | {kind: 'manual', hint: string}} InstallPlan
+ */
+
+/**
+ * How to install a tool on this machine: an argv to run, or a manual hint.
+ * @param {Readonly<ToolRow>} tool @param {ToolEnv} [opts]
+ * @returns {Promise<InstallPlan>}
+ */
+export async function installPlan(tool, opts = {}) {
+  const platform = opts.platform ?? process.platform;
+  const onPath = (/** @type {string} */ cmd) => commandOnPath(cmd, { pathEnv: opts.pathEnv ?? process.env.PATH ?? '', platform });
+  if (tool.npm !== null) {
+    const argv = ['npm', 'install', '-g', tool.npm];
+    // Windows: npm is `npm.cmd`, which only a shell runs — never spawned here, the user runs it
+    if (platform === 'win32') return { kind: 'manual', hint: `run: ${argv.join(' ')}` };
+    return (await onPath('npm')) ? { kind: 'run', argv } : { kind: 'manual', hint: `install Node.js/npm first, then: ${argv.join(' ')}` };
+  }
+  if (tool.brew !== null && platform === 'darwin') {
+    return (await onPath('brew')) ? { kind: 'run', argv: ['brew', 'install', ...tool.brew] } : { kind: 'manual', hint: NO_BREW_HINT };
+  }
+  return { kind: 'manual', hint: tool.manual ?? 'no install known' };
+}
+
+/**
+ * `<cmd> --version` with a 10 s timeout: the first non-empty line of stdout (else of stderr), cut
+ * to 120 chars. Any failure (missing, non-zero, timeout, empty) → null.
+ * @param {Readonly<ToolRow>} tool
+ * @param {{exec: typeof import('../util/exec.mjs').exec, env?: NodeJS.ProcessEnv}} deps
+ * @returns {Promise<string|null>}
+ */
+export async function toolVersion(tool, { exec, env }) {
+  try {
+    const res = await exec([tool.command, '--version'], { timeoutMs: VERSION_TIMEOUT_MS, ...(env ? { env } : {}) });
+    if (res.result !== 'ok' || res.timedOut) return null;
+    const firstLine = (/** @type {unknown} */ text) => String(text ?? '').split('\n').map((l) => l.trim()).find((l) => l.length > 0);
+    const first = firstLine(res.stdout) ?? firstLine(res.stderr);
+    return first ? first.slice(0, 120) : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Why an install failed, as a fixed phrase — never the child's error text.
+ * @param {{code?: number|null, signal?: string|null, timedOut?: boolean}} res
+ * @returns {string} `timed out`, `signal S`, `exit n` or `did not start`
+ */
+export function failureReason(res) {
+  if (res.timedOut) return 'timed out';
+  if (typeof res.signal === 'string' && res.signal.length > 0) return `signal ${res.signal}`;
+  if (typeof res.code === 'number') return `exit ${res.code}`;
+  return 'did not start';
+}
+
+/**
+ * Never rejects: a tool whose check throws counts as missing.
+ * @param {ToolEnv} [opts]
+ * @returns {Promise<string[]>} the ids of the tools that are not installed, in table order.
+ */
+export async function missingTools(opts = {}) {
+  const out = [];
+  for (const tool of TOOLS) {
+    let present = false;
+    try {
+      present = await detectTool(tool, opts);
+    } catch {
+      present = false;
+    }
+    if (!present) out.push(tool.id);
+  }
+  return out;
+}

package/src/install/wizard/answers.mjs

@@ -12,7 +12,7 @@ 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';
+import { ANSWER_FLAGS, GATE_NAMES, PROOF_KEYS, PROVIDERS } from './flags.mjs';
 
 /** Harnesses that expose a subagent tool (§5.1: Claude Code's `Agent`, [A13]). */
 export const SUBAGENT_HARNESSES = Object.freeze(['claude']);
@@ -29,28 +29,33 @@ export const COPY_UNTRACKED = Object.freeze({
   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'],
-});
+/** The proof profiles {@link proofProfile} can return. */
+const PROFILES = Object.freeze(['laravel', 'php', 'node', 'python', 'rust', 'go', 'unknown']);
 
-/** 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 one source of truth for `link_dirs` (B24): each dependency folder an export links instead of
+ * copying, with the manifests that make it right to propose. A folder is proposed when one of its
+ * manifests exists, whether or not the dependencies are installed yet.
+ */
+export const LINK_DIR_MANIFESTS = Object.freeze({
+  vendor: Object.freeze(['composer.json', 'go.mod']),
+  node_modules: Object.freeze(['package.json']),
+  '.venv': Object.freeze(['pyproject.toml', 'requirements.txt', 'setup.py', 'Pipfile']),
+  target: Object.freeze(['Cargo.toml']),
 });
 
+/**
+ * The `link_dirs` entries whose manifest exists in `cwd`, in {@link LINK_DIR_MANIFESTS} order, each
+ * with the manifests found for it.
+ * @param {string} cwd
+ * @returns {Array<{dir: string, manifests: string[]}>}
+ */
+export function linkDirsFromManifests(cwd) {
+  return Object.entries(LINK_DIR_MANIFESTS)
+    .map(([dir, manifests]) => ({ dir, manifests: manifests.filter((m) => existsSync(path.join(cwd, m))) }))
+    .filter((e) => e.manifests.length > 0);
+}
+
 /**
  * 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`
@@ -65,7 +70,7 @@ export function proofProfile(stack, cwd) {
   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;
+  if (stack !== 'unknown' && PROFILES.includes(stack)) return stack;
   return composer ? 'php' : 'unknown';
 }
 
@@ -109,16 +114,33 @@ export function proposeJudge(provider) {
 }
 
 /**
- * Step 8's proposal for a stack.
+ * Step 8's `copy_untracked` candidates for a profile, before the project is looked at.
+ * @param {string} profile
+ * @returns {string[]}
+ */
+export function copyCandidates(profile) {
+  return [...(COPY_UNTRACKED[profile] ?? [])];
+}
+
+/**
+ * Step 8's proposal (B24): nothing is asked. High-risk paths are a deliberate blank (the project
+ * never says which paths are high-risk) and isolation is `export`. `link_dirs` is every folder whose
+ * manifest ({@link LINK_DIR_MANIFESTS}) exists in `cwd`, installed or not, whatever the profile (a
+ * PHP app with a `package.json` links `node_modules` too); `copy_untracked` keeps the profile's
+ * candidates that exist in `cwd` themselves. Nothing kept gives `[]`. Without `cwd` nothing can be
+ * looked at: `link_dirs` is `[]` and `copy_untracked` the unfiltered candidates.
  * @param {string} profile
+ * @param {string} [cwd]
  * @returns {{high: string[], isolation: 'export', link_dirs: string[], copy_untracked: string[]}}
  */
-export function proposeProof(profile) {
+export function proposeProof(profile, cwd) {
+  const candidates = copyCandidates(profile);
+  if (cwd === undefined) return { high: [], isolation: 'export', link_dirs: [], copy_untracked: candidates };
   return {
-    high: [...(HIGH_PATHS[profile] ?? [])],
+    high: [],
     isolation: 'export',
-    link_dirs: [...(LINK_DIRS[profile] ?? LINK_DIRS.unknown)],
-    copy_untracked: [...(COPY_UNTRACKED[profile] ?? [])],
+    link_dirs: linkDirsFromManifests(cwd).map((e) => e.dir),
+    copy_untracked: candidates.filter((rel) => existsSync(path.join(cwd, rel))),
   };
 }
 
@@ -272,6 +294,12 @@ function gateArgv(gate) {
  * @property {boolean} doctor
  */
 
+/**
+ * Where each gate and each proof value came from (B24): `flag`, `existing` (the current
+ * `.code-forge.yml`), `detected` (the project on disk) or `default`.
+ * @typedef {{gates: Record<string, 'flag'|'existing'|'detected'>, proof: Record<string, 'flag'|'existing'|'detected'|'default'>}} Origins
+ */
+
 /** The answer keys in step order. */
 export const ANSWER_KEYS = Object.freeze([
   'tools', 'yes_tools', 'harnesses', 'scope', 'method', 'provider', 'levels', 'refresh_models',
@@ -283,11 +311,13 @@ export const ANSWER_KEYS = Object.freeze([
  * @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'>}}
+ * @returns {{values: Answers, sources: Record<string, 'default'|'existing'|'flag'>, origins: Origins}}
  */
 export function resolveAnswers(ctx, existing, user, given) {
   /** @type {Record<string, 'default'|'existing'|'flag'>} */
   const sources = {};
+  /** @type {Origins} */
+  const origins = { gates: {}, proof: {} };
   const ex = existing ?? {};
   /** @type {any} */
   const v = {};
@@ -352,38 +382,64 @@ export function resolveAnswers(ctx, existing, user, given) {
   set('solo_project', user?.solo?.project_id, () => null);
   if (lastFlag('solo_project')) override('solo_project', lastFlag('solo_project').value);
 
+  // Gates and proof are never asked (B24): each value comes from a flag, else the existing
+  // config, else the project. `origins` records which, per gate and per proof key. A gate the
+  // existing config left blank is filled when the project now shows one; a set gate is kept.
   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);
+  const exGates = ex.gates && typeof ex.gates === 'object' ? ex.gates : {};
+  // keys beyond the four gates (`extra`, `full_suite_threshold_files`, …) are kept as they are
+  const gates = /** @type {Record<string, any>} */ (clone(exGates));
+  for (const name of GATE_NAMES) {
+    const kept = exGates[name];
+    const keep = kept !== undefined && kept !== null;
+    gates[name] = keep ? clone(kept) : detectedGates[/** @type {keyof typeof detectedGates} */ (name)];
+    origins.gates[name] = keep ? 'existing' : 'detected';
+  }
+  set('gates', Object.keys(exGates).length > 0 ? gates : undefined, () => gates);
   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 flagged = clone(v.gates);
+    for (const g of flagsFor('gates')) {
+      flagged[g.value.name] = g.value.argv;
+      origins.gates[g.value.name] = 'flag';
+    }
+    override('gates', flagged);
   }
 
-  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);
+  const proposal = proposeProof(ctx.profile, ctx.cwd);
+  const exProof = ex.proof && typeof ex.proof === 'object' ? ex.proof : {};
+  /** @type {Record<string, unknown>} */
+  const exProofValues = {
+    high: exProof.tiers?.high?.paths,
+    isolation: exProof.isolation,
+    link_dirs: exProof.export?.link_dirs,
+    copy_untracked: exProof.export?.copy_untracked,
+  };
+  const proof = /** @type {Record<string, any>} */ ({});
+  for (const key of PROOF_KEYS) {
+    const kept = exProofValues[key];
+    const keep = kept !== undefined && kept !== null;
+    proof[key] = keep ? clone(kept) : proposal[/** @type {keyof typeof proposal} */ (key)];
+    // without a cwd nothing was looked at, so the lists are defaults, not detections
+    const looked = ctx.cwd !== undefined && (key === 'link_dirs' || key === 'copy_untracked');
+    origins.proof[key] = keep ? 'existing' : looked ? 'detected' : 'default';
+  }
+  set('proof', ex.proof && typeof ex.proof === 'object' ? proof : undefined, () => proof);
   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);
+    const flagged = clone(v.proof);
+    for (const g of flagsFor('proof')) {
+      flagged[g.value.key] = g.value.value;
+      origins.proof[g.value.key] = 'flag';
+    }
+    override('proof', flagged);
   }
 
   set('doctor', undefined, () => true);
   if (lastFlag('doctor')) override('doctor', false);
 
-  return { values: v, sources };
+  return { values: v, sources, origins };
 }

package/src/install/wizard/flags.mjs

@@ -13,16 +13,17 @@
  * into any flag by mistake).
  */
 
-import { isOpRef } from '../../keys/onepassword.mjs';
+import { isOpInput } from '../../keys/onepassword.mjs';
 import { HARNESSES } from '../harnesses.mjs';
+import { TOOL_IDS } from '../tools.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']);
+/** Tools step 1 knows how to detect (and, for some, install after a per-tool yes): the shared table's ids (B26). */
+export { TOOL_IDS };
 
 /** flag (as typed) -> the one answer key it overrides. */
 export const ANSWER_FLAGS = Object.freeze({
@@ -166,8 +167,9 @@ function convert(flag, value) {
       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;
+      // shape only here (parsing is sync); an item ID or link is resolved to op:// in run.mjs (B25)
+      if (!isOpInput(value)) throw new UsageError('--jev-ref must be a 1Password item ID, item link or op://vault/item/field reference');
+      return value.trim();
     case '--jev-env':
       if (!ENV_NAME.test(value)) throw new UsageError('--jev-env must be an environment variable name');
       return value;