@specmarket/cli 0.0.4 → 0.0.6

package/src/commands/run.test.ts

@@ -0,0 +1,419 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { mkdir, writeFile, rm } from 'fs/promises';
+import { join } from 'path';
+import { tmpdir } from 'os';
+import { randomUUID } from 'crypto';
+
+// --- Hoisted mocks ---
+
+const { mockSpinner, mockRunSpec, mockSubmitTelemetry, mockPromptTelemetry, mockCheckClaude } =
+  vi.hoisted(() => {
+    const mockSpinner = {
+      start: vi.fn().mockReturnThis(),
+      stop: vi.fn().mockReturnThis(),
+      succeed: vi.fn().mockReturnThis(),
+      fail: vi.fn().mockReturnThis(),
+      text: '',
+    };
+    const mockRunSpec = vi.fn();
+    const mockSubmitTelemetry = vi.fn();
+    const mockPromptTelemetry = vi.fn();
+    const mockCheckClaude = vi.fn().mockResolvedValue(undefined);
+    return { mockSpinner, mockRunSpec, mockSubmitTelemetry, mockPromptTelemetry, mockCheckClaude };
+  });
+
+vi.mock('ora', () => ({
+  default: vi.fn().mockReturnValue(mockSpinner),
+}));
+
+vi.mock('../lib/ralph-loop.js', () => ({
+  runSpec: mockRunSpec,
+  checkClaudeCliInstalled: mockCheckClaude,
+}));
+
+vi.mock('../lib/telemetry.js', () => ({
+  submitTelemetry: mockSubmitTelemetry,
+  promptTelemetryOptIn: mockPromptTelemetry,
+}));
+
+vi.mock('../lib/auth.js', () => ({
+  loadCredentials: vi.fn().mockResolvedValue(null),
+  isAuthenticated: vi.fn().mockResolvedValue(false),
+}));
+
+vi.mock('../lib/convex-client.js', () => ({
+  getConvexClient: vi.fn().mockResolvedValue({ query: vi.fn(), action: vi.fn() }),
+}));
+
+// Mock the module builtin so createRequire can find package.json during tests
+vi.mock('module', () => ({
+  createRequire: vi.fn().mockReturnValue(
+    vi.fn().mockReturnValue({ version: '0.0.4' })
+  ),
+}));
+
+const mockExit = vi.spyOn(process, 'exit').mockImplementation((() => {
+  throw new Error('process.exit called');
+}) as any);
+
+const consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+vi.spyOn(console, 'error').mockImplementation(() => {});
+
+import { handleRun } from './run.js';
+import { SIDECAR_FILENAME } from '@specmarket/shared';
+
+// --- Helpers ---
+
+const VALID_SPECMARKET_YAML = `spec_format: specmarket
+display_name: "Test Spec"
+description: "A valid test spec with enough description length to pass."
+output_type: web-app
+primary_stack: nextjs-typescript
+tags: []
+estimated_tokens: 50000
+estimated_cost_usd: 2.50
+estimated_time_minutes: 30
+`;
+
+const VALID_SPEC_YAML = `name: test-spec
+display_name: "Test Spec"
+description: "A valid test spec with enough description length to pass."
+output_type: web-app
+primary_stack: nextjs-typescript
+version: "1.0.0"
+runner: claude
+min_model: "claude-opus-4-5"
+estimated_tokens: 50000
+estimated_cost_usd: 2.50
+estimated_time_minutes: 30
+tags: []
+`;
+
+const VALID_SUCCESS_CRITERIA = `# Success Criteria
+- [ ] Application builds
+- [ ] Tests pass
+`;
+
+describe('handleRun', () => {
+  let specDir: string;
+
+  beforeEach(async () => {
+    vi.clearAllMocks();
+    mockExit.mockImplementation((() => {
+      throw new Error('process.exit called');
+    }) as any);
+    specDir = join(tmpdir(), `run-test-${randomUUID()}`);
+    await mkdir(specDir, { recursive: true });
+    await mkdir(join(specDir, 'stdlib'), { recursive: true });
+  });
+
+  afterEach(async () => {
+    await rm(specDir, { recursive: true, force: true }).catch(() => {});
+  });
+
+  it('exits with validation error when spec is invalid', async () => {
+    // Create a spec directory missing required files
+    await writeFile(join(specDir, 'spec.yaml'), 'invalid yaml content');
+
+    await expect(handleRun(specDir, {})).rejects.toThrow(
+      'process.exit called'
+    );
+
+    expect(consoleSpy).toHaveBeenCalledWith(
+      expect.stringContaining('validation failed')
+    );
+  });
+
+  it('runs a valid spec and prints summary', async () => {
+    await Promise.all([
+      writeFile(join(specDir, SIDECAR_FILENAME), VALID_SPECMARKET_YAML),
+      writeFile(join(specDir, 'spec.yaml'), VALID_SPEC_YAML),
+      writeFile(join(specDir, 'PROMPT.md'), '# Prompt\nBuild it.'),
+      writeFile(join(specDir, 'SPEC.md'), '# Spec\nDetails.'),
+      writeFile(join(specDir, 'SUCCESS_CRITERIA.md'), VALID_SUCCESS_CRITERIA),
+      writeFile(join(specDir, 'stdlib', 'STACK.md'), '# Stack\nNext.js'),
+    ]);
+
+    mockRunSpec.mockResolvedValue({
+      report: {
+        runId: 'run-123',
+        status: 'success',
+        loopCount: 3,
+        totalTokens: 15000,
+        totalCostUsd: 1.5,
+        totalTimeMinutes: 5.2,
+        successCriteriaResults: [
+          { criterion: 'Application builds', passed: true },
+        ],
+      },
+      outputDir: '/tmp/output',
+    });
+    mockSubmitTelemetry.mockResolvedValue(false);
+
+    await handleRun(specDir, {});
+
+    expect(mockRunSpec).toHaveBeenCalledWith(
+      specDir,
+      expect.objectContaining({ name: 'test-spec', version: '1.0.0' }),
+      expect.any(Object),
+      expect.any(Function)
+    );
+    expect(consoleSpy).toHaveBeenCalledWith(
+      expect.stringContaining('Run Complete')
+    );
+    expect(consoleSpy).toHaveBeenCalledWith(
+      expect.stringContaining('SUCCESS')
+    );
+  });
+
+  it('prints security warning before running', async () => {
+    await Promise.all([
+      writeFile(join(specDir, SIDECAR_FILENAME), VALID_SPECMARKET_YAML),
+      writeFile(join(specDir, 'spec.yaml'), VALID_SPEC_YAML),
+      writeFile(join(specDir, 'PROMPT.md'), '# Prompt\nBuild it.'),
+      writeFile(join(specDir, 'SPEC.md'), '# Spec\nDetails.'),
+      writeFile(join(specDir, 'SUCCESS_CRITERIA.md'), VALID_SUCCESS_CRITERIA),
+      writeFile(join(specDir, 'stdlib', 'STACK.md'), '# Stack\nNext.js'),
+    ]);
+
+    mockRunSpec.mockResolvedValue({
+      report: {
+        runId: 'run-123',
+        status: 'success',
+        loopCount: 1,
+        totalTokens: 1000,
+        totalCostUsd: 0.1,
+        totalTimeMinutes: 1,
+        successCriteriaResults: [],
+      },
+      outputDir: '/tmp/output',
+    });
+    mockSubmitTelemetry.mockResolvedValue(false);
+
+    await handleRun(specDir, {});
+
+    expect(consoleSpy).toHaveBeenCalledWith(
+      expect.stringContaining('SECURITY WARNING')
+    );
+  });
+
+  it('prints harness in run summary', async () => {
+    await Promise.all([
+      writeFile(join(specDir, SIDECAR_FILENAME), VALID_SPECMARKET_YAML),
+      writeFile(join(specDir, 'spec.yaml'), VALID_SPEC_YAML),
+      writeFile(join(specDir, 'PROMPT.md'), '# Prompt\nBuild it.'),
+      writeFile(join(specDir, 'SPEC.md'), '# Spec\nDetails.'),
+      writeFile(join(specDir, 'SUCCESS_CRITERIA.md'), VALID_SUCCESS_CRITERIA),
+      writeFile(join(specDir, 'stdlib', 'STACK.md'), '# Stack\nNext.js'),
+    ]);
+
+    mockRunSpec.mockResolvedValue({
+      report: {
+        runId: 'run-123',
+        status: 'success',
+        loopCount: 1,
+        totalTokens: 1000,
+        totalCostUsd: 0.1,
+        totalTimeMinutes: 1,
+        successCriteriaResults: [],
+      },
+      outputDir: '/tmp/output',
+    });
+    mockSubmitTelemetry.mockResolvedValue(false);
+
+    await handleRun(specDir, { harness: 'codex' });
+
+    expect(consoleSpy).toHaveBeenCalledWith(
+      expect.stringContaining('codex')
+    );
+    expect(mockRunSpec).toHaveBeenCalledWith(
+      specDir,
+      expect.any(Object),
+      expect.objectContaining({ harness: 'codex' }),
+      expect.any(Function)
+    );
+  });
+
+  it('exits with validation error for unknown harness', async () => {
+    await Promise.all([
+      writeFile(join(specDir, SIDECAR_FILENAME), VALID_SPECMARKET_YAML),
+      writeFile(join(specDir, 'spec.yaml'), VALID_SPEC_YAML),
+      writeFile(join(specDir, 'PROMPT.md'), '# Prompt\nBuild it.'),
+      writeFile(join(specDir, 'SPEC.md'), '# Spec\nDetails.'),
+      writeFile(join(specDir, 'SUCCESS_CRITERIA.md'), VALID_SUCCESS_CRITERIA),
+      writeFile(join(specDir, 'stdlib', 'STACK.md'), '# Stack\nNext.js'),
+    ]);
+
+    await expect(handleRun(specDir, { harness: 'unknown-harness' })).rejects.toThrow(
+      'process.exit called'
+    );
+    expect(consoleSpy).toHaveBeenCalledWith(
+      expect.stringContaining('Unknown harness')
+    );
+  });
+
+  it('passes --workdir to runSpec as workdir option', async () => {
+    await Promise.all([
+      writeFile(join(specDir, SIDECAR_FILENAME), VALID_SPECMARKET_YAML),
+      writeFile(join(specDir, 'spec.yaml'), VALID_SPEC_YAML),
+      writeFile(join(specDir, 'PROMPT.md'), '# Prompt\nBuild it.'),
+      writeFile(join(specDir, 'SPEC.md'), '# Spec\nDetails.'),
+      writeFile(join(specDir, 'SUCCESS_CRITERIA.md'), VALID_SUCCESS_CRITERIA),
+      writeFile(join(specDir, 'stdlib', 'STACK.md'), '# Stack\nNext.js'),
+    ]);
+
+    mockRunSpec.mockResolvedValue({
+      report: {
+        runId: 'run-123',
+        status: 'success',
+        loopCount: 1,
+        totalTokens: 1000,
+        totalCostUsd: 0.1,
+        totalTimeMinutes: 1,
+        successCriteriaResults: [],
+      },
+      outputDir: '/tmp/myworkdir',
+    });
+    mockSubmitTelemetry.mockResolvedValue(false);
+
+    await handleRun(specDir, { workdir: '/tmp/myworkdir' });
+
+    expect(mockRunSpec).toHaveBeenCalledWith(
+      specDir,
+      expect.any(Object),
+      expect.objectContaining({ workdir: '/tmp/myworkdir' }),
+      expect.any(Function)
+    );
+    expect(consoleSpy).toHaveBeenCalledWith(
+      expect.stringContaining('/tmp/myworkdir')
+    );
+  });
+
+  it('passes steeringQueue to runSpec', async () => {
+    await Promise.all([
+      writeFile(join(specDir, SIDECAR_FILENAME), VALID_SPECMARKET_YAML),
+      writeFile(join(specDir, 'spec.yaml'), VALID_SPEC_YAML),
+      writeFile(join(specDir, 'PROMPT.md'), '# Prompt\nBuild it.'),
+      writeFile(join(specDir, 'SPEC.md'), '# Spec\nDetails.'),
+      writeFile(join(specDir, 'SUCCESS_CRITERIA.md'), VALID_SUCCESS_CRITERIA),
+      writeFile(join(specDir, 'stdlib', 'STACK.md'), '# Stack\nNext.js'),
+    ]);
+
+    mockRunSpec.mockResolvedValue({
+      report: {
+        runId: 'run-123',
+        status: 'success',
+        loopCount: 2,
+        totalTokens: 5000,
+        totalCostUsd: 0.5,
+        totalTimeMinutes: 3,
+        steeringActionCount: 0,
+        successCriteriaResults: [],
+      },
+      outputDir: '/tmp/output',
+    });
+    mockSubmitTelemetry.mockResolvedValue(false);
+
+    await handleRun(specDir, {});
+
+    // runSpec must receive a steeringQueue array in opts
+    expect(mockRunSpec).toHaveBeenCalledWith(
+      specDir,
+      expect.any(Object),
+      expect.objectContaining({ steeringQueue: expect.any(Array) }),
+      expect.any(Function)
+    );
+  });
+
+  it('shows steering action count in summary when > 0', async () => {
+    await Promise.all([
+      writeFile(join(specDir, SIDECAR_FILENAME), VALID_SPECMARKET_YAML),
+      writeFile(join(specDir, 'spec.yaml'), VALID_SPEC_YAML),
+      writeFile(join(specDir, 'PROMPT.md'), '# Prompt\nBuild it.'),
+      writeFile(join(specDir, 'SPEC.md'), '# Spec\nDetails.'),
+      writeFile(join(specDir, 'SUCCESS_CRITERIA.md'), VALID_SUCCESS_CRITERIA),
+      writeFile(join(specDir, 'stdlib', 'STACK.md'), '# Stack\nNext.js'),
+    ]);
+
+    mockRunSpec.mockResolvedValue({
+      report: {
+        runId: 'run-123',
+        status: 'success',
+        loopCount: 5,
+        totalTokens: 20000,
+        totalCostUsd: 2.0,
+        totalTimeMinutes: 10,
+        steeringActionCount: 3,
+        successCriteriaResults: [],
+      },
+      outputDir: '/tmp/output',
+    });
+    mockSubmitTelemetry.mockResolvedValue(false);
+
+    await handleRun(specDir, {});
+
+    expect(consoleSpy).toHaveBeenCalledWith(
+      expect.stringContaining('Steering Actions: 3')
+    );
+  });
+
+  it('omits steering count from summary when 0', async () => {
+    await Promise.all([
+      writeFile(join(specDir, SIDECAR_FILENAME), VALID_SPECMARKET_YAML),
+      writeFile(join(specDir, 'spec.yaml'), VALID_SPEC_YAML),
+      writeFile(join(specDir, 'PROMPT.md'), '# Prompt\nBuild it.'),
+      writeFile(join(specDir, 'SPEC.md'), '# Spec\nDetails.'),
+      writeFile(join(specDir, 'SUCCESS_CRITERIA.md'), VALID_SUCCESS_CRITERIA),
+      writeFile(join(specDir, 'stdlib', 'STACK.md'), '# Stack\nNext.js'),
+    ]);
+
+    mockRunSpec.mockResolvedValue({
+      report: {
+        runId: 'run-123',
+        status: 'success',
+        loopCount: 2,
+        totalTokens: 5000,
+        totalCostUsd: 0.5,
+        totalTimeMinutes: 3,
+        steeringActionCount: 0,
+        successCriteriaResults: [],
+      },
+      outputDir: '/tmp/output',
+    });
+    mockSubmitTelemetry.mockResolvedValue(false);
+
+    await handleRun(specDir, {});
+
+    const calls = consoleSpy.mock.calls.map((c) => String(c[0]));
+    expect(calls.some((c) => c.includes('Steering Actions'))).toBe(false);
+  });
+
+  it('exits with budget_exceeded code on budget runs', async () => {
+    await Promise.all([
+      writeFile(join(specDir, SIDECAR_FILENAME), VALID_SPECMARKET_YAML),
+      writeFile(join(specDir, 'spec.yaml'), VALID_SPEC_YAML),
+      writeFile(join(specDir, 'PROMPT.md'), '# Prompt\nBuild it.'),
+      writeFile(join(specDir, 'SPEC.md'), '# Spec\nDetails.'),
+      writeFile(join(specDir, 'SUCCESS_CRITERIA.md'), VALID_SUCCESS_CRITERIA),
+      writeFile(join(specDir, 'stdlib', 'STACK.md'), '# Stack\nNext.js'),
+    ]);
+
+    mockRunSpec.mockResolvedValue({
+      report: {
+        runId: 'run-123',
+        status: 'budget_exceeded',
+        loopCount: 50,
+        totalTokens: 500000,
+        totalCostUsd: 10.0,
+        totalTimeMinutes: 60,
+        successCriteriaResults: [],
+      },
+      outputDir: '/tmp/output',
+    });
+    mockSubmitTelemetry.mockResolvedValue(false);
+
+    await expect(handleRun(specDir, {})).rejects.toThrow(
+      'process.exit called'
+    );
+  });
+});

package/src/commands/run.ts

@@ -4,12 +4,12 @@ import ora from 'ora';
 import { readFile, mkdir, writeFile as writeFileFn } from 'fs/promises';
 import { join, resolve, isAbsolute } from 'path';
 import { parse as parseYaml } from 'yaml';
-import { specYamlSchema, EXIT_CODES } from '@specmarket/shared';
+import { specYamlSchema, EXIT_CODES, KNOWN_HARNESSES } from '@specmarket/shared';
 import { validateSpec } from './validate.js';
 import { loadCredentials, isAuthenticated } from '../lib/auth.js';
 import { getConvexClient } from '../lib/convex-client.js';
 import { submitTelemetry, promptTelemetryOptIn } from '../lib/telemetry.js';
-import { runSpec } from '../lib/ralph-loop.js';
+import { runSpec, checkClaudeCliInstalled } from '../lib/ralph-loop.js';
 import type { LoopIteration } from '@specmarket/shared';
 import createDebug from 'debug';
 import { createRequire } from 'module';
@@ -46,6 +46,8 @@ export async function handleRun(
     dryRun?: boolean;
     resume?: string;
     output?: string;
+    harness?: string;
+    workdir?: string;
   }
 ): Promise<void> {
   // Resolve spec directory (and registry spec ID if downloaded from registry)
@@ -94,15 +96,63 @@ export async function handleRun(
     await promptTelemetryOptIn();
   }
 
+  // Validate --harness value
+  if (opts.harness && !(KNOWN_HARNESSES as readonly string[]).includes(opts.harness)) {
+    console.log(chalk.red(`\n✗ Unknown harness "${opts.harness}". Supported: ${KNOWN_HARNESSES.join(', ')}`));
+    process.exit(EXIT_CODES.VALIDATION_ERROR);
+  }
+
+  // Pre-flight check: Ensure the selected harness CLI is installed
+  try {
+    await checkClaudeCliInstalled(opts.harness);
+  } catch (err) {
+    console.log(chalk.red(`\n✗ ${(err as Error).message}`));
+    process.exit(EXIT_CODES.VALIDATION_ERROR);
+  }
+
   const maxLoops = opts.maxLoops ? parseInt(opts.maxLoops, 10) : undefined;
   const maxBudget = opts.maxBudget ? parseFloat(opts.maxBudget) : undefined;
 
+  const harness = opts.harness ?? 'claude-code';
   console.log(chalk.cyan(`\nRunning spec: ${chalk.bold(specYaml.display_name)}`));
   console.log(chalk.gray(`  Version: ${specYaml.version}`));
   console.log(chalk.gray(`  Model: ${opts.model ?? specYaml.min_model}`));
+  console.log(chalk.gray(`  Harness: ${harness}`));
+  if (opts.workdir) {
+    console.log(chalk.gray(`  Working dir: ${opts.workdir}`));
+  }
   console.log(chalk.gray(`  Max loops: ${maxLoops ?? 50}`));
   console.log(chalk.gray(`  Estimated tokens: ${specYaml.estimated_tokens.toLocaleString()}`));
   console.log(chalk.gray(`  Estimated cost: $${specYaml.estimated_cost_usd.toFixed(2)}`));
+
+  // Set up steering input: collect lines from stdin and queue them for injection
+  // at the next iteration boundary. Works when stdin is a TTY (interactive) or
+  // a pipe (scripted input). Non-blocking — the run continues regardless.
+  const steeringQueue: string[] = [];
+  let steeringInputBuffer = '';
+  const steeringDataHandler = (chunk: Buffer | string): void => {
+    const data = typeof chunk === 'string' ? chunk : chunk.toString('utf-8');
+    steeringInputBuffer += data;
+    const lines = steeringInputBuffer.split('\n');
+    steeringInputBuffer = lines.pop() ?? '';
+    for (const line of lines) {
+      const trimmed = line.trim();
+      if (trimmed) {
+        steeringQueue.push(trimmed);
+        // Write to stderr so it doesn't overwrite the spinner on stdout
+        process.stderr.write(
+          `\n${chalk.cyan('[steering]')} Queued: "${trimmed.length > 60 ? trimmed.slice(0, 60) + '…' : trimmed}"\n`
+        );
+      }
+    }
+  };
+
+  if (!opts.dryRun) {
+    process.stdin.setEncoding('utf-8');
+    process.stdin.resume();
+    process.stdin.on('data', steeringDataHandler);
+    console.log(chalk.gray('  Tip: Type a message + Enter to steer the agent mid-run.'));
+  }
   console.log('');
 
   const spinner = ora({ text: 'Starting loop iteration 1...', spinner: 'dots' }).start();
@@ -126,13 +176,20 @@ export async function handleRun(
         dryRun: opts.dryRun,
         resumeRunId: opts.resume,
         outputDir: opts.output,
+        harness: opts.harness,
+        workdir: opts.workdir,
         cliVersion: CLI_VERSION,
+        steeringQueue,
       },
       (iteration: LoopIteration) => {
         spinner.text = `Loop ${iteration.iteration}: ${iteration.tokens.toLocaleString()} tokens, ${(iteration.durationMs / 1000).toFixed(1)}s`;
       }
     );
 
+    // Stop collecting steering input now that the run is complete
+    process.stdin.removeListener('data', steeringDataHandler);
+    process.stdin.pause();
+
     const { report } = result;
     const statusColor =
       report.status === 'success'
@@ -150,6 +207,9 @@ export async function handleRun(
     console.log(`  Tokens: ${report.totalTokens.toLocaleString()}`);
     console.log(`  Cost: $${report.totalCostUsd.toFixed(4)}`);
     console.log(`  Time: ${report.totalTimeMinutes.toFixed(1)} minutes`);
+    if (report.steeringActionCount && report.steeringActionCount > 0) {
+      console.log(`  Steering Actions: ${report.steeringActionCount}`);
+    }
     console.log(`  Run ID: ${chalk.gray(report.runId)}`);
     console.log(`  Output: ${chalk.gray(result.outputDir)}`);
 
@@ -362,7 +422,7 @@ async function resolveSpecPath(pathOrId: string): Promise<ResolvedSpec> {
 export function createRunCommand(): Command {
   return new Command('run')
     .description('Execute a spec locally using the Ralph Loop')
-    .argument('<path-or-id>', 'Local path to spec directory or registry ID (@user/name[@version])')
+    .argument('[path-or-id]', 'Local path to spec directory or registry ID (@user/name[@version])', '.')
     .option('--max-loops <n>', 'Maximum loop iterations (default: 50)')
     .option('--max-budget <usd>', 'Maximum budget in USD (default: 2x estimated)')
     .option('--no-telemetry', 'Disable telemetry submission for this run')
@@ -370,6 +430,14 @@ export function createRunCommand(): Command {
     .option('--dry-run', 'Validate and show config without executing')
     .option('--resume <run-id>', 'Resume a previous run from where it left off')
     .option('--output <dir>', 'Custom output directory for run artifacts')
+    .option(
+      '--harness <harness>',
+      `Agentic harness to use (default: claude-code). One of: ${KNOWN_HARNESSES.join(', ')}`
+    )
+    .option(
+      '--workdir <dir>',
+      'Run in an existing directory instead of a fresh sandbox (spec files not copied)'
+    )
     .action(async (pathOrId: string, opts) => {
       try {
         await handleRun(pathOrId, opts);

package/src/commands/search.test.ts

@@ -0,0 +1,147 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+// --- Hoisted mocks ---
+
+const { mockQuery, mockClient, mockSpinner } = vi.hoisted(() => {
+  const mockQuery = vi.fn();
+  const mockClient = { query: mockQuery };
+  const mockSpinner = {
+    start: vi.fn().mockReturnThis(),
+    stop: vi.fn().mockReturnThis(),
+    succeed: vi.fn().mockReturnThis(),
+    fail: vi.fn().mockReturnThis(),
+  };
+  return { mockQuery, mockClient, mockSpinner };
+});
+
+vi.mock('../lib/convex-client.js', () => ({
+  getConvexClient: vi.fn().mockResolvedValue(mockClient),
+}));
+
+vi.mock('ora', () => ({
+  default: vi.fn().mockReturnValue(mockSpinner),
+}));
+
+vi.mock('@specmarket/convex/api', () => ({
+  api: {
+    specs: { search: 'specs.search' },
+  },
+}));
+
+const mockExit = vi.spyOn(process, 'exit').mockImplementation((() => {
+  throw new Error('process.exit called');
+}) as any);
+
+const consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+vi.spyOn(console, 'error').mockImplementation(() => {});
+
+import { handleSearch } from './search.js';
+
+// --- Test data ---
+
+const MOCK_RESULTS = [
+  {
+    scopedName: '@alice/todo-app',
+    description: 'A simple todo application with authentication and dark mode',
+    replacesSaas: 'Todoist',
+    successRate: 0.85,
+    avgCostUsd: 1.5,
+    communityRating: 4.2,
+  },
+  {
+    scopedName: '@bob/crm-tool',
+    description: 'Customer relationship manager with pipeline tracking',
+    replacesSaas: null,
+    successRate: 0,
+    avgCostUsd: 0,
+    communityRating: 0,
+  },
+];
+
+describe('handleSearch', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockExit.mockImplementation((() => {
+      throw new Error('process.exit called');
+    }) as any);
+  });
+
+  it('displays results in table format', async () => {
+    mockQuery.mockResolvedValue(MOCK_RESULTS);
+
+    await handleSearch('todo', {});
+
+    expect(mockQuery).toHaveBeenCalledWith('specs.search', {
+      query: 'todo',
+      limit: 20,
+    });
+    expect(consoleSpy).toHaveBeenCalledWith(
+      expect.stringContaining('Found 2 spec(s)')
+    );
+  });
+
+  it('shows no-results message when no specs match', async () => {
+    mockQuery.mockResolvedValue([]);
+
+    await handleSearch('nonexistent', {});
+
+    expect(consoleSpy).toHaveBeenCalledWith(
+      expect.stringContaining('No specs found')
+    );
+  });
+
+  it('passes filter options to backend query', async () => {
+    mockQuery.mockResolvedValue([]);
+
+    await handleSearch('test', {
+      outputType: 'web-app',
+      primaryStack: 'nextjs-typescript',
+      replacesSaas: 'Notion',
+      limit: '10',
+      tag: ['productivity'],
+      freeTierOnly: true,
+    });
+
+    expect(mockQuery).toHaveBeenCalledWith('specs.search', {
+      query: 'test',
+      limit: 10,
+      outputType: 'web-app',
+      primaryStack: 'nextjs-typescript',
+      replacesSaas: 'Notion',
+      tags: ['productivity'],
+      freeTierOnly: true,
+    });
+  });
+
+  it('converts min-success-rate from percentage to decimal', async () => {
+    mockQuery.mockResolvedValue([]);
+
+    await handleSearch('test', { minSuccessRate: '80' });
+
+    expect(mockQuery).toHaveBeenCalledWith('specs.search', {
+      query: 'test',
+      limit: 20,
+      minSuccessRate: 0.8,
+    });
+  });
+
+  it('exits with error for invalid min-success-rate', async () => {
+    await expect(
+      handleSearch('test', { minSuccessRate: '150' })
+    ).rejects.toThrow('process.exit called');
+
+    expect(mockSpinner.fail).toHaveBeenCalledWith(
+      expect.stringContaining('--min-success-rate must be between 0 and 100')
+    );
+  });
+
+  it('exits with error for invalid max-cost', async () => {
+    await expect(
+      handleSearch('test', { maxCost: '-5' })
+    ).rejects.toThrow('process.exit called');
+
+    expect(mockSpinner.fail).toHaveBeenCalledWith(
+      expect.stringContaining('--max-cost must be a non-negative number')
+    );
+  });
+});