@haystackeditor/cli 0.18.0 → 0.20.0

package/dist/index.js

@@ -6,7 +6,7 @@
  * Automated PR review, triage, and merge queue for AI-assisted development.
  *
  * Usage:
- *   npx @haystackeditor/cli init           # Set up .haystack.json
+ *   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
@@ -133,7 +133,7 @@ function getVersion() {
 const program = new Command();
 program
     .name('haystack')
-    .description('Haystack CLI — automated PR review, triage, and merge queue')
+    .description('Haystack CLI — haystack verify runs your app with and without a change and shows what it broke')
     .version(getVersion())
     // commander 13 made surplus positional arguments an error; the CLI has always
     // ignored them. Every command created below inherits this setting.
@@ -144,18 +144,38 @@ program
     .action((name) => (name ? schemaCommand(name) : listSchemas()));
 program
     .command('init')
-    .description('Create .haystack.json configuration')
-    .option('-f, --force', 'Overwrite existing .haystack.json')
+    .description('Set this repository up for `haystack verify` and start onboarding the app')
+    .option('-y, --yes', 'Make the changes without asking')
+    .option('--json', 'The result as one JSON document on stdout (see `haystack schema init`)')
     .addHelpText('after', `
-This creates a .haystack.json file with auto-detected settings:
-  • Dev server command and port
-  • Services (for monorepos)
-  • Auth bypass for CI environments
+There is no setup file: Haystack works out how to run the app from what the
+repository already keeps working. init shows each change as a diff, then makes
+it with --yes (or a yes at the prompt):
+  • Claude Code's Stop hook (\`haystack verify precompute --hook\`) in the
+    per-developer .claude/settings.local.json, kept out of commits, when
+    Claude Code is in use here
+  • a short note in AGENTS.md (and CLAUDE.md when the repository keeps one)
+    telling coding agents to run \`haystack verify\` after a change
+Then it starts onboarding the app, so it is usually ready by the first
+\`haystack verify\`. Running it again changes only what is missing and shows
+where onboarding is (\`haystack verify onboarding\` shows that too).
 
-After running, use \`haystack setup\` to scan your repos for rules,
-CI signals, and review policies.
+Exit codes:
+  0  set up: onboarding is running or the app is ready
+  1  the command failed
+  2  changes were shown but not made: run \`haystack init --yes\`
+  3  onboarding is blocked: the output says what would unblock it
+  4  not logged in: run \`haystack login\`
+  5  the Haystack GitHub App is not installed on the repository's owner:
+     the output links to it
+  6  set up, but onboarding stopped before finishing: run \`haystack init\` again
+
+Examples:
+  haystack init
+  haystack init --yes
+  haystack init --yes --json
 `)
-    .action(initCommand);
+    .action(options => runPublicCommand(() => initCommand(options), options.json));
 program
     .command('setup')
     .description('Onboarding wizard — scan repos for rules/policies and write Haystack config')
@@ -208,7 +228,7 @@ const verify = program
     .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')
-    .option('--interval <seconds>', 'Polling interval while waiting (default 5)')
+    .option('--minutes <n>', 'How long the crawl may take, 1-30 (default: .haystack.json crawl.minutes, else 3)')
     .option('--json', 'The crawl as one JSON document on stdout (see `haystack schema verify`)')
     .addHelpText('after', `
 Run inside a git checkout; nothing needs to be committed or pushed. It captures
@@ -222,25 +242,40 @@ again), says so, and follows that crawl.
 
 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
-every difference. The command waits until the crawl finishes, printing each
-step; Ctrl-C stops waiting, never the crawl. It then prints where your change
-shows up in the app (each changed spot, how far the crawl got with it, and the
-steps that reached it), what the crawl found (bugs first, with the steps to see
-each), and the changed code it never ran.
+every difference it can within its time: 3 minutes unless the repository's
+.haystack.json sets crawl.minutes or --minutes says otherwise (1 to 30).
+Differences it had no time to check are listed as not finished in time. The
+command waits for the crawl, printing each step and each bug the moment the
+crawl finds it; it finishes when the crawl answers, as soon as its time is up,
+without waiting for the crawl's machines to shut down. Ctrl-C stops waiting,
+never the crawl. It then prints where your change shows up in the app (each
+changed spot, how far the crawl got with it, and the steps that reached it),
+what the crawl found (bugs first, with the steps to see each), and the changed
+code it never ran.
+
+The first verify on a base the service has not onboarded yet prepares the app
+(reads the repository, plans how to run it, builds its runtime, starts it,
+prepares its data and test accounts, proves a workflow); the command shows each
+step, and the crawl runs once the app is ready. When onboarding cannot go on it
+says why and what would unblock it, for example a question to answer with
+\`haystack verify answer <question-id> <choice>\`.
 
 Exit codes:
-  0  the crawl finished (the bugs it found are in the output), or it is
-     still running and --no-wait was given
+  0  the crawl answered or finished (the bugs it found are in the output), or
+     it is still running and --no-wait was given
   1  the command failed, or no crawl could be started for this change
   2  the crawl ended without finishing: it stopped early or was cancelled
      (a newer stop in the repository replaces an older crawl), or the
-     machines it used could not be proven shut down
+     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
 
 The hosted fleet run of pushed commits is \`haystack verify hosted start\`.
 
 Examples:
   haystack verify
   haystack verify --no-wait
+  haystack verify --minutes 10
   haystack verify --json
   haystack verify history owner/repo --limit 20
   haystack verify hosted status cv_<48 lowercase hex characters> --wait
@@ -267,6 +302,49 @@ function verifyCommandOptions(command) {
     }
     return options;
 }
+verify
+    .command('answer')
+    .description('Answer a question onboarding asked about your app, then run `haystack init` to continue')
+    .argument('<question-id>', 'The question id onboarding printed')
+    .argument('<choice>', 'One of the question\'s choices, exactly as printed')
+    .option('--repo <owner/repo>', 'GitHub repository (default: origin remote)')
+    .option('--account <login>', 'Use a specific saved Haystack account')
+    .option('--json', 'The repository\'s onboarding facts after the answer, as one JSON document')
+    .addHelpText('after', `
+An answer is a fact about your app (never setup); onboarding plans from it the
+next time it runs, so \`haystack init\` or a new \`haystack verify\` continues
+from there.
+
+Example:
+  haystack verify answer q_<id> "postgres 15 (terraform/db.tf)"
+`)
+    .action(async (questionId, choice, _options, cmd) => {
+    const options = verifyCommandOptions(cmd);
+    const { verifyAnswerCommand } = await import('./commands/verify-onboarding.js');
+    return runPublicCommand(() => verifyAnswerCommand(questionId, choice, options), options.json);
+});
+verify
+    .command('onboarding')
+    .description('Show where onboarding of this checkout\'s base is, without starting anything')
+    .option('--account <login>', 'Use a specific saved Haystack account')
+    .option('--wait', 'Follow onboarding until it is ready, blocked or stopped')
+    .option('--json', 'The onboarding as one JSON document (see `haystack schema verify-onboarding`)')
+    .addHelpText('after', `
+Reads the onboarding of the base \`haystack verify\` would use for this
+checkout. \`haystack init\` starts it; so does the first \`haystack verify\`.
+
+Exit codes:
+  0  the app is ready, or onboarding is running
+  1  the command failed
+  2  onboarding has not started, stopped before finishing, or was cancelled:
+     \`haystack init\` starts it again
+  3  onboarding is blocked: the output says what would unblock it
+`)
+    .action(async (_options, cmd) => {
+    const options = verifyCommandOptions(cmd);
+    const { verifyOnboardingCommand } = await import('./commands/verify-onboarding.js');
+    return runPublicCommand(() => verifyOnboardingCommand(options), options.json);
+});
 verify
     .command('history')
     .description('Read your recent finished hosted verification runs without starting a run')
@@ -564,6 +642,15 @@ program
     .option('--label <name>', '(--headless) Label to display in the dashboard for this token')
     .option('--scope <repos>', '(--headless) Comma-separated repos to scope the token to (or "all")', (val) => val.split(',').map((s) => s.trim()).filter(Boolean))
     .option('--token <hsk_live_...>', '(--headless) Skip the browser handshake — paste a token minted in the dashboard')
+    .option('--no-wait', 'Print the sign-in URL and code and return; the next `haystack login` finishes signing in')
+    .option('--json', 'The sign-in (URL and code, or the account signed in) as one JSON document (see `haystack schema login`)')
+    .addHelpText('after', `
+Signing in uses GitHub's device flow: open the URL, enter the code. A coding
+agent runs \`haystack login --no-wait\`, shows the person the URL and code, and
+then runs \`haystack login\`, which waits until the code is entered. A login
+stopped while it waits is finished the same way, with the same code, until
+GitHub expires it.
+`)
     .action(async (opts) => {
     if (opts.headless) {
         try {
@@ -575,7 +662,7 @@ program
         }
         return;
     }
-    return loginCommand();
+    return loginCommand({ wait: opts.wait, json: opts.json });
 });
 program
     .command('logout [login]')
@@ -1525,15 +1612,6 @@ fleetPolicy
     const { fleetPolicyHistoryCommand } = await import('./commands/fleet-policy.js');
     await runAdminCommand(() => fleetPolicyHistoryCommand(repository, options));
 });
-fleetPolicy
-    .command('import-kv')
-    .description('One time: import the KV policies and tenant overrides into D1')
-    .option('--dry-run', 'Report what would be imported without writing')
-    .option(workerUrlOption, workerUrlHelp)
-    .action(async (options) => {
-    const { fleetPolicyImportKvCommand } = await import('./commands/fleet-policy.js');
-    await runAdminCommand(() => fleetPolicyImportKvCommand(options));
-});
 // ─── rules ───────────────────────────────────────────────────────────────────
 const rules = program.command('rules').description('Manage .haystack/pr-rules.yml');
 rules

package/dist/schema.js

@@ -20,7 +20,11 @@ export const SCHEMA_VERSIONS = {
     action: '1.0.0',
     'cloud-verifier': '1.0.0',
     'case-batch': '1.0.1',
-    verify: '1.0.0',
+    verify: '1.0.2',
+    'verify-answer': '1.0.0',
+    'verify-onboarding': '1.0.0',
+    init: '1.0.0',
+    login: '1.0.0',
     error: '1.0.0',
 };
 /** Wrap a payload with the `schema_version` envelope. */

package/dist/types.js

@@ -294,6 +294,9 @@ const PreferencesSchema = z.object({
 export const HaystackConfigSchema = z.object({
     /** Config version (must be "1") */
     version: z.literal('1'),
+    /** Hosted crawls of this repository (`haystack verify`, the stop hook): how long one may take, whole minutes from 1 to 30.
+     * Absent: the service's default (3 minutes). `haystack verify --minutes` overrides it for one run. */
+    crawl: z.object({ minutes: z.number().int().min(1).max(30).optional() }).strict().optional(),
     /** Project name (for display) */
     name: z.string().optional(),
     /** Repository-level Haystack behavior */

package/dist/utils/config.js

@@ -42,22 +42,6 @@ export async function loadConfig(configPath) {
         throw new Error(`Failed to parse ${resolvedPath}: ${err.message}`);
     }
 }
-/**
- * Save config to file
- */
-export async function saveConfig(config, configPath) {
-    const resolvedPath = configPath || path.join(process.cwd(), CONFIG_FILENAME);
-    const content = JSON.stringify(config, null, 2);
-    await fs.writeFile(resolvedPath, content, 'utf-8');
-    return resolvedPath;
-}
-/**
- * Check if config exists
- */
-export async function configExists(startDir) {
-    const configPath = await findConfigPath(startDir);
-    return configPath !== null;
-}
 /**
  * Get the project root (directory containing .haystack.json or current dir)
  */

package/dist/utils/haystack-api.js

@@ -45,6 +45,13 @@ export const SUBSCRIPTION_REQUIRED_MESSAGE = 'This account has no active Haystac
  * repository and team). Its message names the repository; print it as is.
  */
 export const REPO_NOT_ENTITLED_CODE = 'repo_not_entitled';
+/**
+ * The server returns this `code` (HTTP 403, beside a readable `error`) when the
+ * repository's owner has not installed the Haystack GitHub App, which the
+ * service needs to read the repository.
+ */
+export const INSTALLATION_REQUIRED_CODE = 'installation-required';
+export const HAYSTACK_APP_INSTALL_URL = 'https://github.com/apps/haystack-code-reviewer-pr-hook/installations/new';
 /**
  * Extract the server's own message (and its `error` code) if the body is
  * JSON; truncate raw bodies.
@@ -66,7 +73,8 @@ async function serverMessage(response) {
         const parsed = JSON.parse(text);
         return {
             detail: parsed.message ?? parsed.error ?? null,
-            code: typeof parsed.error === 'string' ? parsed.error : null,
+            // Routes that answer { error: <readable text>, code } carry the stable code in `code`.
+            code: typeof parsed.code === 'string' ? parsed.code : typeof parsed.error === 'string' ? parsed.error : null,
         };
     }
     catch {
@@ -90,6 +98,9 @@ export async function classifyHttpError(response, context) {
             : 'This account is not entitled to use Haystack on this repository. See https://haystack.sh/pricing or email akshay@haystack.sh to get access.';
         return new HaystackApiError(403, message, code);
     }
+    if (response.status === 403 && code === INSTALLATION_REQUIRED_CODE) {
+        return new HaystackApiError(403, `${detail ?? 'Install the Haystack GitHub App on the repository\'s owner'}: ${HAYSTACK_APP_INSTALL_URL}`, code);
+    }
     if (response.status === 401) {
         return new HaystackApiError(401, `${context}: authentication failed${suffix}. Run \`haystack login\` to re-authenticate.`);
     }

package/dist/utils/secrets.js

@@ -9,8 +9,6 @@
  * - detect-secrets
  * - truffleHog
  */
-import * as fs from 'fs/promises';
-import * as path from 'path';
 /**
  * Common secret patterns
  */
@@ -188,52 +186,3 @@ export function scanForSecrets(content, filename) {
     }
     return findings;
 }
-/**
- * Scan a file for secrets
- */
-export async function scanFile(filePath) {
-    try {
-        const content = await fs.readFile(filePath, 'utf-8');
-        return scanForSecrets(content, path.basename(filePath));
-    }
-    catch {
-        return [];
-    }
-}
-/**
- * Scan .haystack.json specifically for secrets
- */
-export async function scanHaystackConfig(configPath) {
-    return scanFile(configPath);
-}
-/**
- * Validate that a config doesn't contain hardcoded secrets
- * Returns true if safe, false if secrets detected
- */
-export async function validateConfigSecurity(configPath) {
-    const findings = await scanHaystackConfig(configPath);
-    const highSeverity = findings.filter((f) => f.severity === 'high');
-    return {
-        safe: highSeverity.length === 0,
-        findings,
-    };
-}
-/**
- * Get a security report string for display
- */
-export function formatSecurityReport(findings) {
-    if (findings.length === 0) {
-        return '✓ No secrets detected';
-    }
-    const lines = [
-        `⚠️  ${findings.length} potential secret(s) detected:\n`,
-    ];
-    for (const finding of findings) {
-        const severity = finding.severity === 'high' ? '🔴' : finding.severity === 'medium' ? '🟡' : '🟢';
-        lines.push(`  ${severity} ${finding.file}:${finding.line}:${finding.column}`);
-        lines.push(`     ${finding.description}`);
-        lines.push(`     Matched: ${finding.match}\n`);
-    }
-    lines.push('Use $VARIABLE syntax to reference secrets instead of hardcoding values.\n');
-    return lines.join('\n');
-}

package/dist/utils/telemetry.js

@@ -197,6 +197,38 @@ export function trackPrecomputeEvent(outcome, wallMs, timeoutMs) {
         // Telemetry must never crash or delay the CLI.
     }
 }
+/** Track one onboarding state `haystack verify` saw: started, blocked (with the block's kind) or ready. */
+export function trackOnboardingEvent(outcome, kind) {
+    try {
+        if (telemetryDisabled() || typeof globalThis.fetch !== 'function')
+            return;
+        const event = {
+            api_key: POSTHOG_API_KEY,
+            distinct_id: getDistinctId(),
+            event: 'cli_verify_onboarding',
+            properties: {
+                cli_version: getCLIVersion(),
+                os: process.platform,
+                arch: process.arch,
+                timestamp: new Date().toISOString(),
+                ...minimizeMetadata({ outcome, ...(kind === undefined ? {} : { kind }) }),
+                $ip: null,
+            },
+            timestamp: new Date().toISOString(),
+        };
+        globalThis.fetch(`${POSTHOG_HOST}/capture/`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(event),
+        }).catch(() => {
+            // Documented fire-and-forget product telemetry: delivery cannot affect
+            // the CLI command being measured.
+        });
+    }
+    catch {
+        // Telemetry must never crash the CLI
+    }
+}
 function getCLIVersion() {
     try {
         const packageJson = JSON.parse(readFileSync(PACKAGE_JSON_PATH, 'utf8'));

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@haystackeditor/cli",
-  "version": "0.18.0",
-  "description": "Set up Haystack for your project — automated PR review, triage, and merge queue",
+  "version": "0.20.0",
+  "description": "haystack verify: run your app with and without a change, and see what the change broke",
   "type": "module",
   "bin": {
     "haystack": "dist/index.js"

package/schemas/init.v1.json

@@ -0,0 +1,35 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://docs.haystackeditor.com/cli/schemas/init.v1.json",
+  "title": "Haystack init: this repository's setup for `haystack verify`",
+  "description": "Machine-readable output of `haystack init --json`. `changes` are the project-local changes init planned (made when status is done); `onboarding` is the base's OnboardingStatusV1 (onboarding_contracts.ts, APP-ONBOARDING-V1) as POST /api/agent/cloud-verifier/onboarding returns it, null unless status is done. Exit codes: 0 done (onboarding running or ready), 1 failed (the error envelope), 2 planned (nothing written; run with --yes), 3 done but onboarding blocked, 4 login-required, 5 app-required (install the Haystack GitHub App), 6 done but onboarding stopped before finishing (run init again).",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema_version", "status", "repository", "changes", "notices", "onboarding"],
+  "properties": {
+    "schema_version": { "const": "1.0.0" },
+    "status": { "enum": ["done", "planned", "login-required", "app-required"] },
+    "repository": { "type": "string" },
+    "changes": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["path", "action", "reason", "diff"],
+        "properties": {
+          "path": { "type": "string" },
+          "action": { "enum": ["create", "update"] },
+          "reason": { "type": "string" },
+          "diff": { "type": "array", "items": { "type": "string" } }
+        }
+      }
+    },
+    "notices": { "type": "array", "items": { "type": "string" } },
+    "onboarding": {
+      "oneOf": [
+        { "type": "null" },
+        { "$ref": "verify.v1.json#/$defs/onboardingStatus" }
+      ]
+    }
+  }
+}

package/schemas/login.v1.json

@@ -0,0 +1,17 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://docs.haystackeditor.com/cli/schemas/login.v1.json",
+  "title": "Haystack login: a GitHub device-flow sign-in",
+  "description": "Machine-readable output of `haystack login --json`. With --no-wait, status is pending and carries the URL to open and the code to enter (never the device code); the next `haystack login` finishes it. Otherwise status is logged-in with the account signed in.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema_version", "status", "verificationUri", "userCode", "expiresAt", "login"],
+  "properties": {
+    "schema_version": { "const": "1.0.0" },
+    "status": { "enum": ["pending", "logged-in"] },
+    "verificationUri": { "type": ["string", "null"] },
+    "userCode": { "type": ["string", "null"] },
+    "expiresAt": { "type": ["string", "null"], "format": "date-time" },
+    "login": { "type": ["string", "null"] }
+  }
+}

package/schemas/verify-answer.v1.json

@@ -0,0 +1,86 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://docs.haystackeditor.com/cli/schemas/verify-answer.v1.json",
+  "title": "Haystack verify answer: the repository's onboarding facts after an answer",
+  "description": "Machine-readable output of `haystack verify answer <question-id> <choice> --json`: OnboardingFactsView (onboarding_contracts.ts, APP-ONBOARDING-V1) as POST /api/agent/cloud-verifier/onboarding/answers returns it.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_version",
+    "facts"
+  ],
+  "properties": {
+    "schema_version": {
+      "const": "1.0.0"
+    },
+    "facts": {
+      "type": "object",
+      "required": [
+        "repository",
+        "facts",
+        "factsDigest",
+        "openQuestions"
+      ],
+      "properties": {
+        "repository": {
+          "type": "string"
+        },
+        "factsDigest": {
+          "type": "string",
+          "pattern": "^[0-9a-f]{64}$"
+        },
+        "facts": {
+          "type": "object",
+          "required": [
+            "dbProfile",
+            "answers"
+          ],
+          "properties": {
+            "dbProfile": {
+              "oneOf": [
+                {
+                  "type": "null"
+                },
+                {
+                  "type": "string",
+                  "pattern": "^[0-9a-f]{64}$"
+                }
+              ]
+            },
+            "answers": {
+              "type": "object",
+              "additionalProperties": {
+                "type": "string"
+              }
+            }
+          }
+        },
+        "openQuestions": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": [
+              "id",
+              "message",
+              "choices"
+            ],
+            "properties": {
+              "id": {
+                "type": "string"
+              },
+              "message": {
+                "type": "string"
+              },
+              "choices": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/schemas/verify-onboarding.v1.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://docs.haystackeditor.com/cli/schemas/verify-onboarding.v1.json",
+  "title": "Haystack verify onboarding: the onboarding of this checkout's base",
+  "description": "Machine-readable output of `haystack verify onboarding --json`: OnboardingStatusV1 (onboarding_contracts.ts, APP-ONBOARDING-V1) of the base `haystack verify` would use, as GET /api/agent/cloud-verifier/onboarding?repository=&baseCommit= returns it.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema_version", "onboarding"],
+  "properties": {
+    "schema_version": { "const": "1.0.0" },
+    "onboarding": { "$ref": "verify.v1.json#/$defs/onboardingStatus" }
+  }
+}