feat: AnalysisRunner interface + ClaudeNativeRunner + ProviderRunner

[melagiri]

Context

Part of the Native Analysis via Claude Code Hooks feature (Phase 12, v4.8.0).
Plan: docs/plans/2026-03-28-native-analysis-hooks.md

Issue 2 of 6 — Depends on #238 (prompt module migration).

Problem

The insights command needs to run analysis via two different backends: claude -p (native) and the existing LLM provider abstraction. We need a clean interface so the command doesn't care which backend is used.

Solution

AnalysisRunner Interface

interface AnalysisRunner {
  readonly name: string;
  runAnalysis(params: RunAnalysisParams): Promise<RunAnalysisResult>;
}

Two Implementations

1. ClaudeNativeRunner — executes claude -p via execFileSync (not exec — shell injection safety)

   • Writes system prompt to temp file
   • Writes JSON schema to temp file
   • Pipes conversation via stdin
   • Returns raw JSON response
   • Records tokens=0, cost=0 (counted in Claude subscription)

2. ProviderRunner — wraps existing server/src/llm/client.ts LLM abstraction

   • Same behavior as current dashboard/API analysis
   • Returns actual token counts and costs

JSON Schema Files

Hand-maintained flat JSON schemas for claude -p --json-schema:

• cli/src/analysis/schemas/session-analysis.json (from AnalysisResponse type)
• cli/src/analysis/schemas/prompt-quality.json (from PromptQualityResponse type)

Test that validates schema properties match TypeScript interface fields.

New Files

File	Purpose
cli/src/analysis/runner-types.ts	AnalysisRunner interface + param/result types
cli/src/analysis/native-runner.ts	ClaudeNativeRunner (claude -p via execFileSync)
cli/src/analysis/provider-runner.ts	ProviderRunner (wraps existing LLM client)
cli/src/analysis/schemas/session-analysis.json	JSON schema for session analysis
cli/src/analysis/schemas/prompt-quality.json	JSON schema for prompt quality
cli/src/analysis/schemas/__tests__/schema-sync.test.ts	Schema ↔ TypeScript sync test

Acceptance Criteria

• AnalysisRunner interface defined with RunAnalysisParams/RunAnalysisResult
• ClaudeNativeRunner validates claude CLI in PATH, uses execFileSync
• ProviderRunner delegates to existing LLM client
• JSON schema files cover all required fields of AnalysisResponse and PromptQualityResponse
• Schema sync test passes in CI
• Unit tests for both runners (mocked execFileSync / LLM client)
• SOLID: adding future runners (e.g., Cursor) requires only implementing the interface

[melagiri]

PM Handoff: Implementation Context for Dev Agent

This comment contains all the context needed to implement Issue #239. The worktree is at ../code-insights-runner-interface/ on branch feature/runner-interface.

---

Prerequisites Already in Place

PR #245 has landed. The cli/src/analysis/ directory already contains all prompt/parser/normalizer modules:

• prompt-types.ts — AnalysisResponse, PromptQualityResponse, and all related types
• prompt-constants.ts, prompts.ts, message-format.ts, response-parsers.ts
• normalize-utils.ts, friction-normalize.ts, pattern-normalize.ts, prompt-quality-normalize.ts
• __tests__/ — existing tests for the normalizers

This PR adds NEW files only. No modifications to existing files.

---

Files to Create

File	Purpose
cli/src/analysis/runner-types.ts	AnalysisRunner interface + RunAnalysisParams + RunAnalysisResult
cli/src/analysis/native-runner.ts	ClaudeNativeRunner — execFileSync only, NOT exec
cli/src/analysis/provider-runner.ts	ProviderRunner — wraps existing server/src/llm/client.ts
cli/src/analysis/schemas/session-analysis.json	Flat JSON Schema from AnalysisResponse
cli/src/analysis/schemas/prompt-quality.json	Flat JSON Schema from PromptQualityResponse
cli/src/analysis/schemas/__tests__/schema-sync.test.ts	Schema ↔ TypeScript property validation
cli/src/analysis/native-runner.test.ts	Unit tests for ClaudeNativeRunner
cli/src/analysis/provider-runner.test.ts	Unit tests for ProviderRunner

---

Interface Definition (copy verbatim into runner-types.ts)

export interface AnalysisRunner {
  readonly name: string;
  runAnalysis(params: RunAnalysisParams): Promise<RunAnalysisResult>;
}

export interface RunAnalysisParams {
  systemPrompt: string;
  userPrompt: string;
  jsonSchema?: object;   // NativeRunner uses this for --json-schema; ProviderRunner ignores it
}

export interface RunAnalysisResult {
  rawJson: string;
  durationMs: number;
  inputTokens: number;
  outputTokens: number;
  cacheCreationTokens?: number;
  cacheReadTokens?: number;
  model: string;
  provider: string;
}

---

ClaudeNativeRunner Implementation Notes

• File: cli/src/analysis/native-runner.ts
• MUST use execFileSync from child_process — NOT exec or execSync with shell string. This prevents shell injection.
• Write systemPrompt to a temp file, pass via --append-system-prompt-file
• Write jsonSchema (if provided) to a temp file, pass via --json-schema
• Pipe userPrompt via stdin buffer (the input option in execFileSync)
• Clean up both temp files in a finally block
• Static validate() method: call execFileSync('claude', ['--version'], { stdio: 'pipe' }) to verify Claude CLI is in PATH
• Timeout: 120_000 ms (2 minutes)
• Max buffer: 10 * 1024 * 1024 (10MB)
• Return inputTokens: 0, outputTokens: 0 — tokens are counted as part of the Claude Code subscription, not tracked separately
• Return model: 'claude-native', provider: 'claude-code-native'
• The plan doc (Section 3) contains the exact implementation — follow it precisely

---

ProviderRunner Implementation Notes

• File: cli/src/analysis/provider-runner.ts
• Import createLLMClient from server/src/llm/client.ts (this is a server package dep — see note below)
• Call client.chat() with:

  [
    { role: 'system', content: params.systemPrompt },
    { role: 'user', content: params.userPrompt },
  ]

• Return response.content as rawJson
• Map response.usage → RunAnalysisResult token fields (default to 0 if usage is undefined)
• Return client.provider and client.model for the result fields
• Note: ProviderRunner lives in cli/src/analysis/ but imports from server/src/llm/client.ts. This is acceptable because server is a workspace dependency of cli (check cli/package.json — it lists @code-insights/server or the import resolves via workspace). If that dependency path is not already set up, look at how server/src/routes/analysis.ts imports from cli for the reverse pattern and adjust accordingly.

---

JSON Schema Files

The schemas must be flat (no $defs, no $ref) — claude -p --json-schema requires flat schemas.

cli/src/analysis/schemas/session-analysis.json — covers top-level required fields of AnalysisResponse:

Required top-level properties: summary (object with title, content, bullets), decisions (array), learnings (array). The facets property is optional.

cli/src/analysis/schemas/prompt-quality.json — covers all required fields of PromptQualityResponse:

Required: efficiency_score (number), message_overhead (number), assessment (string), takeaways (array), findings (array), dimension_scores (object with the 5 dimension number fields).

Use JSON Schema draft-07 format with "$schema": "http://json-schema.org/draft-07/schema#".

---

Schema Sync Test

File: cli/src/analysis/schemas/__tests__/schema-sync.test.ts

This test doesn't run TypeScript compilation — it validates that the JSON schema property names match the known fields of AnalysisResponse and PromptQualityResponse. Pattern:

import sessionAnalysisSchema from '../session-analysis.json' assert { type: 'json' };
import promptQualitySchema from '../prompt-quality.json' assert { type: 'json' };

describe('schema-sync', () => {
  it('session-analysis.json covers AnalysisResponse required fields', () => {
    const props = Object.keys(sessionAnalysisSchema.properties);
    expect(props).toContain('summary');
    expect(props).toContain('decisions');
    expect(props).toContain('learnings');
    // summary sub-fields
    const summaryProps = Object.keys(sessionAnalysisSchema.properties.summary.properties);
    expect(summaryProps).toContain('title');
    expect(summaryProps).toContain('content');
    expect(summaryProps).toContain('bullets');
  });

  it('prompt-quality.json covers PromptQualityResponse required fields', () => {
    const props = Object.keys(promptQualitySchema.properties);
    const required = ['efficiency_score', 'message_overhead', 'assessment', 'takeaways', 'findings', 'dimension_scores'];
    for (const field of required) {
      expect(props).toContain(field);
    }
    // dimension_scores sub-fields
    const dimProps = Object.keys(promptQualitySchema.properties.dimension_scores.properties);
    const dims = ['context_provision', 'request_specificity', 'scope_management', 'information_timing', 'correction_quality'];
    for (const dim of dims) {
      expect(dimProps).toContain(dim);
    }
  });
});

---

Unit Tests

native-runner.test.ts:

• Mock child_process.execFileSync (vi.mock)
• Test happy path: mock returns valid JSON string → rawJson matches
• Test validate() throws when execFileSync throws (claude not found)
• Test temp file cleanup on error (verify unlinkSync is called in finally)
• Test timeout is passed correctly (120_000)

provider-runner.test.ts:

• Mock createLLMClient to return a mock LLMClient
• Test happy path: mock client returns { content: '{"ok":true}', usage: { inputTokens: 10, outputTokens: 5 } } → verify RunAnalysisResult fields
• Test missing usage: defaults to 0 tokens
• Test provider and model from client are passed through

---

Build Verification

After implementing, from the worktree root (../code-insights-runner-interface/):

pnpm build       # zero errors required
pnpm test        # zero failures required

Only create the PR after both pass.

---

Security Note (NON-NEGOTIABLE)

execFileSync takes an array of arguments, not a shell string. This means:

// CORRECT: array args, no shell
execFileSync('claude', ['-p', '--output-format', 'json', '--append-system-prompt-file', promptFile], { ... })

// WRONG: never do this
exec(`claude -p --output-format json ${promptFile}`, ...)

The temp file paths come from join(tmpdir(), ...) — no user input ever appears in the args array.