@haystackeditor/cli 0.18.0 → 0.20.0

package/README.md

@@ -1,13 +1,23 @@
 # @haystackeditor/cli
 
-Set up Haystack for your project. When PRs are opened, Haystack automatically reviews them for bugs, instruction drift, and rule violations — then routes them to the right place.
+`haystack verify` runs your app with and without your change, explores both side by side, and reports where the change shows up and what it broke.
 
 ## Quick Start
 
 ```bash
 npm install -g @haystackeditor/cli
-haystack login
-haystack setup
+haystack login   # GitHub sign-in: open the URL it prints and enter the code
+haystack init    # shows what it will change, then starts onboarding your app
+haystack verify  # after a change: crawl the app with and without it
+```
+
+There is no configuration file: Haystack works out how to run your app from
+what the repository already keeps working (lockfiles, Dockerfiles, compose
+files, package scripts). Or have your coding agent do the setup — paste this
+into Claude Code, Codex or Cursor:
+
+```text
+Set up Haystack for me: fetch https://haystack.sh/agents.md and follow it
 ```
 
 Requires Node.js 22.18 or newer.
@@ -17,15 +27,6 @@ once a day and prints one line on stderr when a newer version exists. It never
 runs with `--json`, when stdout is not a TTY, or when `CI` is set. Set
 `HAYSTACK_NO_UPDATE_CHECK=1` to turn it off.
 
-The `setup` command walks you through an interactive wizard:
-
-1. **Select repositories** to configure
-2. **Scan for coding rules** (conventions your team follows)
-3. **Scan for CI/bot signals** (checks to wait for before merging)
-4. **Scan for review policies** (who should review what)
-5. **Review and toggle** discovered items
-6. **Write `.haystack.json`** to your repos
-
 The CLI sends limited operational events to PostHog by default so Haystack can
 measure setup reliability. Events contain a pseudonymous install identifier
 (a random id generated once and stored in `~/.haystack/telemetry-id`; it is
@@ -106,8 +107,11 @@ acknowledged; it never shows a crawl of another revision or another title.
 A crawl builds the app with and without your change, starts from the changed
 code, reaches it in the running app, explores outward with both builds side by
 side, and double-checks and judges every difference. `haystack verify` waits
-until the crawl finishes, printing each step as it happens; there is no time
-limit, and Ctrl-C stops waiting, never the crawl. It then prints:
+for the crawl, printing each step as it happens and each bug the moment the
+crawl finds it (each read is held by the service until the crawl changes, so
+nothing waits on a polling interval). It finishes when the crawl answers, as
+soon as its time is up, without waiting for its machines to shut down; there
+is no time limit, and Ctrl-C stops waiting, never the crawl. It then prints:
 
 - a headline: how many bugs it found, none, or why the crawl could not finish;
 - **Where your change shows up in the app**: every changed spot as
@@ -120,14 +124,15 @@ limit, and Ctrl-C stops waiting, never the crawl. It then prints:
 - **What the crawl never ran**: changed files no path ran, and how many of the
   functions your change affects ran.
 
-`--no-wait` prints the crawl's current state and returns. `--interval
-<seconds>` sets the polling interval (default 5), `--account <login>` picks a
-saved account, and `--repo owner/repo` names the repository when `origin` does
-not. `--json` prints one document, `{ "schema_version", "crawl" }`, where
-`crawl` is the crawl as the service returns it (or `null` when no crawl of the
-capture could be started); `haystack schema verify` prints its schema. Exit codes
-follow `haystack case-batch status`: 0 when the crawl finished (the bugs it
-found are in the output) or is still running under `--no-wait`; 2 when it ended
+`--no-wait` prints the crawl's current state and returns. `--account <login>`
+picks a saved account, and `--repo owner/repo` names the repository when
+`origin` does not. `--json` prints one document, `{ "schema_version", "crawl" }`,
+where `crawl` is the crawl as the service returns it, with its `answer` (what it
+found so far, or its answer once its time is up) while no sealed `manifest`
+exists (or `null` when no crawl of the capture could be started);
+`haystack schema verify` prints its schema. Exit codes follow
+`haystack case-batch status`: 0 when the crawl answered or finished (the bugs
+it found are in the output) or is still running under `--no-wait`; 2 when it ended
 without finishing (stopped early, or cancelled because a newer stop in the
 repository replaced it) or the machines it used could not be proven shut down;
 1 when the command failed or no crawl could be started.
@@ -228,13 +233,23 @@ haystack setup
 
 ### `haystack init`
 
-Quick local setup — auto-detects your project and creates `.haystack.json` without scanning:
+Sets the repository up for `haystack verify` and starts onboarding the app. It
+shows each change as a diff and makes it only with `--yes` (or a yes at the
+prompt): Claude Code's Stop hook in the per-developer
+`.claude/settings.local.json` (kept out of commits), and a short note in
+AGENTS.md telling coding agents to run `haystack verify` after a change.
+Running it again changes only what is missing and shows where onboarding is.
 
 ```bash
-haystack init              # Auto-detect and create config
-haystack init --force      # Overwrite existing .haystack.json
+haystack init              # Preview, then confirm
+haystack init --yes --json # Apply without asking; one JSON document (haystack schema init)
+haystack verify onboarding # Where onboarding is; --wait follows it
 ```
 
+Exit codes: 0 set up, 1 failed, 2 changes shown but not made, 3 onboarding
+blocked, 4 not logged in, 5 the Haystack GitHub App is not installed, 6 set up
+but onboarding stopped before finishing (run it again).
+
 ### `haystack status`
 
 Check if your project is configured:
@@ -252,6 +267,8 @@ haystack login
 ```
 
 This uses GitHub's device flow - you'll get a code to enter at github.com/login/device.
+A coding agent runs `haystack login --no-wait --json` to get the URL and code
+without waiting, shows them to you, then runs `haystack login` to finish.
 
 ```bash
 # Log out (removes stored credentials)
@@ -725,28 +742,18 @@ haystack policy init --force                  # Overwrite existing
 
 ---
 
-## Configuration
-
-The `setup` wizard writes `.haystack.json` to your repos with discovered rules, signals, and policies. You can also create a base config locally with `haystack init`:
-
-```json
-{
-  "version": "1",
-  "name": "my-app"
-}
-```
-
----
-
 ## How It Works
 
-1. Run `haystack setup` to configure your repos (or `haystack init` for local-only config)
-2. Install the [Haystack GitHub App](https://github.com/apps/haystack-code-reviewer-pr-hook/installations/new)
-3. When PRs are opened, Haystack automatically:
-   - Analyzes the code for bugs, instruction drift, and rule violations
-   - Reports results on the PR
-   - Routes the PR to the right inbox tab (Good to Merge, Issues Found, etc.)
-   - If auto-merge is enabled, clean PRs merge automatically
+1. `haystack init` starts onboarding: Haystack reads the repository, builds the
+   app, starts it with its databases and services, prepares its data and test
+   accounts, and proves one workflow works. It needs the
+   [Haystack GitHub App](https://github.com/apps/haystack-code-reviewer-pr-hook/installations/new)
+   on the repository's owner.
+2. After a change, `haystack verify` builds the app at the base and with your
+   change on Haystack's isolated machines (no internet access), explores both
+   side by side starting from the changed code, and judges every difference.
+3. It prints where your change shows up, the bugs it found with the steps to
+   see each, and the changed code it never ran. See https://haystack.sh/docs.
 
 ## License
 

package/dist/commands/case-batch.js

@@ -90,6 +90,8 @@ function requireRunId(runId) {
     }
     return runId;
 }
+/** How long any gateway request may take unless its caller says otherwise. */
+export const GATEWAY_TIMEOUT_MS = 120_000;
 /** Every outbound request. The header set is built here and nowhere else, so
  * the credential surface of this command is one line: the login bearer.
  * `haystack verify` reads crawls through this same client. */
@@ -104,7 +106,7 @@ export async function gatewayFetch(path, token, init = { method: 'GET' }) {
         method: init.method,
         headers,
         ...(init.body === undefined ? {} : { body: init.body }),
-        signal: AbortSignal.timeout(120_000),
+        signal: AbortSignal.timeout(init.timeoutMs ?? GATEWAY_TIMEOUT_MS),
     });
 }
 async function gatewayJson(path, token, init = { method: 'GET' }) {

package/dist/commands/crawl-contract.js

@@ -1,3 +1,9 @@
 export const CRAWL_TITLE_MAX_CHARS = 200;
+/** Amendment 8: the time a crawl may be asked to take, whole seconds from 1 to 30 minutes. */
+export const CRAWL_BUDGET_MIN_MS = 60_000;
+export const CRAWL_BUDGET_MAX_MS = 30 * 60_000;
 export const CRAWL_MAX_FINDINGS = 50;
 export const CRAWL_MAX_FINDING_STEPS = 64;
+/** Amendment 9: what a crawl has found so far (`exploring`) or its answer at the budget (`answered`), before the sealed manifest;
+ * findings carry no images. A read may pass `waitAfter=<updatedAt>` to be held until the crawl changes (at most CRAWL_WAIT_MAX_MS). */
+export const CRAWL_WAIT_MAX_MS = 25_000;

package/dist/commands/fleet-policy.js

@@ -1,5 +1,5 @@
 /**
- * `haystack admin fleet-policy show|diff|set|revoke|history|import-kv`: the
+ * `haystack admin fleet-policy show|diff|set|revoke|history`: the
  * operator command for the fleet policy authority in D1 (FLEET PHASE 1,
  * design Appendix A). The only credential is the operator's Cloudflare Access
  * token from `cloudflared access token -app=<worker URL>`, sent as
@@ -282,24 +282,3 @@ export function fleetPolicyHistoryCommand(repository, options) {
         return FLEET_POLICY_CLI_EXIT.ok;
     });
 }
-export function fleetPolicyImportKvCommand(options) {
-    return run(async () => {
-        const dryRun = options.dryRun === true;
-        const result = await post(workerOrigin(options), FLEET_POLICY_ADMIN_ROUTES.importKv, { dryRun });
-        if (result.kind !== 'ok')
-            return reportFailure(result);
-        const { policies, overrides } = result.body;
-        console.log(chalk.bold(`${dryRun ? 'dry run: ' : ''}${policies.length} policy keys, ${overrides.length} tenant override keys`));
-        for (const item of policies) {
-            const scope = item.scope ? ` ${item.scope.tenantId} ${item.scope.repositoryId}` : '';
-            console.log(`  ${item.outcome} ${item.key}${scope}${item.repositoryFullName ? ` (${item.repositoryFullName})` : ''}`
-                + `${item.scopeKind ? ` ${item.scopeKind}` : ''}${item.binding ? ` [${bindingText(item.binding)}]` : ''}`
-                + `${item.policySha256 ? ` ${item.policySha256}` : ''}${item.detail ? `: ${item.detail}` : ''}`);
-        }
-        for (const item of overrides) {
-            console.log(`  ${item.outcome} ${item.key}${item.tenantId ? ` -> ${item.tenantId}` : ''}${item.detail ? `: ${item.detail}` : ''}`);
-        }
-        const failed = [...policies, ...overrides].filter(item => item.outcome === 'conflict' || item.outcome === 'invalid');
-        return failed.length === 0 ? FLEET_POLICY_CLI_EXIT.ok : FLEET_POLICY_CLI_EXIT.error;
-    });
-}