@codedology/code-forge 0.2.1 → 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/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;

package/src/install/wizard/run.mjs

@@ -26,17 +26,18 @@ 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, askProjectSettings, askSettingsChoice, CancelledError, HINTS, withHint } 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. */
@@ -47,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');
 
@@ -80,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;
   }
 }
 
@@ -100,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 */
@@ -174,10 +176,10 @@ export async function runInit(args, deps = {}) {
 
   /**
    * 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`));
@@ -194,7 +196,7 @@ export async function runInit(args, deps = {}) {
     if (jsonMode) {
       const body = error === null
         ? { ok: code === 0, wrote, harnesses: linked, engine_stop: engineStop, doctor, settings: summary?.settings ?? null, blank: summary?.blank ?? [], log, log_tail: tail }
-        : { ok: false, error, wrote, 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) {
       const rest = lines.slice(printed);
@@ -259,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)');
       }
@@ -319,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)`);
         }
       }
     }
@@ -385,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

package/src/install/wizard/steps.mjs

@@ -8,7 +8,7 @@
  * because it is asked only when the chain resolves nothing.
  */
 
-import { isOpRef } from '../../keys/onepassword.mjs';
+import { isOpRef, OP_MESSAGES } 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';
@@ -32,8 +32,20 @@ async function answer(ui, pending) {
   return value;
 }
 
-/** The 1Password option's hint: where to find the reference in the app. */
-export const OP_REF_HINT = 'In the 1Password app, right-click the key field → Copy Secret Reference (op://vault/item/field).';
+/** The 1Password option's hint: where to find the item ID, link or reference in the app. */
+export const OP_REF_HINT = "Paste the item ID (from `op item list`), the item's link, or its op:// secret reference.";
+
+/** The 1Password question (B25): an item ID or link is resolved to a full `op://` reference. */
+export const OP_REF_QUESTION = '1Password item ID, item link, or op:// reference';
+
+/** The question after "Enter a full op:// reference": op:// only, no lookup. */
+export const OP_FULL_REF_QUESTION = 'Full op://vault/item/field reference';
+
+/** The menu message when the resolver itself threw (its message is never shown). */
+export const OP_RESOLVE_FAILED = '1Password CLI failed (unexpected error); run `op item get <item-id>` yourself to see why';
+
+/** Printed when the Jev key is left unset, so the person knows how to set it later. */
+export const JEV_LATER_TEXT = 'keys: jev not set — set it later with: code-forge keys set jev --op <item-id>';
 
 /** The one-sentence hint line under each question (B24). */
 export const HINTS = Object.freeze({
@@ -262,40 +274,114 @@ export async function askProjectSettings(values, origins, ui) {
   return changed;
 }
 
+/**
+ * @typedef {(input: string) => Promise<{ref: string|null, error?: string, kind?: string, title?: string, vault?: string, field?: string}>} OpResolver
+ * @typedef {{ref: string|null, source: string, found?: {title?: string, vault?: string, field?: string}}} JevAnswer
+ */
+
+/**
+ * The 1Password branch: ask for an item ID, link or reference, resolve it, and on a failure offer
+ * Try again · Enter a full op:// reference · Choose another key source · Skip for now. Never throws
+ * on a 1Password failure. Returns null for "choose another key source".
+ * @param {Ui} ui
+ * @param {OpResolver} resolve
+ * @param {{input: string, error: string}|null} pending - start at the failure menu (a flag value that failed).
+ * @returns {Promise<JevAnswer|null>}
+ */
+async function askOpRef(ui, resolve, pending) {
+  let input = pending?.input ?? '';
+  let error = pending?.error ?? null;
+  let question = OP_REF_QUESTION;
+  for (;;) {
+    if (error === null) {
+      input = String(await answer(ui, ui.text({ message: withHint(question, OP_REF_HINT), ...(input ? { initialValue: input } : {}) }))).trim();
+      /** @type {Awaited<ReturnType<OpResolver>>} */
+      let res;
+      if (question !== OP_REF_QUESTION && !isOpRef(input)) {
+        // "full reference" mode takes op:// only; nothing is looked up
+        res = { ref: null, kind: 'op_bad_input', error: OP_MESSAGES.op_bad_input };
+      } else {
+        try {
+          const got = await resolve(input);
+          // a resolver that answers with anything but the documented shape counts as a failure
+          res = got && typeof got === 'object' && (got.ref === null || typeof got.ref === 'string')
+            ? got
+            : { ref: null, kind: 'op_failed', error: OP_RESOLVE_FAILED };
+        } catch {
+          // never the thrown message: it could carry op output
+          res = { ref: null, kind: 'op_failed', error: OP_RESOLVE_FAILED };
+        }
+      }
+      if (res.ref !== null) {
+        return { ref: res.ref, source: 'op', found: { title: res.title, vault: res.vault, field: res.field } };
+      }
+      error = res.error ?? OP_RESOLVE_FAILED;
+    }
+    const next = await answer(ui, ui.select({
+      message: withHint('1Password lookup failed. What next?', error),
+      options: [
+        { value: 'retry', label: 'Try again' },
+        { value: 'full', label: 'Enter a full op:// reference' },
+        { value: 'other', label: 'Choose another key source' },
+        { value: 'skip', label: 'Skip for now' },
+      ],
+      initialValue: 'retry',
+    }));
+    error = null;
+    if (next === 'other') return null;
+    if (next === 'skip') return { ref: null, source: 'none' };
+    if (next === 'full') {
+      question = OP_FULL_REF_QUESTION;
+      input = '';
+    } else {
+      question = OP_REF_QUESTION;
+    }
+  }
+}
+
 /**
  * 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.
+ * input and handed straight to `store`; it is never returned, echoed or logged. A 1Password item ID
+ * or link is resolved to `op://<vaultId>/<itemId>/<fieldId>` through `opts.resolve` (B25).
  * @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}>}
+ * @param {{resolve?: OpResolver, pending?: {input: string, error: string}|null}} [opts]
+ * @returns {Promise<JevAnswer>}
  */
-export async function askJevSource(ui, getStore) {
-  const choice = await answer(ui, ui.select({
-    message: withHint('Where is the Jev key?', HINTS.jev),
-    options: [
-      { value: 'op', label: '1Password reference', hint: OP_REF_HINT },
-      { 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: withHint('1Password reference (op://vault/item/field)', OP_REF_HINT) }))).trim();
-    if (!isOpRef(ref)) throw new UsageError('not an op://vault/item/field reference');
-    return { ref, source: 'op' };
+export async function askJevSource(ui, getStore, { resolve, pending = null } = {}) {
+  if (typeof resolve !== 'function') throw new TypeError('askJevSource: opts.resolve (the 1Password resolver) is required');
+  if (pending) {
+    const fromOp = await askOpRef(ui, resolve, pending);
+    if (fromOp) return fromOp;
   }
-  if (choice === 'env') {
-    const name = String(await answer(ui, ui.text({ message: withHint('Environment variable name', HINTS.env) }))).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: withHint('Jev key (input hidden)', HINTS.paste) }));
-    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' };
+  for (;;) {
+    const choice = await answer(ui, ui.select({
+      message: withHint('Where is the Jev key?', HINTS.jev),
+      options: [
+        { value: 'op', label: '1Password item or reference', hint: OP_REF_HINT },
+        { 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 fromOp = await askOpRef(ui, resolve, null);
+      if (fromOp) return fromOp;
+      continue;
+    }
+    if (choice === 'env') {
+      const name = String(await answer(ui, ui.text({ message: withHint('Environment variable name', HINTS.env) }))).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: withHint('Jev key (input hidden)', HINTS.paste) }));
+      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' };
   }
-  return { ref: null, source: 'none' };
 }