@haystackeditor/cli 0.26.0 → 0.27.0

package/dist/commands/verify.js

@@ -27,74 +27,23 @@ import chalk from 'chalk';
 import { withSchema } from '../schema.js';
 import { findGitRoot } from '../utils/hooks.js';
 import { resolveAuthContext } from '../utils/auth.js';
-import { classifyHttpError, readWithRetries, SERVICE_SILENCE_LIMIT_MS, ServiceSilentError, transientReadFailure, } from '../utils/haystack-api.js';
+import { classifyHttpError, readWithRetries, SERVICE_SILENCE_LIMIT_MS, ServiceSilentError, transientReadFailure, repoApiPath, } from '../utils/haystack-api.js';
 import { GATEWAY_TIMEOUT_MS, gatewayFetch } from './case-batch.js';
 import { CRAWL_BRIEF_MAX_FUNCTIONS, CRAWL_BRIEF_MAX_GROUPS, CRAWL_BRIEF_MAX_PRODUCTION_ROWS, CRAWL_BUDGET_MAX_MS, CRAWL_BUDGET_MIN_MS, CRAWL_MAX_FINDINGS, CRAWL_MAX_FINDING_STEPS, CRAWL_MAX_IDEAS, CRAWL_MAX_STAND_IN_LINES, CRAWL_MAX_STAND_IN_ROWS, CRAWL_MAX_TEXT_CHARS, CRAWL_WAIT_MAX_MS, CRAWL_POOLS, } from './crawl-contract.js';
 import { captureCheckout, crawlUnavailableText, EXPLICIT_WALL_MS, normalModeFailure, postPrecomputeCapture, } from './verify-precompute.js';
+import { SPOT_WORDS, TERMINAL, VERDICT_WORDS, VERDICTS, currentStep, errorWords, headline, plural, reportedStatus, results, verifyReport, } from './crawl-report.js';
 import { formatOnboarding, onboardingExitCode, readOnboardingStatus, reportOnboardingState, reviewNotes, standInGapNotes, waitForOnboarding, } from './verify-onboarding.js';
 import { formatCapture, readPreVerifyCapture } from './capture-brief.js';
-const CRAWLS_PATH = '/api/agent/cloud-verifier/crawls';
 /** A held read (waitAfter): the service's hold, then the time any read gets. */
 const HELD_READ_TIMEOUT_MS = CRAWL_WAIT_MAX_MS + GATEWAY_TIMEOUT_MS;
 const RUN_ID = /^cv_[0-9a-f]{48}$/;
 const REPOSITORY_COMPONENT = /^[A-Za-z0-9_.-]{1,100}$/;
 const STATUSES = ['queued', 'preparing', 'crawling', 'draining', 'completed', 'prepared', 'incomplete', 'cancelled'];
-const TERMINAL = new Set(['completed', 'prepared', 'incomplete', 'cancelled']);
 const STAGES = ['reconcile', 'source', 'worlds', 'blast', 'knobs', 'prepare', 'crawl', 'publish', 'cleanup'];
 const ERROR_CODES = ['source-mismatch', 'blast-unavailable', 'world-build-failed',
     'prepare-failed', 'crawl-failed', 'no-capacity', 'stalled', 'lease-lost', 'cancelled'];
-const VERDICTS = ['bug', 'cant-tell', 'being-judged', 'not-a-bug'];
 const SPOT_STAGES = ['resolved', 'loaded', 'exposed', 'activated', 'pressed', 'observed', 'confirmed', 'judged'];
 const REUSE = ['hit', 'miss', null];
-const STATUS_WORDS = {
-    queued: 'waiting for a machine',
-    preparing: 'getting ready',
-    crawling: 'exploring the app',
-    draining: 'finishing the last checks',
-    completed: 'finished',
-    prepared: 'built and ready to check',
-    incomplete: 'stopped before finishing',
-    cancelled: 'cancelled',
-};
-const STAGE_WORDS = {
-    reconcile: 'cleaning up after an earlier try',
-    source: 'rebuilding your change',
-    worlds: 'building and starting the app with and without your change',
-    blast: 'waiting for the analysis of what your change touches',
-    knobs: "reading the app's settings",
-    prepare: 'setting up starting points next to your change',
-    crawl: 'exploring the app',
-    publish: 'saving the results',
-    cleanup: 'shutting down the machines it used',
-};
-const ERROR_WORDS = {
-    'source-mismatch': 'your change could not be rebuilt exactly as it was captured',
-    'blast-unavailable': 'the analysis of what your change touches was not available',
-    'world-build-failed': 'the app did not build or start, with or without your change',
-    'prepare-failed': 'setting up starting points next to your change failed',
-    'crawl-failed': 'exploring the app failed',
-    'no-capacity': 'there was no room on the machines for it',
-    stalled: 'it stopped making progress',
-    'lease-lost': 'the machine running it stopped responding',
-    cancelled: 'it was cancelled',
-};
-const SPOT_WORDS = {
-    resolved: 'never reached',
-    loaded: 'loaded but never ran',
-    exposed: 'shown on screen',
-    activated: 'ran',
-    pressed: 'ran when its control was pressed',
-    observed: 'a difference seen',
-    confirmed: 'a difference seen and confirmed',
-    // The stage, not the verdict: a judged difference may be judged not a bug. The findings carry the verdicts.
-    judged: 'a difference seen, confirmed and judged',
-};
-const VERDICT_WORDS = {
-    bug: 'Bug',
-    'cant-tell': "Can't tell",
-    'being-judged': 'Still being judged',
-    'not-a-bug': 'Not a bug',
-};
 /** A response the CLI will not print: malformed, contradictory, or another revision's. */
 export class CrawlResponseError extends Error {
     constructor(message) {
@@ -363,16 +312,15 @@ async function responseBody(response) {
 function read(path, token, waitAfter) {
     return waitAfter === undefined
         ? gatewayFetch(path, token)
-        : gatewayFetch(`${path}&waitAfter=${encodeURIComponent(waitAfter)}`, token, { method: 'GET', timeoutMs: HELD_READ_TIMEOUT_MS });
+        : gatewayFetch(`${path}${path.includes('?') ? '&' : '?'}waitAfter=${encodeURIComponent(waitAfter)}`, token, { method: 'GET', timeoutMs: HELD_READ_TIMEOUT_MS });
 }
 /** The caller's newest crawl of this capture's revision, or null. Its change
  * title may differ from the capture's (sameChange). */
 async function readCrawl(identity, token, waitAfter) {
-    const path = `${CRAWLS_PATH}?repository=${encodeURIComponent(identity.repository)}`
-        + `&workCommit=${encodeURIComponent(identity.workCommit)}`;
+    const path = repoApiPath(identity.repository, `/checks?commit=${encodeURIComponent(identity.workCommit)}`);
     const response = await read(path, token, waitAfter);
     if (!response.ok)
-        throw await classifyHttpError(response, `Haystack API ${CRAWLS_PATH}`);
+        throw await classifyHttpError(response, `Haystack API ${path}`);
     const body = await responseBody(response);
     if (!isRecord(body) || !Object.hasOwn(body, 'crawl'))
         invalid('no crawl field');
@@ -382,9 +330,10 @@ async function readCrawl(identity, token, waitAfter) {
 async function readCrawlRun(runId, identity, token, waitAfter) {
     if (!RUN_ID.test(runId))
         invalid('an acknowledged run id');
-    const response = await read(`${CRAWLS_PATH}/${runId}?repository=${encodeURIComponent(identity.repository)}`, token, waitAfter);
+    const path = repoApiPath(identity.repository, `/checks/${runId}`);
+    const response = await read(path, token, waitAfter);
     if (!response.ok)
-        throw await classifyHttpError(response, `Haystack API ${CRAWLS_PATH}/${runId}`);
+        throw await classifyHttpError(response, `Haystack API ${path}`);
     const view = parseCrawlView(await responseBody(response), identity);
     if (view.runId !== runId || !sameChange(view, identity)) {
         throw new CrawlResponseError(`The crawl service returned another crawl for ${runId}; it is not shown.`);
@@ -397,52 +346,6 @@ function safe(value) {
     // eslint-disable-next-line no-control-regex -- replacing control characters is the point
     return value.replace(/[\u0000-\u001f\u007f-\u009f]/g, ' ');
 }
-function plural(count, noun) {
-    return `${count} ${noun}${count === 1 ? '' : 's'}`;
-}
-function errorWords(error) {
-    return error.code === 'stalled'
-        ? `${ERROR_WORDS.stalled} while ${STAGE_WORDS[error.stage]}`
-        : ERROR_WORDS[error.code];
-}
-/** What a running crawl is doing now: its stage, except while it waits for a
- * machine or finishes its last checks, which its status says better. */
-function currentStep(view) {
-    return view.status === 'queued' || view.status === 'draining' ? STATUS_WORDS[view.status] : STAGE_WORDS[view.stage];
-}
-/** The crawl's results: its sealed manifest, else (amendment 9) its answer at the budget, which has the same findings and reach. */
-function results(view) {
-    return view.manifest ?? (view.answer?.status === 'answered' ? view.answer : null);
-}
-/** The status the command reports: a running crawl that has answered (amendment 9: its budget is up and its work is
- * done; only its shutdown remains) reads as completed. */
-function reportedStatus(view) {
-    return !TERMINAL.has(view.status) && view.answer?.status === 'answered' ? 'completed' : view.status;
-}
-function headline(view) {
-    const bugs = results(view)?.bugs ?? view.totals.bugs;
-    const found = bugs > 0 ? ` It found ${plural(bugs, 'bug')} before it stopped.` : '';
-    switch (reportedStatus(view)) {
-        case 'completed':
-            return bugs > 0 ? `Found ${plural(bugs, 'bug')} in your change.` : 'No bugs found in your change.';
-        case 'incomplete': {
-            const error = results(view)?.error ?? view.error;
-            return `The crawl could not finish: ${error ? errorWords(error) : 'no reason was recorded'}.${found}`;
-        }
-        case 'prepared':
-            // Amendment 12: the turn-end hook built and froze this change; `haystack verify` asks for the crawl itself.
-            return 'Your change is built and ready to check, but was not crawled yet. Run `haystack verify` to check it.';
-        case 'cancelled':
-            return `The crawl was cancelled.${found}`;
-        default: {
-            const so = bugs > 0 ? ` ${plural(bugs, 'bug')} found so far.` : '';
-            if (view.cancelRequested) {
-                return `Being cancelled: ${currentStep(view)}.${so}`;
-            }
-            return `Still running: ${currentStep(view)}.${so}`;
-        }
-    }
-}
 function spotLines(spot) {
     const how = spot.furthest === null ? 'never reached' : SPOT_WORDS[spot.furthest];
     const found = spot.findingIds.length === 0 ? ''
@@ -555,57 +458,12 @@ export function formatCrawl(view) {
     }
     return lines.join('\n');
 }
-export function verifyReport(view) {
-    const status = reportedStatus(view);
-    const published = results(view);
-    const error = published?.error ?? view.error;
-    const explored = published !== null && view.clocks.crawlStartedAt !== null;
-    const findings = explored ? VERDICTS.flatMap(verdict => published.findings.filter(finding => finding.verdict === verdict)) : [];
-    const ideaWords = { covered: 'tried', blocked: 'could not try', unfinished: 'not finished' };
-    return {
-        runId: view.runId,
-        repository: view.repository,
-        title: view.changeTitle,
-        baseCommit: view.baseCommit,
-        workCommit: view.workCommit,
-        status,
-        headline: headline(view),
-        bugs: published?.bugs ?? view.totals.bugs,
-        findings: findings.map(finding => ({
-            id: finding.id,
-            verdict: finding.verdict,
-            why: finding.why,
-            start: finding.start,
-            steps: finding.steps,
-            outsideServices: finding.standIns && (finding.standIns.old.length > 0 || finding.standIns.new.length > 0)
-                ? { withoutChange: finding.standIns.old, withChange: finding.standIns.new }
-                : null,
-        })),
-        spots: explored ? published.reach.spots.map(spot => ({
-            file: spot.file,
-            line: spot.line,
-            reached: spot.furthest === null ? 'never reached' : SPOT_WORDS[spot.furthest],
-            reachedBy: spot.reachedBy && { start: spot.reachedBy.start, steps: spot.reachedBy.steps, page: spot.reachedBy.page },
-            findingIds: spot.findingIds,
-        })) : [],
-        ideas: explored && published.ideas !== undefined
-            ? published.ideas.map(idea => ({ text: idea.text, result: ideaWords[idea.state], reason: idea.reason, findingIds: idea.findingIds }))
-            : null,
-        neverRan: explored ? {
-            files: published.reach.unreachedChangedFiles,
-            functions: published.reach.blast === null ? null : { ran: published.reach.blast.ran, total: published.reach.blast.functions },
-        } : null,
-        notFinishedInTime: explored ? published.notFinishedInTime : 0,
-        outsideServiceGaps: explored ? published.standIns?.gaps ?? [] : [],
-        error: error ? { code: error.code, message: error.message } : null,
-        machinesNotProvenShutDown: TERMINAL.has(view.status) ? view.totals.cleanupUnproven : 0,
-    };
-}
 /** Case-batch status conventions: 0 finished (or answered: amendment 9, its work
  * is done and only its shutdown remains), or still running with --no-wait;
  * 2 ended without finishing (incomplete, cancelled) or finished with cleanup
  * unproven (an answered crawl has not finished its cleanup, so it is not judged); bugs
  * found never change it. The command's own failures exit 1 elsewhere. */
+export { verifyReport };
 export function crawlExitCode(view) {
     const status = reportedStatus(view);
     if (!TERMINAL.has(status))

package/dist/index.js

@@ -1,23 +1,13 @@
 #!/usr/bin/env node
 /**
- * Haystack CLI
+ * Haystack CLI: `haystack verify` runs your app with and without a change and shows what it broke.
  *
- * Set up your project for Haystack.
- * Automated PR review, triage, and merge queue for AI-assisted development.
+ *   haystack init       Set this repository up for `haystack verify` and start onboarding the app
+ *   haystack verify     After a change: crawl the app with and without it, and report what broke
+ *   haystack feedback   Tell the Haystack team what went wrong
+ *   haystack login      Sign in with GitHub
  *
- * Usage:
- *   npx @haystackeditor/cli init           # Set this repository up for `haystack verify`
- *   npx @haystackeditor/cli setup          # Interactive onboarding wizard
- *   npx @haystackeditor/cli status         # Check configuration
- *   npx @haystackeditor/cli login          # Authenticate with GitHub
- *   npx @haystackeditor/cli submit         # Create a PR (auto-merge or review)
- *   npx @haystackeditor/cli triage          # Check last submitted PR
- *   npx @haystackeditor/cli triage 123     # View analysis results for a PR
- *   npx @haystackeditor/cli dismiss 123    # Dismiss findings for a PR
- *   npx @haystackeditor/cli mark-reviewed 123 # Mark review as not needed
- *   npx @haystackeditor/cli request-review 123 # Tag a PR as needing human review
- *   npx @haystackeditor/cli pr-status 123  # Show PR status in Haystack pipeline
- *   npx @haystackeditor/cli config         # Manage preferences
+ * Without a global install: npx -y -p @haystackeditor/cli@latest haystack <command>
  */
 import { readFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
@@ -29,7 +19,6 @@ import { lazy } from './lazy.js';
 // Command modules load on first use (see src/lazy.ts). Keep new commands
 // on this pattern: a static import here puts its whole dependency graph on
 // the startup path of every invocation, including --version and --help.
-const statusCommand = lazy(() => import('./commands/status.js'), 'statusCommand');
 const initCommand = lazy(() => import('./commands/init.js'), 'initCommand');
 const captureManifestCommand = lazy(() => import('./commands/capture-manifest.js'), 'captureManifestCommand');
 const authListCommand = lazy(() => import('./commands/login.js'), 'authListCommand');
@@ -93,7 +82,7 @@ program
     // ignored them. Every command created below inherits this setting.
     .allowExcessArguments();
 program
-    .command('schema [name]')
+    .command('schema [name]', { hidden: true })
     .description('Print the JSON Schema for a command\'s --json output')
     .action((name) => (name ? schemaCommand(name) : listSchemas()));
 program
@@ -170,10 +159,6 @@ Examples:
   haystack init --yes --json --notes haystack-notes.json
 `)
     .action(options => runPublicCommand(() => initCommand(options), options.json));
-program
-    .command('status')
-    .description('Check if .haystack.json exists and is valid')
-    .action(statusCommand);
 const verify = program
     .command('verify')
     .description('Crawl the running app with your current change: where it shows up and what broke')
@@ -670,7 +655,7 @@ GitHub expires it.
 program
     .command('logout [login]')
     .description('Remove a saved GitHub account (use --headless to remove the local CLI token)')
-    .option('--headless', 'Remove the local hsk_live_* token file (does not revoke server-side — use `haystack tokens revoke <id>`)')
+    .option('--headless', 'Remove the local hsk_live_* token file (does not revoke server-side — use `haystack auth revoke <id>`)')
     .action(async (login, opts) => {
     if (opts.headless) {
         try {
@@ -684,24 +669,37 @@ program
     }
     return logoutCommand(login);
 });
-// ─── tokens (server-side hsk_live_*) ─────────────────────────────────────────
-const tokens = program.command('tokens').description('Manage server-side hsk_live_* tokens');
-tokens
+program
+    .command('whoami')
+    .description('Show the active Haystack GitHub account')
+    .action(whoamiCommand);
+const authProgram = program
+    .command('auth')
+    .description('Saved accounts and long-lived (hsk_live) tokens');
+authProgram
     .command('list')
-    .description('List your CLI tokens')
+    .description('List saved Haystack GitHub accounts')
+    .action(authListCommand);
+authProgram
+    .command('use <login>')
+    .description('Set the active Haystack GitHub account')
+    .action(authUseCommand);
+authProgram
+    .command('tokens')
+    .description('List your long-lived (hsk_live) tokens')
     .option('--json', 'Machine-readable output')
     .action(async (opts) => {
     try {
         await listTokensCommand(opts);
     }
     catch (err) {
-        console.error(chalk.red('list failed:'), err instanceof Error ? err.message : err);
+        console.error(chalk.red('tokens failed:'), err instanceof Error ? err.message : err);
         process.exit(1);
     }
 });
-tokens
+authProgram
     .command('revoke <id>')
-    .description('Revoke a token by id (cannot be undone)')
+    .description('Revoke a long-lived token by id (cannot be undone)')
     .action(async (id) => {
     try {
         await revokeTokenCommand(id);
@@ -711,21 +709,6 @@ tokens
         process.exit(1);
     }
 });
-program
-    .command('whoami')
-    .description('Show the active Haystack GitHub account')
-    .action(whoamiCommand);
-const authProgram = program
-    .command('auth')
-    .description('Manage saved Haystack GitHub accounts');
-authProgram
-    .command('list')
-    .description('List saved Haystack GitHub accounts')
-    .action(authListCommand);
-authProgram
-    .command('use <login>')
-    .description('Set the active Haystack GitHub account')
-    .action(authUseCommand);
 const telemetry = program.command('telemetry').description('Add privacy-safe production telemetry without an application SDK')
     .addHelpText('after', `
 Next.js bundles its server code, so instead of \`instrument\` add the CLI as a

package/dist/utils/haystack-api.js

@@ -1,6 +1,14 @@
 export function haystackApiBase() {
     return process.env.HAYSTACK_API_BASE ?? 'https://haystackeditor.com';
 }
+/** A public API path for `repository` (owner/repo): /v1/repos/{owner}/{repo}{rest}. */
+export function repoApiPath(repository, rest) {
+    const parts = repository.split('/');
+    if (parts.length !== 2 || parts.some(part => !/^[A-Za-z0-9_.-]{1,100}$/.test(part))) {
+        throw new Error(`Invalid repository ${repository}: it must be owner/repo.`);
+    }
+    return `/v1/repos/${parts[0]}/${parts[1]}${rest}`;
+}
 export function haystackApiUrl(path) {
     if (!path.startsWith('/'))
         throw new Error('Haystack API path must be absolute');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@haystackeditor/cli",
-  "version": "0.26.0",
+  "version": "0.27.0",
   "description": "haystack verify: run your app with and without a change, and see what the change broke",
   "type": "module",
   "bin": {

package/dist/commands/status.js

@@ -1,35 +0,0 @@
-/**
- * haystack status - Check if .haystack.json exists and is valid
- */
-import chalk from 'chalk';
-import { loadConfig, findConfigPath } from '../utils/config.js';
-export async function statusCommand() {
-    const configPath = await findConfigPath();
-    if (!configPath) {
-        console.log(chalk.yellow('⚠ No .haystack.json found'));
-        console.log(chalk.dim('\nRun `haystack init` to create one.\n'));
-        process.exit(1);
-    }
-    console.log(chalk.green(`✓ Found ${configPath}`));
-    try {
-        const config = await loadConfig(configPath);
-        if (!config) {
-            console.log(chalk.red('✗ Failed to load config'));
-            process.exit(1);
-        }
-        console.log(chalk.green('✓ Config is valid\n'));
-        // Show config summary
-        if (config.name) {
-            console.log(`  ${chalk.dim('Name:')} ${config.name}`);
-        }
-        if (config.services) {
-            const serviceNames = Object.keys(config.services);
-            console.log(`  ${chalk.dim('Services:')} ${serviceNames.join(', ')}`);
-        }
-        console.log('');
-    }
-    catch (e) {
-        console.log(chalk.red(`✗ Config is invalid: ${e.message}`));
-        process.exit(1);
-    }
-}