@haystackeditor/cli 0.8.0 → 0.9.0

package/dist/triage/prompts.js

@@ -0,0 +1,266 @@
+/**
+ * Prompt builders for pre-PR triage sub-agents.
+ *
+ * Each function returns a prompt string that instructs the sub-agent to:
+ * 1. Analyze the git diff against the base branch
+ * 2. Write structured JSON results to a specific file path
+ *
+ * The sub-agent uses its own tools (Bash, Read, Grep, etc.) to explore the codebase.
+ */
+// ============================================================================
+// JSON schemas (embedded in prompts so sub-agents know what to write)
+// ============================================================================
+const ISSUE_SCHEMA = `{
+  "file": "relative/path/to/file.ts",
+  "line": 42,
+  "severity": "error | warning | info",
+  "message": "Description of the issue"
+}`;
+const CODE_REVIEW_SCHEMA = `{
+  "checker": "code-review",
+  "issues": [${ISSUE_SCHEMA}],
+  "summary": "Brief 1-sentence summary",
+  "passed": true
+}`;
+const RULES_VALIDATOR_SCHEMA = `{
+  "checker": "rules-validator",
+  "issues": [
+    {
+      "file": "relative/path/to/file.ts",
+      "line": 42,
+      "severity": "error | warning",
+      "message": "Description of the violation",
+      "rule": "PR001"
+    }
+  ],
+  "summary": "Brief 1-sentence summary",
+  "rulesChecked": 3,
+  "passed": true
+}`;
+const INTENT_DRIFT_SCHEMA = `{
+  "checker": "intent-drift",
+  "issues": [
+    {
+      "file": "relative/path/to/file.ts",
+      "line": 42,
+      "severity": "error | warning | info",
+      "message": "Description of the drift or incomplete fulfillment",
+      "pattern": "intent_drift | incomplete_fulfillment"
+    }
+  ],
+  "summary": "Brief 1-sentence summary",
+  "sessionsChecked": 2,
+  "passed": true
+}`;
+// ============================================================================
+// Prompt builders
+// ============================================================================
+/**
+ * Build the code review prompt.
+ * Always runs — looks for objective bugs in the diff.
+ */
+export function buildCodeReviewPrompt(baseBranch, outputPath) {
+    return `You are a pre-PR code reviewer. Your job is to find OBJECTIVE BUGS in the code changes that will cause incorrect runtime behavior.
+
+## Instructions
+
+1. Run \`git diff ${baseBranch}...HEAD --name-only\` to see which files changed.
+2. Run \`git diff ${baseBranch}...HEAD\` to see the full diff. For large diffs, review file by file.
+3. For each changed file, read the surrounding code if needed to understand context.
+4. Identify only REAL BUGS — things that will definitely crash, produce wrong results, or corrupt data.
+
+## What to flag
+
+- Logic errors (wrong condition, off-by-one, inverted boolean)
+- Null/undefined access that will crash at runtime
+- Type mismatches that cause runtime errors (not just TypeScript warnings)
+- Missing return statements that change behavior
+- Resource leaks (unclosed handles, missing cleanup)
+- Race conditions or concurrency bugs
+- Security vulnerabilities (SQL injection, XSS, command injection)
+- Broken API contracts (wrong argument order, missing required fields)
+
+## What NOT to flag
+
+- Style preferences, naming conventions, or formatting
+- "Might be an issue" or "could potentially cause problems" — only flag definite bugs
+- Missing error handling unless it WILL crash (not "should have" error handling)
+- Performance concerns unless they cause functional breakage
+- Code that is ugly but correct
+- Pre-existing issues in unchanged code
+
+## Output
+
+Write your results to \`${outputPath}\` as JSON with this exact schema:
+
+\`\`\`json
+${CODE_REVIEW_SCHEMA}
+\`\`\`
+
+- Set \`passed\` to \`true\` if no issues found (empty issues array)
+- Set \`passed\` to \`false\` if any issues have severity "error"
+- Keep the summary to 1 sentence
+- You MUST write the result file even if no issues are found
+
+Be extremely conservative. False positives waste the developer's time. Only flag things you are highly confident are real bugs.`;
+}
+/**
+ * Build the rules validator prompt.
+ * Runs if .haystack/pr-rules.yml exists OR agent instruction files are found.
+ *
+ * @returns The prompt string, or null if no rules content or agent policies provided.
+ */
+export function buildRulesValidatorPrompt(baseBranch, rulesYaml, outputPath, agentPolicies) {
+    const hasRules = rulesYaml.trim().length > 0;
+    const hasPolicies = agentPolicies && agentPolicies.length > 0;
+    if (!hasRules && !hasPolicies)
+        return null;
+    let rulesSection = '';
+    if (hasRules) {
+        rulesSection = `## Structured rules (pr-rules.yml)
+
+The following rules are defined in the project's \`.haystack/pr-rules.yml\`:
+
+\`\`\`yaml
+${rulesYaml}
+\`\`\`
+
+For each structured rule:
+- Read the rule's \`llm.prompt\` to understand what to look for.
+- If the rule has a \`llm.files\` glob, only check files matching that pattern.
+- If you find a violation, record it with the rule's ID (e.g., "PR001") and severity.
+- Use the rule's \`severity\` field (error or warning) for each violation.
+- Use the rule's \`message\` field as guidance for what the violation description should convey.
+
+`;
+    }
+    let policiesSection = '';
+    if (hasPolicies) {
+        const policyBlocks = agentPolicies.map(p => `### ${p.filename}
+
+\`\`\`
+${p.content}
+\`\`\``).join('\n\n');
+        policiesSection = `## Agent instruction policies
+
+The following agent instruction files contain project policies that apply to all code changes.
+Extract ACTIONABLE, CHECKABLE rules from these files — directives like "don't do X", "always do Y",
+"never use Z", "avoid X". Ignore general documentation, architecture descriptions, setup instructions,
+and command references.
+
+Pay special attention to policies about:
+- Backwards-compatibility hacks, shims, or legacy framing (in code, tests, comments, and naming)
+- Required tools or workflows (e.g., "always use X instead of Y")
+- Prohibited patterns or anti-patterns
+- Security requirements
+
+${policyBlocks}
+
+For each extracted policy violation:
+- Set \`rule\` to the source filename (e.g., "CLAUDE.md") instead of a rule ID.
+- Set \`severity\` to "error" for clear "never"/"don't"/"must not" directives, "warning" for "avoid"/"prefer not".
+- Check test code, comments, and variable/function names — not just production code logic. Backwards-compatibility
+  framing in test names (e.g., "test_backward_compat", "legacy") or comments (e.g., "# No X field (legacy)")
+  violates policies against backwards-compatibility hacks just as much as production shims do.
+
+`;
+    }
+    return `You are a PR rules validator. Your job is to check the code changes against project rules and policies, then flag violations.
+
+${rulesSection}${policiesSection}## Instructions
+
+1. Run \`git diff ${baseBranch}...HEAD --name-only\` to see which files changed.
+2. Run \`git diff ${baseBranch}...HEAD\` to see the full diff.
+3. Check ONLY the changed code (lines added or modified in the diff), not pre-existing code.
+4. If you need more context, read the relevant source files.
+
+## Important
+
+- Only flag violations in NEW or CHANGED code. Do not flag pre-existing issues.
+- Be precise about file paths and line numbers.
+- Structured pr-rules.yml rules take precedence if they overlap with agent policy directives.
+
+## Output
+
+Write your results to \`${outputPath}\` as JSON with this exact schema:
+
+\`\`\`json
+${RULES_VALIDATOR_SCHEMA}
+\`\`\`
+
+- Set \`rulesChecked\` to the total number of rules evaluated (structured rules + extracted agent policies)
+- Set \`passed\` to \`true\` if no violations found
+- Set \`passed\` to \`false\` if any violations with severity "error" were found
+- You MUST write the result file even if no violations are found`;
+}
+/**
+ * Build the intent drift prompt.
+ * Only runs if relevant trace files exist.
+ *
+ * @returns The prompt string, or null if no trace files provided.
+ */
+export function buildIntentDriftPrompt(baseBranch, traceFiles, outputPath) {
+    if (traceFiles.length === 0)
+        return null;
+    const traceFileList = traceFiles.map(f => `- \`${f}\``).join('\n');
+    return `You are an intent drift detector. Your job is to check whether an AI coding agent faithfully implemented what the user asked for.
+
+## Context
+
+This PR was created by an AI coding agent. The agent's session transcripts (traces) are stored locally. You will compare what the user asked the agent to do against what was actually implemented in the diff.
+
+## Instructions
+
+1. Read each of these files (they contain the user's messages extracted from the agent session, one per section):
+${traceFileList}
+
+2. From each file, identify:
+   - The user's original instruction/prompt (the first message)
+   - Any follow-up instructions or corrections from the user
+
+3. Run \`git diff ${baseBranch}...HEAD\` to see what was actually implemented.
+
+4. Compare the user's intent against the actual implementation. Look for:
+
+### Intent Drift
+The agent implemented something DIFFERENT from what was asked:
+- User says "delay as long as possible" → agent uses a fixed 30s timeout
+- User says "only when X" → agent does it unconditionally
+- User says "use library A" → agent uses library B
+- User says "lazy load" → agent loads eagerly
+
+### Incomplete Fulfillment
+The agent didn't finish everything that was asked:
+- User requested 3 things, agent only did 2
+- Interface fields declared but never populated
+- Functions stubbed with TODO/placeholder comments
+- Agent said "I'll skip X for now" for something the user explicitly requested
+- Tests not written when user asked for tests
+
+## Red flags to search for in the diff
+
+- Fixed/hardcoded values where dynamic behavior was requested
+- TODO, FIXME, placeholder, stub comments in new code
+- Empty function bodies or early returns
+- Interface fields that are declared but never assigned anywhere
+
+## Output
+
+Write your results to \`${outputPath}\` as JSON with this exact schema:
+
+\`\`\`json
+${INTENT_DRIFT_SCHEMA}
+\`\`\`
+
+- Set \`sessionsChecked\` to the number of trace files you read
+- Set \`passed\` to \`true\` if no drift or incomplete fulfillment found
+- Set \`passed\` to \`false\` if any issues with severity "error" were found
+- For each issue, set \`pattern\` to either "intent_drift" or "incomplete_fulfillment"
+- You MUST write the result file even if no issues are found
+
+## Severity guidelines
+
+- **error**: Core user intent violated — the main thing they asked for is wrong or missing
+- **warning**: Secondary requirement missed or approximated
+- **info**: Minor simplification that mostly still works as intended`;
+}

package/dist/triage/runner.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Triage runner — orchestrates parallel sub-agent execution for pre-PR checks.
+ *
+ * Detects the user's agentic CLI (Claude Code, Codex, Gemini), spawns
+ * parallel sub-processes for each checker, and collects structured JSON results.
+ */
+import type { AgenticCLI, TriageResult } from './types.js';
+/**
+ * Detect which agentic CLI is installed.
+ * Returns the first one found, or null if none available.
+ */
+export declare function detectAgenticCLI(): AgenticCLI | null;
+/**
+ * Run pre-PR triage checks using parallel sub-agent processes.
+ *
+ * @param gitRoot - Absolute path to the git repository root
+ * @param baseBranch - The base branch to diff against (e.g., "main")
+ * @returns Aggregated triage results
+ * @throws If no agentic CLI is detected
+ */
+export declare function runTriage(gitRoot: string, baseBranch: string): Promise<TriageResult>;

package/dist/triage/runner.js

@@ -0,0 +1,325 @@
+/**
+ * Triage runner — orchestrates parallel sub-agent execution for pre-PR checks.
+ *
+ * Detects the user's agentic CLI (Claude Code, Codex, Gemini), spawns
+ * parallel sub-processes for each checker, and collects structured JSON results.
+ */
+import { execSync, spawn } from 'child_process';
+import { existsSync, readFileSync, mkdirSync, rmSync } from 'fs';
+import { join } from 'path';
+import chalk from 'chalk';
+import { buildCodeReviewPrompt, buildRulesValidatorPrompt, buildIntentDriftPrompt } from './prompts.js';
+import { findRelevantTraces } from './traces.js';
+// ============================================================================
+// Constants
+// ============================================================================
+const TRIAGE_DIR = '.haystack/triage';
+const TIMEOUT_MS = 300_000; // 5 minutes per checker
+/** Max agentic turns per checker */
+const MAX_TURNS = {
+    'code-review': 30,
+    'rules-validator': 30,
+    'intent-drift': 30,
+};
+// ============================================================================
+// Agent policy file discovery
+// ============================================================================
+/** Well-known agent instruction files, checked in discovery order at repo root. */
+const AGENT_POLICY_FILENAMES = [
+    'CLAUDE.md',
+    'AGENTS.md',
+    'COPILOT.md',
+    '.cursorrules',
+    join('.github', 'copilot-instructions.md'),
+];
+/**
+ * Discover agent instruction files at the repo root.
+ * Returns all that exist with their contents.
+ */
+function discoverAgentPolicyFiles(gitRoot) {
+    const results = [];
+    for (const filename of AGENT_POLICY_FILENAMES) {
+        const fullPath = join(gitRoot, filename);
+        if (existsSync(fullPath)) {
+            const content = readFileSync(fullPath, 'utf-8').trim();
+            if (content) {
+                results.push({ filename, content });
+            }
+        }
+    }
+    return results;
+}
+// ============================================================================
+// CLI detection
+// ============================================================================
+/**
+ * Detect which agentic CLI is installed.
+ * Returns the first one found, or null if none available.
+ */
+export function detectAgenticCLI() {
+    const isWindows = process.platform === 'win32';
+    const inCodexSession = Boolean(process.env.CODEX_SHELL || process.env.CODEX_THREAD_ID || process.env.CODEX_CI);
+    const inClaudeSession = Boolean(process.env.CLAUDE_CODE || process.env.CLAUDECODE);
+    const clis = inCodexSession
+        ? ['codex', 'claude', 'gemini']
+        : inClaudeSession
+            ? ['claude', 'codex', 'gemini']
+            : ['claude', 'codex', 'gemini'];
+    for (const name of clis) {
+        try {
+            execSync(isWindows ? `where ${name}` : `which ${name}`, { stdio: 'ignore' });
+            return name;
+        }
+        catch {
+            // Not installed
+        }
+    }
+    return null;
+}
+/**
+ * Build the CLI command + args for the detected agentic tool.
+ */
+function buildCommand(cli, prompt, maxTurns) {
+    switch (cli) {
+        case 'claude':
+            return {
+                command: 'claude',
+                args: [
+                    '-p', prompt,
+                    '--dangerously-skip-permissions',
+                    '--max-turns', String(maxTurns),
+                    '--allowedTools', 'Bash', 'Read', 'Glob', 'Grep', 'Write',
+                ],
+            };
+        case 'codex':
+            return {
+                command: 'codex',
+                args: ['exec', prompt, '--full-auto', '--ephemeral'],
+            };
+        case 'gemini':
+            return {
+                command: 'gemini',
+                args: ['-p', prompt, '-y'],
+            };
+    }
+}
+/**
+ * Spawn a sub-agent process and wait for it to complete.
+ * Returns the exit code.
+ */
+function spawnChecker(cli, config, cwd) {
+    return new Promise((resolve) => {
+        const { command, args } = buildCommand(cli, config.prompt, config.maxTurns);
+        let stdout = '';
+        let stderr = '';
+        const codexHome = join(cwd, '.haystack', 'triage', 'codex-home');
+        if (cli === 'codex') {
+            mkdirSync(codexHome, { recursive: true });
+        }
+        const proc = spawn(command, args, {
+            cwd,
+            stdio: ['ignore', 'pipe', 'pipe'],
+            env: {
+                ...process.env,
+                CLAUDECODE: undefined,
+                CODEX_HOME: cli === 'codex' ? codexHome : process.env.CODEX_HOME,
+            },
+        });
+        proc.stdout?.on('data', (data) => {
+            stdout += data.toString();
+        });
+        proc.stderr?.on('data', (data) => {
+            stderr += data.toString();
+        });
+        // Timeout
+        const timer = setTimeout(() => {
+            proc.kill('SIGTERM');
+            stderr += `\nProcess killed after ${TIMEOUT_MS / 1000}s timeout`;
+        }, TIMEOUT_MS);
+        proc.on('close', (code) => {
+            clearTimeout(timer);
+            resolve({ exitCode: code ?? 1, output: `${stdout}\n${stderr}`.trim() });
+        });
+        proc.on('error', (err) => {
+            clearTimeout(timer);
+            resolve({ exitCode: 1, output: err.message });
+        });
+    });
+}
+function summarizeCheckerFailureOutput(output) {
+    const lines = output
+        .split('\n')
+        .map(line => line.trim())
+        .filter(Boolean);
+    if (lines.length === 0)
+        return null;
+    const priorityPatterns = [
+        /not logged in/i,
+        /stream disconnected|error sending request|failed to refresh available models/i,
+        /operation not permitted|readonly database|permission denied/i,
+        /timeout|timed out/i,
+        /unauthorized|forbidden/i,
+        /^error:/i,
+        /failed/i,
+    ];
+    let summary = lines[lines.length - 1];
+    for (const pattern of priorityPatterns) {
+        const match = lines.find(line => pattern.test(line));
+        if (match) {
+            summary = match;
+            break;
+        }
+    }
+    return summary.length > 220
+        ? `${summary.slice(0, 217)}...`
+        : summary;
+}
+// ============================================================================
+// Result reading
+// ============================================================================
+/**
+ * Read and validate a checker result JSON file.
+ */
+function readCheckerResult(outputPath, checkerName) {
+    if (!existsSync(outputPath)) {
+        return null;
+    }
+    try {
+        const content = readFileSync(outputPath, 'utf-8');
+        const result = JSON.parse(content);
+        // Basic validation
+        if (!result.checker || !Array.isArray(result.issues) || typeof result.passed !== 'boolean') {
+            return null;
+        }
+        // Ensure issues have required fields
+        result.issues = result.issues.filter((issue) => issue.file && issue.message && issue.severity);
+        // Recalculate passed based on issues
+        result.passed = !result.issues.some((i) => i.severity === 'error');
+        return result;
+    }
+    catch {
+        return null;
+    }
+}
+// ============================================================================
+// Main runner
+// ============================================================================
+/**
+ * Run pre-PR triage checks using parallel sub-agent processes.
+ *
+ * @param gitRoot - Absolute path to the git repository root
+ * @param baseBranch - The base branch to diff against (e.g., "main")
+ * @returns Aggregated triage results
+ * @throws If no agentic CLI is detected
+ */
+export async function runTriage(gitRoot, baseBranch) {
+    const startTime = Date.now();
+    // Detect CLI
+    const cli = detectAgenticCLI();
+    if (!cli) {
+        throw new Error('No agentic CLI found. Install Claude Code (claude), Codex CLI (codex), or Gemini CLI (gemini).');
+    }
+    // Fast-fail in Codex app shells where outbound network is disabled.
+    // Spawning nested `codex exec` will fail after retries; skip triage immediately instead.
+    const codexNetworkDisabled = process.env.CODEX_SANDBOX_NETWORK_DISABLED === '1';
+    if (cli === 'codex' && codexNetworkDisabled) {
+        throw new Error('Codex shell has network disabled (CODEX_SANDBOX_NETWORK_DISABLED=1), so triage sub-agents cannot run. Re-run outside this sandbox or use --force.');
+    }
+    console.log(chalk.dim(`  Using: ${cli}`));
+    // Prepare output directory
+    const triageDir = join(gitRoot, TRIAGE_DIR);
+    if (existsSync(triageDir)) {
+        rmSync(triageDir, { recursive: true });
+    }
+    mkdirSync(triageDir, { recursive: true });
+    // Build checker configs
+    const checkers = [];
+    // 1. Code review (always runs)
+    const codeReviewOutput = join(triageDir, 'code-review.json');
+    checkers.push({
+        name: 'code-review',
+        prompt: buildCodeReviewPrompt(baseBranch, codeReviewOutput),
+        outputFile: codeReviewOutput,
+        maxTurns: MAX_TURNS['code-review'],
+    });
+    // 2. Rules validator (if pr-rules.yml or agent instruction files exist)
+    const rulesPath = join(gitRoot, '.haystack', 'pr-rules.yml');
+    const hasRulesYaml = existsSync(rulesPath);
+    const rulesYaml = hasRulesYaml ? readFileSync(rulesPath, 'utf-8') : '';
+    const agentPolicyFiles = discoverAgentPolicyFiles(gitRoot);
+    if (hasRulesYaml || agentPolicyFiles.length > 0) {
+        const rulesValidatorOutput = join(triageDir, 'rules-validator.json');
+        const rulesPrompt = buildRulesValidatorPrompt(baseBranch, rulesYaml, rulesValidatorOutput, agentPolicyFiles);
+        if (rulesPrompt) {
+            checkers.push({
+                name: 'rules-validator',
+                prompt: rulesPrompt,
+                outputFile: rulesValidatorOutput,
+                maxTurns: MAX_TURNS['rules-validator'],
+            });
+        }
+    }
+    // 3. Intent drift (only if relevant trace files exist)
+    const traceFiles = findRelevantTraces(gitRoot, baseBranch);
+    if (traceFiles.length > 0) {
+        const intentDriftOutput = join(triageDir, 'intent-drift.json');
+        const driftPrompt = buildIntentDriftPrompt(baseBranch, traceFiles, intentDriftOutput);
+        if (driftPrompt) {
+            checkers.push({
+                name: 'intent-drift',
+                prompt: driftPrompt,
+                outputFile: intentDriftOutput,
+                maxTurns: MAX_TURNS['intent-drift'],
+            });
+        }
+    }
+    // Log what we're running
+    const checkerNames = checkers.map(c => c.name);
+    console.log(chalk.dim(`  Checkers: ${checkerNames.join(', ')}`));
+    if (traceFiles.length > 0) {
+        console.log(chalk.dim(`  Traces: ${traceFiles.length} relevant session(s) found`));
+    }
+    console.log(chalk.dim(`  Running ${checkers.length} checker(s) in parallel...\n`));
+    // Spawn all checkers in parallel
+    const spawnResults = await Promise.allSettled(checkers.map(async (checker) => {
+        const startLabel = chalk.dim(`  [${checker.name}]`);
+        console.log(`${startLabel} Starting...`);
+        const result = await spawnChecker(cli, checker, gitRoot);
+        if (result.exitCode === 0) {
+            console.log(`${startLabel} ${chalk.green('Done')}`);
+        }
+        else {
+            console.log(`${startLabel} ${chalk.yellow(`Exited with code ${result.exitCode}`)}`);
+        }
+        return { checker, result };
+    }));
+    // Collect results
+    const results = [];
+    const errors = [];
+    for (const spawnResult of spawnResults) {
+        if (spawnResult.status === 'rejected') {
+            errors.push(`Checker failed: ${spawnResult.reason}`);
+            continue;
+        }
+        const { checker, result } = spawnResult.value;
+        const checkerResult = readCheckerResult(checker.outputFile, checker.name);
+        if (checkerResult) {
+            results.push(checkerResult);
+        }
+        else {
+            // Sub-agent didn't produce valid output
+            const failureSummary = summarizeCheckerFailureOutput(result.output);
+            const errMsg = result.exitCode !== 0
+                ? `${checker.name}: process exited with code ${result.exitCode}${failureSummary ? ` (${failureSummary})` : ''}`
+                : `${checker.name}: no valid result file produced`;
+            errors.push(errMsg);
+        }
+    }
+    const passed = results.every(r => r.passed) && errors.length === 0;
+    return {
+        passed,
+        results,
+        errors,
+        duration: Date.now() - startTime,
+    };
+}

package/dist/triage/traces.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Local Entire CLI trace discovery for intent drift analysis.
+ *
+ * Finds .entire/metadata/ session files whose modified files
+ * overlap with the current diff's changed files.
+ */
+/**
+ * Find local Entire CLI trace files relevant to the current diff.
+ *
+ * Scans .entire/metadata/ for session directories containing full.jsonl,
+ * then checks if any files modified in those sessions overlap with the
+ * files changed in the current diff.
+ *
+ * Returns paths to condensed files containing only user messages (not the
+ * raw multi-MB traces). This keeps the intent-drift sub-agent focused on
+ * user intent without burning its context window on tool outputs.
+ *
+ * @returns Array of absolute paths to condensed user-messages files
+ */
+export declare function findRelevantTraces(gitRoot: string, baseBranch: string): string[];