@haystackeditor/cli 0.15.13 → 0.15.15

package/dist/assets/skills/install-verification.md

@@ -0,0 +1,67 @@
+# Install Haystack Verification
+
+Add a Haystack verification contract to this repository so Haystack (and any
+coding agent) can safely verify risky PRs and produce reviewable evidence.
+
+The deliverable is a small, reviewable PR containing:
+
+- `.haystack/verification.yml` — the verification contract
+- `scripts/haystack-preflight` — proves the app is up and answering
+- `scripts/haystack-smoke` — boots the app, runs a basic logged-in check, captures evidence
+- `.haystack/AGENTS.md` — how agents should use the contract
+
+## Ground rules
+
+1. **No production behavior changes.** Anything you add must be dev/test-only,
+   clearly isolated, and easy for a reviewer to verify as inert in production.
+2. **Prefer existing test utilities** (seed scripts, factories, test logins,
+   fixtures) over new application code.
+3. **Only add dev-only endpoints when necessary**, and gate them so they cannot
+   run in production (`NODE_ENV !== 'production'` or the framework equivalent).
+   If you add one, also add a test proving it is disabled in production mode,
+   and wire that test into `safety.production_disabled_check`.
+4. **Never reference real credentials, real payment providers, real email
+   delivery, or customer data.** Sandbox or mock everything external.
+5. **Keep the integration small.** A working smoke scenario beats ten
+   aspirational ones.
+
+## Steps
+
+1. **Scaffold.** Run `npx @haystackeditor/cli verification init` (or
+   `haystack verification init` if installed). This detects the framework and
+   writes starter files. Review everything it generated.
+
+2. **Inspect the repo.** Identify:
+   - framework, package manager, and how the app starts locally
+   - how the app knows it's "ready" (port, health endpoint, log line)
+   - existing seed/test data and how tests authenticate
+   - existing E2E/smoke tests you can reuse as scenarios
+
+3. **Fix the environment section.** Make `setup`, `start`, and `preflight`
+   real: `setup` must work on a clean clone; `preflight` must exit 0 only when
+   the app is actually usable (prefer a health endpoint over a port check).
+
+4. **Wire personas if a safe login path exists.** Personas are seeded fake
+   users (admin/member/viewer). Use an existing test-login helper if there is
+   one. If none exists and one is genuinely needed, add a dev-only helper per
+   ground rule 3 — otherwise leave personas empty.
+
+5. **Make the smoke scenario real.** It should boot the app, reach a
+   meaningful logged-in (or at least rendered) state, and leave evidence in the
+   artifact directory: server logs, the captured page, and screenshots if a
+   browser runner is available. If part of the flow can't be tested, append a
+   line to `<artifact_dir>/gaps.txt` saying what was skipped.
+
+6. **Validate until clean.** Iterate until both pass:
+   ```bash
+   haystack verification validate
+   haystack verification check-safety
+   haystack verification run smoke
+   ```
+   `validate` must not report `not_ready` or `unsafe`; `run smoke` must end
+   `verified` and write a manifest + review packet under the artifact dir.
+
+7. **Open a reviewable PR.** Keep it focused on the verification contract.
+   In the description, state explicitly: what was added, why each piece is
+   dev-only, and what the smoke scenario proves. Include the review packet
+   from your successful `run smoke` as evidence.

package/dist/assets/skills/submit.md

@@ -151,7 +151,20 @@ This uses GitHub device flow - no tokens to copy/paste.
 - The command uses your current branch as the PR head
 - Labels are applied automatically based on your chosen mode
 - You don't need to push manually - the command handles it
-- Use `haystack triage <pr>` to view full analysis results (rating, findings, agent fix prompts) for any PR at any time
+
+## Close the Loop After Submitting
+
+After `haystack submit` creates the PR, **run `haystack triage <pr>` before ending your turn.**
+It blocks until Haystack's full analysis completes (waking instantly on the completion event),
+then prints the rating, findings, and a per-finding `agentFixPrompt`.
+
+- **Findings marked auto-fixing**: leave them alone — Haystack's fixer is already on them
+- **Actionable findings**: address them (the `agentFixPrompt` is written for you), commit, and
+  push — analysis re-runs on the new commit
+- **Good to merge**: report the rating to your user and stop
+
+Don't end the session right after submit without checking — the verdict usually lands within a
+few minutes, and acting on it immediately is much cheaper than a human bouncing the PR back.
 
 ---
 

package/dist/commands/init.js

@@ -4,8 +4,10 @@
  * Creates .haystack.json with auto-detected settings.
  */
 import chalk from 'chalk';
+import * as fs from 'fs/promises';
 import * as path from 'path';
 import { detectProject } from '../utils/detect.js';
+import { parseRemoteUrl, UnsupportedRemoteUrlError } from '../utils/git.js';
 import { saveConfig, configExists } from '../utils/config.js';
 import { validateConfigSecurity, formatSecurityReport } from '../utils/secrets.js';
 export async function initCommand(options) {
@@ -32,7 +34,10 @@ export async function initCommand(options) {
     }
     console.log('');
     // Build config from detection (no interactive prompts)
-    const config = buildConfigFromDetection(detected);
+    const config = await buildConfigFromDetection(detected);
+    if (config.dev_server) {
+        console.log(`  Dev server: ${chalk.bold(config.dev_server.command)} (port ${config.dev_server.port})\n`);
+    }
     const configPath = await saveConfig(config);
     console.log(chalk.green(`✓ Created ${configPath}`));
     // Security validation
@@ -53,12 +58,14 @@ async function runSecurityCheck(configPath) {
         console.log(chalk.dim('\n' + formatSecurityReport(findings)));
     }
 }
-function buildConfigFromDetection(detected) {
+async function buildConfigFromDetection(detected) {
     const env = {};
     if (detected.suggestedAuthBypass) {
         const [key, value] = detected.suggestedAuthBypass.split('=');
         env[key] = value || 'true';
     }
+    const pkgJson = await readPackageJson();
+    const name = resolveProjectName(pkgJson);
     if (detected.isMonorepo && detected.services?.length) {
         const services = {};
         for (const s of detected.services) {
@@ -74,12 +81,72 @@ function buildConfigFromDetection(detected) {
         }
         return {
             version: '1',
-            name: path.basename(process.cwd()),
+            name,
             services,
         };
     }
+    const devServer = buildDevServer(detected, pkgJson?.scripts, env);
     return {
         version: '1',
-        name: path.basename(process.cwd()),
+        name,
+        ...(devServer ? { dev_server: devServer } : {}),
     };
 }
+/**
+ * Prefer the GitHub repo name, then package.json name, then the directory
+ * name. The directory basename alone is often a worktree or clone-dir name
+ * that has nothing to do with the project.
+ */
+function resolveProjectName(pkgJson) {
+    try {
+        return parseRemoteUrl().repo;
+    }
+    catch (err) {
+        // Classify by type, not message text (PR007). A remote that exists but
+        // isn't recognized deserves a warning — the fallback name may not match
+        // the repo. A missing remote/repo is normal for fresh projects.
+        if (err instanceof UnsupportedRemoteUrlError) {
+            console.log(chalk.yellow(`⚠ Git remote URL not recognized (${err.message}); using package.json/directory name instead`));
+        }
+        else {
+            console.log(chalk.dim('  No git remote found; using package.json/directory name'));
+        }
+    }
+    return pkgJson?.name || path.basename(process.cwd());
+}
+/**
+ * Build a dev_server block for single-repo projects, but only when there is
+ * real evidence of one: a dev/start script in package.json. Without that
+ * gate we'd fabricate commands like `npm dev` that don't exist.
+ */
+function buildDevServer(detected, scripts, env) {
+    const script = scripts?.dev ? 'dev' : scripts?.start ? 'start' : null;
+    if (!script)
+        return undefined;
+    const pm = detected.packageManager;
+    // npm and bun need the `run` form; pnpm/yarn run scripts directly.
+    const command = pm === 'npm' || pm === 'bun' ? `${pm} run ${script}` : `${pm} ${script}`;
+    return {
+        command,
+        port: detected.suggestedPort || 3000,
+        ready_pattern: detected.suggestedReadyPattern || 'ready|started|listening|Local:',
+        ...(Object.keys(env).length > 0 ? { env } : {}),
+    };
+}
+async function readPackageJson() {
+    try {
+        const raw = await fs.readFile(path.join(process.cwd(), 'package.json'), 'utf-8');
+        return JSON.parse(raw);
+    }
+    catch (err) {
+        // A missing package.json is normal (non-Node projects). Anything else —
+        // unreadable file, malformed JSON — degrades name resolution and
+        // dev-server detection, so say so instead of silently falling back.
+        if (err.code === 'ENOENT') {
+            return null;
+        }
+        const message = err instanceof Error ? err.message : String(err);
+        console.log(chalk.yellow(`⚠ Could not read package.json (${message}); skipping dev-server detection`));
+        return null;
+    }
+}

package/dist/commands/setup.js

@@ -94,32 +94,31 @@ const SEVERITY_LABELS = {
     medium: 'Medium',
     low: 'Low',
 };
-async function fetchUserRepos(token) {
-    const repos = [];
-    let page = 1;
-    // Fetch up to 200 repos (non-archived, sorted by recent push)
-    while (page <= 2) {
-        const response = await fetch(`${GITHUB_API}/user/repos?sort=pushed&per_page=100&page=${page}&type=owner`, {
-            headers: {
-                Authorization: `Bearer ${token}`,
-                Accept: 'application/vnd.github.v3+json',
-                'User-Agent': 'Haystack-CLI',
-            },
-        });
-        if (!response.ok) {
-            throw new Error(`Failed to fetch repos: ${response.status}`);
+// =============================================================================
+// GitHub API helpers
+// =============================================================================
+/**
+ * Source the onboarding repo list from the user's Haystack GitHub App
+ * installations (resolved server-side with the App JWT via
+ * /api/github/user-installations) instead of `GET /user/repos` with the user's
+ * OAuth token. Every repo here is covered by an installation, so the picker can
+ * only ever offer repos Haystack can actually access — no OAuth GitHub-data call,
+ * and no "access denied" downstream when a chosen repo turns out not to be
+ * install-covered. Sorted most-recently-pushed first.
+ */
+async function fetchInstallCoveredRepos(token) {
+    const installations = await fetchHaystackInstallations(token);
+    const pushedByName = new Map();
+    for (const inst of installations) {
+        for (const repo of inst.repositories ?? []) {
+            if (repo?.full_name && !pushedByName.has(repo.full_name)) {
+                pushedByName.set(repo.full_name, repo.pushed_at ?? '');
+            }
         }
-        const batch = (await response.json());
-        if (batch.length === 0)
-            break;
-        repos.push(...batch);
-        if (batch.length < 100)
-            break;
-        page++;
     }
-    return repos
-        .filter((r) => !r.archived)
-        .map((r) => r.full_name);
+    return [...pushedByName.entries()]
+        .sort((a, b) => b[1].localeCompare(a[1])) // ISO pushed_at desc → recent first
+        .map(([fullName]) => fullName);
 }
 // Bootstrap PR constants — kept in sync with the web wizard
 // (src/features/onboarding/services/onboardingApi.ts). The branch prefix and
@@ -762,9 +761,10 @@ async function stepEnsureAppInstalled(token) {
 async function stepSelectRepos(token) {
     console.log(chalk.bold('\n  Step 1: Select repositories\n'));
     console.log(chalk.dim('  Fetching your repositories...'));
-    const repos = await fetchUserRepos(token);
+    const repos = await fetchInstallCoveredRepos(token);
     if (repos.length === 0) {
-        console.log(chalk.yellow('\n  No repositories found.\n'));
+        console.log(chalk.yellow('\n  No repositories found on your Haystack App installation(s).'));
+        console.log(chalk.dim(`  Add repositories to the install at ${HAYSTACK_APP_INSTALL_URL}, then re-run \`haystack setup\`.\n`));
         process.exit(1);
     }
     let selectedRepos = [];

package/dist/commands/triage.js

@@ -20,6 +20,7 @@
  *   (default) Rich terminal output
  */
 import chalk from 'chalk';
+import WebSocket from 'ws';
 import { checkAnalysisReady, fetchRatingSynthesis, fetchAutoFixManifest } from '../utils/analysis-api.js';
 import { parseRemoteUrl } from '../utils/git.js';
 import { loadToken } from '../utils/auth.js';
@@ -202,31 +203,111 @@ function printHookOutput(pr, synthesis, manifest, status) {
     }
 }
 // ============================================================================
-// Polling
+// Waiting (event-driven with polling fallback)
 // ============================================================================
 const POLL_INTERVAL_MS = 5_000;
 const POLL_TIMEOUT_MS = 5 * 60 * 1000; // 5 minutes
+/** With a live event subscription, checks are event-driven; this slow cycle
+ *  is only a safety net against a silently dead socket. */
+const SUBSCRIBED_RECHECK_MS = 60_000;
+const PR_EVENTS_WS_BASE = process.env.HAYSTACK_PR_EVENTS_WS_URL ?? 'wss://haystackeditor.com/api/pr-events';
+/**
+ * Subscribe to the pr-events worker for this PR — the same real-time channel
+ * the web inbox uses. Any event (analysis_complete, commit_pushed, ...) calls
+ * `onEvent`, and the caller re-checks analysis state immediately instead of
+ * discovering it on the next poll tick. Returns null when a socket can't even
+ * be constructed; connection failures after that surface via isConnected().
+ */
+function subscribeToPrEvents(owner, repo, prNumber, token, onEvent, quiet) {
+    // Diagnostics are dim stderr lines, once per failure mode — polling is the
+    // designed fallback, but WHY live updates are off must stay visible (PR001).
+    // quiet (--hook) mode stays terse: the hook output is machine-parsed.
+    const diag = (msg) => {
+        if (!quiet)
+            process.stderr.write(`\n  ${chalk.dim(`[live updates unavailable: ${msg}; using polling]`)}\n`);
+    };
+    try {
+        const ws = new WebSocket(`${PR_EVENTS_WS_BASE}/${owner}/${repo}/${prNumber}/subscribe`, {
+            headers: { Authorization: `Bearer ${token}` },
+        });
+        let connected = false;
+        let reported = false;
+        ws.on('open', () => { connected = true; });
+        ws.on('message', () => onEvent());
+        ws.on('error', (err) => {
+            connected = false;
+            if (!reported) {
+                reported = true;
+                diag(err.message);
+            }
+        });
+        ws.on('close', () => { connected = false; });
+        const keepalive = setInterval(() => {
+            // A failed send means the socket died between ticks; the 'error'/'close'
+            // handlers above report it and flip isConnected() — nothing extra to say.
+            try {
+                ws.send('ping');
+            }
+            catch { /* surfaced via error/close handlers */ }
+        }, 30_000);
+        keepalive.unref?.();
+        return {
+            isConnected: () => connected,
+            close: () => {
+                clearInterval(keepalive);
+                // Idempotent teardown, not a fallback: close() on an already-dead
+                // socket can throw in ws and there is genuinely nothing to handle.
+                try {
+                    ws.close();
+                }
+                catch { /* already closed */ }
+            },
+        };
+    }
+    catch (err) {
+        diag(err instanceof Error ? err.message : String(err));
+        return null;
+    }
+}
 async function waitForAnalysis(owner, repo, prNumber, timeoutMs, token, quiet) {
     const deadline = Date.now() + timeoutMs;
     let consecutiveErrors = 0;
-    while (Date.now() < deadline) {
-        const result = await checkAnalysisReady(owner, repo, prNumber, token);
-        if (result.status === 'ready')
-            return 'ready';
-        if (result.status === 'error') {
-            consecutiveErrors++;
-            if (consecutiveErrors >= 5)
-                return 'error';
-        }
-        else {
-            consecutiveErrors = 0;
-        }
-        if (!quiet) {
-            process.stderr.write(`\r  ${chalk.dim('Waiting for analysis to complete...')}${'  '.repeat(5)}`);
+    // Event-driven wake: a pr-events message resolves the current sleep so the
+    // re-check happens the moment analysis completes, not on the next tick.
+    let wake = null;
+    const subscription = token
+        ? subscribeToPrEvents(owner, repo, prNumber, token, () => wake?.(), quiet)
+        : null;
+    try {
+        while (Date.now() < deadline) {
+            const result = await checkAnalysisReady(owner, repo, prNumber, token);
+            if (result.status === 'ready')
+                return 'ready';
+            if (result.status === 'error') {
+                consecutiveErrors++;
+                if (consecutiveErrors >= 5)
+                    return 'error';
+            }
+            else {
+                consecutiveErrors = 0;
+            }
+            const live = subscription?.isConnected() ?? false;
+            if (!quiet) {
+                const mode = live ? 'Waiting for analysis (live)...' : 'Waiting for analysis to complete...';
+                process.stderr.write(`\r  ${chalk.dim(mode)}${'  '.repeat(5)}`);
+            }
+            const interval = Math.min(live ? SUBSCRIBED_RECHECK_MS : POLL_INTERVAL_MS, Math.max(deadline - Date.now(), 0));
+            await new Promise((resolve) => {
+                const timer = setTimeout(() => { wake = null; resolve(); }, interval);
+                timer.unref?.();
+                wake = () => { clearTimeout(timer); wake = null; resolve(); };
+            });
         }
-        await new Promise(r => setTimeout(r, POLL_INTERVAL_MS));
+        return 'pending';
+    }
+    finally {
+        subscription?.close();
     }
-    return 'pending';
 }
 // ============================================================================
 // PR resolution

package/dist/commands/verification.d.ts

@@ -0,0 +1,21 @@
+export declare function verificationInitCommand(options: {
+    force?: boolean;
+    skill?: boolean;
+}): Promise<void>;
+export declare function verificationValidateCommand(options: {
+    json?: boolean;
+}): Promise<void>;
+export declare function verificationPreflightCommand(): Promise<void>;
+export declare function verificationRunCommand(scenarioName: string, options: {
+    json?: boolean;
+    skipPreflight?: boolean;
+    setup?: boolean;
+    timeout?: number;
+}): Promise<void>;
+export declare function verificationCollectCommand(options: {
+    scenario?: string;
+    json?: boolean;
+}): Promise<void>;
+export declare function verificationCheckSafetyCommand(options: {
+    json?: boolean;
+}): Promise<void>;