@haystackeditor/cli 0.15.18 → 0.15.20

package/README.md

@@ -21,6 +21,60 @@ The `setup` command walks you through an interactive wizard:
 
 ---
 
+## For AI agents: the machine-readable contract
+
+Most consumers of this CLI are coding agents. These invariants hold everywhere:
+
+- **`--json` means pure stdout.** When `--json` is passed, stdout carries exactly
+  one JSON document (NDJSON stream for `setup --json`); all progress, spinners,
+  and prose go to stderr. On failure, stdout still gets a versioned error
+  envelope (`haystack schema error`: `{"schema_version": "1.0.0", "status":
+  "error", "error": "..."}`) and the process exits 1.
+- **Every JSON payload is versioned and schema'd.** Payloads carry
+  `schema_version`; print the contract with `haystack schema <name>`
+  (`haystack schema` lists all: `triage`, `pr`, `pr-status`, `inbox`, `ask`,
+  `traces`, `submit`, `action`, `error`, `setup`). Schemas are JSON-Schema
+  2020-12 and CI-guarded against drift.
+- **One state vocabulary.** All state tokens are snake_case across every
+  command: verdicts are `good_to_merge` / `needs_review` / `needs_input`;
+  feed buckets are `analyzing`, `good_to_merge`, `issues`, `needs_assignment`,
+  `needs_shepherding`, etc. No command emits kebab-case states.
+- **PR refs are uniform.** Every command taking a PR accepts `123`, `#123`,
+  `owner/repo#123`, or a GitHub PR URL. Bare numbers infer the repo from the
+  `origin` remote.
+- **Exit codes**: 0 = the requested action happened (a created PR with findings
+  is still 0 — read the verdict from the JSON); 1 = it did not. Commands never
+  print an error and exit 0.
+- **Waiting is bounded and skippable.** `submit` waits up to 10 min for
+  analysis, `triage` polls up to 5 min, `review` up to 25 min; every waiting
+  command takes `--no-wait`. Non-terminal outcomes include a `next` field with
+  the follow-up command (usually `haystack triage <ref> --json`).
+- **"review" disambiguation**: `haystack review` re-runs the *machine*
+  analysis. For *human* review use `haystack submit --review` or
+  `haystack request-review`.
+
+**The agent workflow for submitting:**
+
+```bash
+haystack submit --json          # emits the submit payload incl. ref + analysis verdict
+haystack triage <ref> --json    # poll findings later / after --no-wait
+```
+
+**`haystack mcp`** runs a stdio MCP server exposing the same payloads as tools:
+`inbox_list`, `pr_get`, `pr_status`, `triage_get`, `ask_haystack`,
+`traces_list`, `traces_get`, `dismiss`, `mark_reviewed`, `undismiss`,
+`request_review`, `trigger_review`, and `schema`.
+
+**`haystack setup --json`** speaks NDJSON: events (`question`, `permission`,
+`progress`, `result`) on stdout, replies on stdin keyed by
+`requestID`/`permissionID`. `haystack schema setup` documents the full
+protocol, including the reply shapes. Pre-supply answers with `--repo`,
+`--yes`, `--no-auto-merge`, or `--answers <file>` to skip questions. Note:
+`--yes` enables auto-merge (the wizard default) — pass `--no-auto-merge` to
+opt out.
+
+---
+
 ## CLI Commands
 
 ### `haystack setup`
@@ -69,12 +123,18 @@ Create a PR from current changes. Runs pre-PR triage (code review, rules validat
 
 ```bash
 haystack submit                      # Triage -> create PR -> wait for analysis
+haystack submit --json               # Agent mode: one JSON doc on stdout, progress on stderr
 haystack submit --title "Fix auth"   # Custom PR title
 haystack submit --draft              # Create as draft PR
 haystack submit --force              # Skip triage checks
 haystack submit --no-wait            # Don't wait for analysis results
 ```
 
+The `--json` payload (`haystack schema submit`) reports the PR ref, the
+resolved title/body and where each came from, auto-merge/auto-fix state with
+its source (flag vs `.haystack.json`), and the analysis outcome in the shared
+verdict vocabulary.
+
 **Review routing**: By default, PRs go to the auto-merge queue -- if analysis passes, the PR is merged automatically. Use `--review` to route it for human review instead:
 
 ```bash
@@ -145,6 +205,26 @@ haystack traces get owner/repo#42 <checkpoint-id> --cursor 20 --limit 20 --json
 
 These commands expose customer coding-session data, not Haystack's internal analysis-agent execution.
 
+### `haystack review`
+
+Trigger a fresh *machine* analysis of a PR's current head (Haystack analyzes once at PR open; later pushes only get a resolution check). For requesting *human* review, use `haystack request-review`.
+
+```bash
+haystack review 42                   # Re-analyze and wait for the result
+haystack review 42 --no-wait         # Trigger and exit
+haystack review 42 --json            # Machine-readable outcome (schema: action)
+```
+
+### `haystack request-review`
+
+Tag a PR as needing human review (adds `haystack:needs-review`), optionally requesting a specific GitHub user:
+
+```bash
+haystack request-review 42                 # Into the needs-assignment queue
+haystack request-review 42 octocat         # Also request review from octocat
+haystack request-review 42 --json
+```
+
 ### `haystack dismiss`
 
 Dismiss analysis findings for a PR, moving it from "Issues Found" to "Good to Merge" in the feed. The override is tied to the PR's current HEAD commit.
@@ -152,6 +232,7 @@ Dismiss analysis findings for a PR, moving it from "Issues Found" to "Good to Me
 ```bash
 haystack dismiss 42                  # Dismiss findings for PR #42
 haystack dismiss acme/widgets#99     # Dismiss for specific repo
+haystack dismiss 42 --json           # Machine-readable (schema: action)
 ```
 
 ### `haystack undismiss`
@@ -205,10 +286,14 @@ haystack config wait-for-reviewers add cursor         # Wait for Cursor BugBot
 haystack config wait-for-reviewers add cursor coderabbit  # Add multiple
 haystack config wait-for-reviewers remove cursor      # Stop waiting
 haystack config wait-for-reviewers clear              # Wait for none
-# Also accepts raw GitHub bot usernames:
+# Also accepts raw GitHub bot usernames (must end in [bot]):
 haystack config wait-for-reviewers add cursor-bugbot[bot]
 ```
 
+Reviewer names are validated: anything that is neither a known friendly name
+nor a `...[bot]` username is rejected (a stored typo would make the merge
+queue wait forever for a bot that can't post).
+
 ### `haystack skills`
 
 Manage AI skills for your coding CLI:

package/dist/assets/skills/map-your-system.md

@@ -0,0 +1,143 @@
+# Map Your System for Haystack QA
+
+Create `.haystack/system.yml` — a short file of facts about how this
+repository's system works, so Haystack QA can run it.
+
+## Why this file exists
+
+When Haystack reviews a risky PR, it doesn't just read the diff — it runs the
+affected code in a sandbox and captures evidence. Haystack decides **what** to
+test from each PR on its own. What it can't always infer is **how your system
+works**: how to install and build it, how services boot, how to know they're
+ready, how to seed data, how to act as a logged-in test user. That is what
+this file provides. Every fact you add converts risks Haystack identified but
+couldn't execute into checks that actually run.
+
+## Hard rules
+
+1. **Facts only — never test selection.** The file describes how the system
+   works. Keys like `scenarios`, `tests`, `skip`, or `focus` are rejected;
+   Haystack alone decides what to test.
+2. **Only verified facts.** Run every command yourself before declaring it.
+   A wrong fact is worse than a missing one — Haystack tracks which declared
+   facts fail and will flag them on PRs.
+3. **No secrets.** Reference environment variable *names* if needed, never
+   values. Anything that looks like a credential is rejected.
+4. **Personas are seeded FAKE users** reachable through dev/test-only login
+   paths. Never real accounts, never customer data. If a dev login helper
+   exists, it must be disabled in production builds.
+5. **Small and true beats big and aspirational.** Ten verified lines are more
+   useful than sixty guesses. Omit anything you could not verify.
+
+## Steps
+
+### 1. Inspect the repository
+
+Determine, with evidence from the tree (lockfiles, manifests, scripts,
+docker-compose, CI config, READMEs):
+
+- package manager, install command, and any required build/codegen steps
+- each runnable service: start command, port, and how "ready" is observable
+  (health endpoint, log line, or a command that exits 0)
+- how to seed and reset local/test data
+- how existing tests authenticate — is there a seeded test user or dev login?
+- the test runner and any test helpers/factories generated tests should reuse
+- external services the code calls, and how development runs without hitting
+  them for real (mock fixture, log driver, sandbox mode)
+- where runtime logs are written
+
+### 2. Verify each fact by running it
+
+From a clean state where possible: run the install, run the build, boot each
+service and confirm its readiness signal, run the seed command, run the login
+helper. Record the exact commands that worked. Drop anything you could not
+make work — do not declare it with a caveat.
+
+### 3. Ask the developer only what you cannot determine
+
+Typical questions worth asking a human: "Is there a dev-only way to log in as
+a test user?", "Which services must be running for the API to work?", "Is
+there a canonical seed script?". Keep it to the few facts you genuinely
+cannot infer or verify.
+
+### 4. Write `.haystack/system.yml`
+
+```yaml
+version: 1
+
+environment:
+  setup:
+    - run: "pnpm install --frozen-lockfile"
+    - run: "pnpm codegen"
+      rationale: "generated types are imported throughout"
+  toolchain: { node: "20", pnpm: "10" }
+
+services:
+  api:
+    root: "apps/api"                                # optional
+    boot: "pnpm dev"
+    ready: { http: "http://localhost:8080/health" } # or { log_pattern: "listening" } or { command: "pg_isready" }
+    env: { APP_ENV: "test" }
+    depends_on: [postgres]
+
+data:
+  seed: "pnpm db:seed --profile=qa"
+  reset: "pnpm db:reset"
+  personas:
+    admin:
+      login: "pnpm test:login admin"
+      yields: "prints an Authorization header on stdout"
+
+observability:
+  logs: ["apps/api/log/dev.log"]
+  inspect_db: "pnpm db:console --readonly"
+
+external_services:
+  stripe:
+    offline: "repo ships a stripe-mock fixture used by tests"
+    must_not_touch_live: true
+
+testing:
+  runner: "pnpm vitest"
+  probe_helpers: "tests/helpers/ has request builders and DB factories"
+
+constraints:
+  - "full build takes ~6 min; apps/api boots standalone without the web build"
+```
+
+Every section is optional — include only what you verified. All commands run
+from the repo root unless a `cwd`/`root` says otherwise.
+
+### 5. Validate before opening the PR
+
+Run the validator — it applies the same rules Haystack QA applies:
+
+```bash
+npx @haystackeditor/cli system-map validate
+```
+
+Fix every reported error, then confirm the things the validator cannot check:
+
+- [ ] every `run`/`boot`/`login`/`seed` command was executed and worked
+- [ ] every service has a `ready` signal you observed
+- [ ] personas are seeded fake users via dev/test-only paths
+
+Haystack re-validates the file on its next QA run and reports precise errors
+if something is wrong.
+
+### 6. Open a small, reviewable PR
+
+Add only `.haystack/system.yml` (plus a dev login helper if one was genuinely
+needed — dev/test-gated, with a test proving it's off in production). In the
+PR description, list which facts you verified by running them and which came
+from the developer's answers.
+
+## What happens next
+
+Haystack treats each entry as a claim. When a QA run executes a declared
+command successfully, the fact is marked **verified** with the run's receipt;
+if it fails at a newer commit it is marked **broken**, and Haystack will ask
+about it on a PR instead of trusting it. When QA hits something the map
+doesn't cover, it asks at most a couple of targeted questions on the affected
+PR, each with a ready-to-paste snippet — answering them grows this file over
+time.

package/dist/commands/ask.js

@@ -1,9 +1,9 @@
 import chalk from 'chalk';
 import { loadToken } from '../utils/auth.js';
 import { postAskHaystack } from '../utils/haystack-api.js';
-import { parsePrRef } from './pr.js';
+import { parsePrRef } from '../utils/pr-ref.js';
 export async function fetchAskPayload(ref, question, options) {
-    const pr = parsePrRef(ref);
+    const pr = parsePrRef(ref, 'ask');
     const token = await loadToken({ owner: pr.owner, repo: pr.repo });
     if (!token)
         throw new Error('Not authenticated. Run `haystack login` first.');

package/dist/commands/config.d.ts

@@ -33,5 +33,14 @@ export declare function getAutoFixStatus(): Promise<void>;
 export declare function enableAutoFix(): Promise<void>;
 export declare function disableAutoFix(): Promise<void>;
 export declare function handleAutoFix(action?: string): Promise<void>;
+/**
+ * Resolve a source name (e.g. "cursor") to its GitHub bot username. Raw bot
+ * usernames (anything ending in `[bot]`) pass through unchanged.
+ *
+ * Unknown names are REJECTED, not stored: this value must exactly match a
+ * GitHub bot login or the merge queue waits forever for a reviewer that can
+ * never post. (A typo used to be saved verbatim and reported as success.)
+ */
+export declare function resolveToBot(input: string): string;
 export declare function handleWaitForReviewers(action?: string, reviewers?: string[]): Promise<void>;
 export {};

package/dist/commands/config.js

@@ -411,14 +411,32 @@ function printAvailableReviewers(currentBots) {
     }
     console.log();
 }
-/** Resolve a source name (e.g. "cursor") to its GitHub bot username. Also accepts raw bot usernames. */
-function resolveToBot(input) {
+/**
+ * Resolve a source name (e.g. "cursor") to its GitHub bot username. Raw bot
+ * usernames (anything ending in `[bot]`) pass through unchanged.
+ *
+ * Unknown names are REJECTED, not stored: this value must exactly match a
+ * GitHub bot login or the merge queue waits forever for a reviewer that can
+ * never post. (A typo used to be saved verbatim and reported as success.)
+ */
+export function resolveToBot(input) {
+    const lower = input.toLowerCase();
+    if (AI_REVIEWER_SOURCES.includes(lower)) {
+        return AI_REVIEWER_BOT_USERNAMES[lower];
+    }
+    if (input.endsWith('[bot]')) {
+        return input;
+    }
+    throw new Error(`Unknown reviewer: "${input}".\n\n` +
+        `Use a friendly name (${AI_REVIEWER_SOURCES.join(', ')})\n` +
+        `or an exact GitHub bot username ending in [bot] (e.g. cursor-bugbot[bot]).`);
+}
+/** Like resolveToBot, but unknown names pass through verbatim (for `remove`). */
+function resolveToBotLenient(input) {
     const lower = input.toLowerCase();
-    // Check if it's a known friendly source name
     if (AI_REVIEWER_SOURCES.includes(lower)) {
         return AI_REVIEWER_BOT_USERNAMES[lower];
     }
-    // Already a bot username (e.g. "cursor-bugbot[bot]")
     return input;
 }
 function displayName(botUsername) {
@@ -463,7 +481,15 @@ export async function handleWaitForReviewers(action, reviewers) {
             process.exit(1);
             return; // unreachable — satisfies TS narrowing
         }
-        const resolved = reviewers.map(resolveToBot);
+        let resolved;
+        try {
+            resolved = reviewers.map(resolveToBot);
+        }
+        catch (err) {
+            console.error(chalk.red(`\n${err.message}\n`));
+            process.exit(1);
+            return; // unreachable — satisfies TS narrowing
+        }
         const { config, path, bots: current } = getMergeQueueConfig();
         const merged = Array.from(new Set([...current, ...resolved]));
         saveMergeQueueBots(config, path, merged);
@@ -483,7 +509,10 @@ export async function handleWaitForReviewers(action, reviewers) {
             process.exit(1);
             return; // unreachable — satisfies TS narrowing
         }
-        const resolved = reviewers.map(resolveToBot);
+        // Lenient on remove: stored entries may predate strict validation
+        // (arbitrary strings used to be saved verbatim), and removing them must
+        // stay possible.
+        const resolved = reviewers.map(resolveToBotLenient);
         const { config, path, bots: current } = getMergeQueueConfig();
         const removeSet = new Set(resolved);
         const remaining = current.filter(b => !removeSet.has(b));
@@ -506,12 +535,15 @@ export async function handleWaitForReviewers(action, reviewers) {
         console.log(chalk.dim('Commit .haystack.json to share with your team.\n'));
         return;
     }
-    // Unknown action — maybe the user passed reviewer names directly (implicit 'add')
-    const allNames = [action, ...(reviewers ?? [])].filter(Boolean);
-    const resolved = allNames.map(resolveToBot);
-    const { config, path, bots: current } = getMergeQueueConfig();
-    const merged = Array.from(new Set([...current, ...resolved]));
-    saveMergeQueueBots(config, path, merged);
-    console.log(chalk.green(`\nAdded: ${resolved.map(displayName).join(', ')}`));
-    console.log(chalk.dim('Commit .haystack.json to share with your team.\n'));
+    // Unknown action — reject it. This used to fall through to an implicit
+    // "add", so a typo'd action (`wait-for-reviewers ad cursor`) silently
+    // stored a bogus bot named "ad" and reported success.
+    console.error(chalk.red(`\nUnknown action: "${action}".`));
+    console.log('\nActions:');
+    console.log('  list            Show configured reviewer bots (default)');
+    console.log('  add <names>     Add one or more reviewer bots');
+    console.log('  remove <names>  Remove one or more reviewer bots');
+    console.log('  clear           Remove all reviewer bots');
+    console.log(chalk.dim('\nExample: haystack config wait-for-reviewers add cursor\n'));
+    process.exit(1);
 }

package/dist/commands/dismiss.d.ts

@@ -12,6 +12,18 @@
  *   owner/repo#123                         # Fully qualified
  *   https://github.com/owner/repo/pull/123 # GitHub URL
  */
-export declare function dismissCommand(identifier: string): Promise<void>;
-export declare function markReviewedCommand(identifier: string): Promise<void>;
-export declare function undismissCommand(identifier: string): Promise<void>;
+import { type ActionPayload } from '../utils/action-output.js';
+type OverrideType = 'findings-dismissed' | 'review-not-needed';
+/** Post a user override and return the action payload. Throws on failure. */
+export declare function performOverride(identifier: string, type: OverrideType, commandName: string): Promise<ActionPayload & {
+    head_sha: string;
+}>;
+/** Clear all overrides and return the action payload. Throws on failure. */
+export declare function performUndismiss(identifier: string): Promise<ActionPayload>;
+export interface OverrideCommandOptions {
+    json?: boolean;
+}
+export declare function dismissCommand(identifier: string, options?: OverrideCommandOptions): Promise<void>;
+export declare function markReviewedCommand(identifier: string, options?: OverrideCommandOptions): Promise<void>;
+export declare function undismissCommand(identifier: string, options?: OverrideCommandOptions): Promise<void>;
+export {};

package/dist/commands/dismiss.js

@@ -13,38 +13,10 @@
  *   https://github.com/owner/repo/pull/123 # GitHub URL
  */
 import chalk from 'chalk';
+import { emitActionPayload, failAction } from '../utils/action-output.js';
 import { resolveAuthContext } from '../utils/auth.js';
-import { parseRemoteUrl } from '../utils/git.js';
-// ============================================================================
-// PR identifier parsing (shared with triage — duplicated to avoid circular deps)
-// ============================================================================
-function parsePRIdentifier(identifier, commandName) {
-    const urlMatch = identifier.match(/^https?:\/\/github\.com\/([^/]+)\/([^/]+)\/pull\/(\d+)\/?$/);
-    if (urlMatch) {
-        return { owner: urlMatch[1], repo: urlMatch[2], prNumber: parseInt(urlMatch[3], 10) };
-    }
-    const qualifiedMatch = identifier.match(/^([^/]+)\/([^#]+)#(\d+)$/);
-    if (qualifiedMatch) {
-        return { owner: qualifiedMatch[1], repo: qualifiedMatch[2], prNumber: parseInt(qualifiedMatch[3], 10) };
-    }
-    const numberMatch = identifier.match(/^#?(\d+)$/);
-    if (numberMatch) {
-        const prNumber = parseInt(numberMatch[1], 10);
-        try {
-            const remote = parseRemoteUrl('origin');
-            return { owner: remote.owner, repo: remote.repo, prNumber };
-        }
-        catch {
-            throw new Error(`Cannot determine repository for PR #${prNumber}.\n` +
-                `Use the full format: haystack ${commandName} owner/repo#${prNumber}`);
-        }
-    }
-    throw new Error(`Invalid PR identifier: "${identifier}"\n\n` +
-        `Accepted formats:\n` +
-        `  haystack ${commandName} 123\n` +
-        `  haystack ${commandName} owner/repo#123\n` +
-        `  haystack ${commandName} https://github.com/owner/repo/pull/123`);
-}
+import { classifyHttpError } from '../utils/haystack-api.js';
+import { parsePrRef } from '../utils/pr-ref.js';
 // ============================================================================
 // GitHub API helpers
 // ============================================================================
@@ -60,7 +32,7 @@ async function getPRHeadSha(owner, repo, prNumber, token) {
         if (response.status === 404) {
             throw new Error(`PR #${prNumber} not found in ${owner}/${repo}`);
         }
-        throw new Error(`Failed to fetch PR: HTTP ${response.status}`);
+        throw await classifyHttpError(response, `Fetching PR #${prNumber}`);
     }
     const data = await response.json();
     return data.head.sha;
@@ -80,14 +52,7 @@ async function postUserOverride(repoFullName, prNumber, commitSha, type, token)
         body: JSON.stringify({ repoFullName, prNumber, commitSha, type }),
     });
     if (!response.ok) {
-        const body = await response.text().catch(() => '');
-        if (response.status === 401) {
-            throw new Error('Authentication failed. Run `haystack login` to re-authenticate.');
-        }
-        if (response.status === 403) {
-            throw new Error('Access denied — you may not have permission to this repository.');
-        }
-        throw new Error(`API error (${response.status}): ${body}`);
+        throw await classifyHttpError(response, 'User override');
     }
 }
 async function deleteUserOverrides(repoFullName, prNumber, token) {
@@ -101,108 +66,93 @@ async function deleteUserOverrides(repoFullName, prNumber, token) {
         body: JSON.stringify({ repoFullName, prNumber }),
     });
     if (!response.ok) {
-        const body = await response.text().catch(() => '');
-        if (response.status === 401) {
-            throw new Error('Authentication failed. Run `haystack login` to re-authenticate.');
-        }
-        if (response.status === 403) {
-            throw new Error('Access denied — you may not have permission to this repository.');
-        }
-        throw new Error(`API error (${response.status}): ${body}`);
+        throw await classifyHttpError(response, 'Clearing user overrides');
     }
 }
 // ============================================================================
-// Shared runner
+// Pure payload functions (shared by the CLI commands and the MCP server —
+// they throw instead of exiting, and never write to stdout)
 // ============================================================================
-async function runOverride(identifier, type, commandName) {
-    // Parse PR identifier
-    let pr;
-    try {
-        pr = parsePRIdentifier(identifier, commandName);
-    }
-    catch (err) {
-        console.error(chalk.red(`\n${err.message}\n`));
-        process.exit(1);
-    }
-    // Require auth
-    let authContext;
-    try {
-        authContext = await resolveAuthContext({ owner: pr.owner, repo: pr.repo });
-    }
-    catch (err) {
-        console.error(chalk.red(`\n${err.message}\n`));
-        process.exit(1);
-    }
-    const prLabel = `${pr.owner}/${pr.repo}#${pr.prNumber}`;
+/** Post a user override and return the action payload. Throws on failure. */
+export async function performOverride(identifier, type, commandName) {
+    const pr = parsePrRef(identifier, commandName);
+    const authContext = await resolveAuthContext({ owner: pr.owner, repo: pr.repo });
     const repoFullName = `${pr.owner}/${pr.repo}`;
+    const headSha = await getPRHeadSha(pr.owner, pr.repo, pr.prNumber, authContext.token);
+    await postUserOverride(repoFullName, pr.prNumber, headSha, type, authContext.token);
+    return {
+        action: type === 'findings-dismissed' ? 'dismiss' : 'mark_reviewed',
+        status: 'ok',
+        ref: `${repoFullName}#${pr.prNumber}`,
+        head_sha: headSha,
+        detail: type === 'findings-dismissed'
+            ? 'Findings dismissed; the PR moves to "Good to Merge". A new commit with net-new issues resurfaces it.'
+            : 'Human review marked as not needed; the PR moves to "Good to Merge". A new commit invalidates the override.',
+    };
+}
+/** Clear all overrides and return the action payload. Throws on failure. */
+export async function performUndismiss(identifier) {
+    const pr = parsePrRef(identifier, 'undismiss');
+    const authContext = await resolveAuthContext({ owner: pr.owner, repo: pr.repo });
+    const repoFullName = `${pr.owner}/${pr.repo}`;
+    await deleteUserOverrides(repoFullName, pr.prNumber, authContext.token);
+    return {
+        action: 'undismiss',
+        status: 'ok',
+        ref: `${repoFullName}#${pr.prNumber}`,
+        detail: 'All overrides cleared; the PR returns to its original feed bucket.',
+    };
+}
+async function runOverride(identifier, type, commandName, options) {
+    const action = type === 'findings-dismissed' ? 'dismiss' : 'mark_reviewed';
     const actionLabel = type === 'findings-dismissed'
         ? 'Dismissing findings'
         : 'Marking review as not needed';
-    console.log(chalk.dim(`\n${actionLabel} for ${prLabel}...`));
-    // Get PR HEAD SHA
-    let headSha;
+    if (!options.json)
+        console.log(chalk.dim(`\n${actionLabel} for ${identifier}...`));
+    let payload;
     try {
-        headSha = await getPRHeadSha(pr.owner, pr.repo, pr.prNumber, authContext.token);
+        payload = await performOverride(identifier, type, commandName);
     }
     catch (err) {
-        console.error(chalk.red(`\n${err.message}\n`));
-        process.exit(1);
+        failAction(options.json, action, null, err.message);
+        return; // unreachable — satisfies TS narrowing
     }
-    // Post the override
-    try {
-        await postUserOverride(repoFullName, pr.prNumber, headSha, type, authContext.token);
-    }
-    catch (err) {
-        console.error(chalk.red(`\n${err.message}\n`));
-        process.exit(1);
+    if (options.json) {
+        emitActionPayload(payload);
+        return;
     }
-    // Success
     if (type === 'findings-dismissed') {
-        console.log(chalk.green(`\n  Findings dismissed for ${prLabel}`));
+        console.log(chalk.green(`\n  Findings dismissed for ${payload.ref}`));
     }
     else {
-        console.log(chalk.green(`\n  Review marked as not needed for ${prLabel}`));
+        console.log(chalk.green(`\n  Review marked as not needed for ${payload.ref}`));
     }
-    console.log(chalk.dim(`  Commit: ${headSha.slice(0, 7)}`));
+    console.log(chalk.dim(`  Commit: ${payload.head_sha.slice(0, 7)}`));
     console.log(chalk.dim('  The PR will move to "Good to Merge" in the feed.'));
     console.log(chalk.dim('  If a new commit introduces net-new issues, the PR will resurface.\n'));
 }
-// ============================================================================
-// Exported commands
-// ============================================================================
-export async function dismissCommand(identifier) {
-    await runOverride(identifier, 'findings-dismissed', 'dismiss');
+export async function dismissCommand(identifier, options = {}) {
+    await runOverride(identifier, 'findings-dismissed', 'dismiss', options);
 }
-export async function markReviewedCommand(identifier) {
-    await runOverride(identifier, 'review-not-needed', 'mark-reviewed');
+export async function markReviewedCommand(identifier, options = {}) {
+    await runOverride(identifier, 'review-not-needed', 'mark-reviewed', options);
 }
-export async function undismissCommand(identifier) {
-    let pr;
-    try {
-        pr = parsePRIdentifier(identifier, 'undismiss');
-    }
-    catch (err) {
-        console.error(chalk.red(`\n${err.message}\n`));
-        process.exit(1);
-    }
-    let authContext;
+export async function undismissCommand(identifier, options = {}) {
+    if (!options.json)
+        console.log(chalk.dim(`\nClearing overrides for ${identifier}...`));
+    let payload;
     try {
-        authContext = await resolveAuthContext({ owner: pr.owner, repo: pr.repo });
+        payload = await performUndismiss(identifier);
     }
     catch (err) {
-        console.error(chalk.red(`\n${err.message}\n`));
-        process.exit(1);
+        failAction(options.json, 'undismiss', null, err.message);
+        return; // unreachable — satisfies TS narrowing
     }
-    const prLabel = `${pr.owner}/${pr.repo}#${pr.prNumber}`;
-    const repoFullName = `${pr.owner}/${pr.repo}`;
-    console.log(chalk.dim(`\nClearing overrides for ${prLabel}...`));
-    try {
-        await deleteUserOverrides(repoFullName, pr.prNumber, authContext.token);
-    }
-    catch (err) {
-        console.error(chalk.red(`\n${err.message}\n`));
-        process.exit(1);
+    if (options.json) {
+        emitActionPayload(payload);
+        return;
     }
-    console.log(chalk.green(`\n  Overrides cleared for ${prLabel}`));
+    console.log(chalk.green(`\n  Overrides cleared for ${payload.ref}`));
     console.log(chalk.dim('  The PR will return to its original feed bucket.\n'));
 }