peaks-cli 2.0.2 → 2.0.4

package/.claude-plugin/marketplace.json

@@ -1,13 +1,13 @@
 {
   "metadata": {
     "pluginRoot": ".",
-    "version": "2.0.2"
+    "version": "2.0.3"
   },
   "plugins": [
     {
       "name": "peaks-cli",
       "description": "Cross-AI-IDE workflow-gating CLI + 11-skill family. Turns LLM improvisation into auditable engineering process. Skills cover PRD / R&D / UI / QA / change-control / context / SOP definition / orchestration. Soft-fail gates block irreversible actions mid-conversation (even under --dangerously-skip-permissions).",
-      "version": "2.0.2",
+      "version": "2.0.3",
       "author": {
         "name": "SquabbyZ"
       },

package/CHANGELOG.md

@@ -7,6 +7,73 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [2.0.4] — 2026-06-13 (hotfix)
+
+### Fixed
+
+- **PreToolUse hook `command` field was bare JavaScript source, not a
+  `node -e "..."` one-liner.** `peaks workspace init` writes
+  `.claude/settings.local.json` containing two PreToolUse hooks (one
+  for `Bash`, one for `Write|Edit|MultiEdit`) whose `command` field
+  was the inner JS payload without the `node -e "..."` wrapper.
+  Claude Code executes the `command` field as a shell string, so
+  bash saw literal `const c=process.argv[1]...` and tripped
+  `syntax error near unexpected token`. Net effect on every 2.0.3
+  install on Windows + macOS + Linux:
+  - Every Bash tool call (peaks CLI or otherwise) was rejected.
+  - Every Write / Edit / MultiEdit call was rejected.
+  - The [Fact-Forcing Gate] bypass that `peaks workspace init` was
+    supposed to install was therefore self-defeating — the bypass
+    broke the gate itself, and the gate could not be reached to fix
+    it.
+  Recovery required the user to delete `.claude/settings.local.json`
+  manually (losing the bypass permanently) or hand-patch the
+  `command` field (drift vs the template).
+  The fix wraps both builders' JS payloads in a real shell-evaluable
+  `node -e "<js>"` form via a new `wrapAsNodeOneLiner` helper in
+  `src/services/workspace/claude-settings-template.ts`. Inner `"`
+  are escaped to `\"`; backslashes pass through unchanged so regex
+  literals like `/\.peaks\//` still match correctly. `process.argv[1]`
+  is the correct slot under `-e` per Node.js docs
+  (https://nodejs.org/api/process.html#processargv) — consistent
+  across Windows, macOS, and Linux. The docstring is reconciled
+  with the implementation (the previous docstring incorrectly said
+  `argv[2]`).
+
+  Regression tests cover:
+  - `buildBashHookCommand()` and `buildWriteHookCommand()` return
+    `node -e "..."` form.
+  - Inner `"` are escaped to `\"`.
+  - Spawning the wrapped command with `peaks workspace init --project . --json`
+    exits 0; with `npm install foo` exits non-zero.
+  - Spawning the Write hook with `.peaks/_runtime/...` and
+    `.peaks/<changeId>/...` paths exits 0; with `src/...`,
+    `package.json`, `.peaks/_archive/...` exits non-zero.
+  - The existing workspace-init round-trip test (case A/B/C) still
+    passes with the wrapper.
+
+---
+
+## [2.0.3] — 2026-06-13
+
+### Fixed
+
+- **`@alibaba-group/open-code-review` reverted to `optionalDependency`**
+  (was promoted to a hard `dependency` in 2.0.1 and carried through
+  2.0.2). The ocr npm package's `postinstall` downloads a Go binary
+  via HTTPS, which fails in restricted/proxied environments and was
+  aborting the whole `npm i -g peaks-cli` flow. The 5-state detector
+  (`ready` / `package-missing` / `binary-missing` / `config-missing` /
+  `detection-failed`) and the soft-fail policy are unchanged — peaks-cli
+  never blocks on ocr being installed; it just no longer forces the
+  install. Users who want the second-opinion review run
+  `npm i -g @alibaba-group/open-code-review` explicitly. Under pnpm
+  they also need `pnpm approve-builds @alibaba-group/open-code-review`
+  for the binary download to run. Source-of-truth refactor (ocr config
+  under `peaksConfig.ocr.llm`) from 2.0.1 is unchanged.
+
+---
+
 ## [2.0.0] — 2026-06-12
 
 ### 🎯 Headline
@@ -29,6 +96,15 @@ alongside the LLM-only review. Soft-fails so missing ocr never blocks
 a slice. New CLI: `peaks code-review detect-ocr` / `run-ocr`. See
 `skills/peaks-rd/references/ocr-integration.md` for the contract.
 
+> **Note:** This `optionalDependency` classification was briefly
+> promoted to a hard `dependency` in 2.0.1 (alongside the source-of-truth
+> refactor) because the user feedback was "peaks-cli should not leave
+> install to the user". 2.0.3 reverts just the classification — the
+> source-of-truth refactor stays — because the ocr postinstall
+> downloads a Go binary via HTTPS, which fails in restricted/proxied
+> environments and was aborting `npm i -g peaks-cli`. See the 2.0.3
+> entry above for the full rationale.
+
 ### Breaking Changes
 
 - **`.claude/rules/` is no longer the source of truth for project standards.**
@@ -71,6 +147,14 @@ config surface.
   to download the platform binary still soft-fail at runtime
   (`binary-missing` state) — the install-time failure risk is the
   trade-off.
+
+  > **Reverted in 2.0.3.** The install-time failure risk turned out
+  > to bite too many real-world installs (corporate proxies, region
+  > firewalls, sandboxed dev environments all abort the whole
+  > `npm i -g peaks-cli`). 2.0.3 puts ocr back under
+  > `optionalDependencies`; everything else in this section
+  > (env-var injection, `config-template` CLI, `missingKeys`,
+  > source-of-truth under `peaksConfig.ocr.llm`) is unchanged.
 - **`detectOcr` / `runOcrReview` no longer read `~/.opencodereview/config.json`.**
   The source of truth is `peaksConfig.ocr.llm` (parsed by
   `getOcrLlmConfig()` in `config-service.ts`). Missing fields surface

package/dist/src/cli/commands/code-review-commands.js

@@ -5,7 +5,7 @@ import { fail, ok } from '../../shared/result.js';
 export function registerCodeReviewCommands(program, io) {
     const codeReview = program
         .command('code-review')
-        .description('Code-review primitives for peaks-rd Gate B3. Wraps the soft-optional `@alibaba-group/open-code-review` (ocr) tool when it is installed + configured; peaks-rd uses the structured JSON output as a second-opinion review alongside its own LLM review. ocr ships as a peaks-cli dependency (not optional). LLM endpoint config lives under `peaksConfig.ocr.llm` in the user config — run `peaks code-review config-template` to see the JSON snippet to paste.');
+        .description('Code-review primitives for peaks-rd Gate B3. Wraps the soft-optional `@alibaba-group/open-code-review` (ocr) tool when it is installed + configured; peaks-rd uses the structured JSON output as a second-opinion review alongside its own LLM review. ocr is an optional dependency of peaks-cli 2.0.3+ (was briefly promoted to a hard dependency in 2.0.1/2.0.2 — reverted because its postinstall downloads a Go binary via HTTPS and would otherwise abort `npm i -g peaks-cli` in restricted environments). LLM endpoint config lives under `peaksConfig.ocr.llm` in the user config — run `peaks code-review config-template` to see the JSON snippet to paste.');
     addJsonOption(codeReview
         .command('detect-ocr')
         .description('Read-only probe: returns the ocr install + config state as a JSON envelope (5 reasons: ready / package-missing / binary-missing / config-missing / detection-failed). peaks-rd calls this first to decide whether to invoke `run-ocr`. Reads the LLM endpoint from `peaksConfig.ocr.llm` (not from ~/.opencodereview/config.json).')

package/dist/src/services/code-review/ocr-service.js

@@ -36,12 +36,17 @@
  * To see the JSON template to paste, run:
  *   `peaks code-review config-template`
  *
- * The ocr package is declared in package.json:dependencies (was
- * previously optionalDependencies) so `npm i -g peaks-cli@2.0.x`
- * pulls it automatically (npm runs the ocr postinstall by default,
- * which downloads the Go binary). pnpm-based installs need
- * `pnpm approve-builds @alibaba-group/open-code-review`. Either
- * way, peaks-cli detects the install state and reports it.
+ * The ocr package is declared in package.json:optionalDependencies
+ * (was promoted to `dependencies` in 2.0.1 and reverted in 2.0.3 —
+ * the ocr postinstall downloads a Go binary via HTTPS, which fails
+ * in restricted/proxied environments and would otherwise abort the
+ * whole `npm i -g peaks-cli` flow). Peaks-cli ships with ocr *not*
+ * installed; if the user wants it, they run
+ *   `npm i -g @alibaba-group/open-code-review`
+ * and peaks-cli's 5-state detector (below) reports whether the
+ * binary is actually usable. pnpm-based installs additionally need
+ * `pnpm approve-builds @alibaba-group/open-code-review` for the
+ * binary download to run. Either way, peaks-cli never blocks on it.
  */
 import { spawnSync } from 'node:child_process';
 import { existsSync } from 'node:fs';
@@ -50,7 +55,7 @@ import { fileURLToPath } from 'node:url';
 import { dirname } from 'node:path';
 const OCR_DETECT_TIMEOUT_MS = 5000;
 const OCR_REVIEW_TIMEOUT_MS = 180000;
-const OCR_INSTALL_HINT = 'Install: `npm i -g @alibaba-group/open-code-review` (it is a hard dependency of peaks-cli 2.0.x and ships in the regular `npm install` flow). Then add your LLM endpoint to ~/.peaks/config.json — run `peaks code-review config-template` for the JSON snippet to paste.';
+const OCR_INSTALL_HINT = 'Install: `npm i -g @alibaba-group/open-code-review` (peaks-cli 2.0.3 ships with ocr as an optional dependency — its postinstall downloads a Go binary via HTTPS, which fails in some restricted/proxied environments; that\'s why peaks-cli does not auto-install it). Then add your LLM endpoint to ~/.peaks/config.json — run `peaks code-review config-template` for the JSON snippet to paste. Under pnpm you also need `pnpm approve-builds @alibaba-group/open-code-review` to allow the binary download.';
 const OCR_CONFIG_TEMPLATE = JSON.stringify({
     ocr: {
         llm: {

package/dist/src/services/workspace/claude-settings-template.js

@@ -52,10 +52,43 @@ const PEAKS_SUBCOMMAND_ALLOWLIST = [
     'upgrade'
 ];
 /**
- * Build the Bash matcher command. The command is a node -e one-liner
- * that reads its candidate command string from argv[2] and exits 0
- * iff the command starts with `peaks <whitelisted-subcommand> ` (or
- * is exactly `peaks <whitelisted-subcommand>` with no trailing args).
+ * Wrap an inner JavaScript payload as a shell-evaluable `node -e "..."`
+ * one-liner. The returned string is what Claude Code writes verbatim
+ * into `.claude/settings.local.json` under the `command` field. Per
+ * Node.js docs (https://nodejs.org/api/process.html#processargv), when
+ * using `-e` there is no script-file slot, so `process.argv[1]` is the
+ * first user-passed extra argument. This is consistent across Windows,
+ * macOS, and Linux.
+ *
+ * Every `"` character in the inner JS must be JSON-escaped as `\\"`
+ * so that the surrounding wrapper `node -e "..."` parses correctly:
+ * the shell sees the escape and passes a literal `"` to Node. A
+ * single missed escape closes the wrapper early and the entire hook
+ * regresses to the bash-syntax-error class of bug.
+ *
+ * @param js Inner JavaScript payload. Must be a single statement or a
+ *           sequence of statements joined with `;`. The wrapper does
+ *           not insert any `;` between the payload and the closing
+ *           `"` because Node accepts a trailing expression with `;`
+ *           already terminated by the payload itself.
+ */
+function wrapAsNodeOneLiner(js) {
+    // Only `"` needs JSON-escaping: the wrapper uses double quotes, so an
+    // unescaped inner `"` would close the wrapper prematurely. Backslashes
+    // do NOT need escaping here — bash inside a `"..."` wrapper reduces
+    // `\\` to `\`, so any `\X` in the inner JS reaches Node as `\X`,
+    // which is what regex literals like `/\.peaks\//` need. Adding a
+    // second `\\` → `\\` pass would double-escape backslashes and break
+    // every regex literal the inner JS contains.
+    const escaped = js.replace(/"/g, '\\"');
+    return `node -e "${escaped}"`;
+}
+/**
+ * Build the Bash matcher command. The command is a `node -e "..."`
+ * one-liner that reads its candidate command string from `argv[1]`
+ * and exits 0 iff the command starts with
+ * `peaks <whitelisted-subcommand> ` (or is exactly
+ * `peaks <whitelisted-subcommand>` with no trailing args).
  *
  * The list is serialised as a JSON array literal embedded in the
  * command string so we avoid regex special-character pitfalls and
@@ -63,15 +96,17 @@ const PEAKS_SUBCOMMAND_ALLOWLIST = [
  */
 function buildBashHookCommand() {
     const allowlistLiteral = JSON.stringify(PEAKS_SUBCOMMAND_ALLOWLIST);
-    // The command reads process.argv[2] (the tool-call command string),
-    // checks it starts with `peaks `, splits on whitespace, and looks
-    // up the second token in the allowlist. Exit 0 = allow, exit 1 =
-    // deny (so the gate fires for non-peaks commands).
-    return ('const c=process.argv[1]||"";' +
+    // The command reads process.argv[1] (the tool-call command string
+    // passed by Claude Code), checks it starts with `peaks `, splits on
+    // whitespace, and looks up the second token in the allowlist. Exit
+    // 0 = allow, exit 1 = deny (so the gate fires for non-peaks
+    // commands).
+    const js = 'const c=process.argv[1]||"";' +
         'if(!c.startsWith("peaks "))process.exit(1);' +
         'const sub=c.slice(6).trim().split(/\\s+/)[0];' +
         `if(${allowlistLiteral}.indexOf(sub)===-1)process.exit(1);` +
-        'process.exit(0)');
+        'process.exit(0)';
+    return wrapAsNodeOneLiner(js);
 }
 /**
  * Build the Write|Edit|MultiEdit matcher command. The command reads
@@ -91,12 +126,14 @@ function buildWriteHookCommand() {
     // Path-matching: allow when the path contains `.peaks/_runtime/`
     // OR when the second `.peaks/` segment starts with anything that
     // looks like a change-id (kebab-case slug). Exit 0 for allow, exit
-    // 1 for deny.
-    return ('const p=process.argv[1]||"";' +
+    // 1 for deny. The candidate path arrives on `process.argv[1]` per
+    // Node.js argv layout under `-e` (cross-platform consistent).
+    const js = 'const p=process.argv[1]||"";' +
         'if(p.includes(".peaks/_runtime/"))process.exit(0);' +
         'const m=p.match(/\\.peaks\\/([a-z0-9][a-z0-9.-]*)\\//);' +
         'if(m&&m[1]&&m[1]!=="_runtime"&&m[1]!=="_dogfood"&&m[1]!=="_sub_agents"&&m[1]!=="_archive"&&m[1]!=="memory"&&m[1]!=="issues"&&m[1]!=="sops"&&m[1]!=="retrospective"&&m[1]!=="project-scan"&&m[1]!=="perf-baseline")process.exit(0);' +
-        'process.exit(1)');
+        'process.exit(1)';
+    return wrapAsNodeOneLiner(js);
 }
 /**
  * Build the full template object. The shape is the subset of Claude

package/dist/src/shared/version.d.ts

@@ -1 +1 @@
-export declare const CLI_VERSION = "2.0.2";
+export declare const CLI_VERSION = "2.0.4";

package/dist/src/shared/version.js

@@ -1 +1 @@
-export const CLI_VERSION = "2.0.2";
+export const CLI_VERSION = "2.0.4";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "peaks-cli",
-  "version": "2.0.2",
+  "version": "2.0.4",
   "description": "Cross-AI-IDE workflow-gating CLI + skill family (Claude Code shipped, Trae in progress; Codex / Cursor / Qoder / Tongyi Lingma on the roadmap).",
   "author": "SquabbyZ",
   "license": "MIT",
@@ -59,12 +59,14 @@
     "node": ">=20.0.0"
   },
   "dependencies": {
-    "@alibaba-group/open-code-review": "1.3.1",
     "@colbymchenry/codegraph": "0.7.10",
     "commander": "^12.1.0",
     "fzf": "^0.5.2",
     "headroom-ai": "0.22.4"
   },
+  "optionalDependencies": {
+    "@alibaba-group/open-code-review": "1.3.1"
+  },
   "devDependencies": {
     "@types/node": "^22.10.2",
     "@vitest/coverage-v8": "^2.1.8",

package/skills/peaks-rd/references/ocr-integration.md

@@ -2,11 +2,16 @@
 
 > Soft-optional second-opinion code review for peaks-rd Gate B3.
 > Mirrors the ECC 64-agents pattern (spec §7.2): peaks-cli ships
-> `@alibaba-group/open-code-review` as a **required dependency** and
-> reads the LLM endpoint config from `peaksConfig.ocr.llm` in the
-> user's `~/.peaks/config.json` (single source of truth, user-managed).
-> When present + configured, the wrapper turns the output into
-> structured `code-review.md` evidence.
+> `@alibaba-group/open-code-review` as an **`optionalDependency`**
+> (was promoted to `dependencies` in 2.0.1 and reverted in 2.0.3
+> because its postinstall downloads a Go binary via HTTPS and would
+> otherwise abort `npm i -g peaks-cli` in restricted/proxied
+> environments). The LLM endpoint config still lives under
+> `peaksConfig.ocr.llm` in the user's `~/.peaks/config.json` (single
+> source of truth, user-managed). When the user installs + configures
+> ocr, the wrapper turns its output into structured `code-review.md`
+> evidence; when missing, peaks-rd proceeds LLM-only and the slice
+> ships without the second opinion.
 
 ## What ocr is
 
@@ -34,9 +39,19 @@ ships without the second opinion.
 
 ## Install
 
-`@alibaba-group/open-code-review` is a **required `dependency`** of
-peaks-cli 2.0.1+. `npm i -g peaks-cli` pulls it automatically and
-downloads the platform binary in the postinstall step. Verify with:
+`@alibaba-group/open-code-review` is an **`optionalDependency`** of
+peaks-cli 2.0.3+ (was a required `dependency` in 2.0.1/2.0.2; reverted
+because the postinstall downloads a Go binary via HTTPS, which fails in
+restricted/proxied environments and would otherwise abort
+`npm i -g peaks-cli`). peaks-cli does NOT auto-install it. To enable
+the second-opinion review:
+
+```bash
+npm i -g @alibaba-group/open-code-review
+```
+
+(Under pnpm you also need `pnpm approve-builds @alibaba-group/open-code-review`
+so the binary download script can run.) Verify with:
 
 ```bash
 peaks code-review detect-ocr --json
@@ -47,7 +62,7 @@ Five possible states:
 | state | Meaning | Recovery |
 |---|---|---|
 | `ready` | Installed + binary downloaded + peaks-cli's `peaksConfig.ocr.llm` valid | Nothing — `run-ocr` will work. |
-| `package-missing` | npm dep not installed (corrupt node_modules, or user removed it) | `npm i -g @alibaba-group/open-code-review` (peaks-cli 2.0.1+ does this automatically; this state is rare) |
+| `package-missing` | npm dep not installed (peaks-cli 2.0.3+ ships with ocr as an `optionalDependency`, so the common cause is the user has not installed it yet, or it was removed from node_modules) | `npm i -g @alibaba-group/open-code-review` (peaks-cli no longer auto-installs it; under pnpm also run `pnpm approve-builds @alibaba-group/open-code-review`) |
 | `binary-missing` | npm dep present but Go binary did not download | `pnpm approve-builds @alibaba-group/open-code-review`, OR run `node node_modules/@alibaba-group/open-code-review/scripts/install.js`, OR manually fetch from https://github.com/alibaba/open-code-review/releases and place the binary at the path shown in `nextActions[2]`. |
 | `config-missing` | binary present but `peaksConfig.ocr.llm` is empty or partial | See "Configure" below. |
 | `detection-failed` | Unexpected error during detection | Inspect stderr; re-run probe. |