pqcheck 0.16.15 → 0.16.17

package/README.md

@@ -8,7 +8,7 @@
 [![npm downloads](https://img.shields.io/npm/dm/pqcheck.svg?style=flat-square&color=06b6d4)](https://www.npmjs.com/package/pqcheck)
 [![license](https://img.shields.io/npm/l/pqcheck.svg?style=flat-square&color=06b6d4)](./LICENSE)
 
-> **Latest: v0.16.12** — ⚠️ **Existing GitHub Action users:** one-line fix required in `.github/workflows/cipherwake.yml` (`uses: cipherwakelabs/pqcheck@v3` → `cipherwakelabs/pqcheck/action@v3`). The old ref was broken since v0.15 and silently failed every CI run; today's end-to-end test caught it. Re-running `pqcheck onboard` also regenerates the workflow correctly. Plus: README rewritten to advertise both `pqcheck <domain>` and `pqcheck deploy-check --ai` equally, rate limits corrected. [Full changelog →](./CHANGELOG.md)
+> **Latest: v0.16.17** — fail-loud AI guard now covers the no-baseline first-deploy fallback. `pqcheck deploy-check <new-domain> --ai` previously exited 3 with bare `error: /api/scan returned 429` if the very first scan got rate-limited — no `CIPHERWAKE_AI_GUARD_RESULT` block, leaving the calling AI agent with no `ship_decision` to route on. Now every error path in that fallback emits a `ship_decision=review` block with a status-specific `top_issue` code. [Full changelog →](./CHANGELOG.md)
 
 ## Two ways to use it
 

package/bin/pqcheck.js

@@ -3051,12 +3051,51 @@ async function runScanBasedDeployCheck(domain, args) {
   try {
     resp = await fetch(`${API_BASE}/api/scan?domain=${encodeURIComponent(domain)}`, { headers });
   } catch (err) {
+    // v0.16.17 — the v0.16.13 fail-loud AI guard fix was applied to the main
+    // trust-diff deploy-check path but missed THIS fallback path (no-baseline
+    // first-deploy), so a network blip on the very first `pqcheck deploy-check
+    // <new-domain> --ai` exited 3 with no CIPHERWAKE_AI_GUARD_RESULT block.
+    // The calling AI agent then had no ship_decision to route on and could
+    // silently continue shipping — exactly the failure mode the protocol
+    // exists to prevent. Same emit-block-and-exit pattern as trust-diff.
     console.error(color("red", `error: network failure calling /api/scan: ${err.message}`));
-    process.exit(3);
+    return emitAiGuardReviewAndExit(args, {
+      code: "deploy_check_fetch_failed",
+      message: `Network failure calling /api/scan: ${err?.message || "fetch failed"}`,
+      exitCode: 3,
+    });
   }
   if (!resp.ok) {
-    console.error(color("red", `error: /api/scan returned ${resp.status}`));
-    process.exit(3);
+    // v0.16.17 — same fix as above for the HTTP-non-OK path. The 429 case
+    // is especially load-bearing: a brand new AI-coder workflow trying its
+    // first deploy-check on a fresh project will commonly hit per-IP rate
+    // limits, get a bare `error: /api/scan returned 429`, and exit 3 with no
+    // guard block. The AI agent then has nothing to parse. Emitting a
+    // ship_decision=review block with a quota-specific error code lets the
+    // agent surface the rate-limit problem to the user instead of silently
+    // continuing. Surface the body message + auth hint when available so
+    // the user knows whether to wait or get an API key.
+    const body = await safeJSON(resp);
+    const statusLabel = resp.status === 429
+      ? "rate-limited"
+      : resp.status === 401 || resp.status === 403
+        ? "auth failed"
+        : `${resp.status}`;
+    console.error(color("red", `error: /api/scan returned ${resp.status} (${statusLabel})`));
+    if (body?.message) console.error(color("dim", body.message));
+    if (body?.hint) console.error(color("dim", body.hint));
+    if (resp.status === 429) {
+      console.error(color("dim", "Higher quota via free API key (no card): https://cipherwake.io/account#api-keys"));
+    }
+    const code = resp.status === 429
+      ? "deploy_check_rate_limited"
+      : resp.status === 401 || resp.status === 403
+        ? "deploy_check_auth_failed"
+        : "deploy_check_scan_failed";
+    const message = resp.status === 429
+      ? (body?.message || "Per-IP rate limit hit on /api/scan. Wait ~1 minute or use an API key for higher quota.")
+      : body?.message || `Cipherwake /api/scan returned ${resp.status}.`;
+    return emitAiGuardReviewAndExit(args, { code, message, exitCode: 3 });
   }
   const report = await resp.json();
   const findings = Array.isArray(report.findings) ? report.findings : [];
@@ -4441,7 +4480,7 @@ function renderReleaseChecklist(domain, opts = {}) {
 // `pqcheck init` — interactive workflow scaffold (habit-loop #4, locked 2026-05-16)
 // =============================================================================
 // Writes a ready-to-commit .github/workflows/cipherwake.yml that calls
-// cipherwakelabs/pqcheck/action@v3 in trust-diff mode. Zero copy-paste docs friction.
+// cipherwakelabs/pqcheck@v4 in trust-diff mode. Zero copy-paste docs friction.
 //
 // Flags:
 //   --domain <d>       Skip the domain prompt
@@ -4618,7 +4657,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Run Cipherwake Trust Diff
-        uses: cipherwakelabs/pqcheck/action@v3
+        uses: cipherwakelabs/pqcheck@v4
         with:
           mode: trust-diff
           domain: ${domain}
@@ -5613,9 +5652,23 @@ async function runProtocolCommand(args) {
   console.log("Here's what would be added:");
   console.log("");
   if (detected.length === 0) {
+    // Default to creating project-local ./CLAUDE.md rather than global
+    // ~/.claude/CLAUDE.md. Mirrors the cli/setup --scope=project default
+    // (commit 4450e77): don't pollute global config when no signal exists
+    // that the user wants machine-wide installation. Pass --scope=global
+    // to override and create ~/.claude/CLAUDE.md instead.
+    const scopeRaw = (parseFlag(args, "--scope") || "project").toLowerCase();
+    const useGlobal = scopeRaw === "global";
+    const fallbackPath = useGlobal
+      ? path.join(os.homedir(), ".claude", "CLAUDE.md")
+      : path.join(process.cwd(), "CLAUDE.md");
+    const fallbackDisplay = fallbackPath.replace(os.homedir(), "~");
     console.log(color("dim", "  No existing CLAUDE.md / .cursorrules / .aider.conf.yml found."));
-    console.log(color("dim", "  Creating ~/.claude/CLAUDE.md with the protocol."));
-    detected.push({ label: "Claude Code (will create)", path: path.join(os.homedir(), ".claude", "CLAUDE.md") });
+    console.log(color("dim", `  Creating ${fallbackDisplay} with the protocol.`));
+    if (!useGlobal) {
+      console.log(color("dim", "  (pass --scope global to create ~/.claude/CLAUDE.md instead)"));
+    }
+    detected.push({ label: useGlobal ? "Claude Code (will create global)" : "Claude Code (will create project)", path: fallbackPath });
   }
   for (const d of detected) {
     console.log(`  • Append a ~30-line "## Pre-deploy verification with Cipherwake" section to ${color("bold", d.path)}`);
@@ -5927,11 +5980,21 @@ async function runSetupCommand(args) {
   const skipHook = args.includes("--skip-hook");
   const skipStatusline = args.includes("--skip-statusline");
   const skipVscode = args.includes("--skip-vscode");
+  // Where to install Claude Code statusLine + hooks. Default 'project' keeps
+  // Cipherwake scoped to the current repo (avoids the "Cipherwake badge
+  // follows me into unrelated projects" UX bug). 'global' is opt-in for
+  // power users who want one canonical domain badge across every project.
+  const settingsScope = (parseFlag(args, "--scope") || "project").toLowerCase();
+  if (!["project", "global"].includes(settingsScope)) {
+    console.error(color("red", `error: --scope must be 'project' or 'global' (got '${settingsScope}')`));
+    process.exit(3);
+  }
 
   if (!domain) {
     console.error(color("red", "error: pqcheck setup requires --domain"));
     console.error(color("dim", "Usage: npx pqcheck setup --auto --domain example.com"));
-    console.error(color("dim", "  --plan         Print the install plan without writing any files"));
+    console.error(color("dim", "  --plan                     Print the install plan without writing any files"));
+    console.error(color("dim", "  --scope project|global     Where to install Claude Code hooks (default: project — this repo only)"));
     console.error(color("dim", "  --invoked-by=\"<name>\" --consent-phrase=\"<words>\"   (audit trail)"));
     console.error(color("dim", "Skip flags: --skip-workflow --skip-protocol --skip-hook --skip-statusline --skip-vscode"));
     process.exit(3);
@@ -5977,11 +6040,17 @@ async function runSetupCommand(args) {
     }
     if (!skipHook) planEntries.push({ what: "git pre-push hook", to: path.join(process.cwd(), ".git", "hooks", "pre-push"), op: "create (if git repo)" });
     if (!skipStatusline) {
-      const settingsPath = path.join(os.homedir(), ".claude", "settings.json");
+      const settingsPath = settingsScope === "global"
+        ? path.join(os.homedir(), ".claude", "settings.json")
+        : path.join(process.cwd(), ".claude", "settings.json");
       let exists = false;
       try { await fs.access(settingsPath); exists = true; } catch { /* */ }
-      planEntries.push({ what: "Claude Code statusLine", to: settingsPath, op: exists ? "deep-merge (backup first)" : "create" });
+      const scopeNote = settingsScope === "global"
+        ? " [GLOBAL — fires in every project on this machine]"
+        : " [PROJECT-LOCAL — fires only when Claude Code runs in this directory]";
+      planEntries.push({ what: `Claude Code statusLine${scopeNote}`, to: settingsPath, op: exists ? "deep-merge (backup first)" : "create" });
       planEntries.push({ what: "Claude Code chat-hook (PostToolUse Bash)", to: settingsPath, op: exists ? "deep-merge into hooks.PostToolUse" : "create" });
+      planEntries.push({ what: "Claude Code prompt-hook (UserPromptSubmit)", to: settingsPath, op: exists ? "deep-merge into hooks.UserPromptSubmit" : "create" });
     }
     if (!skipVscode) planEntries.push({ what: "VS Code / Cursor extension", to: "via `code --install-extension cipherwakelabs.cipherwake-statusbar`", op: "attempt (soft-fail if Marketplace listing missing)" });
     for (const e of planEntries) {
@@ -6012,6 +6081,48 @@ async function runSetupCommand(args) {
     console.log("");
   }
 
+  // Resolve where to write Claude Code statusLine + hook entries.
+  // Default 'project' = ./.claude/settings.json (this repo only). 'global' = ~/.claude/settings.json
+  // (fires in every Claude Code session on this machine). Project-local is the right default for
+  // anyone with multiple projects; global is the legacy behavior and now an opt-in for the
+  // "one canonical domain across everything" use case.
+  const claudeSettingsPath = settingsScope === "global"
+    ? path.join(os.homedir(), ".claude", "settings.json")
+    : path.join(process.cwd(), ".claude", "settings.json");
+
+  if (!skipStatusline) {
+    const displayPath = claudeSettingsPath.replace(os.homedir(), "~");
+    const scopeLabel = settingsScope === "global"
+      ? `global (${displayPath} — fires in EVERY project on this machine)`
+      : `project (${displayPath} — fires only when Claude Code runs in this directory)`;
+    console.log(color("dim", `Settings scope: ${scopeLabel}`));
+    console.log(color("dim", settingsScope === "global"
+      ? `  (omit --scope or pass --scope project to install for this repo only)`
+      : `  (pass --scope global to install for every project on this machine)`));
+    console.log("");
+
+    // Detect existing GLOBAL Cipherwake install while doing a project install.
+    // Warn so the user doesn't end up with two layers firing on top of each other.
+    if (settingsScope === "project") {
+      try {
+        const globalPath = path.join(os.homedir(), ".claude", "settings.json");
+        const raw = await fs.readFile(globalPath, "utf8");
+        const parsed = JSON.parse(raw);
+        const hasGlobalCipherwake =
+          (parsed.statusLine?.command && String(parsed.statusLine.command).includes("cipherwake")) ||
+          JSON.stringify(parsed.hooks || {}).includes("cipherwake");
+        if (hasGlobalCipherwake) {
+          console.log(color("yellow", `  ⚠ A GLOBAL Cipherwake install already exists at ~/.claude/settings.json`));
+          console.log(color("dim", `    It will continue firing across every project. To remove the global install,`));
+          console.log(color("dim", `    edit ~/.claude/settings.json and delete the statusLine entry and the`));
+          console.log(color("dim", `    cipherwake-chat-hook / cipherwake-prompt-hook commands. Backups are taken`));
+          console.log(color("dim", `    automatically before any write, so changes are reversible.`));
+          console.log("");
+        }
+      } catch { /* no global install — fine */ }
+    }
+  }
+
   const installSummary = [];
 
   // -------------------------------------------------------------------------
@@ -6176,7 +6287,8 @@ async function runSetupCommand(args) {
   }
 
   if (!skipStatusline) {
-    const settingsPath = path.join(os.homedir(), ".claude", "settings.json");
+    const settingsPath = claudeSettingsPath;
+    const displayPath = settingsPath.replace(os.homedir(), "~");
     try {
       let settings = {};
       let existed = false;
@@ -6187,7 +6299,7 @@ async function runSetupCommand(args) {
       } catch { /* will create */ }
       if (existed && settings.statusLine && typeof settings.statusLine === "object") {
         // Already has a statusLine config — don't overwrite.
-        console.log(color("dim", `  ⊝ ~/.claude/settings.json already has a statusLine entry — leaving alone`));
+        console.log(color("dim", `  ⊝ ${displayPath} already has a statusLine entry — leaving alone`));
         console.log(color("dim", `    To use the Cipherwake statusline instead, set: "command": "npx --package=pqcheck@latest cipherwake-statusline"`));
         installSummary.push({ component: "Claude Code statusLine", path: settingsPath, status: "skipped-existing-config" });
       } else {
@@ -6196,7 +6308,7 @@ async function runSetupCommand(args) {
         settings.statusLine = { type: "command", command: "npx --package=pqcheck@latest cipherwake-statusline" };
         await fs.mkdir(path.dirname(settingsPath), { recursive: true });
         await fs.writeFile(settingsPath, JSON.stringify(settings, null, 2) + "\n", "utf8");
-        console.log(color("green", `  ✓ added statusLine config → ~/.claude/settings.json`));
+        console.log(color("green", `  ✓ added statusLine config → ${displayPath}`));
         installSummary.push({ component: "Claude Code statusLine", path: settingsPath, status: existed ? "installed-updated" : "installed-created", backup: backupPath });
       }
     } catch (err) {
@@ -6212,7 +6324,8 @@ async function runSetupCommand(args) {
   // doesn't clobber other hooks per CLAUDE.md Rule 17.
   // -------------------------------------------------------------------------
   if (!skipStatusline) {
-    const settingsPath = path.join(os.homedir(), ".claude", "settings.json");
+    const settingsPath = claudeSettingsPath;
+    const displayPath = settingsPath.replace(os.homedir(), "~");
     try {
       let settings = {};
       let existed = false;
@@ -6238,7 +6351,7 @@ async function runSetupCommand(args) {
       );
 
       if (alreadyInstalled) {
-        console.log(color("dim", `  ⊝ chat-hook already configured in ~/.claude/settings.json PostToolUse — skipping`));
+        console.log(color("dim", `  ⊝ chat-hook already configured in ${displayPath} PostToolUse — skipping`));
         installSummary.push({ component: "Claude Code chat-hook", path: settingsPath, status: "skipped-already-present" });
       } else {
         const backupPath = existed ? await backupSettingsJson(settingsPath) : null;
@@ -6246,7 +6359,7 @@ async function runSetupCommand(args) {
         bashEntry.hooks.push({ type: "command", command: cipherwakeHookCmd });
         await fs.mkdir(path.dirname(settingsPath), { recursive: true });
         await fs.writeFile(settingsPath, JSON.stringify(settings, null, 2) + "\n", "utf8");
-        console.log(color("green", `  ✓ added chat-hook (PostToolUse Bash) → ~/.claude/settings.json`));
+        console.log(color("green", `  ✓ added chat-hook (PostToolUse Bash) → ${displayPath}`));
         console.log(color("dim", `    Every \`pqcheck\` run will now push a live status message into Claude Code chat`));
         installSummary.push({ component: "Claude Code chat-hook", path: settingsPath, status: existed ? "installed-updated" : "installed-created", backup: backupPath });
       }
@@ -6265,7 +6378,8 @@ async function runSetupCommand(args) {
   // / ship_decision=pass (no spam).
   // -------------------------------------------------------------------------
   if (!skipStatusline) {
-    const settingsPath = path.join(os.homedir(), ".claude", "settings.json");
+    const settingsPath = claudeSettingsPath;
+    const displayPath = settingsPath.replace(os.homedir(), "~");
     try {
       let settings = {};
       let existed = false;
@@ -6285,7 +6399,7 @@ async function runSetupCommand(args) {
       );
 
       if (alreadyInstalled) {
-        console.log(color("dim", `  ⊝ prompt-hook already configured in ~/.claude/settings.json UserPromptSubmit — skipping`));
+        console.log(color("dim", `  ⊝ prompt-hook already configured in ${displayPath} UserPromptSubmit — skipping`));
         installSummary.push({ component: "Claude Code prompt-hook", path: settingsPath, status: "skipped-already-present" });
       } else {
         const backupPath = existed ? await backupSettingsJson(settingsPath) : null;
@@ -6293,7 +6407,7 @@ async function runSetupCommand(args) {
         settings.hooks.UserPromptSubmit.push({ hooks: [{ type: "command", command: cipherwakeHookCmd }] });
         await fs.mkdir(path.dirname(settingsPath), { recursive: true });
         await fs.writeFile(settingsPath, JSON.stringify(settings, null, 2) + "\n", "utf8");
-        console.log(color("green", `  ✓ added prompt-hook (UserPromptSubmit) → ~/.claude/settings.json`));
+        console.log(color("green", `  ✓ added prompt-hook (UserPromptSubmit) → ${displayPath}`));
         console.log(color("dim", `    Claude will see latest ship_decision in context on every prompt (when REVIEW/BLOCK)`));
         installSummary.push({ component: "Claude Code prompt-hook", path: settingsPath, status: existed ? "installed-updated" : "installed-created", backup: backupPath });
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pqcheck",
-  "version": "0.16.15",
+  "version": "0.16.17",
   "description": "Deploy gate for AI-coded web apps. `pqcheck deploy-check --ai` returns ship_decision=pass|review|block for Claude Code / Cursor / Copilot / Aider to gate deploys before they ship. Anonymous, no signup, free for first use.",
   "keywords": [
     "ai-coder",