@haystackeditor/cli 0.15.17 → 0.15.19

package/README.md

@@ -69,7 +69,6 @@ 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 --auto-fix           # Discouraged alpha auto-fix for straightforward mechanical issues
 haystack submit --title "Fix auth"   # Custom PR title
 haystack submit --draft              # Create as draft PR
 haystack submit --force              # Skip triage checks
@@ -85,8 +84,6 @@ haystack submit --review octocat     # Request review from a specific teammate
 
 When `--review` is used without a username, the PR is labeled `haystack:needs-review` and appears in your team's assignment queue. When a username is provided, that person is also requested as a reviewer on GitHub.
 
-The `--auto-fix` flag is an alpha feature and is discouraged by default. It opts into a sandbox agent that attempts straightforward mechanical fixes before surfacing issues in the Feed. For most PRs, prefer plain `haystack submit`.
-
 ### `haystack triage`
 
 View Haystack analysis results for any PR. Shows the same data as the Haystack web feed: rating, verdict, structured findings with details, verified bugs, human review reasons, and agent fix prompts.
@@ -102,9 +99,51 @@ haystack triage --hook                      # Minimal one-liner (for session hoo
 haystack triage --clear                     # Clear pending submit state
 ```
 
-When called without a PR identifier, checks the last PR submitted via `haystack submit`. The `--hook` flag produces a single-line summary with the Haystack rating and auto-fixer status, designed for session-start hooks.
+When called without a PR identifier, checks the last PR submitted via `haystack submit`. The `--hook` flag produces a single-line summary with the Haystack rating, designed for session-start hooks.
+
+The `--json` output includes every finding and its customer-facing `suggested_fix` when available.
+
+### `haystack inbox list`
+
+List PRs in your Haystack inbox with the reason each PR is present and the next action:
+
+```bash
+haystack inbox list
+haystack inbox list --json
+```
+
+### `haystack pr get`
+
+Get the useful state of one PR: triage, minimal merge blockers, and customer-trace availability:
+
+```bash
+haystack pr get 42
+haystack pr get owner/repo#42 --json
+```
+
+### `haystack ask`
+
+Ask Haystack Chat about a PR. Machine output contains the answer and every customer-facing source Chat consulted:
+
+```bash
+haystack ask 42 "Why is this finding legitimate?"
+haystack ask owner/repo#42 "Show the implementation" --json
+haystack ask owner/repo#42 "What about its callers?" --session <session-id> --json
+```
+
+Chat may search the complete authorized repository when the changed files are insufficient. Search results and fetched source are included in `evidence`.
+
+### `haystack traces`
+
+Inspect retained customer-owned Entire checkpoints and transcript chunks:
+
+```bash
+haystack traces list owner/repo#42 --json
+haystack traces get owner/repo#42 <checkpoint-id> --json
+haystack traces get owner/repo#42 <checkpoint-id> --cursor 20 --limit 20 --json
+```
 
-The `--json` output includes `agentFixPrompt` fields -- ready-to-paste instructions for coding agents to fix each finding.
+These commands expose customer coding-session data, not Haystack's internal analysis-agent execution.
 
 ### `haystack dismiss`
 
@@ -135,7 +174,7 @@ haystack mark-reviewed acme/widgets#99     # Mark for specific repo
 
 ### `haystack pr-status`
 
-Show what bucket a PR is in within the Haystack pipeline (analyzing, auto-fixing, good-to-merge, issues, needs-assignment, etc.):
+Show what bucket a PR is in within the Haystack pipeline (analyzing, good-to-merge, issues, needs-assignment, etc.):
 
 ```bash
 haystack pr-status 42                          # Current repo, PR #42

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

@@ -0,0 +1,138 @@
+# 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. Self-check before opening the PR
+
+- [ ] `version: 1` is present and the file is valid YAML
+- [ ] no test-selection keys (`scenarios`, `tests`, `skip`, `focus`, ...)
+- [ ] no secret values anywhere (env var names only)
+- [ ] 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.d.ts

@@ -0,0 +1,14 @@
+export interface AskOptions {
+    json?: boolean;
+    session?: string;
+}
+export interface AskResponse {
+    schema_version: string;
+    ref: string;
+    head_sha: string;
+    answer: string;
+    evidence: Array<Record<string, unknown>>;
+    session_id: string;
+}
+export declare function fetchAskPayload(ref: string, question: string, options: Pick<AskOptions, 'session'>): Promise<AskResponse>;
+export declare function askHaystackCommand(ref: string, question: string, options: AskOptions): Promise<void>;

package/dist/commands/ask.js

@@ -0,0 +1,20 @@
+import chalk from 'chalk';
+import { loadToken } from '../utils/auth.js';
+import { postAskHaystack } from '../utils/haystack-api.js';
+import { parsePrRef } from './pr.js';
+export async function fetchAskPayload(ref, question, options) {
+    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.');
+    return postAskHaystack(pr.owner, pr.repo, pr.prNumber, question, options.session, token);
+}
+export async function askHaystackCommand(ref, question, options) {
+    const response = await fetchAskPayload(ref, question, options);
+    if (options.json) {
+        console.log(JSON.stringify(response, null, 2));
+        return;
+    }
+    console.log(`\n${response.answer}\n`);
+    console.log(chalk.dim(`${response.evidence.length} source${response.evidence.length === 1 ? '' : 's'} consulted · session ${response.session_id}\n`));
+}

package/dist/commands/inbox.d.ts

@@ -0,0 +1,65 @@
+interface GitHubPull {
+    number: number;
+    title: string;
+    html_url: string;
+    draft?: boolean;
+    user: {
+        id: number;
+        login: string;
+    };
+    assignees?: Array<{
+        id: number;
+        login: string;
+    }>;
+    requested_reviewers?: Array<{
+        id: number;
+        login: string;
+    }>;
+    head: {
+        sha: string;
+        ref: string;
+    };
+    base: {
+        ref: string;
+    };
+}
+interface InboxCandidate extends GitHubPull {
+    owner: string;
+    repo: string;
+}
+interface AnalysisSummary {
+    analysisStatus?: 'pending' | 'in_queue' | 'ready' | 'error';
+    analysisVerdict?: 'clean' | 'has-issues' | 'needs-review';
+    haystackRating?: number;
+    needsHumanReview?: boolean;
+    findingsCount?: number;
+    merge?: {
+        status: string;
+        reason: string;
+        blocking_checks: string[];
+        action: string | null;
+    };
+}
+export interface InboxListOptions {
+    json?: boolean;
+}
+export declare function isRelevantToUser(pr: GitHubPull, userId: number): boolean;
+export declare function classify(candidate: InboxCandidate, analysis: AnalysisSummary | undefined): {
+    bucket: string;
+    reason: string;
+    action: string;
+};
+export declare function fetchInboxPayload(token: string): Promise<{
+    pull_requests: {
+        bucket: string;
+        reason: string;
+        action: string;
+        ref: string;
+        title: string;
+        head_sha: string;
+    }[];
+} & {
+    schema_version: string;
+}>;
+export declare function inboxListCommand(options: InboxListOptions): Promise<void>;
+export {};

package/dist/commands/inbox.js

@@ -0,0 +1,137 @@
+import chalk from 'chalk';
+import { loadToken } from '../utils/auth.js';
+import { fetchCliIdentity, fetchGitHubJson, fetchHaystackInstallations, haystackJson, } from '../utils/haystack-api.js';
+import { withSchema } from '../schema.js';
+async function fetchOpenPulls(owner, repo, token) {
+    const pulls = [];
+    for (let page = 1;; page++) {
+        const batch = await fetchGitHubJson(`/repos/${encodeURIComponent(owner)}/${encodeURIComponent(repo)}/pulls?state=open&per_page=100&page=${page}`, token);
+        pulls.push(...batch);
+        if (batch.length < 100)
+            return pulls;
+    }
+}
+export function isRelevantToUser(pr, userId) {
+    return pr.user.id === userId
+        || (pr.assignees ?? []).some((user) => user.id === userId)
+        || (pr.requested_reviewers ?? []).some((user) => user.id === userId);
+}
+async function mapConcurrent(values, concurrency, fn) {
+    const results = new Array(values.length);
+    let next = 0;
+    await Promise.all(Array.from({ length: Math.min(concurrency, values.length) }, async () => {
+        while (next < values.length) {
+            const index = next++;
+            results[index] = await fn(values[index]);
+        }
+    }));
+    return results;
+}
+export function classify(candidate, analysis) {
+    const findingCount = analysis?.findingsCount ?? 0;
+    const failedChecks = analysis?.merge?.blocking_checks ?? [];
+    if (analysis?.analysisStatus === 'error') {
+        return {
+            bucket: 'needs_shepherding',
+            reason: 'Haystack analysis failed.',
+            action: 'Retry the analysis or inspect the failure.',
+        };
+    }
+    if (!analysis || analysis.analysisStatus === 'pending' || analysis.analysisStatus === 'in_queue') {
+        return {
+            bucket: 'analyzing',
+            reason: 'Haystack is still analyzing this PR.',
+            action: 'Wait for analysis to complete.',
+        };
+    }
+    if (analysis.analysisVerdict === 'has-issues' || (analysis.haystackRating ?? 5) < 4) {
+        return {
+            bucket: 'needs_shepherding',
+            reason: findingCount > 0
+                ? `Haystack found ${findingCount} author-actionable finding${findingCount === 1 ? '' : 's'}.`
+                : 'Haystack found author-actionable issues.',
+            action: 'Read the triage findings and resolve the issues.',
+        };
+    }
+    if (failedChecks.length > 0 || analysis.merge?.status === 'blocked') {
+        return {
+            bucket: 'needs_shepherding',
+            reason: failedChecks.length > 0
+                ? `${failedChecks.length} required check${failedChecks.length === 1 ? ' is' : 's are'} failing: ${failedChecks.join(', ')}.`
+                : (analysis.merge?.reason ?? 'The PR is blocked from merging.'),
+            action: analysis.merge?.action ?? 'Resolve the merge blockers.',
+        };
+    }
+    if (analysis.analysisVerdict === 'needs-review' || analysis.needsHumanReview) {
+        return {
+            bucket: 'needs_review',
+            reason: 'Analysis is clean, but review policy requires a human reviewer.',
+            action: 'Complete or request the required review.',
+        };
+    }
+    return {
+        bucket: 'good_to_merge',
+        reason: 'Haystack found no blocking issues.',
+        action: 'No user action is required.',
+    };
+}
+export async function fetchInboxPayload(token) {
+    const [identity, installations] = await Promise.all([
+        fetchCliIdentity(token),
+        fetchHaystackInstallations(token),
+    ]);
+    const repos = [...new Set(installations.flatMap((i) => i.repositories ?? []).map((r) => r.full_name))];
+    const batches = await mapConcurrent(repos, 8, async (fullName) => {
+        const [owner, repo] = fullName.split('/');
+        if (!owner || !repo)
+            throw new Error(`Invalid repository returned by Haystack: ${fullName}`);
+        const pulls = await fetchOpenPulls(owner, repo, token);
+        return pulls
+            .filter((pr) => isRelevantToUser(pr, identity.id))
+            .map((pr) => ({ ...pr, owner, repo }));
+    });
+    const candidates = batches.flat();
+    const refs = candidates.map((pr) => `${pr.owner}/${pr.repo}#${pr.number}`);
+    const analysis = refs.length === 0
+        ? {}
+        : await haystackJson('/api/bulk-analysis-summaries', token, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({
+                prIdentifiers: refs,
+                prBaseBranches: Object.fromEntries(candidates.map((pr) => [`${pr.owner}/${pr.repo}#${pr.number}`, pr.base.ref])),
+                prHeadShas: Object.fromEntries(candidates.map((pr) => [`${pr.owner}/${pr.repo}#${pr.number}`, pr.head.sha])),
+            }),
+        });
+    return withSchema('inbox', {
+        pull_requests: candidates.map((pr) => {
+            const ref = `${pr.owner}/${pr.repo}#${pr.number}`;
+            return {
+                ref,
+                title: pr.title,
+                head_sha: pr.head.sha,
+                ...classify(pr, analysis[ref]),
+            };
+        }),
+    });
+}
+export async function inboxListCommand(options) {
+    const token = await loadToken();
+    if (!token)
+        throw new Error('Not authenticated. Run `haystack login` first.');
+    const payload = await fetchInboxPayload(token);
+    if (options.json) {
+        console.log(JSON.stringify(payload, null, 2));
+        return;
+    }
+    if (payload.pull_requests.length === 0) {
+        console.log(chalk.dim('\nNo PRs need your attention.\n'));
+        return;
+    }
+    console.log(chalk.bold('\nHaystack inbox\n'));
+    for (const pr of payload.pull_requests) {
+        console.log(`${chalk.cyan(pr.ref)}  ${chalk.bold(pr.title)}`);
+        console.log(`  ${pr.reason}`);
+        console.log(`  ${chalk.dim('Next:')} ${pr.action}\n`);
+    }
+}