@simonren/quorum 0.7.0

package/dist/context.js

@@ -0,0 +1,383 @@
+/**
+ * Rich Context Protocol for Review Handoff
+ *
+ * Defines the structured information that should flow from CC to reviewers.
+ * This replaces the simple "ccOutput: string" with a rich, queryable context.
+ */
+import { z } from 'zod';
+// =============================================================================
+// FILE CHANGE CONTEXT
+// =============================================================================
+/**
+ * Represents a change to a single file with semantic understanding
+ */
+export const FileChangeSchema = z.object({
+    path: z.string().describe('Relative path from working directory'),
+    language: z.string().optional().describe('Programming language'),
+    changeType: z.enum(['created', 'modified', 'deleted', 'renamed']),
+    // The actual changes
+    diff: z.string().optional().describe('Unified diff format'),
+    linesAdded: z.number().int().nonnegative().optional(),
+    linesRemoved: z.number().int().nonnegative().optional(),
+    // For small/new files, include full content
+    content: z.string().optional().describe('Full file content (for new/small files)'),
+    // Semantic understanding
+    changedSymbols: z.array(z.object({
+        name: z.string(),
+        type: z.enum(['function', 'class', 'variable', 'type', 'import', 'export', 'other']),
+        lineStart: z.number().int().positive().optional(),
+        lineEnd: z.number().int().positive().optional(),
+    })).optional().describe('Symbols that were modified'),
+    // Relationships
+    imports: z.array(z.string()).optional().describe('Modules this file imports'),
+    importedBy: z.array(z.string()).optional().describe('Files that import this module'),
+    testFile: z.string().optional().describe('Related test file path'),
+});
+// =============================================================================
+// EXECUTION CONTEXT
+// =============================================================================
+/**
+ * Results from running tests, build, lint, etc.
+ */
+export const ExecutionContextSchema = z.object({
+    // Test results
+    tests: z.object({
+        ran: z.boolean(),
+        passed: z.number().int().nonnegative().optional(),
+        failed: z.number().int().nonnegative().optional(),
+        skipped: z.number().int().nonnegative().optional(),
+        failures: z.array(z.object({
+            testName: z.string(),
+            file: z.string().optional(),
+            error: z.string(),
+        })).optional(),
+    }).optional(),
+    // Build status
+    build: z.object({
+        ran: z.boolean(),
+        success: z.boolean().optional(),
+        errors: z.array(z.object({
+            file: z.string(),
+            line: z.number().int().positive().optional(),
+            message: z.string(),
+        })).optional(),
+        warnings: z.array(z.object({
+            file: z.string(),
+            line: z.number().int().positive().optional(),
+            message: z.string(),
+        })).optional(),
+    }).optional(),
+    // Type checking
+    typeCheck: z.object({
+        ran: z.boolean(),
+        errors: z.array(z.object({
+            file: z.string(),
+            line: z.number().int().positive().optional(),
+            message: z.string(),
+            code: z.string().optional(), // e.g., "TS2345"
+        })).optional(),
+    }).optional(),
+    // Linting
+    lint: z.object({
+        ran: z.boolean(),
+        issues: z.array(z.object({
+            file: z.string(),
+            line: z.number().int().positive().optional(),
+            rule: z.string().optional(),
+            severity: z.enum(['error', 'warning', 'info']),
+            message: z.string(),
+        })).optional(),
+    }).optional(),
+});
+// =============================================================================
+// GIT CONTEXT
+// =============================================================================
+export const GitContextSchema = z.object({
+    branch: z.string().optional(),
+    baseBranch: z.string().optional().describe('Branch this was based on (e.g., main)'),
+    // Recent commits by CC
+    commits: z.array(z.object({
+        hash: z.string(),
+        message: z.string(),
+        filesChanged: z.array(z.string()),
+    })).optional(),
+    // If this is for a PR
+    pullRequest: z.object({
+        title: z.string().optional(),
+        description: z.string().optional(),
+        targetBranch: z.string().optional(),
+    }).optional(),
+    // Uncommitted changes
+    uncommittedChanges: z.boolean().optional(),
+});
+// =============================================================================
+// CC'S ANALYSIS & DECISIONS
+// =============================================================================
+export const CCAnalysisSchema = z.object({
+    // What CC was asked to do
+    originalRequest: z.string().describe("User's original request/task"),
+    taskType: z.enum(['feature', 'bugfix', 'refactor', 'security-fix', 'performance', 'review', 'other']).optional(),
+    // What CC did
+    summary: z.string().describe('Brief summary of changes made'),
+    // CC's findings (if reviewing/analyzing)
+    findings: z.array(z.object({
+        category: z.string(),
+        description: z.string(),
+        location: z.string().optional(),
+        confidence: z.number().min(0).max(1).optional(),
+        addressed: z.boolean().optional().describe('Whether CC already fixed this'),
+    })).optional(),
+    // What CC is uncertain about
+    uncertainties: z.array(z.object({
+        topic: z.string(),
+        question: z.string(),
+        ccBestGuess: z.string().optional().describe("CC's current assumption"),
+    })).optional().describe('Things CC is unsure about - reviewer should verify'),
+    // Assumptions CC made
+    assumptions: z.array(z.string()).optional(),
+    // Decisions CC made and why
+    decisions: z.array(z.object({
+        decision: z.string(),
+        rationale: z.string(),
+        alternatives: z.array(z.string()).optional(),
+    })).optional(),
+    // Overall confidence
+    confidence: z.number().min(0).max(1).optional().describe("CC's overall confidence in the work"),
+});
+// =============================================================================
+// REVIEW SCOPE & GUIDANCE
+// =============================================================================
+export const ReviewScopeSchema = z.object({
+    // What MUST be reviewed (critical paths)
+    mustReview: z.array(z.object({
+        path: z.string(),
+        reason: z.string(),
+        specificConcerns: z.array(z.string()).optional(),
+    })).optional(),
+    // What SHOULD be reviewed (important but not critical)
+    shouldReview: z.array(z.object({
+        path: z.string(),
+        reason: z.string(),
+    })).optional(),
+    // What MAY be reviewed (nice to have)
+    mayReview: z.array(z.string()).optional(),
+    // What to SKIP (already validated, unchanged, etc.)
+    skipReview: z.array(z.object({
+        path: z.string(),
+        reason: z.string(),
+    })).optional(),
+    // Specific questions CC wants answered
+    questions: z.array(z.object({
+        question: z.string(),
+        context: z.string().optional(),
+        relevantFiles: z.array(z.string()).optional(),
+        ccAnswer: z.string().optional().describe("What CC thinks - for comparison"),
+    })).optional(),
+});
+// =============================================================================
+// FULL REVIEW CONTEXT
+// =============================================================================
+/**
+ * Complete context for a review request.
+ * This is what should be passed from CC to reviewers.
+ */
+export const ReviewContextSchema = z.object({
+    // Metadata
+    timestamp: z.string().datetime().optional(),
+    workingDir: z.string(),
+    // Code changes
+    changes: z.object({
+        files: z.array(FileChangeSchema),
+        totalLinesAdded: z.number().int().nonnegative().optional(),
+        totalLinesRemoved: z.number().int().nonnegative().optional(),
+        impactedModules: z.array(z.string()).optional(),
+    }),
+    // CC's work
+    analysis: CCAnalysisSchema,
+    // Execution results
+    execution: ExecutionContextSchema.optional(),
+    // Git info
+    git: GitContextSchema.optional(),
+    // Review guidance
+    scope: ReviewScopeSchema.optional(),
+    // Focus areas
+    focusAreas: z.array(z.string()).optional(),
+    // Custom instructions
+    customInstructions: z.string().optional(),
+});
+// =============================================================================
+// CONTEXT BUILDERS
+// =============================================================================
+/**
+ * Build a minimal context from legacy inputs
+ */
+export function buildMinimalContext(workingDir, ccOutput, analyzedFiles, focusAreas, customPrompt) {
+    return {
+        workingDir,
+        changes: {
+            files: (analyzedFiles || []).map(path => ({
+                path,
+                changeType: 'modified',
+            })),
+        },
+        analysis: {
+            originalRequest: 'Not specified',
+            summary: ccOutput,
+        },
+        focusAreas,
+        customInstructions: customPrompt,
+    };
+}
+/**
+ * Build context from git diff
+ */
+export async function buildContextFromGitDiff(workingDir, baseBranch = 'main') {
+    // This would shell out to git to get actual diff info
+    // For now, return a placeholder
+    return {
+        workingDir,
+        git: {
+            baseBranch,
+        },
+    };
+}
+/**
+ * Optimize context to fit within token limits while preserving important info
+ */
+export function optimizeContext(context, options) {
+    const optimized = { ...context };
+    // Prioritize files based on focus areas
+    if (options.focusAreas && options.focusAreas.length > 0) {
+        const priorityPatterns = getPriorityPatterns(options.focusAreas);
+        optimized.changes.files = optimized.changes.files.sort((a, b) => {
+            const aPriority = getPriority(a.path, priorityPatterns);
+            const bPriority = getPriority(b.path, priorityPatterns);
+            return bPriority - aPriority;
+        });
+    }
+    // Truncate diffs if too large
+    if (!options.includeDiffs) {
+        optimized.changes.files = optimized.changes.files.map(f => ({
+            ...f,
+            diff: undefined,
+        }));
+    }
+    // Remove full content if not needed
+    if (!options.includeFullContent) {
+        optimized.changes.files = optimized.changes.files.map(f => ({
+            ...f,
+            content: undefined,
+        }));
+    }
+    return optimized;
+}
+function getPriorityPatterns(focusAreas) {
+    const patterns = [];
+    if (focusAreas.includes('security')) {
+        patterns.push(/auth/i, /login/i, /password/i, /crypto/i, /token/i, /api/i);
+    }
+    if (focusAreas.includes('performance')) {
+        patterns.push(/database/i, /query/i, /cache/i, /service/i);
+    }
+    if (focusAreas.includes('testing')) {
+        patterns.push(/test/i, /spec/i, /mock/i);
+    }
+    return patterns;
+}
+function getPriority(path, patterns) {
+    return patterns.filter(p => p.test(path)).length;
+}
+// =============================================================================
+// CONTEXT SERIALIZATION FOR PROMPTS
+// =============================================================================
+/**
+ * Convert context to a string suitable for inclusion in prompts
+ */
+export function contextToPromptString(context) {
+    const sections = [];
+    // Section 1: Task Overview
+    sections.push(`## Task Overview
+**Original Request:** ${context.analysis.originalRequest}
+**Summary:** ${context.analysis.summary}
+${context.analysis.taskType ? `**Task Type:** ${context.analysis.taskType}` : ''}
+${context.analysis.confidence !== undefined ? `**CC Confidence:** ${Math.round(context.analysis.confidence * 100)}%` : ''}`);
+    // Section 2: Files Changed
+    if (context.changes.files.length > 0) {
+        sections.push(`\n## Files Changed (${context.changes.files.length})`);
+        for (const file of context.changes.files) {
+            let fileInfo = `\n### ${file.path} [${file.changeType}]`;
+            if (file.changedSymbols && file.changedSymbols.length > 0) {
+                fileInfo += `\nModified: ${file.changedSymbols.map(s => `${s.name} (${s.type})`).join(', ')}`;
+            }
+            if (file.linesAdded !== undefined || file.linesRemoved !== undefined) {
+                fileInfo += `\nLines: +${file.linesAdded || 0} / -${file.linesRemoved || 0}`;
+            }
+            if (file.diff) {
+                fileInfo += `\n\`\`\`diff\n${file.diff}\n\`\`\``;
+            }
+            sections.push(fileInfo);
+        }
+    }
+    // Section 3: CC's Uncertainties (IMPORTANT for reviewer)
+    if (context.analysis.uncertainties && context.analysis.uncertainties.length > 0) {
+        sections.push(`\n## CC's Uncertainties (Please Verify)`);
+        for (const u of context.analysis.uncertainties) {
+            sections.push(`\n**${u.topic}**
+Question: ${u.question}
+${u.ccBestGuess ? `CC's guess: ${u.ccBestGuess}` : ''}`);
+        }
+    }
+    // Section 4: Questions for Reviewer
+    if (context.scope?.questions && context.scope.questions.length > 0) {
+        sections.push(`\n## Specific Questions`);
+        for (const q of context.scope.questions) {
+            sections.push(`\n- ${q.question}${q.ccAnswer ? ` (CC thinks: ${q.ccAnswer})` : ''}`);
+        }
+    }
+    // Section 5: Execution Results
+    if (context.execution) {
+        const exec = context.execution;
+        const execLines = [];
+        if (exec.tests?.ran) {
+            const t = exec.tests;
+            execLines.push(`Tests: ${t.passed || 0} passed, ${t.failed || 0} failed, ${t.skipped || 0} skipped`);
+            if (t.failures && t.failures.length > 0) {
+                for (const f of t.failures.slice(0, 3)) {
+                    execLines.push(`  ❌ ${f.testName}: ${f.error.slice(0, 100)}`);
+                }
+            }
+        }
+        if (exec.build?.ran) {
+            execLines.push(`Build: ${exec.build.success ? '✓ Success' : '❌ Failed'}`);
+        }
+        if (exec.typeCheck?.ran && exec.typeCheck.errors && exec.typeCheck.errors.length > 0) {
+            execLines.push(`Type Errors: ${exec.typeCheck.errors.length}`);
+        }
+        if (execLines.length > 0) {
+            sections.push(`\n## Execution Results\n${execLines.join('\n')}`);
+        }
+    }
+    // Section 6: Review Priorities
+    if (context.scope?.mustReview && context.scope.mustReview.length > 0) {
+        sections.push(`\n## Priority Review Areas`);
+        for (const r of context.scope.mustReview) {
+            sections.push(`- **${r.path}**: ${r.reason}`);
+        }
+    }
+    return sections.join('\n');
+}
+/**
+ * Check if a file:line reference is valid
+ */
+export function verifyFileLineReference(reference, verification) {
+    if (!verification.existingFiles.has(reference.file)) {
+        return { valid: false, reason: `File does not exist: ${reference.file}` };
+    }
+    if (reference.line !== undefined) {
+        const lineCount = verification.fileLineCounts.get(reference.file);
+        if (lineCount && reference.line > lineCount) {
+            return { valid: false, reason: `Line ${reference.line} exceeds file length (${lineCount} lines)` };
+        }
+    }
+    return { valid: true };
+}

package/dist/decoders/claude.d.ts

@@ -0,0 +1,53 @@
+/**
+ * ClaudeEventDecoder — Parses Claude CLI stream-json JSONL events.
+ *
+ * Event stream format (with --output-format stream-json --verbose):
+ *   {"type":"system","subtype":"init",...}
+ *   {"type":"assistant","message":{"content":[{"type":"text","text":"..."}],...},...}
+ *   {"type":"result","subtype":"success","result":"...","duration_ms":...,"usage":{...}}
+ */
+export interface ClaudeEvent {
+    type: string;
+    subtype?: string;
+    session_id?: string;
+    model?: string;
+    result?: string;
+    is_error?: boolean;
+    duration_ms?: number;
+    message?: {
+        content?: Array<{
+            type: string;
+            text?: string;
+        }>;
+        usage?: {
+            input_tokens: number;
+            output_tokens: number;
+            cache_read_input_tokens?: number;
+            cache_creation_input_tokens?: number;
+        };
+    };
+    usage?: {
+        input_tokens: number;
+        output_tokens: number;
+        cache_read_input_tokens?: number;
+        cache_creation_input_tokens?: number;
+    };
+    tool_use_id?: string;
+    tool_name?: string;
+}
+export declare class ClaudeEventDecoder {
+    onProgress?: (eventType: string, detail?: string) => void;
+    private _finalResponse;
+    private _usage;
+    private _error;
+    private _eventCount;
+    private _durationMs;
+    processLine(line: string): void;
+    getFinalResponse(): string | null;
+    getUsage(): ClaudeEvent['usage'] | null;
+    getError(): string | null;
+    getDurationMs(): number | null;
+    hasNoOutput(): boolean;
+    private _handleEvent;
+    private _describeEvent;
+}

package/dist/decoders/claude.js

@@ -0,0 +1,106 @@
+/**
+ * ClaudeEventDecoder — Parses Claude CLI stream-json JSONL events.
+ *
+ * Event stream format (with --output-format stream-json --verbose):
+ *   {"type":"system","subtype":"init",...}
+ *   {"type":"assistant","message":{"content":[{"type":"text","text":"..."}],...},...}
+ *   {"type":"result","subtype":"success","result":"...","duration_ms":...,"usage":{...}}
+ */
+// =============================================================================
+// DECODER
+// =============================================================================
+export class ClaudeEventDecoder {
+    onProgress;
+    _finalResponse = null;
+    _usage = null;
+    _error = null;
+    _eventCount = 0;
+    _durationMs = null;
+    // =============================================================================
+    // PUBLIC API
+    // =============================================================================
+    processLine(line) {
+        const trimmed = line.trim();
+        if (trimmed.length === 0)
+            return;
+        let event;
+        try {
+            const parsed = JSON.parse(trimmed);
+            if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed))
+                return;
+            event = parsed;
+        }
+        catch {
+            return;
+        }
+        if (!event.type)
+            return;
+        this._handleEvent(event);
+    }
+    getFinalResponse() {
+        return this._finalResponse;
+    }
+    getUsage() {
+        return this._usage;
+    }
+    getError() {
+        return this._error;
+    }
+    getDurationMs() {
+        return this._durationMs;
+    }
+    hasNoOutput() {
+        return this._eventCount > 0 && this._finalResponse === null;
+    }
+    // =============================================================================
+    // PRIVATE HELPERS
+    // =============================================================================
+    _handleEvent(event) {
+        this._eventCount++;
+        switch (event.type) {
+            case 'result':
+                // The result event contains the final text response
+                if (event.subtype === 'success' && typeof event.result === 'string') {
+                    this._finalResponse = event.result;
+                }
+                if (event.is_error) {
+                    this._error = event.result || 'Claude review failed';
+                }
+                if (event.usage) {
+                    this._usage = event.usage;
+                }
+                if (event.duration_ms != null) {
+                    this._durationMs = event.duration_ms;
+                }
+                break;
+            case 'assistant':
+                // Track usage from assistant messages
+                if (event.message?.usage) {
+                    this._usage = event.message.usage;
+                }
+                break;
+            case 'error':
+                this._error = event.result || 'Unknown error from Claude CLI';
+                break;
+        }
+        this.onProgress?.(event.type, this._describeEvent(event));
+    }
+    _describeEvent(event) {
+        switch (event.type) {
+            case 'system':
+                if (event.subtype === 'init')
+                    return `model: ${event.model || 'opus'}`;
+                if (event.subtype)
+                    return event.subtype;
+                return undefined;
+            case 'assistant':
+                return 'assistant message';
+            case 'tool_use':
+                return event.tool_name ? `tool: ${event.tool_name}` : 'tool use';
+            case 'result':
+                return `status: ${event.subtype || 'unknown'}`;
+            default:
+                return undefined;
+        }
+    }
+}

package/dist/decoders/codex.d.ts

@@ -0,0 +1,71 @@
+/**
+ * CodexEventDecoder
+ *
+ * Parses JSONL streaming events emitted by `codex exec --json` on stdout.
+ * Extracts the final agent_message text and usage statistics.
+ *
+ * Event stream format:
+ *   {"type":"thread.started","thread_id":"..."}
+ *   {"type":"turn.started"}
+ *   {"type":"item.started","item":{...}}
+ *   {"type":"item.completed","item":{...}}
+ *   {"type":"turn.completed","usage":{...}}
+ */
+export interface CodexEvent {
+    type: string;
+    thread_id?: string;
+    item?: {
+        id: string;
+        type: string;
+        text?: string;
+        command?: string;
+        status?: string;
+        exit_code?: number;
+        message?: string;
+    };
+    usage?: {
+        input_tokens: number;
+        cached_input_tokens?: number;
+        output_tokens: number;
+    };
+    error?: {
+        message: string;
+    };
+    message?: string;
+}
+export declare class CodexEventDecoder {
+    /**
+     * Optional callback invoked for every successfully parsed event.
+     * @param eventType - The `type` field of the event (e.g. "item.completed").
+     * @param detail    - A human-readable detail string for logging (may be undefined).
+     */
+    onProgress?: (eventType: string, detail?: string) => void;
+    private _finalResponse;
+    private _usage;
+    private _error;
+    private _eventCount;
+    /**
+     * Parse a single JSONL line. Silently skips malformed or empty input.
+     */
+    processLine(line: string): void;
+    /**
+     * Returns the text from the LAST `item.completed` event whose item type is
+     * `"agent_message"`, or `null` if no such event has been seen.
+     */
+    getFinalResponse(): string | null;
+    /**
+     * Returns the usage stats from the most recent `turn.completed` event, or
+     * `null` if no such event has been seen.
+     */
+    getUsage(): CodexEvent['usage'] | null;
+    /**
+     * Returns the error message from `error` or `turn.failed` events, or `null`.
+     */
+    getError(): string | null;
+    /**
+     * Returns true if events were received but no agent_message was produced.
+     * Combined with a fast exit, this indicates rate limiting or instant rejection.
+     */
+    hasNoOutput(): boolean;
+    private _handleEvent;
+}