@codedology/code-forge 0.2.0 → 0.2.2

package/src/install/wizard/run.mjs

@@ -1,7 +1,9 @@
 /**
  * `code-forge init` — the nine-step setup wizard (plan §2; block B13a).
  *
- * Order: answers (defaults ← existing config ← flags; then questions when interactive) → step 5
+ * Order: answers (defaults ← existing config ← flags; then questions when interactive) → the
+ * "Project settings (detected)" summary of gates and proof (B24; interactive: one "Use these /
+ * Customize now / Leave for later" choice, and the eight pre-filled questions on Customize) → step 5
  * key source → build + merge + validate the config (nothing is written when it is invalid or a
  * required answer is missing) → write `.code-forge.yml` only when it changes → tools (step 1),
  * model refresh (3), harness links (2), user config → the §5.1 stop line when the harness has no
@@ -9,7 +11,7 @@
  *
  * Output: an agent harness (`CLAUDECODE`, `CLAUDE_CODE`, `CURSOR_AGENT`, `CODEX_SANDBOX*`, `AI_AGENT`) or
  * a non-TTY stdin gets exactly ONE JSON line on stdout — `{ok, wrote, harnesses, engine_stop,
- * doctor, log, log_tail}` on success, `{ok: false, error, wrote, log, log_tail}` on any failure
+ * doctor, settings, blank, log, log_tail}` on success, `{ok: false, error, wrote, log, log_tail}` on any failure
  * after the flags parsed; a person gets the lines (and `init: <error>` on stderr). Either way the
  * lines go to `~/.code-forge/logs/init-<ts>.log`, on failure too. Every line passes through
  * `redact`; a key typed at the prompt goes to the key store and nowhere else — the config holds its
@@ -24,17 +26,19 @@ import { parse as parseYAML } from 'yaml';
 import { DEFAULT_CONFIG_FILENAME, loadConfigFile } from '../../config/load.mjs';
 import { refreshFromCliCaches } from '../../config/refresh.mjs';
 import { validateConfig } from '../../config/validate.mjs';
+import { describeOpItem, isOpRef, OP_MESSAGES, toOpRef } from '../../keys/onepassword.mjs';
 import { createDefaultKeyStore, resolveKey } from '../../keys/store.mjs';
 import { exec } from '../../util/exec.mjs';
 import { redact } from '../../util/redact.mjs';
 import { writeAgentJson } from '../agent-env.mjs';
-import { commandOnPath } from '../detect.mjs';
+import { detectTool, failureReason, installPlan, TOOLS } from '../tools.mjs';
 import { getHarness, globalSkillPath, projectSkillPath } from '../harnesses.mjs';
 import { install, installsPath } from '../link.mjs';
 import { currentHarness, effectiveProvider, gatherContext, judgeCollision, proposeJudge, resolveAnswers, SUBAGENT_HARNESSES } from './answers.mjs';
 import { changedPaths, generatedConfig, mergeConfig, mergeInto, serializeConfig } from './project-file.mjs';
 import { parseInitArgs, UsageError } from './flags.mjs';
-import { askAnswers, askJevSource, CancelledError } from './steps.mjs';
+import { askAnswers, askJevSource, askProjectSettings, askSettingsChoice, CancelledError, HINTS, JEV_LATER_TEXT, withHint } from './steps.mjs';
+import { summarizeSettings } from './summary.mjs';
 
 /** §5.1's stop text, printed at setup (not at the first run) when there is no engine to use. */
 export const NO_ENGINE_STOP_TEXT = [
@@ -44,20 +48,17 @@ export const NO_ENGINE_STOP_TEXT = [
   '  Then re-run. (R2: this engine is never selected automatically.)',
 ].join('\n');
 
-/** Step 1's recommended tools: detect, print the install command, install only after a per-tool yes. */
-export const TOOLS = Object.freeze([
-  { id: 'solo', command: null, install: null, hint: 'install the Solo app (https://soloterm.com) and add its MCP entry' },
-  { id: 'codex', command: 'codex', install: ['npm', 'install', '-g', '@openai/codex'], hint: null },
-  { id: 'grok', command: 'grok', install: null, hint: 'install the Grok CLI from its vendor page' },
-  { id: 'gemini', command: 'gemini', install: ['npm', 'install', '-g', '@google/gemini-cli'], hint: null },
-  { id: 'op', command: 'op', install: ['brew', 'install', '1password-cli'], hint: null },
-]);
+/**
+ * Step 1's recommended tools: the shared table (B26, `src/install/tools.mjs`) — detect, print the
+ * install command, install only after a per-tool yes.
+ */
+export { TOOLS };
 
 export const USAGE = [
   'usage: code-forge init [--no-interaction] [--tools recommended|current] [--yes-tool <tool>]…',
   '  [--harness a,b] [-g|-p] [--copy] [--provider P] [--level Ln=model[:effort][@provider]]…',
   '  [--refresh-models] [--multimodel on|off] [--second-provider P]',
-  '  [--jev-ref op://… | --jev-env NAME | --no-jev] [--engine auto|solo|harness] [--solo-project N]',
+  '  [--jev-ref <item-id|link|op://…> | --jev-env NAME | --no-jev] [--engine auto|solo|harness] [--solo-project N]',
   '  [--gate name=cmd]… [--proof isolation=export|lock | high=a,b | link_dirs=a,b | copy_untracked=a,b]… [--skip-doctor]',
 ].join('\n');
 
@@ -77,10 +78,11 @@ const JEV_ENV_NAME = 'CODE_FORGE_KEY_JEV';
 
 /** A failure after the flags parsed: carries the exit code; the message names key paths, never values. */
 class InitFailure extends Error {
-  /** @param {number} code @param {string} message */
-  constructor(code, message) {
+  /** @param {number} code @param {string} message @param {string|null} [kind] - a 1Password failure kind (B25) */
+  constructor(code, message, kind = null) {
     super(message);
     this.code = code;
+    this.kind = kind;
   }
 }
 
@@ -97,9 +99,12 @@ class InitFailure extends Error {
  * @property {import('./steps.mjs').Ui} [ui] - default `@clack/prompts`.
  * @property {() => Promise<any>} [getStore] - the B2 key store (default: the production chain).
  * @property {(opts: {cwd: string, env: NodeJS.ProcessEnv}) => Promise<Array<{status: string, label: string, detail: string}>>} [doctor]
- * @property {(argv: string[]) => Promise<{result: string}>} [installTool]
+ * @property {(argv: string[]) => Promise<{result: string, code?: number|null, signal?: string|null, timedOut?: boolean}>} [installTool]
  * @property {string} [skillSource]
  * @property {() => Date} [now]
+ * @property {typeof exec} [opExec] - runs `op` to resolve a 1Password item ID (default B0 `exec`).
+ * @property {NodeJS.Platform} [platform] - step 1's install plan (brew on macOS only; default `process.platform`).
+ * @property {(p: string) => boolean} [toolExists] - step 1's Solo app check (tests: a fake).
  */
 
 /** @param {string} file @returns {Promise<Record<string, any>|null>} a missing or unreadable user config reads as null */
@@ -164,13 +169,17 @@ export async function runInit(args, deps = {}) {
   let engineStop = false;
   /** @type {{ok: boolean, counts: Record<string, number>} | null} */
   let doctor = null;
+  /** @type {import('./summary.mjs').SettingsSummary | null} */
+  let summary = null;
+  // lines already on stdout (the settings summary): `finish` prints only the rest
+  let printed = 0;
 
   /**
    * The one exit: writes the log, then either the success shape or `{ok: false, error, wrote, …}`.
-   * @param {number} code @param {string|null} error
+   * @param {number} code @param {string|null} error @param {string|null} [kind] - a 1Password failure kind
    * @returns {Promise<number>}
    */
-  const finish = async (code, error) => {
+  const finish = async (code, error, kind = null) => {
     if (error !== null) {
       say(`error: ${error}`);
       stderr.write(redact(`init: ${error}\n`));
@@ -186,11 +195,12 @@ export async function runInit(args, deps = {}) {
     const tail = lines.slice(-10);
     if (jsonMode) {
       const body = error === null
-        ? { ok: code === 0, wrote, harnesses: linked, engine_stop: engineStop, doctor, log, log_tail: tail }
-        : { ok: false, error, wrote, log, log_tail: tail };
+        ? { ok: code === 0, wrote, harnesses: linked, engine_stop: engineStop, doctor, settings: summary?.settings ?? null, blank: summary?.blank ?? [], log, log_tail: tail }
+        : { ok: false, error, ...(kind ? { kind } : {}), wrote, log, log_tail: tail };
       writeAgentJson(JSON.parse(redact(JSON.stringify(body))), { stdout });
     } else if (error === null) {
-      stdout.write(`${lines.join('\n')}\nlog: ${log}\n`);
+      const rest = lines.slice(printed);
+      stdout.write(`${rest.length > 0 ? `${rest.join('\n')}\n` : ''}log: ${log}\n`);
     }
     return code;
   };
@@ -215,12 +225,34 @@ export async function runInit(args, deps = {}) {
     const userFile = path.join(cfDir, USER_CONFIG_FILE);
     const userCfg = await readUserConfig(userFile);
 
-    const { values, sources } = resolveAnswers(ctx, existing, userCfg, parsed.given);
+    const { values, sources, origins } = resolveAnswers(ctx, existing, userCfg, parsed.given);
     if (interactive) {
       ui = deps.ui ?? /** @type {any} */ (await import('@clack/prompts'));
       await askAnswers(values, sources, ctx, ui);
     }
 
+    // Gates and proof are never asked (B24): the summary says what was found and what is blank.
+    // A person sees it now, before anything is written; agent mode gets it in the JSON line.
+    summary = summarizeSettings(values, origins, ctx);
+    /** @param {string[]} shown - logged, and printed at once for a person */
+    const showNow = (shown) => {
+      for (const line of shown) say(line);
+      if (jsonMode) return;
+      stdout.write(`${lines.slice(printed).join('\n')}\n`);
+      printed = lines.length;
+    };
+    showNow(summary.lines);
+    if (interactive) {
+      const choice = await askSettingsChoice(ui);
+      if (choice === 'customize') {
+        const changedKeys = await askProjectSettings(values, origins, ui);
+        say(`settings: customized (${changedKeys.length > 0 ? changedKeys.join(', ') : 'no change'})`);
+      } else if (choice === 'later') {
+        const keys = summary.blank.length > 0 ? summary.blank : Object.keys(summary.settings);
+        showNow([`settings: edit .code-forge.yml later: ${keys.join(', ')} — then run \`code-forge validate\``]);
+      }
+    }
+
     // Step 5 — where the Jev key comes from. Only a reference is ever kept: `env:NAME` when the
     // environment holds it, else `user` (the key store holds it, whatever backend the store
     // reports — keychain, file, a cached 1Password read…); the backend name is recorded as the
@@ -229,16 +261,43 @@ export async function runInit(args, deps = {}) {
     const missing = [];
     let jevRef = null;
     let jevSource = 'none';
+    const resolveOp = (/** @type {string} */ input) => toOpRef(input, deps.opExec ? { exec: deps.opExec } : {});
+    /** @param {import('./steps.mjs').JevAnswer} a */
+    const takeAnswer = (a) => {
+      jevRef = a.ref;
+      jevSource = a.source;
+      const found = a.found ? describeOpItem(a.found) : null;
+      if (found) say(`keys: jev from ${found}`);
+      if (a.ref === null) say(JEV_LATER_TEXT);
+    };
     if (values.jev.mode === 'ref') {
       jevRef = values.jev.ref;
-      jevSource = jevRef.startsWith('env:') ? 'env' : jevRef.startsWith('op://') ? 'op' : 'keychain';
+      // B25: a --jev-ref item ID or link becomes a full op:// reference before anything is written
+      if (!jevRef.startsWith('env:') && !isOpRef(jevRef) && jevRef !== 'user' && !jevRef.startsWith('keychain:')) {
+        /** @type {Awaited<ReturnType<typeof toOpRef>>} */
+        let res;
+        try {
+          res = await resolveOp(jevRef);
+        } catch {
+          // never the thrown message: it could carry op output
+          res = { ref: null, kind: 'op_failed', error: `${OP_MESSAGES.op_failed} (unexpected error)` };
+        }
+        if (res.ref !== null) {
+          takeAnswer({ ref: res.ref, source: 'op', found: { title: res.title, vault: res.vault, field: res.field } });
+        } else {
+          const error = res.error ?? OP_MESSAGES.op_failed;
+          if (interactive) takeAnswer(await askJevSource(ui, getStore, { resolve: resolveOp, pending: { input: jevRef, error } }));
+          else throw new InitFailure(2, `--jev-ref: ${error}. Nothing written.`, res.kind ?? 'op_failed');
+        }
+      }
+      if (jevRef !== null) jevSource = jevRef.startsWith('env:') ? 'env' : jevRef.startsWith('op://') ? 'op' : 'keychain';
     } else if (values.jev.mode === 'auto') {
       const res = await resolveKey('jev', { store: await getStore(), env });
       if (res.value !== null && typeof res.source === 'string') {
         jevRef = res.source === 'env' ? `env:${JEV_ENV_NAME}` : 'user';
         jevSource = res.source;
       } else if (interactive) {
-        ({ ref: jevRef, source: jevSource } = await askJevSource(ui, getStore));
+        takeAnswer(await askJevSource(ui, getStore, { resolve: resolveOp }));
       } else {
         missing.push('keys.jev (pass --jev-ref, --jev-env or --no-jev)');
       }
@@ -278,7 +337,7 @@ export async function runInit(args, deps = {}) {
       say(`${DEFAULT_CONFIG_FILENAME}: unchanged`);
     } else {
       if (existing) say(`${DEFAULT_CONFIG_FILENAME}: changes ${changed.join(', ')}`);
-      const go = existing && interactive ? await ui.confirm({ message: `Apply ${changed.length} change(s) to ${DEFAULT_CONFIG_FILENAME}?`, initialValue: true }) : true;
+      const go = existing && interactive ? await ui.confirm({ message: withHint(`Apply ${changed.length} change(s) to ${DEFAULT_CONFIG_FILENAME}?`, HINTS.apply), initialValue: true }) : true;
       if (ui?.isCancel(go) || go !== true) throw new CancelledError('cancelled — nothing written');
       await writeText(configFile, serializeConfig(merged));
       wrote.push(configFile);
@@ -289,15 +348,19 @@ export async function runInit(args, deps = {}) {
 
     // Step 1 — tools.
     if (values.tools === 'recommended') {
+      const toolOpts = { pathEnv: env.PATH ?? '', platform: deps.platform ?? process.platform, home, ...(deps.toolExists ? { exists: deps.toolExists } : {}) };
       for (const tool of TOOLS) {
-        const present = tool.command === null ? ctx.solo : await commandOnPath(tool.command, { pathEnv: env.PATH ?? '' });
+        const present = (tool.id === 'solo' && ctx.solo) || (await detectTool(tool, toolOpts));
         if (present) {
           say(`tool ${tool.id}: present`);
-        } else if (tool.install && values.yes_tools.includes(tool.id)) {
-          const res = await (deps.installTool ?? ((argv) => exec(argv, { timeoutMs: 600_000, env })))(tool.install);
-          say(`tool ${tool.id}: ${res.result === 'ok' ? 'installed' : 'install failed'} (${tool.install.join(' ')})`);
+          continue;
+        }
+        const plan = await installPlan(tool, toolOpts);
+        if (plan.kind === 'run' && values.yes_tools.includes(tool.id)) {
+          const res = await (deps.installTool ?? ((argv) => exec(argv, { timeoutMs: 600_000, env })))(plan.argv);
+          say(`tool ${tool.id}: ${res.result === 'ok' ? 'installed' : `install failed (${failureReason(res)})`} (${plan.argv.join(' ')})`);
         } else {
-          say(`tool ${tool.id}: missing — ${tool.install ? `install with: ${tool.install.join(' ')}` : tool.hint} (doctor WARNs)`);
+          say(`tool ${tool.id}: missing — ${plan.kind === 'run' ? `install with: ${plan.argv.join(' ')}` : plan.hint} (or: code-forge tools install)`);
         }
       }
     }
@@ -355,7 +418,7 @@ export async function runInit(args, deps = {}) {
 
     return await finish(doctor === null || doctor.ok ? 0 : 1, null);
   } catch (err) {
-    if (err instanceof InitFailure) return finish(err.code, err.message);
+    if (err instanceof InitFailure) return finish(err.code, err.message, err.kind);
     if (err instanceof UsageError) return finish(2, err.message);
     if (err instanceof CancelledError) return finish(1, err.message);
     // an unexpected throw (an installer, a link, the doctor…): the log keeps the stack, redacted