@haystackeditor/cli 0.2.0

package/README.md

@@ -0,0 +1,202 @@
+# @haystackeditor/cli
+
+Unified CLI for Haystack verification, fixtures, and sandboxes.
+
+## Installation
+
+```bash
+# Global install
+npm install -g @haystackeditor/cli
+
+# Or run directly with npx
+npx @haystackeditor/cli init
+```
+
+## Commands
+
+### `haystack init`
+
+Interactive setup wizard to create `.haystack.yml` configuration:
+
+```bash
+haystack init              # Interactive wizard
+haystack init -y           # Accept all defaults
+```
+
+### `haystack login`
+
+Authenticate with Haystack via GitHub OAuth:
+
+```bash
+haystack login             # Opens browser for GitHub OAuth
+haystack login --token     # Use existing GitHub token
+haystack logout            # Clear stored credentials
+```
+
+### `haystack secrets`
+
+Manage secrets for fixtures and integrations:
+
+```bash
+haystack secrets list                # List all secrets
+haystack secrets set KEY value       # Set a secret
+haystack secrets delete KEY          # Delete a secret
+```
+
+Secrets are stored securely in the Haystack platform and referenced in `.haystack.yml` using `$VARIABLE` syntax.
+
+### `haystack record`
+
+Record API responses as fixtures:
+
+```bash
+haystack record https://api.example.com/data
+haystack record https://api.example.com/data --output fixtures/data.json
+```
+
+### `haystack verify`
+
+Run verification commands from `.haystack.yml`:
+
+```bash
+haystack verify                # Run all verification commands
+haystack verify -c build       # Run specific command
+haystack verify --dry-run      # Show commands without running
+```
+
+### `haystack dev`
+
+Start dev server with fixtures enabled:
+
+```bash
+haystack dev                   # Start dev server
+haystack dev -s frontend       # Start specific service (monorepo)
+haystack dev --no-fixtures     # Start without fixture loading
+```
+
+### `haystack sandbox`
+
+Manage Haystack sandboxes:
+
+```bash
+haystack sandbox create        # Create sandbox for current branch
+haystack sandbox status        # Check sandbox status
+haystack sandbox open          # Open sandbox in browser
+haystack sandbox logs          # Stream sandbox logs
+haystack sandbox destroy       # Destroy sandbox
+```
+
+### `haystack mcp`
+
+Run as MCP server for Claude Code integration:
+
+```bash
+# Add to Claude Code
+claude mcp add haystack -- npx @haystackeditor/cli mcp
+```
+
+## Configuration
+
+Create `.haystack.yml` in your project root:
+
+### Simple Project
+
+```yaml
+version: "1"
+name: my-app
+
+dev_server:
+  command: pnpm dev
+  port: 3000
+  ready_pattern: "Local:"
+  env:
+    SKIP_AUTH: "true"
+
+verification:
+  commands:
+    - name: build
+      run: pnpm build
+    - name: lint
+      run: pnpm lint
+    - name: typecheck
+      run: pnpm tsc --noEmit
+```
+
+### Monorepo
+
+```yaml
+version: "1"
+name: my-monorepo
+
+services:
+  frontend:
+    command: pnpm dev
+    port: 3000
+    ready_pattern: "Local:"
+    env:
+      SKIP_AUTH: "true"
+
+  api:
+    root: packages/api
+    command: pnpm dev
+    port: 8080
+    ready_pattern: "listening"
+
+  worker:
+    root: infra/worker
+    command: pnpm dev
+    ready_pattern: "Ready"
+
+  analysis:
+    root: packages/analysis
+    type: batch
+    command: pnpm start
+
+verification:
+  commands:
+    - name: build
+      run: pnpm build
+    - name: test
+      run: pnpm test
+
+  fixtures:
+    "*/api/github/*":
+      source: file://fixtures/github-api.json
+
+    "*/api/analysis/*":
+      source: pr://haystackeditor/example-repo/42
+```
+
+## Fixtures
+
+Fixtures mock external API responses during development and testing. Sources:
+
+| Prefix | Description |
+|--------|-------------|
+| `file://` | Local JSON file |
+| `https://` | Remote URL (cached) |
+| `s3://` | AWS S3 bucket |
+| `r2://` | Cloudflare R2 bucket |
+| `pr://owner/repo/number` | Haystack PR analysis data |
+| `recorded://id` | Previously recorded fixture |
+| `passthrough` | Don't intercept, let request through |
+
+### Using Secrets in Fixtures
+
+```yaml
+fixtures:
+  "*/api/private/*":
+    source: s3://my-bucket/fixtures/data.json
+    headers:
+      Authorization: Bearer $AWS_TOKEN
+```
+
+Set the secret:
+
+```bash
+haystack secrets set AWS_TOKEN "your-token-here"
+```
+
+## License
+
+MIT

package/dist/commands/init.d.ts

@@ -0,0 +1,10 @@
+/**
+ * haystack init - Interactive setup wizard
+ *
+ * Creates .haystack.yml with auto-detected settings.
+ */
+interface InitOptions {
+    yes?: boolean;
+}
+export declare function initCommand(options: InitOptions): Promise<void>;
+export {};

package/dist/commands/init.js

@@ -0,0 +1,299 @@
+/**
+ * haystack init - Interactive setup wizard
+ *
+ * Creates .haystack.yml with auto-detected settings.
+ */
+import inquirer from 'inquirer';
+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 { validateConfigSecurity, formatSecurityReport } from '../utils/secrets.js';
+export async function initCommand(options) {
+    console.log(chalk.cyan('\n🌾 Haystack Setup Wizard\n'));
+    // Check if config already exists
+    if (await configExists()) {
+        const { overwrite } = await inquirer.prompt([
+            {
+                type: 'confirm',
+                name: 'overwrite',
+                message: '.haystack.yml already exists. Overwrite?',
+                default: false,
+            },
+        ]);
+        if (!overwrite) {
+            console.log(chalk.yellow('Setup cancelled.'));
+            return;
+        }
+    }
+    // Detect project
+    console.log(chalk.dim('Detecting project configuration...\n'));
+    const detected = await detectProject();
+    // Show what was detected
+    console.log(chalk.green('✓ Detected:'));
+    console.log(`  Package manager: ${chalk.bold(detected.packageManager)}`);
+    if (detected.framework) {
+        console.log(`  Framework: ${chalk.bold(detected.framework)}`);
+    }
+    if (detected.isMonorepo) {
+        console.log(`  Monorepo: ${chalk.bold(detected.monorepoTool || 'yes')}`);
+        if (detected.services?.length) {
+            console.log(`  Services: ${chalk.bold(detected.services.map((s) => s.name).join(', '))}`);
+        }
+    }
+    console.log('');
+    // If --yes flag, use all defaults
+    if (options.yes) {
+        const config = buildConfigFromDetection(detected);
+        const configPath = await saveConfig(config);
+        console.log(chalk.green(`✓ Created ${configPath}`));
+        // Create skill file for agent discovery
+        const skillPath = await createSkillFile();
+        console.log(chalk.green(`✓ Created ${skillPath}\n`));
+        // Security validation
+        await runSecurityCheck(configPath);
+        printNextSteps();
+        return;
+    }
+    // Interactive prompts
+    const answers = await inquirer.prompt([
+        {
+            type: 'input',
+            name: 'name',
+            message: 'Project name:',
+            default: path.basename(process.cwd()),
+        },
+        {
+            type: 'confirm',
+            name: 'isMonorepo',
+            message: 'Is this a monorepo with multiple services?',
+            default: detected.isMonorepo,
+        },
+    ]);
+    let config;
+    if (answers.isMonorepo) {
+        config = await configureMonorepo(detected, answers.name);
+    }
+    else {
+        config = await configureSingleService(detected, answers.name);
+    }
+    // Verification commands
+    const { commands } = await inquirer.prompt([
+        {
+            type: 'input',
+            name: 'commands',
+            message: 'Verification commands (comma-separated):',
+            default: `${detected.packageManager} build, ${detected.packageManager} lint, ${detected.packageManager} tsc --noEmit`,
+        },
+    ]);
+    config.verification = {
+        commands: commands
+            .split(',')
+            .map((cmd) => cmd.trim())
+            .filter(Boolean)
+            .map((cmd) => {
+            const name = cmd.split(' ').pop() || cmd;
+            return { name, run: cmd };
+        }),
+    };
+    // Save config
+    const configPath = await saveConfig(config);
+    console.log(chalk.green(`✓ Created ${configPath}`));
+    // Create skill file for agent discovery
+    const skillPath = await createSkillFile();
+    console.log(chalk.green(`✓ Created ${skillPath}\n`));
+    // Show the generated config
+    console.log(chalk.dim('Generated configuration:'));
+    console.log(chalk.dim('─'.repeat(40)));
+    const yaml = await import('yaml');
+    console.log(yaml.stringify(config));
+    console.log(chalk.dim('─'.repeat(40)));
+    // Security validation
+    await runSecurityCheck(configPath);
+    printNextSteps();
+}
+/**
+ * Run security check on config file
+ */
+async function runSecurityCheck(configPath) {
+    const { safe, findings } = await validateConfigSecurity(configPath);
+    if (!safe) {
+        console.log(chalk.yellow('\n⚠️  Security Warning:\n'));
+        console.log(formatSecurityReport(findings));
+        console.log(chalk.yellow('Please remove hardcoded secrets before committing.\n'));
+    }
+    else if (findings.length > 0) {
+        console.log(chalk.dim('\n' + formatSecurityReport(findings)));
+    }
+}
+async function configureSingleService(detected, name) {
+    const answers = await inquirer.prompt([
+        {
+            type: 'input',
+            name: 'command',
+            message: 'Dev server command:',
+            default: detected.suggestedDevCommand,
+        },
+        {
+            type: 'number',
+            name: 'port',
+            message: 'Dev server port:',
+            default: detected.suggestedPort,
+        },
+        {
+            type: 'input',
+            name: 'readyPattern',
+            message: 'Ready pattern (stdout text when server is ready):',
+            default: detected.suggestedReadyPattern,
+        },
+        {
+            type: 'input',
+            name: 'authBypass',
+            message: 'Auth bypass env var (leave blank if no auth):',
+            default: detected.suggestedAuthBypass,
+        },
+    ]);
+    const env = {};
+    if (answers.authBypass) {
+        const [key, value] = answers.authBypass.split('=');
+        env[key] = value || 'true';
+    }
+    return {
+        version: '1',
+        name,
+        dev_server: {
+            command: answers.command,
+            port: answers.port,
+            ready_pattern: answers.readyPattern,
+            ...(Object.keys(env).length > 0 ? { env } : {}),
+        },
+    };
+}
+async function configureMonorepo(detected, name) {
+    // Get list of services
+    const detectedServices = detected.services || [];
+    const serviceNames = detectedServices.map((s) => s.name);
+    const { selectedServices } = await inquirer.prompt([
+        {
+            type: 'checkbox',
+            name: 'selectedServices',
+            message: 'Which services should the sandbox run?',
+            choices: serviceNames.length > 0 ? serviceNames : ['frontend', 'api'],
+            default: serviceNames,
+        },
+    ]);
+    // Ask about auth bypass
+    const { authBypass } = await inquirer.prompt([
+        {
+            type: 'input',
+            name: 'authBypass',
+            message: 'Auth bypass env var (applied to all services):',
+            default: detected.suggestedAuthBypass,
+        },
+    ]);
+    const services = {};
+    for (const serviceName of selectedServices) {
+        const detectedService = detectedServices.find((s) => s.name === serviceName);
+        console.log(chalk.dim(`\nConfiguring ${serviceName}...`));
+        const answers = await inquirer.prompt([
+            {
+                type: 'input',
+                name: 'root',
+                message: `  Directory:`,
+                default: detectedService?.root || './',
+            },
+            {
+                type: 'input',
+                name: 'command',
+                message: `  Command:`,
+                default: detectedService?.suggestedCommand || `${detected.packageManager} dev`,
+            },
+            {
+                type: 'list',
+                name: 'type',
+                message: `  Type:`,
+                choices: ['server', 'batch'],
+                default: detectedService?.type || 'server',
+            },
+            {
+                type: 'number',
+                name: 'port',
+                message: `  Port:`,
+                default: detectedService?.suggestedPort || 3000,
+                when: (ans) => ans.type === 'server',
+            },
+        ]);
+        const env = {};
+        if (authBypass) {
+            const [key, value] = authBypass.split('=');
+            env[key] = value || 'true';
+        }
+        services[serviceName] = {
+            ...(answers.root !== './' ? { root: answers.root } : {}),
+            command: answers.command,
+            ...(answers.type === 'server' ? { port: answers.port } : { type: 'batch' }),
+            ready_pattern: 'ready|started|listening|Local:',
+            ...(Object.keys(env).length > 0 ? { env } : {}),
+        };
+    }
+    return {
+        version: '1',
+        name,
+        services,
+    };
+}
+function buildConfigFromDetection(detected) {
+    const env = {};
+    if (detected.suggestedAuthBypass) {
+        const [key, value] = detected.suggestedAuthBypass.split('=');
+        env[key] = value || 'true';
+    }
+    if (detected.isMonorepo && detected.services?.length) {
+        const services = {};
+        for (const s of detected.services) {
+            services[s.name] = {
+                ...(s.root !== './' ? { root: s.root } : {}),
+                command: s.suggestedCommand || 'pnpm dev',
+                ...(s.type === 'server' && s.suggestedPort ? { port: s.suggestedPort } : {}),
+                ...(s.type === 'batch' ? { type: 'batch' } : {}),
+                ready_pattern: 'ready|started|listening|Local:',
+                ...(Object.keys(env).length > 0 ? { env } : {}),
+            };
+        }
+        return {
+            version: '1',
+            name: path.basename(process.cwd()),
+            services,
+            verification: {
+                commands: [
+                    { name: 'build', run: `${detected.packageManager} build` },
+                    { name: 'lint', run: `${detected.packageManager} lint` },
+                ],
+            },
+        };
+    }
+    return {
+        version: '1',
+        name: path.basename(process.cwd()),
+        dev_server: {
+            command: detected.suggestedDevCommand || 'pnpm dev',
+            port: detected.suggestedPort || 3000,
+            ready_pattern: detected.suggestedReadyPattern || 'Local:',
+            ...(Object.keys(env).length > 0 ? { env } : {}),
+        },
+        verification: {
+            commands: [
+                { name: 'build', run: `${detected.packageManager} build` },
+                { name: 'lint', run: `${detected.packageManager} lint` },
+            ],
+        },
+    };
+}
+function printNextSteps() {
+    console.log(chalk.cyan('Next steps:'));
+    console.log(`  1. Review .haystack.yml and adjust as needed`);
+    console.log(`  2. Add auth bypass env var if your app requires login`);
+    console.log(`  3. Add flows to describe key user journeys to verify`);
+    console.log(`  4. Commit: ${chalk.green('git add .haystack.yml .agents/ && git commit -m "Add Haystack"')}\n`);
+}

package/dist/commands/status.d.ts

@@ -0,0 +1,4 @@
+/**
+ * haystack status - Check if .haystack.yml exists and is valid
+ */
+export declare function statusCommand(): Promise<void>;

package/dist/commands/status.js

@@ -0,0 +1,42 @@
+/**
+ * haystack status - Check if .haystack.yml exists and is valid
+ */
+import chalk from 'chalk';
+import { loadConfig, findConfigPath } from '../utils/config.js';
+export async function statusCommand() {
+    const configPath = await findConfigPath();
+    if (!configPath) {
+        console.log(chalk.yellow('⚠ No .haystack.yml found'));
+        console.log(chalk.dim('\nRun `haystack init` to create one.\n'));
+        process.exit(1);
+    }
+    console.log(chalk.green(`✓ Found ${configPath}`));
+    try {
+        const config = await loadConfig(configPath);
+        if (!config) {
+            console.log(chalk.red('✗ Failed to load config'));
+            process.exit(1);
+        }
+        console.log(chalk.green('✓ Config is valid\n'));
+        // Show config summary
+        if (config.name) {
+            console.log(`  ${chalk.dim('Name:')} ${config.name}`);
+        }
+        if (config.dev_server) {
+            console.log(`  ${chalk.dim('Dev server:')} ${config.dev_server.command} (port ${config.dev_server.port})`);
+        }
+        if (config.services) {
+            const serviceNames = Object.keys(config.services);
+            console.log(`  ${chalk.dim('Services:')} ${serviceNames.join(', ')}`);
+        }
+        if (config.verification?.commands?.length) {
+            const cmdNames = config.verification.commands.map((c) => c.name);
+            console.log(`  ${chalk.dim('Verification:')} ${cmdNames.join(', ')}`);
+        }
+        console.log('');
+    }
+    catch (e) {
+        console.log(chalk.red(`✗ Config is invalid: ${e.message}`));
+        process.exit(1);
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+/**
+ * Haystack CLI
+ *
+ * Set up your project for Haystack verification.
+ * This enables AI agents to spin up sandboxes of your app for testing.
+ *
+ * Usage:
+ *   npx @haystackeditor/cli init    # Set up .haystack.yml
+ *   npx @haystackeditor/cli status  # Check configuration
+ */
+export {};

package/dist/index.js

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+/**
+ * Haystack CLI
+ *
+ * Set up your project for Haystack verification.
+ * This enables AI agents to spin up sandboxes of your app for testing.
+ *
+ * Usage:
+ *   npx @haystackeditor/cli init    # Set up .haystack.yml
+ *   npx @haystackeditor/cli status  # Check configuration
+ */
+import { Command } from 'commander';
+import { statusCommand } from './commands/status.js';
+import { initCommand } from './commands/init.js';
+const program = new Command();
+program
+    .name('haystack')
+    .description('Set up Haystack verification for your project')
+    .version('0.2.0');
+program
+    .command('init')
+    .description('Create .haystack.yml configuration')
+    .option('-y, --yes', 'Use auto-detected defaults without prompting')
+    .addHelpText('after', `
+This creates a .haystack.yml file that configures:
+  • How to start your dev server
+  • Verification commands (build, lint, typecheck)
+  • Auth bypass for sandbox environments
+
+Once set up, AI agents can automatically spin up and test your app.
+`)
+    .action(initCommand);
+program
+    .command('status')
+    .description('Check if .haystack.yml exists and is valid')
+    .action(statusCommand);
+// Show help if no command provided
+if (process.argv.length === 2) {
+    program.help();
+}
+program.parse();