@haystackeditor/cli 0.27.3 → 0.28.0

package/README.md

@@ -43,8 +43,9 @@ Most users of this CLI are coding agents. What to know:
 
 - **After a change, two steps** inside the checkout (nothing needs to be
   committed or pushed):
-  1. `haystack pre-verify` shows what the change touches, what production and
-     real users do there, and Haystack's ideas of what could break.
+  1. `haystack verify` is the handshake: it shows what the change touches, what
+     production and real users do there, and Haystack's ideas of what could
+     break, then asks you to steer (exit 4).
   2. `haystack verify --intent "<the task, in the user's words>" --idea "<as you
      would tell a tester>"` explores the app with your steering: keep the ideas
      worth trying, add your own (repeat `--idea`); yours are explored first.
@@ -120,7 +121,7 @@ not be proven shut down;
 `haystack verify precompute --hook` whenever an agent turn stops. It captures
 the checkout within five seconds and hands the request to a detached sender.
 The service then builds the app with and without the change, works out what
-the change touches (the brief `haystack pre-verify` prints) and sets up starting
+the change touches (the brief the handshake shows) and sets up starting
 points next to it, and stops there: it never crawls. `haystack verify` then
 crawls from that prepared app instead of building it again. No run cancels
 another: each runs to its end unless it is cancelled. `haystack verify precompute`

package/dist/commands/capture-brief.js

@@ -1,4 +1,4 @@
-/** CAPTURE-V1 rule 7b in `haystack pre-verify`: the routes a change touches (the brief's blast-radius files and the changed
+/** CAPTURE-V1 rule 7b in the handshake (`haystack verify` without --intent): the routes a change touches (the brief's blast-radius files and the changed
  * files, joined through the route manifest's source entries) with their share of captured sessions over the window, the union
  * over all of them, freshness and drops; sessions on routes no manifest names are unmapped, never zero. One section per app
  * whose `.haystack/capture.json` (rule 8b, written by `haystack init` in the app's directory, apps/web in a monorepo) records it,
@@ -49,7 +49,7 @@ async function readApp(gitRoot, app, repository, token, files, now) {
         return { app, applicationId, state: 'unavailable', reason: error instanceof Error ? error.message : String(error) };
     }
 }
-/** The pre-verify capture sections, one per app with a record, or null for a checkout with none. `files`: the brief's function
+/** The handshake capture sections, one per app with a record, or null for a checkout with none. `files`: the brief's function
  * files and the changed files. */
 export async function readPreVerifyCapture(gitRoot, repository, token, files, now) {
     let apps;

package/dist/commands/init.js

@@ -49,8 +49,8 @@ export const AGENT_NOTE = [
     'the work done. It runs the app with and without the change, explores it, and reports what broke. It changes nothing,',
     'so run it without asking.',
     '',
-    '1. `haystack pre-verify`: what your change touches, what production and real users do there, and Haystack\'s ideas',
-    '   of what could break.',
+    '1. `haystack verify`: what your change touches, what production and real users do there, and Haystack\'s ideas of',
+    '   what could break. It then asks you to steer (exit 4).',
     '2. `haystack verify --intent "<what you were asked to do, in the user\'s words>" --idea "<something to try>"`: keep the',
     '   ideas worth trying, add your own (repeat --idea); yours are explored first.',
     '',

package/dist/commands/verify.js

@@ -614,6 +614,14 @@ async function waitForCrawl(first, identity, token) {
         process.removeListener('SIGINT', interrupted);
     }
 }
+/** What one `haystack verify` does with its change: a steered call (--intent) submits its crawl; a plain call shows a crawl of
+ * the change that has started (picking it up after a timeout), and otherwise (none, only prepared, or one that ended without
+ * finishing) is the handshake. */
+export function verifyStep(steered, found, stale) {
+    if (steered)
+        return 'submit';
+    return found !== null && stale === null ? 'show' : 'handshake';
+}
 /** A found crawl of the same code that is a different crawl (another title, another time): a new one starts, none is run again. */
 const anotherCrawl = (stale) => stale === 'retitled' || stale === 'other-time';
 const timeWords = (budgetMs) => budgetMs === null ? 'the default time' : `${budgetMs / 60_000} min`;
@@ -709,7 +717,7 @@ function briefOf(view) {
 /** Follows a run until it holds a brief or ends (amendment 18): its own read held until it changes, as waitForCrawl's is. */
 async function waitForBrief(first, identity, token) {
     const interrupted = () => {
-        console.error('\nStopped waiting. The change keeps being prepared; run `haystack pre-verify` again to see its brief.');
+        console.error('\nStopped waiting. The change keeps being prepared; run `haystack verify` again to see what it touches.');
         process.exit(130);
     };
     process.once('SIGINT', interrupted);
@@ -729,7 +737,7 @@ async function waitForBrief(first, identity, token) {
                 if (why === null)
                     throw error;
                 if (Date.now() - answeredAt >= SERVICE_SILENCE_LIMIT_MS)
-                    throw new ServiceSilentError('crawl', 'haystack pre-verify');
+                    throw new ServiceSilentError('crawl', 'haystack verify');
                 if (!failing)
                     progress(`The run's status is unavailable for now (${why}); reading it again.`);
                 failing = true;
@@ -836,103 +844,88 @@ export function formatBrief(brief) {
     }
     return lines.join('\n');
 }
-/** The handshake's question, asked after everything pre-verify shows. */
-const STEER_LINES = ['', 'Next: pick the ideas worth trying, add your own, and say what you were asked to do (the task in the user\'s words, not what your code does):',
-    '  haystack verify --intent "<what you were asked to do>" --idea "<something to try>" [--idea ...]',
-    'Your ideas are explored first; the ideas above are explored in every crawl too.'];
-/** `haystack pre-verify` (CRAWL-V1 amendment 18): the brief of the current change, before any crawl. It captures the checkout as
- * the turn-end hook does, prepares it when no run of that capture is under way or done (it never widens a run to a crawl), and
- * prints the run's brief. Exit codes: 0 with a brief, 2 when the run ended without one, 3 onboarding blocked, 1 otherwise. */
-export async function preVerifyCommand(options) {
-    const note = (line) => { if (options.json)
-        console.error(line);
-    else
-        console.log(line); };
-    const capture = await captureCheckout(Date.now() + EXPLICIT_WALL_MS, 'prepare', repositoryOverride(options.repo));
-    const request = capture.derivation.request;
-    const change = checkedChange(request.baseCommit, request.workCommit);
-    const finish = (onboarding, view, captured = null) => {
-        if (options.json)
-            process.stdout.write(`${JSON.stringify(withSchema('pre-verify', { change, onboarding,
-                run: view === null ? null : { runId: view.runId, status: view.status }, brief: view === null ? null : briefOf(view), capture: captured }), null, 2)}\n`);
-    };
-    if (!request.crawl) {
-        note(`Nothing to check: this checkout has no changes against ${request.baseCommit.slice(0, 12)}.`);
-        finish(null, null);
-        return;
-    }
-    note(checkedLine(change));
-    const identity = { repository: `${request.owner}/${request.repository}`, baseCommit: request.baseCommit,
-        workCommit: request.workCommit, treeSha: request.crawl.treeSha, changeTitle: request.crawl.changeTitle, budgetMs: request.crawl.budgetMs ?? null };
-    const auth = await resolveAuthContext({ preferredLogin: options.account, owner: request.owner, repo: request.repository });
-    let view = await readWithRetries(() => readCrawl(identity, auth.token));
+/** The handshake's question, asked after everything it shows. */
+/** The command to steer with; it keeps the options the handshake was given that choose the crawl (where, and for how long). */
+export function steerCommand(options) {
+    const kept = [options.repo ? ` --repo ${options.repo}` : '', options.account ? ` --account ${options.account}` : '',
+        options.minutes ? ` --minutes ${options.minutes}` : ''].join('');
+    return `haystack verify${kept} --intent "<what you were asked to do>" --idea "<something to try>" [--idea ...]`;
+}
+const steerLines = (command) => ['',
+    'Next: pick the ideas worth trying, add your own, and say what you were asked to do (the task in the user\'s words, not what your code does):',
+    `  ${command}`, 'Your ideas are explored first; the ideas above are explored in every crawl too.'];
+/** The handshake (Akshay, 10/7): a plain `haystack verify` on a change no crawl has started for shows what the change touches,
+ * how production and real users run it, and Haystack's own ideas, then asks the coding agent to run `haystack verify` again
+ * with --intent (and any --idea). It submits the capture in mode 'prepare' when no run of it is preparing, prepared or
+ * crawling, which never starts or narrows a crawl (CRAWL-V1 amendment 12); the steered crawl adopts that run's prepared start
+ * (amendment 17). Exit 4: the agent's steering is needed. */
+async function handshake(capture, identity, change, found, stale, token, options, note) {
+    let view = found;
     let onboarding = null;
-    const stale = view === null ? null : staleCrawl(view, identity);
-    // A run of this capture that is preparing, prepared or crawling holds (or will hold) the brief; any other is asked for again,
-    // in mode 'prepare' (amendment 12: that never narrows a crawl).
+    const finish = (brief, captured) => {
+        printVerifyJson(options, change, onboarding, null, {
+            run: view === null ? null : { runId: view.runId, status: view.status }, brief, capture: captured, next: steerCommand(options),
+        });
+    };
     if (view === null || (stale !== null && stale !== 'prepare-only')) {
-        const found = view === null || stale === null ? null : { view, stale };
-        let submitted = await submitCapture(capture, auth.token, found);
+        const prior = view === null || stale === null ? null : { view, stale };
+        let submitted = await submitCapture(capture, token, prior);
         note(submitted.line);
         if (submitted.onboarding !== null) {
-            onboarding = await readWithRetries(() => readOnboardingStatus(identity.repository, identity.baseCommit, auth.token));
+            onboarding = await readWithRetries(() => readOnboardingStatus(identity.repository, identity.baseCommit, token));
             reportOnboardingState(onboarding);
             if (options.wait !== false && onboarding.state === 'onboarding') {
-                onboarding = await waitForOnboarding(onboarding, auth.token, progress, 'haystack pre-verify');
+                onboarding = await waitForOnboarding(onboarding, token, progress, 'haystack verify');
                 reportOnboardingState(onboarding);
             }
             if (onboarding.state !== 'ready') {
-                if (options.json)
-                    finish(onboarding, null);
-                else
-                    console.log(formatOnboarding(onboarding));
-                process.exitCode = onboardingExitCode(onboarding);
+                finishWithOnboarding(onboarding, options, change);
                 return;
             }
             note(readyLine(onboarding));
-            submitted = await submitCapture(capture, auth.token, found);
+            submitted = await submitCapture(capture, token, prior);
             note(submitted.line);
         }
         if (submitted.runId === null) {
-            finish(onboarding, null);
+            if (options.json || options.raw)
+                printVerifyJson(options, change, onboarding, null);
             process.exitCode = 1;
             return;
         }
         const runId = submitted.runId;
-        view = await readWithRetries(() => readCrawlRun(runId, identity, auth.token));
+        view = await readWithRetries(() => readCrawlRun(runId, identity, token));
     }
+    if (view === null)
+        throw new Error('No run of this change to read its brief from.');
     if (options.wait !== false && briefOf(view) === null && !TERMINAL.has(reportedStatus(view)))
-        view = await waitForBrief(view, identity, auth.token);
+        view = await waitForBrief(view, identity, token);
     const brief = briefOf(view);
     // CAPTURE-V1 rule 7b: the routes the change touches, with their share of captured sessions, per app; null without capture set up.
-    const captured = await readPreVerifyCapture(findGitRoot(), identity.repository, auth.token, [...new Set([...(brief?.functions.map(fn => fn.file) ?? []), ...change.files])], new Date());
-    if (options.json)
-        finish(onboarding, view, captured);
-    else if (brief !== null)
+    const captured = await readPreVerifyCapture(findGitRoot(), identity.repository, token, [...new Set([...(brief?.functions.map(fn => fn.file) ?? []), ...change.files])], new Date());
+    process.exitCode = 4;
+    if (options.json || options.raw) {
+        finish(brief, captured);
+        return;
+    }
+    if (brief !== null)
         console.log(formatBrief(brief));
-    else if (!TERMINAL.has(reportedStatus(view)))
-        console.log(`The brief is not ready yet: ${currentStep(view)}. Run \`haystack pre-verify\` again to see it.`);
-    // What gets a brief now depends on how the run ended (Bugbot): a `prepared` one is crawled by `haystack verify`, whose answers
-    // carry it; a completed one is never run again, so only a new capture (any edit) is prepared afresh; an incomplete or cancelled
-    // one is asked for again by the next pre-verify.
-    else
-        console.log(`Run ${view.runId} ended (${view.status}) without a brief${view.error ? `: ${errorWords(view.error)}` : ''}. `
-            + (view.status === 'prepared' ? 'Run `haystack verify` to crawl the change; its results carry the brief.'
-                : view.status === 'completed' ? 'It was checked before briefs existed and is not run again: change anything in the checkout and run `haystack pre-verify` again.'
-                    : 'Run `haystack pre-verify` again to prepare it again.'));
-    if (!options.json && captured !== null)
+    else if (!TERMINAL.has(reportedStatus(view))) {
+        console.log(`What your change touches is not worked out yet (${currentStep(view)}); run \`haystack verify\` again to see it, or steer now.`);
+    }
+    else {
+        console.log(`Run ${view.runId} ended (${view.status}) without a brief${view.error ? `: ${errorWords(view.error)}` : ''}; steer the crawl without one.`);
+    }
+    if (captured !== null)
         for (const section of captured)
             console.log(`\n${formatCapture(section)}`);
-    if (!options.json && brief !== null)
-        console.log(STEER_LINES.join('\n'));
-    if (brief === null && TERMINAL.has(reportedStatus(view)))
-        process.exitCode = 2;
+    console.log(steerLines(steerCommand(options)).join('\n'));
 }
 /** verify's one JSON document: the report (`--json`) or the service's whole record (`--raw`). */
-function printVerifyJson(options, change, onboarding, view) {
+function printVerifyJson(options, change, onboarding, view, handshake) {
+    const extra = handshake === undefined ? {} : { handshake };
     const document = options.raw
-        ? withSchema('verify-raw', { change, onboarding, crawl: view })
-        : withSchema('verify', { change, onboarding, crawl: view === null ? null : verifyReport(view) });
+        ? withSchema('verify-raw', { change, onboarding, crawl: view, ...extra })
+        : withSchema('verify', { change, onboarding, crawl: view === null ? null : verifyReport(view), ...extra });
     process.stdout.write(`${JSON.stringify(document, null, 2)}\n`);
 }
 export async function verifyCommand(options) {
@@ -943,7 +936,12 @@ export async function verifyCommand(options) {
     else
         console.log(line); };
     const agent = agentDirection(options);
-    const capture = await captureCheckout(Date.now() + EXPLICIT_WALL_MS, 'crawl', repositoryOverride(options.repo), minutesOption(options.minutes), poolOption(options.pool), agent);
+    if (agent.intent === undefined && agent.ideas !== undefined) {
+        throw new Error('Say what you were asked to do with --intent "<the task, in the user\'s words>" alongside --idea.');
+    }
+    // Only a steered call (--intent) starts a crawl; a plain one prepares at most (the handshake).
+    const steered = agent.intent !== undefined;
+    const capture = await captureCheckout(Date.now() + EXPLICIT_WALL_MS, steered ? 'crawl' : 'prepare', repositoryOverride(options.repo), minutesOption(options.minutes), poolOption(options.pool), agent);
     const request = capture.derivation.request;
     const change = checkedChange(request.baseCommit, request.workCommit);
     if (!request.crawl) {
@@ -953,9 +951,6 @@ export async function verifyCommand(options) {
         return;
     }
     note(checkedLine(change));
-    // Measured: a 3-minute crawl answered 13 minutes after the command started (building and preparing both apps).
-    note('A crawl often takes 10 to 15 minutes. If this command times out or is stopped, the crawl keeps going:'
-        + ' run `haystack verify` again to pick up the same crawl.');
     const identity = {
         repository: `${request.owner}/${request.repository}`,
         baseCommit: request.baseCommit,
@@ -969,9 +964,19 @@ export async function verifyCommand(options) {
     let view = await readWithRetries(() => readCrawl(identity, auth.token));
     let onboarding = null;
     const stale = view === null ? null : staleCrawl(view, identity);
-    // A pinned pool (amendment 16), an intent or ideas (amendment 17) make their own crawl, which the capture read cannot tell
-    // apart: always submit, and follow that run (the same ones again are the same run).
-    if (view === null || stale !== null || options.pool !== undefined || agent.intent !== undefined || agent.ideas !== undefined) {
+    // A plain call on a change no crawl has started for (none, or only prepared, or one that ended without finishing) is the
+    // handshake; on a change with a crawl, it shows that crawl (picking it up again after a timeout).
+    const step = verifyStep(steered, view, stale);
+    if (step === 'handshake') {
+        await handshake(capture, identity, change, view, stale, auth.token, options, note);
+        return;
+    }
+    // Measured: a 3-minute crawl answered 13 minutes after the command started (building and preparing both apps).
+    note('A crawl often takes 10 to 15 minutes. If this command times out or is stopped, the crawl keeps going:'
+        + ' run the same `haystack verify` again to pick up the same crawl.');
+    // An intent and ideas (amendment 17), or a pinned pool (amendment 16), make their own crawl, which the capture read cannot tell
+    // apart: a steered call always submits, and follows that run (the same ones again are the same run).
+    if (step === 'submit') {
         const found = view === null || stale === null ? null : { view, stale };
         let submitted = await submitCapture(capture, auth.token, found);
         note(submitted.line);
@@ -1004,6 +1009,9 @@ export async function verifyCommand(options) {
             note('The service did not run it again; its last result follows.');
         }
     }
+    // A plain call reaches here only with a crawl of this change to show; a steered one has just read the run it submitted.
+    if (view === null)
+        throw new Error('No crawl of this change to show.');
     if (options.wait !== false && !TERMINAL.has(reportedStatus(view))) {
         view = await waitForCrawl(view, identity, auth.token);
     }

package/dist/index.js

@@ -32,7 +32,6 @@ const telemetryTokenCommand = lazy(() => import('./commands/telemetry-token.js')
 const schemaCommand = lazy(() => import('./commands/schema-cmd.js'), 'schemaCommand');
 const listSchemas = lazy(() => import('./commands/schema-cmd.js'), 'listSchemas');
 const verifyCommand = lazy(() => import('./commands/verify.js'), 'verifyCommand');
-const preVerifyCommand = lazy(() => import('./commands/verify.js'), 'preVerifyCommand');
 const headlessLoginCommand = lazy(() => import('./commands/tokens.js'), 'headlessLoginCommand');
 const headlessLogoutCommand = lazy(() => import('./commands/tokens.js'), 'headlessLogoutCommand');
 const listTokensCommand = lazy(() => import('./commands/tokens.js'), 'listTokensCommand');
@@ -163,7 +162,7 @@ Examples:
     .action(options => runPublicCommand(() => initCommand(options), options.json));
 const verify = program
     .command('verify')
-    .description('Crawl the running app with your current change: where it shows up and what broke')
+    .description('Check your change: first what it touches and what could break, then (with --intent) explore the app with and without it')
     .option('--repo <owner/repo>', 'GitHub repository (default: origin remote)')
     .option('--account <login>', 'Use a specific saved Haystack account')
     .option('--no-wait', 'Print the crawl\'s current state and return without waiting')
@@ -175,21 +174,25 @@ const verify = program
     .option('--json', 'The report as one JSON document on stdout (see `haystack schema verify`)')
     .option('--raw', 'The service\'s whole crawl record as one JSON document, for scripts (large; see `haystack schema verify-raw`)')
     .addHelpText('after', `
-Run inside a git checkout; nothing needs to be committed or pushed. It captures
-the checkout (committed and uncommitted changes) exactly as the stop hook does,
-with the base at the merge base of HEAD and origin's default branch, and finds
-your crawl of that exact capture: the same code and the same change title (the
-title tells the crawl's judge what the change is). When there is none, or the
-one it finds was cancelled, stopped before finishing or is being cancelled, it
-submits the capture (the service starts the crawl, or runs the stopped one
-again), says so, and follows that crawl. When the stop hook already built and
-froze this change, the crawl starts from that instead of building it again.
+Two calls, run inside a git checkout (nothing needs to be committed or pushed):
 
-The coding agent that made the change can say what it was asked to do (--intent:
-the task in the user's words, not a description of its code) and what to try (--idea, as many as it likes, or --ideas-file). Each idea is
-explored before anything else, and the answer says what became of it: tried,
-could not try (and why), or not finished in time. Other ideas make another
-crawl of the same code; the same ones again follow the same crawl.
+  1. haystack verify
+     The handshake. It shows what your change touches, how production and real
+     users run it, and Haystack's own ideas of what could break, then asks what
+     you were asked to do and what to try. It builds and prepares the change if
+     the stop hook has not, and never starts a crawl. Exit 4.
+  2. haystack verify --intent "<the task, in the user's words>" --idea "<something to try>"
+     The crawl, steered: your ideas (--idea, repeat for more, or --ideas-file)
+     are explored before anything else, and the judge checks the app against
+     your intent. It starts from the app the stop hook or step 1 prepared.
+
+Both capture the checkout (committed and uncommitted changes) exactly as the
+stop hook does, with the base at the merge base of HEAD and origin's default
+branch. A plain call on a change that already has a crawl shows that crawl
+instead of shaking hands again, so after a timeout either call picks up the
+same crawl. Other ideas make another crawl of the same code; the same ones
+again follow the same crawl, and the answer says what became of each idea:
+tried, could not try (and why), or not finished in time.
 
 A crawl builds the app with and without your change, starts from the changed
 code, explores outward with both side by side, and double-checks and judges
@@ -219,11 +222,13 @@ Exit codes:
      or the machines it used could not be proven shut down; or onboarding
      stopped before finishing
   3  onboarding is blocked: the output says what would unblock it
+  4  the handshake: run it again with --intent (and any --idea)
 
 The hosted fleet run of pushed commits is \`haystack verify hosted start\`.
 
 Examples:
   haystack verify
+  haystack verify --intent "Let users pay with a saved card" --idea "Pay with an expired saved card"
   haystack verify --no-wait
   haystack verify --minutes 10
   haystack verify --json
@@ -231,31 +236,6 @@ Examples:
   haystack verify hosted status cv_<48 lowercase hex characters> --wait
 `)
     .action(options => runPublicCommand(() => verifyCommand(options), options.json || options.raw));
-program
-    .command('pre-verify')
-    .description('Before a check: what your change touches, and what could break in it')
-    .option('--repo <owner/repo>', 'GitHub repository (default: origin remote)')
-    .option('--account <login>', 'Use a specific saved Haystack account')
-    .option('--no-wait', 'Print what is known now and return without waiting for the brief')
-    .option('--json', 'The brief as one JSON document on stdout (see `haystack schema pre-verify`)')
-    .addHelpText('after', `
-Run inside a git checkout, like haystack verify. It captures the checkout the
-same way, builds and prepares the change when nothing has yet (the turn-end
-hook usually has), and prints its brief: the functions the change touches, the
-changed ones and those one step away first (every one is in --json), and
-Haystack's own ideas of what could break, each with what to set up, what to do
-and what to watch. With capture set up (an app's .haystack/capture.json, such
-as apps/web/.haystack/capture.json), it also shows, per app, the routes the
-change touches with their share of real users' sessions. It never starts a
-crawl.
-
-Then hand back what you were asked to do and what to try:
-  haystack verify --intent "<what you were asked to do, in the user's words>" --idea "<something to try>"
-
-Exit codes: 0 with a brief; 2 when the run ended without one; 3 when the app's
-onboarding is blocked; 1 when the command failed.
-`)
-    .action(options => runPublicCommand(() => preVerifyCommand(options), options.json));
 /**
  * Options for a `verify` subcommand: its own values, plus any option the user
  * passed to an ancestor (`haystack verify --no-wait hosted status ...`).

package/dist/schema.js

@@ -12,9 +12,8 @@
 export const SCHEMA_VERSIONS = {
     'cloud-verifier': '1.0.0',
     'case-batch': '1.0.1',
-    verify: '2.0.0',
-    'verify-raw': '1.0.0',
-    'pre-verify': '2.0.0',
+    verify: '2.1.0',
+    'verify-raw': '1.1.0',
     'verify-answer': '1.0.1',
     'verify-onboarding': '1.0.0',
     init: '1.0.2',

package/package.json

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