@haystackeditor/cli 0.15.17 → 0.15.19

package/dist/commands/mcp.js

@@ -1,71 +1,74 @@
-/**
- * `haystack mcp` — Model Context Protocol server.
- *
- * Exposes Haystack's read surface to Claude Code, Cursor, Codex, etc. as
- * stdio MCP tools. Every tool wraps the same library function that powers
- * the corresponding `--json` CLI command, so an MCP client and a webhook
- * receiver see byte-identical payloads.
- *
- * Tools:
- *   triage_pr(ref)   same shape as `haystack triage <ref> --json`
- *   pr_state(ref)    PR state in the Haystack pipeline (schemas/pr.v1.json)
- *   schema(name)     prints the JSON Schema for a noun (debugging)
- *
- * Auth: inherited from the local CLI (loadToken). MCP clients run as the
- * operator's user, so they get whatever credentials are on disk — same model
- * as `git`, `gh`, etc.
- */
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
 import { readFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { dirname, join } from 'node:path';
-import { parsePrRef, prReadCommand } from './pr.js';
-import { fetchRatingSynthesis, fetchAutoFixManifest } from '../utils/analysis-api.js';
+import { fetchInboxPayload } from './inbox.js';
+import { fetchPrStatePayload } from './pr.js';
+import { fetchTriagePayload } from './triage.js';
+import { fetchAskPayload } from './ask.js';
+import { fetchTracesGetPayload, fetchTracesListPayload } from './traces.js';
 import { loadToken } from '../utils/auth.js';
-import { SCHEMA_VERSIONS, withSchema } from '../schema.js';
+import { SCHEMA_VERSIONS } from '../schema.js';
+const refInput = {
+    type: 'string',
+    description: 'PR reference: bare number, owner/repo#number, or GitHub URL.',
+};
 const TOOLS = [
     {
-        name: 'triage_pr',
-        description: 'Fetch the latest triage results for a pull request. Returns rating, findings, ' +
-            'and which findings the auto-fixer is already handling. Identical shape to ' +
-            '`haystack triage <ref> --json`.',
+        name: 'inbox_list',
+        description: 'List PRs in the user\'s Haystack inbox with the reason and next action.',
+        inputSchema: { type: 'object', properties: {} },
+    },
+    {
+        name: 'pr_get',
+        description: 'Get useful state for one PR: triage, minimal merge blockers, trace availability, and conditional fixer outcome.',
+        inputSchema: { type: 'object', properties: { ref: refInput }, required: ['ref'] },
+    },
+    {
+        name: 'triage_get',
+        description: 'Get the complete Haystack verdict and every customer-facing finding for one PR.',
+        inputSchema: { type: 'object', properties: { ref: refInput }, required: ['ref'] },
+    },
+    {
+        name: 'ask_haystack',
+        description: 'Ask Haystack about a PR. Returns the answer and every customer-facing source consulted.',
         inputSchema: {
             type: 'object',
             properties: {
-                ref: {
-                    type: 'string',
-                    description: 'PR reference: bare number, owner/repo#number, or GitHub URL.',
-                },
+                ref: refInput,
+                question: { type: 'string', description: 'Question about the pull request.' },
+                session_id: { type: 'string', description: 'Optional prior Ask session to continue.' },
             },
-            required: ['ref'],
+            required: ['ref', 'question'],
         },
     },
     {
-        name: 'pr_state',
-        description: 'Show the Haystack state of a single PR: bucket, last triage rating, merge state.',
+        name: 'traces_list',
+        description: 'List retained customer-owned Entire checkpoints for one PR.',
+        inputSchema: { type: 'object', properties: { ref: refInput }, required: ['ref'] },
+    },
+    {
+        name: 'traces_get',
+        description: 'Get a page of retained customer-owned transcript chunks for one checkpoint.',
         inputSchema: {
             type: 'object',
             properties: {
-                ref: { type: 'string', description: 'PR reference.' },
+                ref: refInput,
+                checkpoint_id: { type: 'string' },
+                cursor: { type: 'string' },
+                limit: { type: 'integer', minimum: 1, maximum: 100 },
             },
-            required: ['ref'],
+            required: ['ref', 'checkpoint_id'],
         },
     },
     {
         name: 'schema',
-        description: 'Return the JSON Schema for a Haystack --json command output. ' +
-            'Use this to discover the exact shape of triage / setup / pr envelopes.',
+        description: 'Return the committed JSON Schema for a Haystack machine response.',
         inputSchema: {
             type: 'object',
-            properties: {
-                name: {
-                    type: 'string',
-                    enum: Object.keys(SCHEMA_VERSIONS),
-                    description: 'Schema noun.',
-                },
-            },
+            properties: { name: { type: 'string', enum: Object.keys(SCHEMA_VERSIONS) } },
             required: ['name'],
         },
     },
@@ -73,113 +76,64 @@ const TOOLS = [
 async function readSchema(name) {
     const major = SCHEMA_VERSIONS[name].split('.')[0];
     const here = dirname(fileURLToPath(import.meta.url));
-    // dist/commands/mcp.js → ../../schemas/<name>.v<major>.json
-    const p = join(here, '..', '..', 'schemas', `${name}.v${major}.json`);
-    return JSON.parse(readFileSync(p, 'utf8'));
-}
-/** Capture process.stdout written by CLI commands and return it. MCP tool
- *  callbacks must return their result, not write it. The simplest way to
- *  reuse the existing --json printers without refactoring them is to
- *  redirect stdout for the duration of the call. */
-async function captureStdout(fn) {
-    const origWrite = process.stdout.write.bind(process.stdout);
-    let captured = '';
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    process.stdout.write = (chunk, encoding, cb) => {
-        captured += typeof chunk === 'string' ? chunk : new TextDecoder().decode(chunk);
-        if (typeof encoding === 'function')
-            encoding();
-        else if (cb)
-            cb();
-        return true;
-    };
-    try {
-        await fn();
-    }
-    finally {
-        process.stdout.write = origWrite;
-    }
-    return captured;
-}
-function jsonFromCapture(captured) {
-    try {
-        return JSON.parse(captured);
-    }
-    catch {
-        return { error: 'tool produced non-JSON output', raw: captured.slice(0, 1000) };
-    }
+    return JSON.parse(readFileSync(join(here, '..', '..', 'schemas', `${name}.v${major}.json`), 'utf8'));
 }
 export async function runMcpServer() {
-    const server = new Server({
-        name: 'haystack-cli',
-        version: '1.0.0',
-    }, {
-        capabilities: { tools: {} },
-    });
+    const server = new Server({ name: 'haystack-cli', version: '1.0.0' }, { capabilities: { tools: {} } });
     server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
     server.setRequestHandler(CallToolRequestSchema, async (request) => {
         const { name, arguments: args } = request.params;
-        const ok = (data) => ({
-            content: [{ type: 'text', text: JSON.stringify(data, null, 2) }],
-        });
-        const fail = (msg) => ({
-            isError: true,
-            content: [{ type: 'text', text: msg }],
-        });
+        const input = (args ?? {});
+        const ok = (data) => ({ content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] });
+        const fail = (message) => ({ isError: true, content: [{ type: 'text', text: message }] });
         try {
-            if (name === 'triage_pr') {
-                const ref = args?.ref;
-                if (!ref)
+            if (name === 'inbox_list') {
+                const token = await loadToken();
+                if (!token)
+                    return fail('Not authenticated. Run `haystack login` first.');
+                return ok(await fetchInboxPayload(token));
+            }
+            if (name === 'pr_get') {
+                if (typeof input.ref !== 'string')
                     return fail('ref required');
-                const pr = parsePrRef(ref);
-                const token = (await loadToken()) ?? undefined;
-                const [synthesis, manifest] = await Promise.all([
-                    fetchRatingSynthesis(pr.owner, pr.repo, pr.prNumber, token),
-                    fetchAutoFixManifest(pr.owner, pr.repo, pr.prNumber, token),
-                ]);
-                if (!synthesis)
-                    return fail(`No triage data for ${pr.owner}/${pr.repo}#${pr.prNumber}`);
-                // Mirror triage --json envelope.
-                return ok(withSchema('triage', {
-                    owner: pr.owner,
-                    repo: pr.repo,
-                    prNumber: pr.prNumber,
-                    rating: synthesis.haystackRating,
-                    autoFixerHandling: manifest?.fixedItems ?? [],
-                    autoFixerSkipped: manifest?.leftForReview ?? [],
-                    findings: (synthesis.synthesisDisplay ?? []).map((f) => ({
-                        category: f.category,
-                        summary: f.summary,
-                        detail: f.detail,
-                        agentFixPrompt: f.agentFixPrompt ?? null,
-                        source: f.source ?? null,
-                    })),
+                return ok(await fetchPrStatePayload(input.ref));
+            }
+            if (name === 'triage_get') {
+                if (typeof input.ref !== 'string')
+                    return fail('ref required');
+                return ok(await fetchTriagePayload(input.ref));
+            }
+            if (name === 'ask_haystack') {
+                if (typeof input.ref !== 'string' || typeof input.question !== 'string')
+                    return fail('ref and question required');
+                return ok(await fetchAskPayload(input.ref, input.question, {
+                    session: typeof input.session_id === 'string' ? input.session_id : undefined,
                 }));
             }
-            if (name === 'pr_state') {
-                const ref = args?.ref;
-                if (!ref)
+            if (name === 'traces_list') {
+                if (typeof input.ref !== 'string')
                     return fail('ref required');
-                const captured = await captureStdout(async () => {
-                    await prReadCommand(ref, { json: true });
-                });
-                return ok(jsonFromCapture(captured));
+                return ok(await fetchTracesListPayload(input.ref));
+            }
+            if (name === 'traces_get') {
+                if (typeof input.ref !== 'string' || typeof input.checkpoint_id !== 'string')
+                    return fail('ref and checkpoint_id required');
+                return ok(await fetchTracesGetPayload(input.ref, input.checkpoint_id, {
+                    cursor: typeof input.cursor === 'string' ? input.cursor : undefined,
+                    limit: typeof input.limit === 'number' ? String(input.limit) : undefined,
+                }));
             }
             if (name === 'schema') {
-                const n = args?.name;
-                if (!n || !(n in SCHEMA_VERSIONS)) {
+                const schema = input.name;
+                if (!(schema in SCHEMA_VERSIONS))
                     return fail(`unknown schema; choose one of ${Object.keys(SCHEMA_VERSIONS).join(', ')}`);
-                }
-                return ok(await readSchema(n));
+                return ok(await readSchema(schema));
             }
             return fail(`unknown tool: ${name}`);
         }
-        catch (err) {
-            return fail(`tool error: ${err instanceof Error ? err.message : String(err)}`);
+        catch (error) {
+            return fail(error instanceof Error ? error.message : String(error));
         }
     });
-    const transport = new StdioServerTransport();
-    await server.connect(transport);
-    // The server runs until stdin closes. Stdio MCP gives no exit signal beyond
-    // that; we don't return.
+    await server.connect(new StdioServerTransport());
 }

package/dist/commands/pr.d.ts

@@ -4,7 +4,43 @@ export interface ParsedPR {
     prNumber: number;
 }
 export declare function parsePrRef(ref: string): ParsedPR;
+interface GitHubPr {
+    number: number;
+    title: string;
+    state: 'open' | 'closed';
+    merged: boolean;
+    mergeable_state?: string;
+    head: {
+        sha: string;
+        ref: string;
+    };
+    base: {
+        ref: string;
+    };
+}
+interface MergeQueueEntry {
+    status?: string;
+    detail?: string;
+    failedChecks?: string[];
+    actionNeeded?: string;
+}
+export declare function mergePublicState(meta: GitHubPr, entry: MergeQueueEntry | undefined, queueAvailable?: boolean): {
+    status: string;
+    reason: string;
+    blocking_checks: string[];
+    action: string | null;
+};
+export declare function fetchMergePublicState(meta: GitHubPr, prNumber: number, owner: string, repo: string, token: string): Promise<{
+    status: string;
+    reason: string;
+    blocking_checks: string[];
+    action: string | null;
+}>;
 export interface PrReadOptions {
     json?: boolean;
 }
-export declare function prReadCommand(ref: string, opts: PrReadOptions): Promise<void>;
+export declare function fetchPrStatePayload(ref: string): Promise<Record<string, unknown> & {
+    schema_version: string;
+}>;
+export declare function prReadCommand(ref: string, options: PrReadOptions): Promise<void>;
+export {};

package/dist/commands/pr.js

@@ -1,103 +1,121 @@
-/**
- * PR-reference helpers shared by the MCP server's `pr_state` tool.
- *
- * No top-level `haystack pr` CLI command — the original `pr <ref>` /
- * `pr <ref> merge|snooze|dismiss` surface was scope creep on the
- * CLI-as-platform spec. Use the pre-existing `haystack pr-status <pr>`
- * for the same read.
- *
- * Output shape is stamped with `schema_version` per `schemas/pr.v1.json`.
- */
 import chalk from 'chalk';
 import { loadToken } from '../utils/auth.js';
-import { fetchRatingSynthesis } from '../utils/analysis-api.js';
+import { fetchAutoFixManifest, fetchRatingSynthesis } from '../utils/analysis-api.js';
 import { parseRemoteUrl } from '../utils/git.js';
+import { fetchAnalysisArtifact, fetchGitHubJson, haystackJson } from '../utils/haystack-api.js';
 import { withSchema } from '../schema.js';
-const GITHUB_PROXY = process.env.HAYSTACK_API_BASE ?? 'https://haystackeditor.com';
 export function parsePrRef(ref) {
     const urlMatch = ref.match(/^https?:\/\/github\.com\/([^/]+)\/([^/]+)\/pull\/(\d+)\/?$/);
     if (urlMatch)
-        return { owner: urlMatch[1], repo: urlMatch[2], prNumber: parseInt(urlMatch[3], 10) };
+        return { owner: urlMatch[1], repo: urlMatch[2], prNumber: Number.parseInt(urlMatch[3], 10) };
     const qualifiedMatch = ref.match(/^([^/]+)\/([^#]+)#(\d+)$/);
     if (qualifiedMatch)
-        return { owner: qualifiedMatch[1], repo: qualifiedMatch[2], prNumber: parseInt(qualifiedMatch[3], 10) };
+        return { owner: qualifiedMatch[1], repo: qualifiedMatch[2], prNumber: Number.parseInt(qualifiedMatch[3], 10) };
     const bare = ref.match(/^#?(\d+)$/);
     if (bare) {
-        const r = parseRemoteUrl('origin');
-        return { owner: r.owner, repo: r.repo, prNumber: parseInt(bare[1], 10) };
+        const remote = parseRemoteUrl('origin');
+        return { owner: remote.owner, repo: remote.repo, prNumber: Number.parseInt(bare[1], 10) };
     }
     throw new Error(`Invalid PR reference: "${ref}". Use 123, owner/repo#123, or a GitHub URL.`);
 }
-async function ghPr(token, owner, repo, num) {
-    const url = `${GITHUB_PROXY}/api/github/repos/${owner}/${repo}/pulls/${num}`;
-    const res = await fetch(url, {
-        headers: {
-            Accept: 'application/vnd.github+json',
-            Authorization: `Bearer ${token}`,
-            'User-Agent': 'Haystack-CLI',
-        },
-    });
-    if (!res.ok) {
-        throw new Error(`GitHub API ${res.status}: ${(await res.text()).slice(0, 200)}`);
+export function mergePublicState(meta, entry, queueAvailable = true) {
+    if (meta.merged) {
+        return { status: 'merged', reason: 'The PR has merged.', blocking_checks: [], action: null };
+    }
+    if (meta.state === 'closed') {
+        return { status: 'closed', reason: 'The PR was closed without merging.', blocking_checks: [], action: null };
+    }
+    if (!queueAvailable) {
+        return {
+            status: 'unavailable',
+            reason: 'Haystack merge status is temporarily unavailable.',
+            blocking_checks: [],
+            action: 'Retry this request before making a merge decision.',
+        };
+    }
+    if (!entry) {
+        return {
+            status: 'not_applicable',
+            reason: 'The PR is not currently in Haystack merge processing.',
+            blocking_checks: [],
+            action: null,
+        };
     }
-    return res.json();
+    const failed = entry.failedChecks ?? [];
+    const blocked = failed.length > 0
+        || entry.status === 'failed'
+        || entry.status === 'needs_shepherding'
+        || entry.status === 'awaiting_human_approval';
+    return {
+        status: blocked ? 'blocked' : 'processing',
+        reason: blocked ? 'The PR has merge blockers.' : 'Haystack is processing the PR.',
+        blocking_checks: failed,
+        action: blocked ? 'Resolve the merge blockers.' : null,
+    };
 }
-export async function prReadCommand(ref, opts) {
-    const pr = parsePrRef(ref);
-    const token = await loadToken();
-    if (!token) {
-        console.error(chalk.red('Not authenticated. Run `haystack login` first.'));
-        process.exit(1);
+export async function fetchMergePublicState(meta, prNumber, owner, repo, token) {
+    try {
+        const mergeQueue = await haystackJson(`/api/merge-queue/status?repo=${encodeURIComponent(`${owner}/${repo}`)}&branch=${encodeURIComponent(meta.base.ref)}`, token);
+        return mergePublicState(meta, mergeQueue.prStatuses?.[String(prNumber)]);
     }
-    const [meta, synthesis] = await Promise.all([
-        ghPr(token, pr.owner, pr.repo, pr.prNumber),
-        // 404 → null is the "not analyzed yet" signal; we still log unexpected
-        // failures so they don't look the same as "not analyzed".
-        fetchRatingSynthesis(pr.owner, pr.repo, pr.prNumber, token).catch((err) => {
-            console.error(chalk.dim(`[pr] rating fetch failed: ${err instanceof Error ? err.message : String(err)}`));
-            return null;
-        }),
-    ]);
-    let bucket = 'analyzing';
-    if (meta.merged)
-        bucket = 'merged';
-    else if (meta.state === 'closed')
-        bucket = 'merged';
-    else if (synthesis?.haystackRating != null) {
-        bucket = synthesis.haystackRating <= 2
-            ? 'issues'
-            : synthesis.haystackRating === 5
-                ? 'good-to-merge'
-                : 'needs-attention';
+    catch {
+        return mergePublicState(meta, undefined, false);
     }
+}
+export async function fetchPrStatePayload(ref) {
+    const pr = parsePrRef(ref);
+    const token = await loadToken({ owner: pr.owner, repo: pr.repo });
+    if (!token)
+        throw new Error('Not authenticated. Run `haystack login` first.');
+    const meta = await fetchGitHubJson(`/repos/${pr.owner}/${pr.repo}/pulls/${pr.prNumber}`, token);
+    const [synthesis, manifest, traces, merge] = await Promise.all([
+        fetchRatingSynthesis(pr.owner, pr.repo, pr.prNumber, token),
+        fetchAutoFixManifest(pr.owner, pr.repo, pr.prNumber, token),
+        fetchAnalysisArtifact(pr.owner, pr.repo, pr.prNumber, 'entire_traces.json', token),
+        fetchMergePublicState(meta, pr.prNumber, pr.owner, pr.repo, token),
+    ]);
+    const verdict = synthesis?.analysisVerdict
+        ?? (synthesis ? (synthesis.haystackRating >= 5 ? 'clean' : 'has-issues') : null);
     const payload = {
-        owner: pr.owner,
-        repo: pr.repo,
-        prNumber: pr.prNumber,
-        bucket,
-        state: meta.merged ? 'merged' : meta.state,
+        ref: `${pr.owner}/${pr.repo}#${pr.prNumber}`,
         title: meta.title,
-        headSha: meta.head.sha,
-        haystackUrl: `https://haystackeditor.com/review/${pr.owner}/${pr.repo}/${pr.prNumber}`,
-        mergeQueue: null,
-        lastTriage: synthesis?.haystackRating != null
+        head_sha: meta.head.sha,
+        triage: synthesis
             ? {
-                rating: synthesis.haystackRating,
-                completedAt: new Date().toISOString(),
-                headSha: meta.head.sha,
+                status: 'complete',
+                verdict: verdict === 'clean' ? 'good_to_merge' : verdict === 'needs-review' ? 'needs_review' : 'needs_input',
+                findings_count: synthesis.synthesisDisplay?.length ?? 0,
             }
-            : null,
+            : { status: 'pending', verdict: null, findings_count: 0 },
+        merge,
+        traces: {
+            available: traces?.hasTraces === true,
+            count: traces?.traces?.length ?? 0,
+        },
     };
-    if (opts.json) {
-        console.log(JSON.stringify(withSchema('pr', payload), null, 2));
-        return;
+    if (manifest) {
+        const fixed = manifest.fixedItems.length;
+        const remaining = manifest.leftForReview.length;
+        payload.fixer = {
+            status: 'completed',
+            result_sha: manifest.resultSha ?? meta.head.sha,
+            summary: `Fixed ${fixed} finding${fixed === 1 ? '' : 's'}; ${remaining} remain${remaining === 1 ? 's' : ''} for review.`,
+        };
     }
-    console.log(`\n  ${chalk.bold(`${pr.owner}/${pr.repo}#${pr.prNumber}`)}  ${chalk.dim(meta.title)}`);
-    console.log(`  ${chalk.dim('bucket:')}    ${bucket}`);
-    console.log(`  ${chalk.dim('state:')}     ${payload.state}`);
-    console.log(`  ${chalk.dim('head:')}      ${meta.head.sha.slice(0, 7)} (${meta.head.ref})`);
-    if (payload.lastTriage) {
-        console.log(`  ${chalk.dim('rating:')}    ★${payload.lastTriage.rating}`);
+    return withSchema('pr', payload);
+}
+export async function prReadCommand(ref, options) {
+    const payload = await fetchPrStatePayload(ref);
+    if (options.json) {
+        console.log(JSON.stringify(payload, null, 2));
+        return;
     }
-    console.log(`  ${chalk.dim(payload.haystackUrl)}\n`);
+    const triage = payload.triage;
+    const merge = payload.merge;
+    console.log(`\n  ${chalk.bold(String(payload.ref))}  ${chalk.dim(String(payload.title))}`);
+    console.log(`  ${chalk.dim('triage:')}  ${triage.status}${triage.verdict ? ` · ${triage.verdict}` : ''} · ${triage.findings_count} findings`);
+    console.log(`  ${chalk.dim('merge:')}   ${merge.status} · ${merge.reason}`);
+    if (merge.action)
+        console.log(`  ${chalk.dim('next:')}    ${merge.action}`);
+    console.log('');
 }

package/dist/commands/review.d.ts

@@ -0,0 +1,24 @@
+/**
+ * review command — Trigger a fresh Haystack analysis for a PR.
+ *
+ * haystack review [pr] [--no-wait]
+ *
+ * Haystack runs a full analysis when a PR is opened (or marked ready);
+ * later pushes only get a resolution check against the existing findings.
+ * This command is the explicit escape hatch: it re-runs full detection on
+ * the PR's current head — use it after substantial new commits, or any
+ * time you want a fresh second opinion.
+ *
+ * When called without a PR identifier, reads the last submitted PR from
+ * `.haystack/pending-submit.json` (written by `haystack submit`).
+ *
+ * Accepts a PR identifier in several formats:
+ *   haystack review                      # Last submitted PR
+ *   haystack review 123                  # Uses current repo's owner/repo
+ *   haystack review owner/repo#123       # Fully qualified
+ *   haystack review https://github.com/owner/repo/pull/123
+ */
+export interface ReviewOptions {
+    wait?: boolean;
+}
+export declare function reviewCommand(identifier: string | undefined, options: ReviewOptions): Promise<void>;