@codedology/code-forge 0.2.2 → 0.3.0

package/src/install/wizard/run.mjs

@@ -26,7 +26,7 @@ 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 { describeOpItem, isOpRef, OP_APPROVE_NOTE, OP_MESSAGES, opItemIdFromInput, toOpRef } from '../../keys/onepassword.mjs';
 import { createDefaultKeyStore, resolveKey } from '../../keys/store.mjs';
 import { exec } from '../../util/exec.mjs';
 import { redact } from '../../util/redact.mjs';
@@ -261,7 +261,12 @@ 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 } : {});
+    const resolveOp = (/** @type {string} */ input) => {
+      // printed at once (stderr), not buffered: the approval prompt appears while op waits
+      // only when op will really be called: an item ID or a 1Password link (an op:// ref is kept as is)
+      if (opItemIdFromInput(String(input ?? '')) !== null) stderr.write(`${OP_APPROVE_NOTE}\n`);
+      return toOpRef(input, deps.opExec ? { exec: deps.opExec } : {});
+    };
     /** @param {import('./steps.mjs').JevAnswer} a */
     const takeAnswer = (a) => {
       jevRef = a.ref;

package/src/keys/onepassword.mjs

@@ -11,9 +11,14 @@
  * reference is built.
  */
 
+import { reportErrorKind } from '../util/error-kind.mjs';
 import { exec as realExec } from '../util/exec.mjs';
 
-export const OP_TIMEOUT_MS = 20_000;
+// Long enough for a person to see and approve the 1Password prompt (Touch ID or password).
+export const OP_TIMEOUT_MS = 60_000;
+
+/** Shown just before a call that may make 1Password ask for approval. */
+export const OP_APPROVE_NOTE = '1Password may ask you to approve access: check the 1Password window (Touch ID or password).';
 
 /** The 1Password failure kinds; agent JSON carries the kind. */
 export const OP_ERROR_KINDS = Object.freeze(['op_missing', 'op_locked', 'op_timeout', 'op_not_found', 'op_bad_output', 'op_no_field', 'op_bad_input', 'op_failed']);
@@ -184,10 +189,13 @@ export async function opRead(ref, { exec = realExec, timeoutMs = OP_TIMEOUT_MS }
   const { res, attempts } = await runOp(['op', 'read', ref], exec, timeoutMs);
   if (res.result !== 'ok') {
     const kind = classifyOpFailure(res);
+    reportErrorKind(kind); // the error log's kind if the verb then fails (B27)
     return { value: null, attempts, error: failureMessage(kind, res, `op read ${ref}`, '; check the reference'), kind };
   }
   const value = res.stdout.replace(/\r?\n$/, '');
-  return value.length > 0 ? { value, attempts } : { value: null, attempts, error: OP_MESSAGES.op_bad_output, kind: 'op_bad_output' };
+  if (value.length > 0) return { value, attempts };
+  reportErrorKind('op_bad_output');
+  return { value: null, attempts, error: OP_MESSAGES.op_bad_output, kind: 'op_bad_output' };
 }
 
 /**
@@ -272,8 +280,10 @@ export async function toOpRef(input, opts = {}) {
   const text = typeof input === 'string' ? input.trim() : input;
   if (isOpRef(text)) return { ref: /** @type {string} */ (text) };
   const id = opItemIdFromInput(text);
-  if (id !== null) return resolveOpItemRef(id, opts);
-  return { ref: null, error: OP_MESSAGES.op_bad_input, kind: 'op_bad_input' };
+  /** @type {OpRefResult} */
+  const res = id !== null ? await resolveOpItemRef(id, opts) : { ref: null, error: OP_MESSAGES.op_bad_input, kind: 'op_bad_input' };
+  if (res.ref === null) reportErrorKind(res.kind); // the error log's kind if the verb then fails (B27)
+  return res;
 }
 
 /**

package/src/session/scrub.mjs

@@ -0,0 +1,266 @@
+/**
+ * The AI cleaning pass of an error report (block B28): a second pass after the deterministic scrub,
+ * never the only one.
+ *
+ * One closed-book session through {@link spawnSession} (plan §5.2; skill/references/security.md
+ * §4): print mode, a fresh empty temp cwd, the packet on stdin, no tools — the `reviewer` role,
+ * whose closed-book shape is exactly that, at level L1 resolved the normal way (`resolveLevel` on
+ * the project's `.code-forge.yml`; outside a project, the shipped defaults of its provider or of
+ * `anthropic`). The model only LISTS what it would hide (`{items: [{text, kind, reason}]}`); this
+ * module replaces every exact substring itself, longest first, with `<kind>`, never inside one of
+ * the tool's own placeholders. An item whose text is not in the report (or is blank or shorter
+ * than 3 characters) is ignored. Anything but a valid answer
+ * — no CLI, login expired, a timeout, bad JSON — makes the pass `unavailable` with a plain reason.
+ */
+
+import { randomBytes } from 'node:crypto';
+import { mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { resolveLevel } from '../config/known-ids.mjs';
+import { defaultsForProvider } from '../config/defaults/index.mjs';
+import { loadProjectConfig } from '../config/load.mjs';
+import { SCRUB_PLACEHOLDERS } from '../util/error-log.mjs';
+import { currentRunRoot } from '../util/tmp.mjs';
+import { spawnSession } from './spawn.mjs';
+
+/** The kinds an item may have; any other kind the model names counts as `other`. */
+export const AI_KINDS = Object.freeze(['person', 'company', 'project', 'host', 'url', 'account', 'path', 'secret', 'other']);
+
+/** Singular and plural for the cleaning summary. */
+const KIND_LABELS = Object.freeze({
+  person: ['person', 'people'],
+  company: ['company', 'companies'],
+  project: ['project', 'projects'],
+  host: ['host', 'hosts'],
+  url: ['URL', 'URLs'],
+  account: ['account', 'accounts'],
+  path: ['path', 'paths'],
+  secret: ['secret', 'secrets'],
+  other: ['other item', 'other items'],
+});
+
+/** The whole packet the AI may see, in bytes (cost guard); a longer report is cut first. */
+export const AI_MAX_BYTES = 16 * 1024;
+
+/** Wall-clock cap of the AI session. */
+export const AI_TIMEOUT_MS = 180_000;
+
+/** An item shorter than this is ignored: replacing it would mangle ordinary words. */
+export const MIN_ITEM_LENGTH = 3;
+
+/** The answer schema (source form; `spawnSession` compiles it per provider). */
+export const SCRUB_SCHEMA = Object.freeze({
+  type: 'object',
+  properties: {
+    items: {
+      type: 'array',
+      items: {
+        type: 'object',
+        properties: { text: { type: 'string' }, kind: { type: 'string' }, reason: { type: 'string' } },
+        required: ['text', 'kind', 'reason'],
+        additionalProperties: false,
+      },
+    },
+  },
+  required: ['items'],
+  additionalProperties: false,
+});
+
+/** The system prompt of the session. */
+export const SCRUB_LENS =
+  'You check an error report before it is posted publicly. You have no tools and no files; the report is in the message. ' +
+  'You never rewrite the report: you only list what should be hidden. Answer once, with JSON only.';
+
+/**
+ * @param {string} report - the title and body, already cleaned by the deterministic scrub.
+ * @returns {string} the packet.
+ */
+export function buildScrubPrompt(report) {
+  return [
+    '# Find private details in this error report',
+    '',
+    'Find anything in the text that could identify a person, a company, a private project, a host, an internal URL, an account, a path, or anything that looks like a secret or credential.',
+    'Placeholders such as <project>, <slug>, <email>, <item-id>, op://<ref> and ~ are already cleaned: leave them out. Public names (code-forge, Node, GitHub, npm, an OS) are fine.',
+    'Return JSON only, exactly this shape:',
+    '{ "items": [{ "text": "<exact substring>", "kind": "person|company|project|host|url|account|path|secret|other", "reason": "<short>" }] }',
+    'Each "text" must be copied exactly from the report. Return { "items": [] } when nothing should be hidden.',
+    '',
+    '## Report',
+    '',
+    report,
+    '',
+  ].join('\n');
+}
+
+/** The report text that fits in the packet with the prompt around it, in bytes. */
+export const AI_REPORT_MAX_BYTES = AI_MAX_BYTES - Buffer.byteLength(buildScrubPrompt(''));
+
+/**
+ * @typedef {{text: string, kind: string}} ScrubItem
+ */
+
+/**
+ * The usable items of an answer: a string `text` of at least {@link MIN_ITEM_LENGTH} characters
+ * that is not blank;
+ * an unknown `kind` becomes `other`.
+ * @param {unknown} answer
+ * @returns {ScrubItem[]|null} null when the answer is not `{items: [...]}`.
+ */
+export function readItems(answer) {
+  if (!answer || typeof answer !== 'object' || !Array.isArray(/** @type {any} */ (answer).items)) return null;
+  /** @type {ScrubItem[]} */
+  const out = [];
+  for (const item of /** @type {any} */ (answer).items) {
+    if (!item || typeof item.text !== 'string' || item.text.trim().length === 0 || item.text.length < MIN_ITEM_LENGTH) continue;
+    const lower = typeof item.kind === 'string' ? item.kind.toLowerCase() : '';
+    const kind = AI_KINDS.includes(lower) ? lower : 'other';
+    out.push({ text: item.text, kind });
+  }
+  return out;
+}
+
+/** The placeholders the tool itself writes: the deterministic scrub's and the AI pass's own. */
+export const PROTECTED_PLACEHOLDERS = Object.freeze([...SCRUB_PLACEHOLDERS, ...AI_KINDS.map((k) => `<${k}>`)]);
+
+/**
+ * Replace every exact occurrence of each item's text with `<kind>`, in one pass over each
+ * ORIGINAL text: match ranges are collected for every item, longest text first, then the output
+ * is built. Only the tool's own placeholders ({@link PROTECTED_PLACEHOLDERS}) are protected: a
+ * range that starts or ends inside one (an item "path" against `<path>`) is skipped, while a range
+ * that fully contains one is replaced as a whole (`acme-<project>-prod` → `<host>`). Any other
+ * `<…>` text (`<jdoe@acme-corp.com>`, `Map<AcmeBillingClient>`) is ordinary text. A range that
+ * overlaps one already taken is skipped. Counts are ranges replaced per kind; a missing text
+ * counts 0.
+ * @param {string[]} texts
+ * @param {ScrubItem[]} items
+ * @returns {{texts: string[], counts: Array<{kind: string, count: number}>}}
+ */
+export function applyItems(texts, items) {
+  const sorted = [...items].sort((a, b) => b.text.length - a.text.length);
+  /** @type {Map<string, number>} */
+  const tally = new Map();
+  const out = texts.map((t) => {
+    /** @type {Array<[number, number]>} */
+    const guarded = [];
+    for (const p of PROTECTED_PLACEHOLDERS) {
+      for (let at = t.indexOf(p); at !== -1; at = t.indexOf(p, at + p.length)) guarded.push([at, at + p.length]);
+    }
+    /** @type {Array<{start: number, end: number, kind: string}>} */
+    const taken = [];
+    const blocked = (/** @type {number} */ a, /** @type {number} */ b) =>
+      // a range that is exactly one of our placeholders is never replaced (nothing new to hide)
+      guarded.some(([s, e]) => (a === s && b === e) || (a < e && s < b && !(a <= s && e <= b))) || taken.some((r) => a < r.end && r.start < b);
+    for (const { text, kind } of sorted) {
+      for (let at = t.indexOf(text); at !== -1; at = t.indexOf(text, at + 1)) {
+        const end = at + text.length;
+        if (blocked(at, end)) continue;
+        taken.push({ start: at, end, kind });
+        tally.set(kind, (tally.get(kind) ?? 0) + 1);
+      }
+    }
+    taken.sort((a, b) => a.start - b.start);
+    let built = '';
+    let pos = 0;
+    for (const r of taken) {
+      built += `${t.slice(pos, r.start)}<${r.kind}>`;
+      pos = r.end;
+    }
+    return built + t.slice(pos);
+  });
+  return { texts: out, counts: AI_KINDS.filter((k) => (tally.get(k) ?? 0) > 0).map((k) => ({ kind: k, count: /** @type {number} */ (tally.get(k)) })) };
+}
+
+/**
+ * "AI pass: 1 host, 1 company." / "AI pass: nothing found." — counts only, never the text.
+ * @param {Array<{kind: string, count: number}>} counts
+ * @returns {string}
+ */
+export function describeAiCounts(counts) {
+  const parts = counts.filter((c) => c.count > 0).map((c) => {
+    const label = Object.hasOwn(KIND_LABELS, c.kind) ? KIND_LABELS[/** @type {keyof typeof KIND_LABELS} */ (c.kind)] : [c.kind, c.kind];
+    return `${c.count} ${c.count === 1 ? label[0] : label[1]}`;
+  });
+  return parts.length > 0 ? `AI pass: ${parts.join(', ')}.` : 'AI pass: nothing found.';
+}
+
+/** @param {{status: string, reason?: string|null}} res @returns {string} */
+function plainReason(res) {
+  if (res.status === 'unavailable') {
+    if (res.reason === 'cli-missing') return 'the model CLI is not installed';
+    if (res.reason === 'login-expired') return 'the model CLI is not logged in';
+    if (res.reason === 'rate-limited' || res.reason === 'http-402') return 'the model is not available right now';
+    return 'the model is not available';
+  }
+  if (res.status === 'timeout') return 'it timed out';
+  if (res.status === 'invalid-output') return 'its answer was not valid JSON';
+  return 'the session failed';
+}
+
+/**
+ * The config L1 is resolved from: the project's when its L1 resolves, else the shipped defaults
+ * alone (of the project's provider, or `anthropic`; never the project's own levels mixed in).
+ * @param {string} cwd
+ * @returns {Promise<Record<string, any>>}
+ * @throws {Error} with a fixed message when the project config cannot be read.
+ */
+async function scrubConfig(cwd) {
+  const unreadable = new Error('the project config could not be read');
+  let loaded;
+  try {
+    loaded = await loadProjectConfig(cwd);
+  } catch {
+    throw unreadable;
+  }
+  if (!loaded.ok) {
+    if (loaded.error !== 'not-found') throw unreadable;
+    return /** @type {Record<string, any>} */ (defaultsForProvider('anthropic'));
+  }
+  try {
+    resolveLevel(loaded.config, 'L1');
+    return loaded.config;
+  } catch {
+    const provider = typeof loaded.config?.provider === 'string' ? loaded.config.provider : 'anthropic';
+    return /** @type {Record<string, any>} */ (defaultsForProvider(provider) ?? defaultsForProvider('anthropic'));
+  }
+}
+
+/**
+ * Run the AI pass over `report` (scrubbed, and cut to {@link AI_REPORT_MAX_BYTES}); a packet over
+ * {@link AI_MAX_BYTES} is refused, never sent.
+ * @param {{report: string, cwd: string, runRoot?: string, timeoutMs?: number}} opts
+ * @param {import('./spawn.mjs').SessionDeps} [deps]
+ * @returns {Promise<{ok: true, items: ScrubItem[]} | {ok: false, reason: string}>}
+ */
+export async function runAiScrub(opts, deps = {}) {
+  const packet = buildScrubPrompt(opts.report);
+  if (Buffer.byteLength(packet) > AI_MAX_BYTES) return { ok: false, reason: 'the report is over 16 KB' };
+  let cfg;
+  try {
+    cfg = await scrubConfig(opts.cwd);
+  } catch (e) {
+    return { ok: false, reason: /** @type {Error} */ (e).message };
+  }
+  let dir = null;
+  try {
+    const root = opts.runRoot ?? currentRunRoot();
+    dir = path.join(root, 'scrub', `${Date.now()}-${randomBytes(4).toString('hex')}`);
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const packetPath = path.join(dir, 'packet.md');
+    writeFileSync(packetPath, packet, { mode: 0o600 });
+    const res = await spawnSession(
+      { cfg, level: 'L1', role: 'reviewer', promptPath: packetPath, schema: SCRUB_SCHEMA, systemPromptText: SCRUB_LENS, runRoot: root, timeoutMs: opts.timeoutMs ?? AI_TIMEOUT_MS },
+      deps,
+    );
+    if (res.status !== 'ok') return { ok: false, reason: plainReason(res) };
+    const items = readItems(res.answer);
+    return items === null ? { ok: false, reason: 'its answer was not valid JSON' } : { ok: true, items };
+  } catch {
+    return { ok: false, reason: 'the session could not start' };
+  } finally {
+    try {
+      if (dir !== null) rmSync(dir, { recursive: true, force: true });
+    } catch {
+      // the packet dir lives in the run root, which the next sweep removes
+    }
+  }
+}

package/src/util/error-hint.mjs

@@ -0,0 +1,92 @@
+/**
+ * The one-line hint after a logged failure (B28). `bin/code-forge.mjs` calls {@link maybeHint}
+ * after the error log took a line; it prints {@link HINT_LINE} on stderr only when:
+ *  - stderr is a terminal and no agent harness runs code-forge (agent mode: one of
+ *    {@link AGENT_ENV_VARS}, the same names `src/install/agent-env.mjs` checks — copied here
+ *    because the router may only load `src/util`; a test keeps the two lists equal);
+ *  - the entry has a well-formed fingerprint (12 hex characters);
+ *  - the exit is not 2 (a usage error says what to fix already);
+ *  - the same fingerprint got no hint in the last 24 hours. The time of each hint is kept in
+ *    `~/.code-forge/logs/hints.json` (`{"<fp>": "<ISO time>"}`, 0600, older ones dropped).
+ * Never throws; a broken state file only means the hint may show again.
+ */
+
+import { mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+
+export const HINT_LINE = 'code-forge: this error was saved to the local log. To send it to us: code-forge logs report\n';
+
+/** A fingerprint: 12 lowercase hex characters. */
+const FP = /^[0-9a-f]{12}$/;
+
+/** At most one hint per fingerprint in this window. */
+export const HINT_WINDOW_MS = 24 * 60 * 60 * 1000;
+
+/** The agent-harness variables (same list and order as `src/install/agent-env.mjs`). */
+export const AGENT_ENV_VARS = Object.freeze(['CLAUDECODE', 'CLAUDE_CODE', 'CURSOR_AGENT', 'AI_AGENT']);
+
+/**
+ * @param {string|null|undefined} home
+ * @returns {string|null} the hint state file next to the error log, or null without a home.
+ */
+export function hintStatePath(home) {
+  return typeof home === 'string' && home.length > 0 ? path.join(home, '.code-forge', 'logs', 'hints.json') : null;
+}
+
+/** @param {NodeJS.ProcessEnv} env */
+function agentMode(env) {
+  return AGENT_ENV_VARS.some((name) => typeof env[name] === 'string' && /** @type {string} */ (env[name]).length > 0);
+}
+
+/**
+ * @param {object} o
+ * @param {{fp?: string}|null} o.entry - the entry the log just took (null: nothing was logged).
+ * @param {number} o.exit
+ * @param {boolean} o.isTTY - whether stderr is a terminal.
+ * @param {NodeJS.ProcessEnv} [o.env]
+ * @param {Date} [o.now]
+ * @param {{write: (s: string) => unknown}} [o.stderr]
+ * @returns {Promise<boolean>} whether the hint was printed.
+ */
+export async function maybeHint(o) {
+  try {
+    const env = o.env ?? process.env;
+    const fp = o.entry?.fp;
+    if (typeof fp !== 'string' || !FP.test(fp) || o.exit === 2 || o.isTTY !== true || agentMode(env)) return false;
+    const file = hintStatePath(env.HOME);
+    if (file === null) return false;
+    const now = (o.now ?? new Date()).getTime();
+    /** @type {Record<string, unknown>} */
+    let state = {};
+    try {
+      const parsed = JSON.parse(await readFile(file, 'utf8'));
+      if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) state = parsed;
+    } catch {
+      // no state yet, or a broken file: start over
+    }
+    const seen = state[fp];
+    const last = typeof seen === 'string' ? Date.parse(seen) : Number.NaN;
+    if (Number.isFinite(last) && now - last < HINT_WINDOW_MS && now >= last) return false;
+    /** @type {Record<string, string>} */
+    const kept = {};
+    for (const [key, ts] of Object.entries(state)) {
+      if (typeof ts !== 'string' || !FP.test(key)) continue;
+      const t = Date.parse(ts);
+      if (Number.isFinite(t) && now - t < HINT_WINDOW_MS && now >= t) kept[key] = ts;
+    }
+    kept[fp] = new Date(now).toISOString();
+    (o.stderr ?? process.stderr).write(HINT_LINE);
+    const tmp = `${file}.tmp-${process.pid}`;
+    try {
+      await mkdir(path.dirname(file), { recursive: true, mode: 0o700 });
+      await writeFile(tmp, `${JSON.stringify(kept)}\n`, { encoding: 'utf8', mode: 0o600 });
+      await rename(tmp, file);
+    } catch {
+      // the hint was shown; only the 24-hour memory is lost (and no temp file is left)
+      await rm(tmp, { force: true }).catch(() => {});
+    }
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/util/error-kind.mjs

@@ -0,0 +1,32 @@
+/**
+ * The error kind a verb reports for the error log (B27). A module that classifies a failure (for
+ * example a 1Password failure: `op_timeout`) calls `reportErrorKind(kind)`; the router clears it
+ * before a verb runs and takes the last one reported when the verb fails. A verb that reports
+ * nothing is logged as `error` (or `usage`/`crash`, see `bin/code-forge.mjs`).
+ */
+
+/** A kind is a short snake_case word; anything else is ignored. */
+const KIND = /^[a-z][a-z0-9_]{0,39}$/;
+
+/** Kinds the router sets itself; a verb reporting one of these is ignored. */
+const RESERVED = new Set(['crash', 'usage', 'error']);
+
+/** @type {string|null} */
+let current = null;
+
+/** @param {unknown} kind */
+export function reportErrorKind(kind) {
+  if (typeof kind === 'string' && KIND.test(kind) && !RESERVED.has(kind)) current = kind;
+}
+
+/** Forget any reported kind (the router calls this before a verb runs). */
+export function clearErrorKind() {
+  current = null;
+}
+
+/** @returns {string|null} the last kind reported since the last clear; clears it. */
+export function takeErrorKind() {
+  const kind = current;
+  current = null;
+  return kind;
+}