@haystackeditor/cli 0.3.0 → 0.4.0

package/dist/commands/init.js

@@ -8,9 +8,15 @@ import chalk from 'chalk';
 import * as path from 'path';
 import { detectProject } from '../utils/detect.js';
 import { saveConfig, configExists } from '../utils/config.js';
-import { createSkillFile } from '../utils/skill.js';
+import { createSkillFile, createClaudeCommand } from '../utils/skill.js';
 import { validateConfigSecurity, formatSecurityReport } from '../utils/secrets.js';
 export async function initCommand(options) {
+    // Auto-use defaults when not in interactive terminal (e.g., when run by AI agents)
+    const isInteractive = process.stdin.isTTY && process.stdout.isTTY;
+    if (!isInteractive && !options.yes) {
+        console.log(chalk.dim('Non-interactive mode detected. Using --yes defaults.\n'));
+        options.yes = true;
+    }
     console.log(chalk.cyan('\n🌾 Haystack Setup Wizard\n'));
     // Check if config already exists
     if (await configExists()) {
@@ -50,10 +56,27 @@ export async function initCommand(options) {
         console.log(chalk.green(`✓ Created ${configPath}`));
         // Create skill file for agent discovery
         const skillPath = await createSkillFile();
-        console.log(chalk.green(`✓ Created ${skillPath}\n`));
+        console.log(chalk.green(`✓ Created ${skillPath}`));
+        // Create Claude Code slash command
+        const commandPath = await createClaudeCommand();
+        console.log(chalk.green(`✓ Created ${commandPath} (use /haystack in Claude Code)\n`));
         // Security validation
         await runSecurityCheck(configPath);
-        printNextSteps();
+        // Explain purpose and next steps
+        console.log(chalk.cyan('━'.repeat(70)));
+        console.log(chalk.cyan.bold('\n📋 WHAT IS HAYSTACK?\n'));
+        console.log(chalk.white('When a PR is opened, Haystack spins up your app in a sandbox and'));
+        console.log(chalk.white('an AI agent verifies the changes work correctly by:\n'));
+        console.log(chalk.white('  • Frontend: Navigating pages, clicking buttons, taking screenshots'));
+        console.log(chalk.white('  • Backend: Calling API endpoints, checking responses\n'));
+        console.log(chalk.white('The "flows" in .haystack.yml tell the agent WHAT to verify.\n'));
+        console.log(chalk.cyan.bold('⚠️  ACTION REQUIRED:\n'));
+        console.log(chalk.white('The config above only has dev server settings. You MUST add flows.\n'));
+        console.log(chalk.white.bold('1. Run: cat .agents/skills/haystack.md'));
+        console.log(chalk.white.bold('2. Read the "Codebase Discovery Guide" section'));
+        console.log(chalk.white.bold('3. Follow it to discover features and add flows to .haystack.yml\n'));
+        console.log(chalk.dim('Without flows, Haystack has nothing to verify.\n'));
+        console.log(chalk.cyan('━'.repeat(70)));
         return;
     }
     // Interactive prompts

package/dist/utils/skill.d.ts

@@ -1,4 +1,10 @@
 /**
  * Create the .agents/skills/haystack.md file for agent discovery
+ * and .claude/commands/haystack.md for Claude Code slash command
  */
 export declare function createSkillFile(): Promise<string>;
+/**
+ * Create the .claude/commands/haystack.md file for Claude Code slash command
+ * Users can invoke with /haystack to start the setup wizard
+ */
+export declare function createClaudeCommand(): Promise<string>;

package/dist/utils/skill.js

@@ -1,11 +1,161 @@
 /**
  * Create the .agents/skills/haystack.md file for agent discovery
+ * and .claude/commands/haystack.md for Claude Code slash command
  */
 import * as fs from 'fs/promises';
 import * as path from 'path';
+/**
+ * Claude Code slash command - invoked with /haystack
+ * This is the "one command" entry point for users.
+ * Uses task decomposition - complete one step, validate, then next step.
+ */
+const CLAUDE_COMMAND_CONTENT = `# Set Up Haystack Verification
+
+You are setting up Haystack PR verification. Complete each step IN ORDER. Do NOT skip ahead.
+
+---
+
+## STEP 1: Initialize config
+
+\`\`\`bash
+npx @haystackeditor/cli init --yes
+\`\`\`
+
+✅ **Checkpoint**: \`.haystack.yml\` exists with dev_server config.
+
+---
+
+## STEP 2: Discover all routes
+
+Find every route in the app:
+\`\`\`bash
+grep -r "path=\\|Route\\|<Link" src/ --include="*.tsx" | head -30
+ls src/pages/ src/app/ 2>/dev/null
+\`\`\`
+
+Add a flow for EACH route to \`.haystack.yml\`. Use \`trigger: always\` for main pages, \`trigger: on_change\` with \`watch_patterns\` for others.
+
+✅ **Checkpoint**: Count your flows. You should have one for every route.
+
+---
+
+## STEP 3: Fix ALL selectors (CRITICAL)
+
+⛔ **STOP**: Look at every \`wait_for\` selector in your flows.
+
+If ANY selector is \`#root\`, \`div\`, or \`h1\`, you MUST fix it now:
+\`\`\`bash
+# Find specific selectors in the codebase
+grep -r "data-testid\\|className=" src/components/ --include="*.tsx" | head -20
+\`\`\`
+
+Replace generic selectors with specific ones:
+- \`[data-testid='dashboard']\`
+- \`.dashboard-content\`
+- \`[role='main']\`
+
+✅ **Checkpoint**: Run \`grep "wait_for" .haystack.yml\` - NONE should have \`#root\`.
+
+---
+
+## STEP 4: Add 3+ interactive flows (REQUIRED)
+
+Find interactive elements:
+\`\`\`bash
+grep -r "onClick\\|Modal\\|Dialog\\|toggle\\|Switch" src/ --include="*.tsx" | head -20
+\`\`\`
+
+Add AT LEAST 3 flows with \`click\` or \`type\` actions:
+
+\`\`\`yaml
+- name: "Theme toggle works"
+  steps:
+    - action: navigate
+      url: "/"
+    - action: click
+      selector: "[data-testid='theme-toggle']"
+    - action: screenshot
+      name: "after-toggle"
+
+- name: "Modal opens"
+  steps:
+    - action: navigate
+      url: "/dashboard"
+    - action: click
+      selector: "button[aria-label='Settings']"
+    - action: wait_for
+      selector: "[role='dialog']"
+    - action: screenshot
+      name: "modal-open"
+\`\`\`
+
+✅ **Checkpoint**: Run \`grep -c "action: click" .haystack.yml\` - must be ≥3.
+
+---
+
+## STEP 5: Add fixtures for data-dependent pages
+
+Find pages that fetch data:
+\`\`\`bash
+grep -r "useParams\\|fetch(\\|useQuery" src/ --include="*.tsx" | head -10
+\`\`\`
+
+For each data-dependent page, add fixtures:
+\`\`\`yaml
+fixtures:
+  - pattern: "/api/user/*"
+    source: "https://staging.example.com/api/user/demo"
+  - pattern: "/api/pr/*"
+    source: "file://fixtures/sample-pr.json"
+\`\`\`
+
+✅ **Checkpoint**: Every page with \`:id\` or API calls has a fixture.
+
+---
+
+## STEP 6: Final validation
+
+Count and verify:
+\`\`\`bash
+echo "=== Selector check (should be 0 #root) ==="
+grep "#root" .haystack.yml | wc -l
+
+echo "=== Interactive flows (should be ≥3) ==="
+grep -c "action: click\\|action: type" .haystack.yml
+
+echo "=== Fixtures (should be >0 for data pages) ==="
+grep -c "pattern:" .haystack.yml
+\`\`\`
+
+If any check fails, GO BACK to that step and fix it.
+
+---
+
+## STEP 7: Commit
+
+\`\`\`bash
+git add .haystack.yml .agents/ .claude/ fixtures/
+git commit -m "Add Haystack verification"
+\`\`\`
+
+🎉 Done!
+`;
 const SKILL_CONTENT = `# Haystack Verification
 
-Haystack provides automated PR verification. When a PR is opened, an AI agent spins up the app in a sandbox and verifies changes work correctly.
+## What is Haystack?
+
+Haystack provides **automated PR verification**. When a PR is opened:
+
+1. A sandbox spins up with your app running (dev server + any backend services)
+2. An AI agent reads the "flows" in \`.haystack.yml\`
+3. The agent executes each flow to verify changes work correctly
+4. Results (screenshots, API responses, errors) are posted to the PR
+
+**Frontend flows**: The agent uses a browser to navigate pages, click buttons, fill forms, and take screenshots. This catches visual regressions and broken interactions.
+
+**Backend flows**: The agent makes HTTP requests to API endpoints and verifies responses. This catches broken endpoints and API contract changes.
+
+**Without flows, Haystack has nothing to verify.** The config's \`dev_server\` settings just tell it how to start your app - the flows tell it what to actually test.
 
 ## Setup Workflow
 
@@ -237,6 +387,263 @@ Most apps need auth bypassed for testing. Common patterns:
 | Rails | \`SKIP_AUTH=true\` |
 
 Add to \`dev_server.env\` or \`services.*.env\` in your config.
+
+## Codebase Discovery Guide
+
+**Follow these steps to create comprehensive verification flows.**
+
+### ⚠️ REQUIRED CHECKLIST - Complete ALL items before finishing:
+
+1. [ ] **Page flows**: Every route in the app has a flow
+2. [ ] **Specific selectors**: Using \`[data-testid='x']\` or \`.specific-class\`, NOT \`#root\` or \`div\`
+3. [ ] **Interactive flows**: At least 3 flows that click buttons, open modals, or submit forms
+4. [ ] **Fixtures**: Pages with \`:id\` params or API fetches have fixtures (staging URL or local file)
+5. [ ] **Backend API flows**: If app has API endpoints, add http_request flows to test them
+6. [ ] **Watch patterns**: Each flow's \`watch_patterns\` matches the component file paths
+
+**You are NOT done until all 6 items are checked.**
+
+---
+
+### Step 1: Trace the Component Tree
+
+Start from the entry point and trace imports to discover ALL features:
+
+\`\`\`bash
+# Find the entry point
+cat src/main.tsx  # or src/index.tsx, pages/_app.tsx, etc.
+
+# Trace the router to find all routes
+grep -r "Route\|path=" src/ --include="*.tsx"
+
+# Find all page/feature components
+ls src/pages/ src/components/ src/features/
+\`\`\`
+
+### Step 2: Find Good Selectors
+
+**DON'T use generic selectors like \`#root\`.** The agent needs specific selectors to know the page loaded correctly.
+
+Priority order for selectors:
+1. \`[data-testid='feature-name']\` - Best, explicit test hooks
+2. \`[role='main']\`, \`[role='navigation']\` - Semantic roles
+3. \`.feature-specific-class\` - Component-specific classes
+4. \`h1\`, \`.page-title\` - Unique page identifiers
+
+**How to find selectors:**
+\`\`\`bash
+# Search for data-testid attributes
+grep -r "data-testid" src/ --include="*.tsx"
+
+# Search for unique classNames in a component
+grep -r "className=" src/components/Dashboard.tsx
+
+# Look for page-specific elements
+grep -r "<h1\|<header\|role=" src/pages/
+\`\`\`
+
+**Example - BAD vs GOOD:**
+\`\`\`yaml
+# BAD - too generic, every page has #root
+- action: wait_for
+  selector: "#root"
+
+# GOOD - specific to this feature
+- action: wait_for
+  selector: "[data-testid='dashboard-content']"
+# or
+- action: wait_for
+  selector: ".dashboard-stats-grid"
+# or
+- action: wait_for
+  selector: "h1:has-text('Dashboard')"
+\`\`\`
+
+### Step 3: Add Interactive Flows
+
+Don't just screenshot static pages. Verify that interactions work:
+
+**Look for interactive elements:**
+\`\`\`bash
+# Find buttons and clickable elements
+grep -r "onClick\|button\|Button" src/ --include="*.tsx"
+
+# Find modals and dialogs
+grep -r "Modal\|Dialog\|Drawer" src/ --include="*.tsx"
+
+# Find forms
+grep -r "<form\|onSubmit\|handleSubmit" src/ --include="*.tsx"
+
+# Find toggles and switches
+grep -r "toggle\|Switch\|theme" src/ --include="*.tsx"
+\`\`\`
+
+**Example interactive flows:**
+\`\`\`yaml
+# Theme toggle
+- name: "Theme toggle works"
+  steps:
+    - action: navigate
+      url: "/"
+    - action: click
+      selector: "[data-testid='theme-toggle']"
+    - action: screenshot
+      name: "dark-mode"
+    - action: click
+      selector: "[data-testid='theme-toggle']"
+    - action: screenshot
+      name: "light-mode"
+
+# Modal open/close
+- name: "Settings modal opens"
+  steps:
+    - action: navigate
+      url: "/dashboard"
+    - action: click
+      selector: "[aria-label='Settings']"
+    - action: wait_for
+      selector: "[role='dialog']"
+    - action: screenshot
+      name: "settings-modal"
+
+# Form submission
+- name: "Contact form submits"
+  steps:
+    - action: navigate
+      url: "/contact"
+    - action: type
+      selector: "input[name='email']"
+      value: "test@example.com"
+    - action: click
+      selector: "button[type='submit']"
+    - action: wait_for
+      selector: ".success-message"
+\`\`\`
+
+### Step 4: Handle Data-Dependent Pages
+
+**How to identify pages that need fixtures:**
+\`\`\`bash
+# Find components that fetch data
+grep -r "useQuery\|useSWR\|fetch(\|axios\|useEffect.*fetch" src/ --include="*.tsx"
+
+# Find API route parameters (these pages need data)
+grep -r "useParams\|router.query\|\[.*\]" src/pages/ src/app/ --include="*.tsx"
+\`\`\`
+
+If a page has \`:id\`, \`:slug\`, or fetches from \`/api/*\`, it needs fixtures.
+
+**Option A: Pull from staging (recommended for large/dynamic data)**
+\`\`\`yaml
+fixtures:
+  # Pull real data from staging API
+  - pattern: "/api/pr/*"
+    source: "https://staging.example.com/api/pr/sample"
+    headers:
+      Authorization: "Bearer $STAGING_TOKEN"
+
+  # Or from S3 bucket
+  - pattern: "/api/analytics/*"
+    source: "s3://my-fixtures-bucket/analytics-sample.json"
+\`\`\`
+
+**Option B: Commit small fixture files**
+For small, stable data only:
+\`\`\`bash
+mkdir -p fixtures
+cat > fixtures/user.json << 'EOF'
+{"id": 1, "name": "Test User", "email": "test@example.com"}
+EOF
+\`\`\`
+
+\`\`\`yaml
+fixtures:
+  - pattern: "/api/user"
+    source: "file://fixtures/user.json"
+\`\`\`
+
+**When to use each:**
+| Data Type | Use |
+|-----------|-----|
+| User profiles, settings | Local file (small, stable) |
+| PR data, analytics, lists | Staging API or S3 (large, dynamic) |
+| Auth tokens, sessions | Passthrough or mock inline |
+
+**Option B: Use demo/example routes**
+\`\`\`bash
+# Look for demo or example routes in the router
+grep -r "demo\|example\|sample" src/ --include="*.tsx"
+\`\`\`
+
+**Option C: Use real test data**
+If the app has seeded test data, use those identifiers:
+\`\`\`yaml
+- name: "PR review page loads"
+  steps:
+    - action: navigate
+      url: "/review/test-org/test-repo/1"  # Known test PR
+    - action: wait_for
+      selector: "[data-testid='pr-diff']"
+\`\`\`
+
+### Step 5: Add Backend API Flows (if applicable)
+
+If the app has API endpoints, test them directly:
+
+\`\`\`bash
+# Find API routes
+ls src/api/ app/api/ pages/api/ 2>/dev/null
+grep -r "app.get\|app.post\|router.get" --include="*.ts"
+\`\`\`
+
+**Example API flows:**
+\`\`\`yaml
+flows:
+  - name: "API health check"
+    description: "Verify API server responds"
+    trigger: always
+    steps:
+      - action: http_request
+        method: GET
+        url: "http://localhost:3001/health"
+      - action: assert_status
+        status: 200
+
+  - name: "API returns valid data"
+    trigger: on_change
+    watch_patterns:
+      - "src/api/**"
+    steps:
+      - action: http_request
+        method: GET
+        url: "http://localhost:3001/api/users"
+      - action: assert_status
+        status: 200
+\`\`\`
+
+### Step 6: Verify Your Flows
+
+After adding flows, validate the config:
+\`\`\`bash
+# Check YAML syntax
+npx @haystackeditor/cli validate
+
+# Or manually check
+cat .haystack.yml | head -50
+\`\`\`
+
+### ✅ Final Checklist (ALL required):
+
+Before you finish, verify:
+
+1. [ ] **Page flows**: Every route has a flow
+2. [ ] **Specific selectors**: All use \`[data-testid='x']\` or \`.class-name\`, NOT \`#root\`/\`div\`/\`h1\`
+3. [ ] **Interactive flows**: At least 3 flows with \`click\` or \`type\` actions
+4. [ ] **Fixtures configured**: Data-dependent pages have fixtures (staging URL preferred, or local JSON)
+5. [ ] **Backend API flows**: API endpoints have \`http_request\` flows (if app has backend)
+6. [ ] **Watch patterns**: Each \`watch_patterns\` matches component file paths
+
+⚠️ **If you have 0 interactive flows or 0 fixtures for data pages, you are not done.**
 `;
 export async function createSkillFile() {
     const skillDir = path.join(process.cwd(), '.agents', 'skills');
@@ -247,3 +654,16 @@ export async function createSkillFile() {
     await fs.writeFile(skillPath, SKILL_CONTENT, 'utf-8');
     return skillPath;
 }
+/**
+ * Create the .claude/commands/haystack.md file for Claude Code slash command
+ * Users can invoke with /haystack to start the setup wizard
+ */
+export async function createClaudeCommand() {
+    const commandDir = path.join(process.cwd(), '.claude', 'commands');
+    const commandPath = path.join(commandDir, 'haystack.md');
+    // Create directory if needed
+    await fs.mkdir(commandDir, { recursive: true });
+    // Write command file
+    await fs.writeFile(commandPath, CLAUDE_COMMAND_CONTENT, 'utf-8');
+    return commandPath;
+}

package/package.json

@@ -1,11 +1,17 @@
 {
   "name": "@haystackeditor/cli",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Set up Haystack verification for your project",
   "type": "module",
   "bin": {
     "haystack": "./dist/index.js"
   },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "node dist/index.js",
+    "prepublishOnly": "npm run build"
+  },
   "keywords": [
     "haystack",
     "verification",
@@ -42,10 +48,5 @@
   ],
   "engines": {
     "node": ">=18"
-  },
-  "scripts": {
-    "build": "tsc",
-    "dev": "tsc --watch",
-    "start": "node dist/index.js"
   }
-}
+}