@haystackeditor/cli 0.18.0 → 0.20.0

package/dist/commands/login.js

@@ -2,12 +2,20 @@
  * Login command - GitHub OAuth device flow
  */
 import chalk from 'chalk';
+import * as fs from 'fs/promises';
 import * as path from 'path';
 import * as os from 'os';
+import { withSchema } from '../schema.js';
 import { getActiveLogin, getRepoDefaultAccount, listStoredAccounts, removeAccount, saveAuthenticatedToken, setActiveAccount, } from '../utils/auth.js';
 import { parseRemoteUrl } from '../utils/git.js';
 const GITHUB_CLIENT_ID = 'Ov23liW3JE38D3gZWa85'; // Haystack GitHub OAuth App
 const CONFIG_DIR = path.join(os.homedir(), '.haystack');
+// A started sign-in the next `haystack login` finishes. The device code in it is
+// a credential until GitHub expires it, so the file is 0600 like credentials.json.
+const PENDING_LOGIN_FILE = path.join(CONFIG_DIR, 'login-pending.json');
+// A pending sign-in this close to expiring is replaced rather than shown to a
+// person; one that is only being finished is used until it expires.
+const SHOWN_LOGIN_MARGIN_MS = 60_000;
 /**
  * Start device flow and get user code
  */
@@ -28,25 +36,79 @@ async function startDeviceFlow() {
     }
     return response.json();
 }
+async function readPendingLogin(marginMs) {
+    let raw;
+    try {
+        raw = await fs.readFile(PENDING_LOGIN_FILE, 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return null;
+        throw error;
+    }
+    const pending = JSON.parse(raw);
+    if (typeof pending.deviceCode !== 'string' || typeof pending.userCode !== 'string' || typeof pending.verificationUri !== 'string'
+        || typeof pending.interval !== 'number' || typeof pending.expiresAt !== 'number') {
+        throw new Error(`${PENDING_LOGIN_FILE} is not a sign-in this CLI started; delete it and run \`haystack login\` again.`);
+    }
+    return pending.expiresAt - Date.now() > marginMs ? pending : null;
+}
+async function savePendingLogin(flow) {
+    const pending = {
+        deviceCode: flow.device_code, userCode: flow.user_code, verificationUri: flow.verification_uri,
+        interval: flow.interval, expiresAt: Date.now() + flow.expires_in * 1000,
+    };
+    await fs.mkdir(CONFIG_DIR, { recursive: true });
+    await fs.writeFile(PENDING_LOGIN_FILE, `${JSON.stringify(pending, null, 2)}\n`, { mode: 0o600 });
+    await fs.chmod(PENDING_LOGIN_FILE, 0o600);
+    return pending;
+}
+async function clearPendingLogin() {
+    await fs.rm(PENDING_LOGIN_FILE, { force: true });
+}
+/** GitHub ended the device flow (expired, denied, or another OAuth error): its code is spent. */
+class DeviceFlowEnded extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'DeviceFlowEnded';
+    }
+}
 /**
- * Poll for access token
+ * Poll for access token. A request that does not reach GitHub, or an answer
+ * that is not GitHub's OAuth JSON, leaves the code usable: the next
+ * `haystack login` finishes with it.
  */
 async function pollForToken(deviceCode, interval) {
+    const unreachable = (detail) => new Error(`Could not get GitHub's answer (${detail}). Run \`haystack login\` again; it continues with the same code.`);
     for (;;) {
         await new Promise(resolve => setTimeout(resolve, interval * 1000));
-        const response = await fetch('https://github.com/login/oauth/access_token', {
-            method: 'POST',
-            headers: {
-                'Accept': 'application/json',
-                'Content-Type': 'application/json',
-            },
-            body: JSON.stringify({
-                client_id: GITHUB_CLIENT_ID,
-                device_code: deviceCode,
-                grant_type: 'urn:ietf:params:oauth:grant-type:device_code',
-            }),
-        });
-        const data = await response.json();
+        let response;
+        try {
+            response = await fetch('https://github.com/login/oauth/access_token', {
+                method: 'POST',
+                headers: {
+                    'Accept': 'application/json',
+                    'Content-Type': 'application/json',
+                },
+                body: JSON.stringify({
+                    client_id: GITHUB_CLIENT_ID,
+                    device_code: deviceCode,
+                    grant_type: 'urn:ietf:params:oauth:grant-type:device_code',
+                }),
+            });
+        }
+        catch (error) {
+            throw unreachable(error instanceof Error ? error.message : String(error));
+        }
+        if (!response.ok)
+            throw unreachable(`HTTP ${response.status}`);
+        let data;
+        try {
+            data = await response.json();
+        }
+        catch (error) {
+            throw unreachable(`an answer that is not JSON: ${error instanceof Error ? error.message : String(error)}`);
+        }
         if (data.access_token) {
             return data.access_token;
         }
@@ -60,38 +122,75 @@ async function pollForToken(deviceCode, interval) {
             continue;
         }
         if (data.error === 'expired_token') {
-            throw new Error('Authorization timed out. Please try again.');
+            throw new DeviceFlowEnded('Authorization timed out. Please try again.');
         }
         if (data.error === 'access_denied') {
-            throw new Error('Authorization denied by user.');
+            throw new DeviceFlowEnded('Authorization denied by user.');
         }
-        throw new Error(`OAuth error: ${data.error}`);
+        throw new DeviceFlowEnded(`OAuth error: ${data.error}`);
     }
 }
-export async function loginCommand() {
+/**
+ * `haystack login`: GitHub's device flow. It prints a URL and a code for the
+ * person to enter, then waits until they have. `--no-wait` prints them and
+ * returns at once, so a coding agent can show them before it runs
+ * `haystack login` again to finish; a run that is stopped while waiting is
+ * finished the same way, with the same code, until GitHub expires it.
+ */
+export async function loginCommand(options = {}) {
+    // In --json mode stdout carries the one document; every other line goes to stderr.
+    const say = (line) => { if (options.json)
+        console.error(line);
+    else
+        console.log(line); };
     try {
-        console.log(chalk.bold('\nHaystack Login\n'));
+        say(chalk.bold('\nHaystack Login\n'));
         const activeLogin = await getActiveLogin();
         if (activeLogin) {
-            console.log(chalk.dim(`Current active account: ${chalk.bold(activeLogin)}`));
-            console.log(chalk.dim('This login will add or refresh a saved account and make it active.\n'));
-        }
-        console.log('Authenticating with GitHub...\n');
-        // Start device flow
-        const deviceFlow = await startDeviceFlow();
-        console.log(chalk.yellow('Open this URL in your browser:\n'));
-        console.log(`  ${chalk.bold(deviceFlow.verification_uri)}\n`);
-        console.log(chalk.yellow('And enter this code:\n'));
-        console.log(`  ${chalk.bold.cyan(deviceFlow.user_code)}\n`);
-        console.log(chalk.dim('Waiting for authorization...'));
-        // Poll for token
-        const token = await pollForToken(deviceFlow.device_code, deviceFlow.interval);
+            say(chalk.dim(`Current active account: ${chalk.bold(activeLogin)}`));
+            say(chalk.dim('This login will add or refresh a saved account and make it active.\n'));
+        }
+        const pending = await readPendingLogin(options.wait === false ? SHOWN_LOGIN_MARGIN_MS : 0)
+            ?? await savePendingLogin(await startDeviceFlow());
+        say(chalk.yellow('Open this URL in your browser:\n'));
+        say(`  ${chalk.bold(pending.verificationUri)}\n`);
+        say(chalk.yellow('And enter this code:\n'));
+        say(`  ${chalk.bold.cyan(pending.userCode)}\n`);
+        if (options.wait === false) {
+            say('Run `haystack login` once the code is entered; it finishes signing in.');
+            if (options.json) {
+                process.stdout.write(`${JSON.stringify(withSchema('login', {
+                    status: 'pending', verificationUri: pending.verificationUri, userCode: pending.userCode,
+                    expiresAt: new Date(pending.expiresAt).toISOString(), login: null,
+                }), null, 2)}\n`);
+            }
+            return;
+        }
+        say(chalk.dim('Waiting for authorization...'));
+        let token;
+        try {
+            token = await pollForToken(pending.deviceCode, pending.interval);
+        }
+        catch (error) {
+            // Expired or denied: the code is spent, so the next login starts afresh.
+            if (error instanceof DeviceFlowEnded)
+                await clearPendingLogin();
+            throw error;
+        }
+        await clearPendingLogin();
         // Verify and save
         const user = await saveAuthenticatedToken(token);
-        console.log(chalk.green(`\nLogged in as ${chalk.bold(user.login)}`));
-        console.log(chalk.dim(`Credentials saved to ${path.join(CONFIG_DIR, 'credentials.json')}\n`));
+        say(chalk.green(`\nLogged in as ${chalk.bold(user.login)}`));
+        say(chalk.dim(`Credentials saved to ${path.join(CONFIG_DIR, 'credentials.json')}\n`));
+        if (options.json) {
+            process.stdout.write(`${JSON.stringify(withSchema('login', {
+                status: 'logged-in', verificationUri: null, userCode: null, expiresAt: null, login: user.login,
+            }), null, 2)}\n`);
+        }
     }
     catch (error) {
+        if (options.json)
+            process.stdout.write(`${JSON.stringify(withSchema('error', { status: 'error', error: `Login failed: ${error.message}` }), null, 2)}\n`);
         console.error(chalk.red(`\nLogin failed: ${error.message}\n`));
         process.exit(1);
     }

package/dist/commands/onboarding-contract.js

@@ -0,0 +1,6 @@
+/** FIXED CONTRACT — mirror of APP-ONBOARDING-V1
+ * (infra/lambda/haystack-design-verifier-shared/onboarding_contracts.ts) for the
+ * published CLI, whose build cannot import repository files outside src. Only
+ * the shapes the CLI reads or sends are mirrored; the source file wins. */
+export const ONBOARDING_VERSION = 'app-onboarding-v1';
+export const ONBOARDING_STAGES = ['inventory', 'plan', 'runtime', 'boot', 'data', 'accounts', 'workflow', 'publish', 'cleanup'];

package/dist/commands/precompute-delivery.js

@@ -3,7 +3,7 @@ import { createHash, randomUUID } from 'node:crypto';
 import { closeSync, constants, fchmodSync, fstatSync, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync, } from 'node:fs';
 import { basename, dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { CRAWL_TITLE_MAX_CHARS } from './crawl-contract.js';
+import { CRAWL_BUDGET_MAX_MS, CRAWL_BUDGET_MIN_MS, CRAWL_TITLE_MAX_CHARS } from './crawl-contract.js';
 const requestFile = 'request.json';
 const receiptFile = 'receipt.json';
 const deliverySchema = 'precompute-delivery-v1';
@@ -150,10 +150,13 @@ function validateRequest(value) {
             throw new Error('Invalid captured crawl submission.');
         return;
     }
-    if (!object(crawl) || !onlyKeys(crawl, ['treeSha', 'changeTitle'])
+    // Amendment 8: budgetMs only when the capture asked for a time, whole seconds from 1 to 30 minutes.
+    if (!object(crawl) || !onlyKeys(crawl, 'budgetMs' in crawl ? ['treeSha', 'changeTitle', 'budgetMs'] : ['treeSha', 'changeTitle'])
         || !characters(crawl.treeSha, '0123456789abcdef', 40)
         || request.cacheKey.split('-')[2] !== crawl.treeSha.slice(0, 16)
-        || typeof crawl.changeTitle !== 'string' || crawl.changeTitle.length > CRAWL_TITLE_MAX_CHARS) {
+        || typeof crawl.changeTitle !== 'string' || crawl.changeTitle.length > CRAWL_TITLE_MAX_CHARS
+        || ('budgetMs' in crawl && (typeof crawl.budgetMs !== 'number' || !Number.isInteger(crawl.budgetMs) || crawl.budgetMs % 1000 !== 0
+            || crawl.budgetMs < CRAWL_BUDGET_MIN_MS || crawl.budgetMs > CRAWL_BUDGET_MAX_MS))) {
         throw new Error('Invalid captured crawl submission.');
     }
 }

package/dist/commands/setup.js

@@ -16,6 +16,7 @@ import { execFileSync, execSync } from 'child_process';
 import { basename } from 'path';
 import { resolveAuthContext } from '../utils/auth.js';
 import { githubRestBaseFor } from '../utils/github-api.js';
+import { HAYSTACK_APP_INSTALL_URL } from '../utils/haystack-api.js';
 import { describeHookOverwrites, hooksInstall } from './hooks.js';
 import { installSessionHooks } from './install-session-hooks.js';
 import { findGitRoot } from '../utils/hooks.js';
@@ -500,8 +501,6 @@ function printInstruction(instruction, index) {
 // =============================================================================
 // Step 0.5: Ensure the Haystack GitHub App is installed
 // =============================================================================
-const HAYSTACK_APP_SLUG = 'haystack-code-reviewer-pr-hook';
-const HAYSTACK_APP_INSTALL_URL = `https://github.com/apps/${HAYSTACK_APP_SLUG}/installations/new`;
 const APP_INSTALL_POLL_INTERVAL_MS = 3000;
 const APP_INSTALL_TIMEOUT_MS = 10 * 60 * 1000;
 class InstallationsAuthError extends Error {

package/dist/commands/verify-onboarding.js

@@ -0,0 +1,365 @@
+/**
+ * App onboarding as `haystack verify` shows it (APP-ONBOARDING-V1 rule 12,
+ * crawl amendment 8). A repository base without a published onboarding record
+ * answers the crawl submission `onboarding` (the service prepares the app and
+ * runs the crawl when it is ready) or `onboarding-blocked` (with what would
+ * unblock it). This module reads and prints the onboarding status, the stage
+ * list, the block and its ask, and files an answer to a question
+ * (`haystack verify answer <id> <choice>`).
+ */
+import chalk from 'chalk';
+import { withSchema } from '../schema.js';
+import { resolveAuthContext } from '../utils/auth.js';
+import { classifyHttpError, HaystackApiError } from '../utils/haystack-api.js';
+import { trackOnboardingEvent } from '../utils/telemetry.js';
+import { gatewayFetch } from './case-batch.js';
+import { ONBOARDING_STAGES, ONBOARDING_VERSION, } from './onboarding-contract.js';
+import { deriveBaseSha, EXPLICIT_WALL_MS, resolveOriginRepository } from './verify-precompute.js';
+import { findGitRoot } from '../utils/hooks.js';
+const ONBOARDING_PATH = '/api/agent/cloud-verifier/onboarding';
+const FACTS_PATH = `${ONBOARDING_PATH}/facts`;
+const ANSWERS_PATH = `${ONBOARDING_PATH}/answers`;
+const ONBOARD_RUN_ID = /^ob_[0-9a-f]{48}$/;
+const SHA256 = /^[0-9a-f]{64}$/;
+const COMMIT = /^[0-9a-f]{40}$/;
+const STATES = ['ready', 'onboarding', 'blocked', 'incomplete', 'cancelled', 'not-started'];
+const BLOCK_KINDS = ['not-enabled', 'no-web-app', 'unsupported', 'question', 'outside-credential',
+    'outside-dependency', 'evidence-too-large', 'budget', 'proof-failed'];
+const STAGE_STATUSES = ['pending', 'running', 'ok', 'reused', 'failed', 'blocked'];
+const STAGE_WORDS = {
+    inventory: 'reading the repository', plan: 'planning how to run the app', runtime: 'building its runtime',
+    boot: 'starting the app', data: 'preparing its data', accounts: 'creating test accounts', workflow: 'proving a workflow',
+    publish: 'publishing', cleanup: 'cleaning up',
+};
+const BLOCK_WORDS = {
+    'not-enabled': 'onboarding is not enabled for this team yet',
+    'no-web-app': 'no web app was found in the repository',
+    unsupported: 'the app uses something onboarding cannot run yet',
+    question: 'onboarding needs an answer',
+    'outside-credential': 'the app needs an outside provider\'s credential',
+    'outside-dependency': 'the app needs an outside service',
+    'evidence-too-large': 'the repository evidence is too large for one planning request',
+    budget: 'onboarding used its model or repair budget',
+    'proof-failed': 'the app could not be proven to work',
+};
+/** A response the CLI will not print: malformed or another repository's. */
+export class OnboardingResponseError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'OnboardingResponseError';
+    }
+}
+function invalid(what) {
+    throw new OnboardingResponseError(`The onboarding service returned an invalid answer (${what}); nothing is shown.`);
+}
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function isStrings(value) {
+    return Array.isArray(value) && value.every(item => typeof item === 'string');
+}
+function safe(value) {
+    // Server text never moves the cursor or rewrites the terminal.
+    // eslint-disable-next-line no-control-regex -- replacing control characters is the point
+    return value.replace(/[\u0000-\u001f\u007f-\u009f]/g, ' ');
+}
+export function parseOnboardingBlock(value) {
+    if (!isRecord(value) || !BLOCK_KINDS.includes(value.kind)
+        || !(value.stage === 'admission' || ONBOARDING_STAGES.includes(value.stage))
+        || typeof value.reason !== 'string' || !isStrings(value.evidence)
+        || (value.names !== undefined && !isStrings(value.names)))
+        invalid('a block');
+    const ask = value.ask;
+    if (ask !== null) {
+        if (!isRecord(ask) || typeof ask.message !== 'string' || (ask.command !== undefined && typeof ask.command !== 'string'))
+            invalid('a block\'s ask');
+        const question = ask.question;
+        if (question !== undefined && (!isRecord(question) || typeof question.id !== 'string' || !isStrings(question.choices))) {
+            invalid('a block\'s question');
+        }
+    }
+    return value;
+}
+/** Accepts only a well-formed status of exactly this repository and base. */
+export function parseOnboardingStatus(value, expected) {
+    if (!isRecord(value) || value.version !== ONBOARDING_VERSION || value.repository !== expected.repository
+        || value.baseCommit !== expected.baseCommit || !STATES.includes(value.state))
+        invalid('its identity');
+    if (value.onboardRunId !== null && !(typeof value.onboardRunId === 'string' && ONBOARD_RUN_ID.test(value.onboardRunId)))
+        invalid('its run id');
+    if (value.recordDigest !== null && !(typeof value.recordDigest === 'string' && SHA256.test(value.recordDigest)))
+        invalid('its record');
+    if (!isStrings(value.dataAbsences))
+        invalid('its data absences');
+    if (!isStrings(value.versionChoices))
+        invalid('its version choices');
+    if (value.block !== null)
+        parseOnboardingBlock(value.block);
+    const checkpoint = value.checkpoint;
+    if (checkpoint !== null) {
+        if (!isRecord(checkpoint) || !ONBOARDING_STAGES.includes(checkpoint.stage) || !isRecord(checkpoint.execution)
+            || !Array.isArray(checkpoint.execution.stages))
+            invalid('its checkpoint');
+        for (const stage of checkpoint.execution.stages) {
+            if (!isRecord(stage) || !ONBOARDING_STAGES.includes(stage.stage)
+                || !STAGE_STATUSES.includes(stage.status))
+                invalid('its stage list');
+        }
+    }
+    if ((value.state === 'blocked') !== (value.block !== null))
+        invalid('its block');
+    if ((value.state === 'ready') !== (value.recordDigest !== null))
+        invalid('its record');
+    return value;
+}
+function parseFactsView(value, repository) {
+    if (!isRecord(value) || value.repository !== repository || typeof value.factsDigest !== 'string' || !SHA256.test(value.factsDigest)
+        || !isRecord(value.facts) || !Array.isArray(value.openQuestions))
+        invalid('the facts');
+    for (const question of value.openQuestions) {
+        if (!isRecord(question) || typeof question.id !== 'string' || typeof question.message !== 'string' || !isStrings(question.choices)) {
+            invalid('an open question');
+        }
+    }
+    return value;
+}
+async function body(response, what) {
+    try {
+        return await response.json();
+    }
+    catch (error) {
+        throw new OnboardingResponseError(`The onboarding service returned ${what} that is not JSON: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+/** The onboarding of `repository` at `baseCommit`, now. */
+export async function readOnboardingStatus(repository, baseCommit, token) {
+    if (!COMMIT.test(baseCommit))
+        throw new Error(`Invalid base commit ${baseCommit}.`);
+    const path = `${ONBOARDING_PATH}?repository=${encodeURIComponent(repository)}&baseCommit=${baseCommit}`;
+    const response = await gatewayFetch(path, token);
+    if (!response.ok)
+        throw await classifyHttpError(response, `Haystack API ${ONBOARDING_PATH}`);
+    return parseOnboardingStatus(await body(response, 'a status'), { repository, baseCommit });
+}
+/** Rule 12's start POST: onboard this base now, before any change exists. Idempotent: a
+ * ready, blocked or running onboarding is answered as it is. */
+export async function startOnboarding(repository, baseCommit, token) {
+    if (!COMMIT.test(baseCommit))
+        throw new Error(`Invalid base commit ${baseCommit}.`);
+    const response = await gatewayFetch(`${ONBOARDING_PATH}?repository=${encodeURIComponent(repository)}`, token, {
+        method: 'POST', body: JSON.stringify({ repository, baseCommit }),
+    });
+    if (!response.ok)
+        throw await classifyHttpError(response, `Haystack API ${ONBOARDING_PATH}`);
+    return parseOnboardingStatus(await body(response, 'a status'), { repository, baseCommit });
+}
+/** How often a command reads onboarding status while it runs. The status route holds no read (a crawl's reads wait for a
+ * change, amendment 9); an onboarding takes tens of minutes, so a read every 15 s shows each stage promptly. */
+const ONBOARDING_READ_EVERY_MS = 15_000;
+const delay = (ms) => new Promise(resolve => setTimeout(resolve, ms));
+/** Polls the base's onboarding until it is no longer running. No wall-time cap:
+ * an interrupt stops waiting and leaves the onboarding running (`resume` is the
+ * command that follows it again). A momentary 429/5xx (a server or runner
+ * restarting) is read again at the next poll. */
+export async function waitForOnboarding(first, token, progress, resume) {
+    const interrupted = () => {
+        console.error(`\nStopped waiting. The onboarding keeps running; run \`${resume}\` again to follow it.`);
+        process.exit(130);
+    };
+    process.once('SIGINT', interrupted);
+    try {
+        let status = first;
+        progress(`Waiting for onboarding ${status.onboardRunId ?? ''} (Ctrl-C stops waiting; the onboarding keeps running).`);
+        progress(onboardingStep(status));
+        while (status.state === 'onboarding') {
+            await delay(ONBOARDING_READ_EVERY_MS);
+            let next;
+            try {
+                next = await readOnboardingStatus(status.repository, status.baseCommit, token);
+            }
+            catch (error) {
+                if (!(error instanceof HaystackApiError && [429, 502, 503, 504].includes(error.status)))
+                    throw error;
+                progress(`The onboarding status is unavailable for now (${error.status}); reading it again.`);
+                continue;
+            }
+            if (onboardingStep(next) !== onboardingStep(status))
+                progress(onboardingStep(next));
+            status = next;
+        }
+        return status;
+    }
+    finally {
+        process.removeListener('SIGINT', interrupted);
+    }
+}
+/** A command that answers with an onboarding exits 3 when it is blocked (its ask says what to do),
+ * 2 when it is neither running nor ready, and 0 when it is ready or running. */
+export function onboardingExitCode(status) {
+    if (status.state === 'blocked')
+        return 3;
+    if (status.state === 'incomplete' || status.state === 'cancelled' || status.state === 'not-started')
+        return 2;
+    return 0;
+}
+/* ----------------------------------------------------------------- output */
+/** What onboarding is doing now, in one line: the stage in progress and the stages done. */
+export function onboardingStep(status) {
+    const stages = status.checkpoint?.execution.stages ?? [];
+    const done = stages.filter(stage => stage.status === 'ok' || stage.status === 'reused').map(stage => stage.stage);
+    const current = status.checkpoint?.stage;
+    const doing = status.state !== 'onboarding' ? status.state
+        : current === undefined ? 'queued' : STAGE_WORDS[current];
+    return `Onboarding: ${doing}${done.length ? ` (done: ${done.join(', ')})` : ''}.`;
+}
+/** The stage list, one line per stage the run has reached. */
+export function onboardingStageLines(status) {
+    const stages = status.checkpoint?.execution.stages ?? [];
+    const byStage = new Map(stages.map(stage => [stage.stage, stage]));
+    return ONBOARDING_STAGES.filter(stage => byStage.has(stage)).map(stage => {
+        const entry = byStage.get(stage);
+        const repairs = entry.attempts.length ? `, ${entry.attempts.length} repair${entry.attempts.length === 1 ? '' : 's'}` : '';
+        return `  ${stage.padEnd(9)} ${entry.status}${repairs}`;
+    });
+}
+/** A block: why onboarding stopped and exactly what would unblock it. */
+export function blockLines(block) {
+    const lines = [chalk.bold(`Onboarding is blocked: ${BLOCK_WORDS[block.kind]}.`), `  ${safe(block.reason)}`];
+    if (block.names?.length)
+        lines.push(`  Names: ${block.names.map(safe).join(', ')}`);
+    if (block.ask === null) {
+        lines.push('  Nothing you can run changes this yet.');
+        return lines;
+    }
+    lines.push('', safe(block.ask.message));
+    if (block.ask.command)
+        lines.push(`  Run: ${safe(block.ask.command)}`);
+    const question = block.ask.question;
+    if (question) {
+        lines.push('  Answer with one of:');
+        for (const choice of question.choices)
+            lines.push(`    haystack verify answer ${question.id} ${JSON.stringify(choice)}`);
+        lines.push('  then run `haystack init` to continue onboarding with it.');
+    }
+    return lines;
+}
+export function formatOnboarding(status) {
+    const lines = [chalk.dim(`  Onboarding ${status.onboardRunId ?? '(none)'} of ${safe(status.repository)} at base ${status.baseCommit.slice(0, 12)}`)];
+    switch (status.state) {
+        case 'ready':
+            lines.push('The app is onboarded for this base.');
+            break;
+        case 'onboarding':
+            lines.push(onboardingStep(status));
+            break;
+        case 'not-started':
+            lines.push('Onboarding has not started for this base. `haystack init` starts it.');
+            break;
+        case 'incomplete':
+            lines.push(`Onboarding stopped before finishing${status.checkpoint?.error ? `: ${safe(status.checkpoint.error.message)}` : ''}.`
+                + ' Run `haystack init` again to continue it.');
+            break;
+        case 'cancelled':
+            lines.push('Onboarding was cancelled. Run `haystack init` to start it again.');
+            break;
+        case 'blocked': break;
+    }
+    const stages = onboardingStageLines(status);
+    if (stages.length)
+        lines.push('', ...stages);
+    if (status.block)
+        lines.push('', ...blockLines(status.block));
+    if (status.dataAbsences.length)
+        lines.push('', ...status.dataAbsences.map(absence => chalk.yellow(`Note: ${safe(absence)}`)));
+    if (status.versionChoices.length)
+        lines.push('', ...status.versionChoices.map(choice => chalk.yellow(`Note: ${safe(choice)}`)));
+    return lines.join('\n');
+}
+/** Telemetry: onboarding started, blocked or ready, once per state a command sees. */
+export function reportOnboardingState(status) {
+    if (status.state === 'onboarding')
+        trackOnboardingEvent('started');
+    else if (status.state === 'blocked')
+        trackOnboardingEvent('blocked', status.block?.kind);
+    else if (status.state === 'ready')
+        trackOnboardingEvent('ready');
+}
+function repositoryOf(value) {
+    if (value !== undefined) {
+        const parts = value.split('/');
+        if (parts.length !== 2 || !parts.every(part => /^[A-Za-z0-9_.-]{1,100}$/.test(part) && part !== '.' && part !== '..')) {
+            throw new Error(`Invalid repository "${value}". Use an exact GitHub owner/repository name.`);
+        }
+        return value;
+    }
+    const gitRoot = findGitRoot();
+    if (!gitRoot)
+        throw new Error('Run this command from a git repository, or pass --repo owner/repo.');
+    const origin = resolveOriginRepository(gitRoot);
+    return `${origin.owner}/${origin.repository}`;
+}
+async function readFacts(repository, token) {
+    const response = await gatewayFetch(`${FACTS_PATH}?repository=${encodeURIComponent(repository)}`, token);
+    if (!response.ok)
+        throw await classifyHttpError(response, `Haystack API ${FACTS_PATH}`);
+    return parseFactsView(await body(response, 'facts'), repository);
+}
+/** `haystack verify answer <question-id> <choice>`: files the answer to an open
+ * onboarding question with compare-and-swap on the facts it read; a concurrent
+ * change of the facts is read again (the question must still be open). */
+export async function verifyAnswerCommand(questionId, choice, options) {
+    const repository = repositoryOf(options.repo);
+    const [owner, repo] = repository.split('/');
+    const auth = await resolveAuthContext({ preferredLogin: options.account, owner, repo });
+    for (let attempt = 1;; attempt += 1) {
+        const facts = await readFacts(repository, auth.token);
+        const question = facts.openQuestions.find(open => open.id === questionId);
+        if (!question) {
+            throw new Error(`No open onboarding question of ${repository} has the id ${questionId}.`
+                + (facts.openQuestions.length ? ` Open: ${facts.openQuestions.map(open => open.id).join(', ')}.` : ' None is open.'));
+        }
+        if (!question.choices.includes(choice)) {
+            throw new Error(`"${choice}" is not one of the question's choices: ${question.choices.map(item => JSON.stringify(item)).join(', ')}.`);
+        }
+        const response = await gatewayFetch(`${ANSWERS_PATH}?repository=${encodeURIComponent(repository)}`, auth.token, {
+            method: 'POST', body: JSON.stringify({ repository, expectedFactsDigest: facts.factsDigest, questionId, answer: choice }),
+        });
+        if (response.status === 409 && attempt < 3) {
+            await response.body?.cancel();
+            continue;
+        }
+        if (!response.ok)
+            throw await classifyHttpError(response, `Haystack API ${ANSWERS_PATH}`);
+        const view = parseFactsView(await body(response, 'facts'), repository);
+        if (options.json) {
+            process.stdout.write(`${JSON.stringify(withSchema('verify-answer', { facts: view }), null, 2)}\n`);
+        }
+        else {
+            console.log(chalk.green(`Answered ${questionId}: ${safe(choice)}.`));
+            console.log('Run `haystack init` (or `haystack verify` after a change) to continue onboarding with it.');
+        }
+        return;
+    }
+}
+const clock = () => new Date().toTimeString().slice(0, 8);
+/** `haystack verify onboarding`: the onboarding of the base `haystack verify` would use for this
+ * checkout, read without starting anything; --wait follows it while it runs. */
+export async function verifyOnboardingCommand(options) {
+    const gitRoot = findGitRoot();
+    if (!gitRoot)
+        throw new Error('Run this command inside a checkout of the app.');
+    const origin = resolveOriginRepository(gitRoot);
+    const repository = `${origin.owner}/${origin.repository}`;
+    const auth = await resolveAuthContext({ preferredLogin: options.account, owner: origin.owner, repo: origin.repository });
+    let status = await readOnboardingStatus(repository, deriveBaseSha(gitRoot, Date.now() + EXPLICIT_WALL_MS), auth.token);
+    reportOnboardingState(status);
+    if (options.wait && status.state === 'onboarding') {
+        status = await waitForOnboarding(status, auth.token, line => console.error(chalk.dim(`${clock()} ${line}`)), 'haystack verify onboarding --wait');
+        reportOnboardingState(status);
+    }
+    if (options.json)
+        process.stdout.write(`${JSON.stringify(withSchema('verify-onboarding', { onboarding: status }), null, 2)}\n`);
+    else
+        console.log(formatOnboarding(status));
+    process.exitCode = onboardingExitCode(status);
+}