@codedology/code-forge 0.2.2 → 0.3.0

package/CHANGELOG.md

@@ -6,6 +6,28 @@ waits on a second real consumer (plan §10.4, Q17).
 
 ## [Unreleased]
 
+## [0.3.0] — 2026-10-01
+
+### Added
+
+- `code-forge logs`: every failed verb is logged (scrubbed, flag names only) to `~/.code-forge/logs/errors.jsonl`;
+  `logs`, `logs summary`, `logs clear`, `logs path`, and `logs report` to share selected errors as a public GitHub issue
+  after you see the full text and say yes (`gh` or a prefilled link; a last secret check stops it). Opt out with
+  `CODE_FORGE_NO_ERROR_LOG=1`.
+- Better error reports (`code-forge logs report`): a second, AI cleaning pass (a closed-book L1 session that only lists
+  names, hosts, URLs, accounts, paths or secrets to hide; code-forge replaces them, and you see counts only),
+  fingerprints that group the same error in `logs`/`logs summary` and find an earlier issue (add a "happened again"
+  comment instead of a duplicate), a version check before reporting, Send · Edit in my editor · Cancel, a GitHub issue
+  form, and a one-line hint after a failure in a terminal; see docs/privacy.md. `--no-ai` skips the AI pass with an
+  extra yes.
+
+## [0.2.3] — 2026-10-01
+
+### Fixed
+
+- 1Password: code-forge prints a line before each call that may make 1Password ask for approval, and waits 60 s instead
+  of 20 s, so a Touch ID or password prompt no longer times out while you look for it.
+
 ## [0.2.2] — 2026-10-01
 
 ### Added

package/README.md

@@ -108,6 +108,8 @@ usage line.
 | `list` | `code-forge list` |
 | `remove` | `code-forge remove [<harness>] [--scope project\|global]` |
 | `upgrade` | `code-forge upgrade [--source <path>]` |
+| `logs` | `code-forge logs [--last N] [--json]` · `logs summary [--days N] [--json]` · `logs clear [--yes]` · `logs path` — the local error log (`~/.code-forge/logs/errors.jsonl`) |
+| `logs report` | `code-forge logs report [--last N] [--kind K] [--verb V] [--note "text"] [--dry-run] [--yes]` — share selected errors as a public GitHub issue; you see the full text first and say yes once |
 | `help` / `version` | `code-forge --help` (or no verb) · `code-forge --version` |
 
 `run`, `block`, `worker`, `spawn`, `s2`, `author`, `facts` and `review-file` are what the Agent

package/bin/code-forge.mjs

@@ -12,6 +12,9 @@ import { realpathSync } from 'node:fs';
 import { readdir } from 'node:fs/promises';
 import path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
+import { clearErrorKind, reportErrorKind, takeErrorKind } from '../src/util/error-kind.mjs';
+import { maybeHint } from '../src/util/error-hint.mjs';
+import { captureStderr, writeVerbFailure } from '../src/util/error-log.mjs';
 import { redact } from '../src/util/redact.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
@@ -95,26 +98,71 @@ export async function run(argv) {
 
   const modulePath = path.join(CLI_DIR, `${verb}.mjs`);
 
-  let exitCode;
+  // B27: a verb that exits non-zero or throws is logged to `~/.code-forge/logs/errors.jsonl`
+  // (scrubbed; never throws; never changes the exit code). The kind a verb reports is cleared
+  // first, and stderr is recorded only while the verb runs (the message is its last text).
+  // Every logging step is guarded on its own: none of them can change the verb's outcome.
+  /** @type {{stop: () => string|null} | null} */
+  let capture = null;
+  try {
+    clearErrorKind();
+    capture = captureStderr(process.stderr);
+  } catch {
+    // no recording: the entry has no message
+  }
+  /** @type {number} */
+  let code;
+  /** @type {unknown} */
+  let thrown;
+  let threw = false;
+  /** @type {string|null} */
+  let stderrText = null;
   try {
     const mod = await import(pathToFileURL(modulePath).href);
     const handler = mod.default;
     if (typeof handler !== 'function') {
       process.stderr.write(redact(`code-forge: verb "${verb}" has no default export function\n`));
-      return 1;
+      code = 1;
+    } else {
+      const exitCode = await handler(rest, { verbs, verb, reportErrorKind });
+      code = exitCode === undefined || exitCode === null ? 0 : isValidExitCode(exitCode) ? exitCode : 1;
     }
-    exitCode = await handler(rest, { verbs, verb });
   } catch (err) {
+    thrown = err;
+    threw = true;
+    code = 1;
     // A verb's error can carry an argv/env token (a fake key in a test, a real one in
     // production); every stderr path here is redacted, this one included.
-    process.stderr.write(redact(`code-forge: verb "${verb}" failed: ${err?.stack ?? String(err)}\n`));
-    return 1;
+    try {
+      process.stderr.write(redact(`code-forge: verb "${verb}" failed: ${/** @type {any} */ (err)?.stack ?? String(err)}\n`));
+    } catch {
+      // a broken stderr never changes the exit code
+    }
+  } finally {
+    try {
+      stderrText = capture ? capture.stop() : null;
+    } catch {
+      stderrText = null;
+    }
   }
-
-  if (exitCode === undefined || exitCode === null) {
-    return 0;
+  /** @type {string|null} */
+  let kind = null;
+  try {
+    kind = takeErrorKind();
+  } catch {
+    kind = null;
+  }
+  if (code !== 0) {
+    try {
+      const entry = await writeVerbFailure({ verb, args: rest, exit: code, kind, stderrText, threw, thrown });
+      // B28: one line on a terminal saying how to send it (not for usage errors, agents, or the
+      // same error twice within 24 h); maybeHint never throws either
+      await maybeHint({ entry, exit: code, isTTY: process.stderr.isTTY === true });
+    } catch {
+      // logging never changes the exit code (writeVerbFailure does not throw; belt and braces)
+    }
   }
-  return isValidExitCode(exitCode) ? exitCode : 1;
+  return code;
 }
 
 /**

package/docs/README.md

@@ -27,6 +27,7 @@ then 5a.
 | [reference/config.md](reference/config.md) | every `.code-forge.yml` key, its type and default. Generated from `schema/code-forge.schema.json` |
 | [reference/blocks.json](reference/blocks.json) | the build blocks of this package and what each one owns |
 | [marketing/code-forge-story.md](marketing/code-forge-story.md) | the marketing content bank (copy, lessons, what not to claim) |
+| [privacy.md](privacy.md) | what the local error log holds, every cleaning rule, the AI check, and how to turn the log off or delete it |
 | [releasing.md](releasing.md) | for maintainers: record changes (`npm run changelog`), cut a release with one command (`npm run release`), GitHub Releases, what stays manual |
 | [`skill/SKILL.md`](../skill/SKILL.md) and [`skill/references/`](../skill/references/) | the Agent Skill the orchestrator follows. The deepest and most exact description of the rules |
 

package/docs/reference/blocks.json

@@ -4,7 +4,7 @@
     "plans/code-forge-plan-v1.3.md §10.4",
     "plans/NIGHT-LOG.md"
   ],
-  "block_count": 28,
+  "block_count": 30,
   "baseline_ids": ["B0", "B1", "B2", "B3", "B4", "B5", "B6", "B7", "B8"],
   "baseline_note": "Wave 0-1 blocks, landed before v1.3; depends_on may name them, but they have no entry under blocks.",
   "blocks": {
@@ -346,6 +346,31 @@
       ],
       "depends_on": ["B13a"],
       "note": "root-added 2026-10-01; not in the v1.3 §10.4 table"
+    },
+    "B27": {
+      "title": "local error log for every verb (~/.code-forge/logs/errors.jsonl, scrubbed), code-forge logs (list, summary, clear, path) and logs report: share selected errors as a GitHub issue after one yes",
+      "wave": 6,
+      "level": "L2",
+      "status": "landed",
+      "owned": [
+        "bin/code-forge.mjs", "src/util/error-log.mjs", "src/util/error-kind.mjs", "src/cli/logs.mjs", "src/keys/onepassword.mjs",
+        "test/cli/logs.test.mjs", "test/util/error-log.test.mjs"
+      ],
+      "depends_on": ["B0.1"],
+      "note": "root-added 2026-10-01; not in the v1.3 §10.4 table"
+    },
+    "B28": {
+      "title": "better error reports: an AI cleaning pass (closed-book L1 session that only lists what to hide), fingerprints and no duplicate issues, a hint after a failure, a version check, edit before sending, and a GitHub issue form",
+      "wave": 6,
+      "level": "L2",
+      "status": "landed",
+      "owned": [
+        "bin/code-forge.mjs", "src/util/error-log.mjs", "src/util/error-hint.mjs", "src/cli/logs.mjs", "src/session/scrub.mjs",
+        ".github/ISSUE_TEMPLATE/error-report.yml", ".github/ISSUE_TEMPLATE/config.yml", "docs/privacy.md",
+        "test/cli/logs.test.mjs", "test/util/error-log.test.mjs"
+      ],
+      "depends_on": ["B27"],
+      "note": "root-added 2026-10-01; not in the v1.3 §10.4 table"
     }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codedology/code-forge",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "description": "Plan/harden/code/review orchestration CLI and Agent Skill for cross-model, parallel, evidence-gated feature delivery.",
   "repository": {
     "type": "git",

package/skill/scripts/forge

@@ -10,7 +10,7 @@
 #      copied install with no package next to it); `test/skill/shim.test.mjs` asserts the pin
 #      equals package.json's version.
 # The shim holds no logic of its own: every verb, flag and message is the CLI's.
-PINNED_VERSION="0.2.2"
+PINNED_VERSION="0.3.0"
 set -eu
 
 self="$0"

package/src/cli/keys.mjs

@@ -16,7 +16,7 @@
  */
 
 import { writeSafe } from '../util/redact.mjs';
-import { describeOpItem, isOpRef, OP_MESSAGES, opItemIdFromInput, toOpRef } from '../keys/onepassword.mjs';
+import { describeOpItem, isOpRef, OP_APPROVE_NOTE, OP_MESSAGES, opItemIdFromInput, toOpRef } from '../keys/onepassword.mjs';
 import { assertKeyName, createDefaultKeyStore, parseRef, readOpAndCache, resolveKey } from '../keys/store.mjs';
 
 const USAGE = 'usage: code-forge keys list | set <name> [--op <item-id|link|op://ref>] | test <name> [--ref <ref>] | remove <name>\n';
@@ -109,6 +109,7 @@ export async function runKeys(args, { store, stdout = process.stdout, stderr = p
     err(`${name}: --op must be a 1Password item ID, item link or op://vault/item/field reference\n`);
     return 2;
   }
+  if (flagArg !== undefined && (itemId !== null || fullRef)) err(`${OP_APPROVE_NOTE}\n`);
   // A 1Password item ID or link becomes a full op:// reference before any store call (B25).
   if (flagArg !== undefined && itemId !== null) {
     /** @type {Awaited<ReturnType<typeof toOpRef>>} */