@haystackeditor/cli 0.8.1 → 0.10.0

package/dist/assets/skills/submit.md

@@ -0,0 +1,154 @@
+# Submit PR via Haystack
+
+**Your job**: Submit your changes as a PR using `haystack submit` instead of `gh pr create` or GitHub API.
+
+---
+
+## Why Use Haystack Submit?
+
+When you create PRs through Haystack, they enter the **auto-merge queue**:
+
+1. **Haystack analyzes** your changes automatically
+2. **If approved**: PR is marked ready-to-merge and merged automatically
+3. **If issues found**: PR is routed for review with detailed feedback
+
+This is faster than waiting for human review on every change.
+
+---
+
+## Command Reference
+
+```bash
+# Default: Submit to auto-merge queue
+haystack submit
+
+# Request Haystack review (for complex/risky changes)
+haystack submit --review
+
+# With custom title
+haystack submit --title "Fix authentication bug"
+
+# Target different base branch
+haystack submit --base develop
+
+# With markdown PR body (write to file first to preserve formatting)
+cat > /tmp/pr-body.md << 'EOF'
+## Summary
+- Fixed authentication bug in session handling
+- Added integration tests for token refresh
+
+## Test plan
+- [x] Auth flow works end-to-end
+EOF
+haystack submit --body-file /tmp/pr-body.md
+```
+
+> **Tip**: Always use `--body-file` instead of `--body` when the description contains markdown.
+> The `--body` flag is a single CLI argument that mangles newlines and special characters (`#`, `*`, etc.).
+
+---
+
+## When to Use Each Mode
+
+### Auto-Merge (Default)
+
+Use for straightforward changes that don't need human review:
+
+- Bug fixes with clear scope
+- Small features with tests
+- Refactoring with no behavior change
+- Documentation updates
+- Dependency updates
+
+```bash
+haystack submit
+```
+
+### Review Mode
+
+> **Do NOT use `--review` unless the user explicitly asks for human review.**
+> The default auto-merge queue already runs full Haystack analysis. Using `--review`
+> blocks auto-merge until a human approves, which delays merging unnecessarily.
+
+Use `--review` only when the user specifically requests human review:
+
+- User says "get someone to review this" or "needs human eyes"
+- User explicitly passes `--review` in their instructions
+
+```bash
+haystack submit --review
+```
+
+---
+
+## Workflow
+
+1. **Make your changes** on a feature branch
+2. **Commit** your changes: `git add . && git commit -m "..."`
+3. **Submit** via Haystack: `haystack submit`
+
+Haystack will:
+- Create a `haystack/<your-branch>` branch
+- Push to origin
+- Create the PR with appropriate labels
+- Trigger analysis automatically
+
+---
+
+## Prerequisites
+
+Before using `haystack submit`, ensure you're logged in:
+
+```bash
+haystack login
+```
+
+This uses GitHub device flow - no tokens to copy/paste.
+
+---
+
+## Important Notes
+
+- **Always use `haystack submit`** instead of `gh pr create` when working in Haystack-enabled repos
+- The command creates a `haystack/` prefixed branch automatically
+- 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
+
+---
+
+## Example Session
+
+```
+Agent: I've fixed the authentication bug. Let me submit this as a PR.
+
+$ haystack submit --title "Fix session expiry handling"
+
+Haystack Submit
+
+✓ Authenticated
+✓ Repository: acme/webapp
+  Current branch: fix-auth
+  Base branch: main
+  Submission type: Auto-merge queue
+
+Creating branch haystack/fix-auth...
+✓ Created branch: haystack/fix-auth
+✓ Branch pushed
+✓ Pull request created: #142
+✓ Applied label: haystack:auto-merge
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Pull Request Created!
+
+  URL:    https://github.com/acme/webapp/pull/142
+  Title:  Fix session expiry handling
+  Branch: haystack/fix-auth → main
+  Type:   Auto-merge queue
+  Label:  haystack:auto-merge
+
+Haystack will analyze this PR and:
+  • Auto-merge if approved
+  • Route for review if issues found
+```

package/dist/assets/templates/CLAUDE.md.snippet

@@ -0,0 +1,42 @@
+# Haystack Verification
+
+This project uses Haystack for PR verification. Configuration is in `.haystack.yml`.
+
+## For the AI Agent
+
+When making changes to this codebase:
+
+1. **After completing changes**, run verification:
+   - Use the `haystack_get_verify_targets` tool to see what URLs to check
+   - Use `haystack_get_auth_config` to get auth bypass instructions
+   - Start the dev server with auth bypass env vars
+   - Navigate to each verification URL and confirm it loads
+
+2. **If `.haystack.yml` doesn't exist**, help the user create one:
+   - Use `haystack_setup_start` to begin the wizard
+   - Ask each question and call `haystack_setup_answer` with responses
+
+3. **Fixture data** is available via `haystack_load_fixtures`:
+   - This loads test data from staging/local files
+   - Use this instead of real API calls when verifying
+
+## Quick Reference
+
+```yaml
+# .haystack.yml structure
+dev:
+  command: pnpm dev      # How to start dev server
+  port: 3000             # What port it runs on
+
+auth:
+  strategy: bypass       # How to skip auth
+  env: "SKIP_AUTH=true"  # Env var to set
+
+fixtures:                # Test data sources
+  - pattern: "/api/*"
+    source: "https://staging.example.com/api"
+
+verify:                  # Pages to check
+  - url: "/"
+    wait_for: "#app"
+```

package/dist/assets/templates/haystack.yml

@@ -0,0 +1,193 @@
+# =============================================================================
+# Haystack Verification Configuration
+# =============================================================================
+#
+# This file tells Haystack how to verify that PRs actually work.
+# When a PR is opened, Haystack spins up a sandbox with your code and
+# runs these verification flows to ensure changes work correctly.
+#
+# For setup help, run: /verify setup
+# =============================================================================
+
+name: my-saas-app
+
+# -----------------------------------------------------------------------------
+# Dev Server - How to run your app
+# -----------------------------------------------------------------------------
+dev:
+  command: pnpm dev
+  port: 3000
+  ready_pattern: "ready in"  # Pattern in stdout that means server is ready
+  cwd: "."                   # Working directory (relative to repo root)
+  env:
+    NODE_ENV: development
+
+# -----------------------------------------------------------------------------
+# Authentication - How to bypass/mock auth in the sandbox
+# -----------------------------------------------------------------------------
+auth:
+  strategy: bypass
+  env: "SKIP_AUTH=true"
+
+  # Other options:
+  # strategy: mock_token
+  # env: "AUTH_TOKEN"  # Set actual value as Haystack secret
+
+  # strategy: test_account
+  # username_env: "TEST_USER"
+  # password_env: "TEST_PASS"
+  # login_url: "/login"
+
+# -----------------------------------------------------------------------------
+# Fixtures - Where to get test data (so sandbox doesn't need real data)
+# -----------------------------------------------------------------------------
+fixtures:
+  # Pull user data from staging API
+  - pattern: "/api/users/*"
+    source: "https://staging.myapp.com/api/users"
+    headers:
+      Authorization: "Bearer $STAGING_API_TOKEN"
+
+  # Use local fixture file for config
+  - pattern: "/api/config"
+    source: "file://fixtures/config.json"
+
+  # Generate dashboard data dynamically
+  - pattern: "/api/dashboard"
+    source: "script://fixtures/generate-dashboard.ts"
+
+  # Let public endpoints go through
+  - pattern: "/api/public/*"
+    source: passthrough
+
+# -----------------------------------------------------------------------------
+# Verification Flows - What to actually test
+# -----------------------------------------------------------------------------
+# These are the flows the agent executes in the sandbox to verify PRs work.
+# Think of them like E2E tests, but run by an AI that can adapt and report.
+
+flows:
+  # ---------------------------------------------------------------------------
+  # Basic smoke test - runs on every PR
+  # ---------------------------------------------------------------------------
+  - name: "Homepage loads"
+    description: "Verify the homepage renders without errors"
+    trigger: always
+    steps:
+      - action: navigate
+        url: "/"
+      - action: wait_for
+        selector: "#app"
+        timeout_ms: 10000
+      - action: assert_no_errors
+        error_selectors:
+          - ".error-toast"
+          - ".error-modal"
+          - "[data-testid='error']"
+      - action: screenshot
+        name: "homepage"
+
+  # ---------------------------------------------------------------------------
+  # Dashboard flow - runs when dashboard files change
+  # ---------------------------------------------------------------------------
+  - name: "Dashboard functionality"
+    description: "Verify dashboard loads and displays data correctly"
+    trigger: on_change
+    watch_patterns:
+      - "src/components/dashboard/**"
+      - "src/pages/dashboard.tsx"
+    steps:
+      - action: navigate
+        url: "/dashboard"
+      - action: wait_for
+        selector: ".dashboard-grid"
+      - action: assert_exists
+        selector: ".metric-card"
+        message: "Dashboard should display metric cards"
+      - action: assert_text
+        selector: ".welcome-message"
+        contains: "Welcome"
+      - action: screenshot
+        name: "dashboard-loaded"
+      # Test interactivity
+      - action: click
+        selector: "[data-testid='refresh-button']"
+        description: "Click refresh button"
+      - action: wait_network_idle
+        timeout_ms: 5000
+      - action: assert_no_errors
+
+  # ---------------------------------------------------------------------------
+  # Settings flow - test form interactions
+  # ---------------------------------------------------------------------------
+  - name: "Settings page"
+    description: "Verify settings can be viewed and saved"
+    trigger: on_change
+    watch_patterns:
+      - "src/components/settings/**"
+      - "src/pages/settings.tsx"
+    steps:
+      - action: navigate
+        url: "/settings"
+      - action: wait_for
+        selector: "form.settings-form"
+      - action: screenshot
+        name: "settings-initial"
+      # Toggle dark mode
+      - action: click
+        selector: "#dark-mode-toggle"
+      - action: assert_exists
+        selector: "body.dark-mode"
+        message: "Dark mode should be applied"
+      - action: screenshot
+        name: "settings-dark-mode"
+      # Test form input
+      - action: type
+        selector: "#display-name"
+        text: "Test User"
+      - action: click
+        selector: "button[type='submit']"
+      - action: wait_network_idle
+      - action: assert_no_errors
+
+  # ---------------------------------------------------------------------------
+  # Checkout flow - critical path, always run
+  # ---------------------------------------------------------------------------
+  - name: "Checkout flow"
+    description: "Verify the complete checkout process works"
+    trigger: always
+    steps:
+      - action: navigate
+        url: "/products"
+      - action: wait_for
+        selector: ".product-grid"
+      - action: click
+        selector: ".product-card:first-child .add-to-cart"
+        description: "Add first product to cart"
+      - action: wait_for
+        selector: ".cart-count"
+      - action: assert_text
+        selector: ".cart-count"
+        contains: "1"
+      - action: navigate
+        url: "/cart"
+      - action: wait_for
+        selector: ".cart-items"
+      - action: click
+        selector: ".checkout-button"
+      - action: wait_for
+        selector: ".checkout-form"
+      - action: screenshot
+        name: "checkout-form"
+        compare_baseline: true  # Visual regression check
+
+# -----------------------------------------------------------------------------
+# Global Settings
+# -----------------------------------------------------------------------------
+settings:
+  default_timeout_ms: 10000
+  error_selectors:
+    - ".error-toast"
+    - ".error-boundary"
+    - "[role='alert'][aria-live='assertive']"
+  screenshot_each_step: false  # Set true for debugging

package/dist/commands/check-pending.d.ts

@@ -0,0 +1,19 @@
+/**
+ * check-pending command — Check status of pending Haystack analysis.
+ *
+ * Reads `.haystack/pending-submit.json`, polls the analysis API if needed,
+ * and outputs a two-state verdict:
+ *   - "Good to merge" (no issues)
+ *   - "Needs your input" (issues found)
+ *
+ * Output modes:
+ *   --hook    Minimal single-line for session-start hooks
+ *   --json    Machine-readable JSON
+ *   (default) Rich terminal output
+ */
+export interface CheckPendingOptions {
+    json?: boolean;
+    hook?: boolean;
+    clear?: boolean;
+}
+export declare function checkPendingCommand(options: CheckPendingOptions): Promise<void>;

package/dist/commands/check-pending.js

@@ -0,0 +1,217 @@
+/**
+ * check-pending command — Check status of pending Haystack analysis.
+ *
+ * Reads `.haystack/pending-submit.json`, polls the analysis API if needed,
+ * and outputs a two-state verdict:
+ *   - "Good to merge" (no issues)
+ *   - "Needs your input" (issues found)
+ *
+ * Output modes:
+ *   --hook    Minimal single-line for session-start hooks
+ *   --json    Machine-readable JSON
+ *   (default) Rich terminal output
+ */
+import chalk from 'chalk';
+import { loadPendingSubmit, updatePendingSubmit, clearPendingSubmit } from '../utils/pending-state.js';
+import { checkAnalysisReady, fetchAnalysisResults } from '../utils/analysis-api.js';
+import { findExistingPR } from '../utils/github-api.js';
+import { loadToken } from './login.js';
+// ============================================================================
+// Polling
+// ============================================================================
+const POLL_INTERVAL_MS = 3_000;
+const POLL_TIMEOUT_MS = 30_000;
+/**
+ * Poll the result endpoint until analysis is ready or timeout.
+ */
+async function waitForAnalysis(owner, repo, prNumber, timeoutMs, token) {
+    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 'completed';
+        if (result.status === 'error') {
+            consecutiveErrors++;
+            if (consecutiveErrors >= 5)
+                return 'failed';
+        }
+        else {
+            consecutiveErrors = 0;
+        }
+        await new Promise(r => setTimeout(r, POLL_INTERVAL_MS));
+    }
+    return 'pending';
+}
+// ============================================================================
+// Output formatting
+// ============================================================================
+function printHookOutput(pending) {
+    if (!pending.analysisResult) {
+        console.log(`[Haystack] PR #${pending.prNumber}: Analysis in progress...`);
+        return;
+    }
+    const result = pending.analysisResult;
+    if (result.state === 'good-to-merge') {
+        if (result.autoMerged) {
+            console.log(`[Haystack] \u2705 PR #${pending.prNumber} "${getBranchLabel(pending)}": Auto-merged`);
+        }
+        else {
+            console.log(`[Haystack] \u2705 PR #${pending.prNumber} "${getBranchLabel(pending)}": Good to merge`);
+        }
+    }
+    else {
+        const parts = [];
+        if (result.bugCount > 0)
+            parts.push(`${result.bugCount} bug(s)`);
+        if (result.ruleViolationCount > 0)
+            parts.push(`${result.ruleViolationCount} rule violation(s)`);
+        if (parts.length === 0)
+            parts.push(`${result.warningCount} warning(s)`);
+        console.log(`[Haystack] \u26A0\uFE0F  PR #${pending.prNumber} "${getBranchLabel(pending)}": Needs your input (${parts.join(', ')})`);
+        console.log(`  Review: ${result.reviewUrl}`);
+    }
+}
+function printRichOutput(pending) {
+    console.log(chalk.bold('\n' + '\u2501'.repeat(50)));
+    console.log(chalk.bold(`  Haystack Analysis: PR #${pending.prNumber}`));
+    console.log(chalk.bold('\u2501'.repeat(50) + '\n'));
+    console.log(`  ${chalk.dim('Branch:')}  ${pending.branch} \u2192 ${pending.baseBranch}`);
+    console.log(`  ${chalk.dim('URL:')}     ${chalk.cyan(pending.prUrl)}`);
+    if (!pending.analysisResult) {
+        if (pending.status === 'polling') {
+            console.log(`  ${chalk.dim('Status:')}  ${chalk.yellow('Analysis in progress...')}`);
+        }
+        else if (pending.status === 'failed') {
+            console.log(`  ${chalk.dim('Status:')}  ${chalk.red('Analysis failed')}`);
+        }
+        else if (pending.status === 'stale') {
+            console.log(`  ${chalk.dim('Status:')}  ${chalk.dim('Stale (submitted > 2h ago)')}`);
+        }
+        console.log('');
+        return;
+    }
+    const result = pending.analysisResult;
+    if (result.state === 'good-to-merge') {
+        if (result.autoMerged) {
+            console.log(`  ${chalk.dim('Verdict:')} ${chalk.green.bold('Auto-merged')}`);
+            console.log(`  ${chalk.dim('Issues:')}  ${chalk.green('None — PR was automatically merged')}`);
+        }
+        else {
+            console.log(`  ${chalk.dim('Verdict:')} ${chalk.green.bold('Good to merge')}`);
+            console.log(`  ${chalk.dim('Issues:')}  ${chalk.green('None')}`);
+        }
+    }
+    else {
+        console.log(`  ${chalk.dim('Verdict:')} ${chalk.yellow.bold('Needs your input')}`);
+        console.log(`  ${chalk.dim('Issues:')}  ${result.summary}`);
+        console.log('');
+        for (const issue of result.issues) {
+            const icon = issue.severity === 'error' ? chalk.red('\u2717') : chalk.yellow('!');
+            const loc = issue.line ? `${issue.file}:${issue.line}` : issue.file;
+            console.log(`  ${icon} ${chalk.dim(loc)} ${issue.message}`);
+        }
+    }
+    console.log(`\n  ${chalk.dim('Review:')} ${chalk.cyan(result.reviewUrl)}`);
+    console.log('');
+}
+function printJsonOutput(pending) {
+    const output = {
+        prNumber: pending.prNumber,
+        prUrl: pending.prUrl,
+        branch: pending.branch,
+        baseBranch: pending.baseBranch,
+        status: pending.status,
+        submittedAt: pending.submittedAt,
+        verdict: pending.analysisResult?.state || null,
+        bugCount: pending.analysisResult?.bugCount || 0,
+        warningCount: pending.analysisResult?.warningCount || 0,
+        ruleViolationCount: pending.analysisResult?.ruleViolationCount || 0,
+        summary: pending.analysisResult?.summary || null,
+        issues: pending.analysisResult?.issues || [],
+        reviewUrl: pending.analysisResult?.reviewUrl || null,
+        autoMerged: pending.analysisResult?.autoMerged || false,
+    };
+    console.log(JSON.stringify(output, null, 2));
+}
+function getBranchLabel(pending) {
+    return pending.branch.replace(/^refs\/heads\//, '');
+}
+// ============================================================================
+// Main command
+// ============================================================================
+export async function checkPendingCommand(options) {
+    // Handle --clear
+    if (options.clear) {
+        clearPendingSubmit();
+        if (!options.hook) {
+            console.log(chalk.dim('Pending submit state cleared.'));
+        }
+        return;
+    }
+    // Load pending state
+    const pending = loadPendingSubmit();
+    if (!pending) {
+        if (options.json) {
+            console.log(JSON.stringify({ status: 'none' }));
+        }
+        else if (!options.hook) {
+            // Silent for hook mode — no pending submits is fine
+            console.log(chalk.dim('No pending submits.\n'));
+        }
+        return;
+    }
+    // Load token for private repo auth (best-effort, don't block if unavailable)
+    const token = await loadToken() || undefined;
+    // If still polling, try to resolve it
+    if (pending.status === 'polling') {
+        // Quick check: is the PR still open?
+        try {
+            const pr = await findExistingPR(pending.owner, pending.repo, pending.branch);
+            if (!pr) {
+                // PR was closed or merged
+                updatePendingSubmit({ status: 'stale', resolvedAt: new Date().toISOString() });
+                pending.status = 'stale';
+            }
+        }
+        catch {
+            // Auth not available or API error — continue with polling
+        }
+        if (pending.status === 'polling') {
+            // For hook mode, do a single quick poll (no waiting)
+            const timeout = options.hook ? 5_000 : POLL_TIMEOUT_MS;
+            const result = await waitForAnalysis(pending.owner, pending.repo, pending.prNumber, timeout, token);
+            if (result === 'completed') {
+                // Fetch the actual analysis results
+                try {
+                    const verdict = await fetchAnalysisResults(pending.owner, pending.repo, pending.prNumber, token);
+                    updatePendingSubmit({
+                        status: 'completed',
+                        analysisResult: verdict,
+                        resolvedAt: new Date().toISOString(),
+                    });
+                    pending.status = 'completed';
+                    pending.analysisResult = verdict;
+                }
+                catch {
+                    // Could not fetch results — leave as polling
+                }
+            }
+            else if (result === 'failed') {
+                updatePendingSubmit({ status: 'failed', resolvedAt: new Date().toISOString() });
+                pending.status = 'failed';
+            }
+            // 'pending' — leave as-is for next check
+        }
+    }
+    // Output based on mode
+    if (options.json) {
+        printJsonOutput(pending);
+    }
+    else if (options.hook) {
+        printHookOutput(pending);
+    }
+    else {
+        printRichOutput(pending);
+    }
+}

package/dist/commands/config.d.ts

@@ -1,33 +1,25 @@
 /**
- * Config commands - manage user preferences stored on Haystack Platform
+ * Config commands - manage preferences
+ *
+ * Repo-level preferences (sandbox_enabled, auto_merge) are stored in .haystack.json.
+ * User-level preferences (agentic_tool) are stored on the Haystack Platform API.
  */
 type AgenticTool = 'opencode' | 'claude-code' | 'codex';
-/**
- * Get current sandbox status
- */
 export declare function getSandboxStatus(): Promise<void>;
-/**
- * Enable sandbox mode
- */
 export declare function enableSandbox(): Promise<void>;
-/**
- * Disable sandbox mode
- */
 export declare function disableSandbox(): Promise<void>;
-/**
- * Handle sandbox subcommand
- */
 export declare function handleSandbox(action?: string): Promise<void>;
-/**
- * Get current agentic tool setting
- */
 export declare function getAgenticToolStatus(): Promise<void>;
-/**
- * Set agentic tool preference
- */
 export declare function setAgenticTool(tool: AgenticTool): Promise<void>;
+export declare function handleAgenticTool(tool?: string): Promise<void>;
 /**
- * Handle agentic-tool subcommand
+ * Check if auto-merge is enabled for the current repo.
+ * Returns false if .haystack.json is missing or on error.
  */
-export declare function handleAgenticTool(tool?: string): Promise<void>;
+export declare function isAutoMergeEnabled(): Promise<boolean>;
+export declare function getAutoMergeStatus(): Promise<void>;
+export declare function enableAutoMerge(): Promise<void>;
+export declare function disableAutoMerge(): Promise<void>;
+export declare function handleAutoMerge(action?: string): Promise<void>;
+export declare function handleWaitForReviewers(action?: string, reviewers?: string[]): Promise<void>;
 export {};