grov 0.1.0

package/dist/lib/anchor-extractor.js

@@ -0,0 +1,296 @@
+// Extract function/class anchors from source files for file-level reasoning
+import { createHash } from 'crypto';
+import { extname } from 'path';
+const TYPESCRIPT_PATTERNS = {
+    // export async function foo() or function foo()
+    function: /^(?:export\s+)?(?:async\s+)?function\s+(\w+)/,
+    // export const foo = async () => or const foo = function()
+    arrowFunction: /^(?:export\s+)?(?:const|let|var)\s+(\w+)\s*=\s*(?:async\s*)?(?:\([^)]*\)\s*=>|\([^)]*\)\s*:\s*\w+\s*=>|function)/,
+    // export class Foo or class Foo
+    class: /^(?:export\s+)?(?:abstract\s+)?class\s+(\w+)/,
+    // async foo() { or foo(): Promise<void> { or private foo() {
+    method: /^\s+(?:public\s+|private\s+|protected\s+)?(?:static\s+)?(?:async\s+)?(\w+)\s*(?:<[^>]*>)?\s*\([^)]*\)/,
+};
+const PYTHON_PATTERNS = {
+    // def foo():
+    function: /^def\s+(\w+)\s*\(/,
+    // class Foo:
+    class: /^class\s+(\w+)/,
+    // def foo(self): (indented method)
+    method: /^\s+def\s+(\w+)\s*\(/,
+};
+const GO_PATTERNS = {
+    // func foo() or func (r *Receiver) foo()
+    function: /^func\s+(?:\([^)]+\)\s+)?(\w+)\s*\(/,
+    // type Foo struct
+    class: /^type\s+(\w+)\s+struct/,
+    // Method receivers are handled by function pattern
+    method: /^func\s+\([^)]+\)\s+(\w+)\s*\(/,
+};
+const RUST_PATTERNS = {
+    // fn foo() or pub fn foo()
+    function: /^(?:pub\s+)?(?:async\s+)?fn\s+(\w+)/,
+    // struct Foo or pub struct Foo
+    class: /^(?:pub\s+)?struct\s+(\w+)/,
+    // fn foo(&self) inside impl block (indented)
+    method: /^\s+(?:pub\s+)?(?:async\s+)?fn\s+(\w+)/,
+};
+/**
+ * Get language patterns based on file extension
+ */
+function getPatternsForFile(filePath) {
+    const ext = extname(filePath).toLowerCase();
+    switch (ext) {
+        case '.ts':
+        case '.tsx':
+        case '.js':
+        case '.jsx':
+        case '.mjs':
+        case '.cjs':
+            return TYPESCRIPT_PATTERNS;
+        case '.py':
+            return PYTHON_PATTERNS;
+        case '.go':
+            return GO_PATTERNS;
+        case '.rs':
+            return RUST_PATTERNS;
+        default:
+            return null;
+    }
+}
+// PERFORMANCE: Maximum anchors per file to prevent DoS
+const MAX_ANCHORS_PER_FILE = 1000;
+// PERFORMANCE: Maximum file size to process (1MB)
+const MAX_FILE_SIZE = 1024 * 1024;
+/**
+ * Extract all anchors from a source file.
+ * PERFORMANCE: Uses single-pass O(n) algorithm instead of O(n²).
+ * SECURITY: Limits anchors to prevent DoS with pathological files.
+ */
+export function extractAnchors(filePath, content) {
+    // SECURITY: Skip files that are too large
+    if (content.length > MAX_FILE_SIZE) {
+        return [];
+    }
+    const patterns = getPatternsForFile(filePath);
+    if (!patterns) {
+        return [];
+    }
+    const lines = content.split('\n');
+    const isPython = filePath.endsWith('.py');
+    const anchors = [];
+    const openAnchors = [];
+    let currentBraceDepth = 0;
+    for (let i = 0; i < lines.length; i++) {
+        // SECURITY: Stop if we've found too many anchors
+        if (anchors.length >= MAX_ANCHORS_PER_FILE) {
+            break;
+        }
+        const line = lines[i];
+        const lineNumber = i + 1; // 1-indexed
+        // Count braces in this line BEFORE pattern matching
+        let lineOpenBraces = 0;
+        let lineCloseBraces = 0;
+        for (const char of line) {
+            if (char === '{')
+                lineOpenBraces++;
+            else if (char === '}')
+                lineCloseBraces++;
+        }
+        // Close any open anchors whose braces have returned to their start level
+        // Do this BEFORE adding line's braces to handle same-line open/close
+        if (!isPython) {
+            // Process closing braces
+            for (let b = 0; b < lineCloseBraces; b++) {
+                currentBraceDepth--;
+                // Check if any open anchor should be closed
+                while (openAnchors.length > 0) {
+                    const top = openAnchors[openAnchors.length - 1];
+                    if (currentBraceDepth < top.braceDepthAtStart) {
+                        openAnchors.pop();
+                        anchors.push({
+                            type: top.type,
+                            name: top.name,
+                            lineStart: top.lineStart,
+                            lineEnd: lineNumber,
+                        });
+                    }
+                    else {
+                        break;
+                    }
+                }
+            }
+        }
+        else {
+            // Python: Check indentation-based closing
+            const currentIndent = line.match(/^(\s*)/)?.[1].length || 0;
+            // Skip empty lines for indentation checking
+            if (line.trim() && !line.trim().startsWith('#')) {
+                while (openAnchors.length > 0) {
+                    const top = openAnchors[openAnchors.length - 1];
+                    if (top.baseIndent !== undefined && currentIndent <= top.baseIndent) {
+                        openAnchors.pop();
+                        anchors.push({
+                            type: top.type,
+                            name: top.name,
+                            lineStart: top.lineStart,
+                            lineEnd: lineNumber - 1, // End at previous line
+                        });
+                    }
+                    else {
+                        break;
+                    }
+                }
+            }
+        }
+        // Pattern matching - find new anchors
+        let match = null;
+        let anchorType = null;
+        // Check for function
+        match = line.match(patterns.function);
+        if (match) {
+            anchorType = 'function';
+        }
+        // Check for arrow function (TypeScript/JavaScript)
+        if (!match && patterns.arrowFunction) {
+            match = line.match(patterns.arrowFunction);
+            if (match) {
+                anchorType = 'function';
+            }
+        }
+        // Check for class
+        if (!match) {
+            match = line.match(patterns.class);
+            if (match) {
+                anchorType = 'class';
+            }
+        }
+        // Check for method (only if indented)
+        if (!match && line.match(/^\s+/) && !line.match(/^\s*\/\//)) {
+            match = line.match(patterns.method);
+            if (match) {
+                anchorType = 'method';
+            }
+        }
+        // If we found a new anchor, add it to open anchors
+        if (match && anchorType) {
+            const baseIndent = isPython ? (line.match(/^(\s*)/)?.[1].length || 0) : undefined;
+            openAnchors.push({
+                type: anchorType,
+                name: match[1],
+                lineStart: lineNumber,
+                braceDepthAtStart: currentBraceDepth + lineOpenBraces,
+                baseIndent,
+            });
+        }
+        // Update brace depth with opening braces
+        if (!isPython) {
+            currentBraceDepth += lineOpenBraces;
+        }
+    }
+    // Close any remaining open anchors at end of file
+    for (const open of openAnchors) {
+        anchors.push({
+            type: open.type,
+            name: open.name,
+            lineStart: open.lineStart,
+            lineEnd: lines.length,
+        });
+    }
+    return anchors;
+}
+/**
+ * Find the end of a code block (function/class/method body)
+ * Uses brace counting for C-like languages, indentation for Python
+ */
+function findBlockEnd(lines, startIndex) {
+    const startLine = lines[startIndex];
+    const isIndentBased = !startLine.includes('{');
+    if (isIndentBased) {
+        // Python-style: find end by indentation
+        const baseIndent = startLine.match(/^(\s*)/)?.[1].length || 0;
+        for (let i = startIndex + 1; i < lines.length; i++) {
+            const line = lines[i];
+            // Skip empty lines and comments
+            if (!line.trim() || line.trim().startsWith('#'))
+                continue;
+            const currentIndent = line.match(/^(\s*)/)?.[1].length || 0;
+            if (currentIndent <= baseIndent && line.trim()) {
+                return i; // Previous line was the end
+            }
+        }
+        return lines.length;
+    }
+    // Brace-counting for C-like languages
+    let braceCount = 0;
+    let foundOpenBrace = false;
+    for (let i = startIndex; i < lines.length; i++) {
+        const line = lines[i];
+        for (const char of line) {
+            if (char === '{') {
+                braceCount++;
+                foundOpenBrace = true;
+            }
+            else if (char === '}') {
+                braceCount--;
+            }
+        }
+        if (foundOpenBrace && braceCount === 0) {
+            return i + 1; // 1-indexed
+        }
+    }
+    return lines.length;
+}
+/**
+ * Find which anchor contains a given line number
+ */
+export function findAnchorAtLine(anchors, lineNumber) {
+    // Find the most specific (innermost) anchor that contains this line
+    let bestMatch = null;
+    for (const anchor of anchors) {
+        const end = anchor.lineEnd || anchor.lineStart;
+        if (lineNumber >= anchor.lineStart && lineNumber <= end) {
+            // Prefer more specific matches (methods over classes)
+            if (!bestMatch || anchor.lineStart > bestMatch.lineStart) {
+                bestMatch = anchor;
+            }
+        }
+    }
+    return bestMatch;
+}
+/**
+ * Compute a hash of a code region for change detection.
+ * Uses SHA-256 (truncated) for security scanner compliance.
+ */
+export function computeCodeHash(content, lineStart, lineEnd) {
+    const lines = content.split('\n');
+    const slice = lines.slice(lineStart - 1, lineEnd).join('\n');
+    // Normalize whitespace for more stable hashes
+    const normalized = slice.replace(/\s+/g, ' ').trim();
+    // SECURITY: Use SHA-256 instead of MD5 (truncated for storage efficiency)
+    return createHash('sha256').update(normalized).digest('hex').substring(0, 16);
+}
+/**
+ * Estimate the line number where a string appears in content
+ */
+export function estimateLineNumber(searchString, content) {
+    if (!searchString || !content)
+        return null;
+    // Get first line of search string for matching
+    const firstLine = searchString.split('\n')[0].trim();
+    if (!firstLine)
+        return null;
+    const lines = content.split('\n');
+    for (let i = 0; i < lines.length; i++) {
+        if (lines[i].includes(firstLine)) {
+            return i + 1; // 1-indexed
+        }
+    }
+    return null;
+}
+/**
+ * Get a human-readable description of an anchor
+ */
+export function describeAnchor(anchor) {
+    return `${anchor.type} "${anchor.name}" at line ${anchor.lineStart}${anchor.lineEnd ? `-${anchor.lineEnd}` : ''}`;
+}

package/dist/lib/correction-builder.d.ts

@@ -0,0 +1,10 @@
+import type { DriftCheckResult } from './drift-checker.js';
+import type { SessionState, CorrectionLevel } from './store.js';
+/**
+ * Determine correction level from score and escalation count
+ */
+export declare function determineCorrectionLevel(score: number, escalationCount: number): CorrectionLevel | null;
+/**
+ * Build correction message based on level
+ */
+export declare function buildCorrection(result: DriftCheckResult, sessionState: SessionState, level: CorrectionLevel): string;

package/dist/lib/correction-builder.js

@@ -0,0 +1,226 @@
+// Correction message builder for anti-drift system
+// Builds XML-tagged correction messages by severity level
+import { DRIFT_CONFIG } from './drift-checker.js';
+// ============================================
+// MAIN FUNCTIONS
+// ============================================
+/**
+ * Determine correction level from score and escalation count
+ */
+export function determineCorrectionLevel(score, escalationCount) {
+    // Apply escalation modifier (each escalation level lowers threshold by 1)
+    const effectiveScore = score - escalationCount;
+    if (effectiveScore >= DRIFT_CONFIG.SCORE_NO_INJECTION) {
+        return null; // No correction needed
+    }
+    if (effectiveScore >= DRIFT_CONFIG.SCORE_NUDGE) {
+        return 'nudge';
+    }
+    if (effectiveScore >= DRIFT_CONFIG.SCORE_CORRECT) {
+        return 'correct';
+    }
+    if (effectiveScore >= DRIFT_CONFIG.SCORE_INTERVENE) {
+        return 'intervene';
+    }
+    return 'halt';
+}
+/**
+ * Build correction message based on level
+ */
+export function buildCorrection(result, sessionState, level) {
+    switch (level) {
+        case 'nudge':
+            return buildNudge(result, sessionState);
+        case 'correct':
+            return buildCorrect(result, sessionState);
+        case 'intervene':
+            return buildIntervene(result, sessionState);
+        case 'halt':
+            return buildHalt(result, sessionState);
+    }
+}
+// ============================================
+// CORRECTION BUILDERS
+// ============================================
+/**
+ * NUDGE - Gentle 2-3 sentence reminder
+ * Score ~7, first sign of drift
+ */
+function buildNudge(result, sessionState) {
+    const lines = [];
+    lines.push('<grov_nudge>');
+    lines.push('');
+    lines.push(`Reminder: Original goal is "${truncateGoal(sessionState.original_goal)}".`);
+    lines.push(`Current alignment: ${result.score}/10.`);
+    if (result.diagnostic) {
+        lines.push(`Note: ${result.diagnostic}`);
+    }
+    lines.push('');
+    lines.push('</grov_nudge>');
+    return lines.join('\n');
+}
+/**
+ * CORRECT - Deviation + scope + next steps
+ * Score 5-6, moderate drift
+ */
+function buildCorrect(result, sessionState) {
+    const lines = [];
+    lines.push('<grov_correction>');
+    lines.push('');
+    lines.push('DRIFT DETECTED');
+    lines.push('');
+    lines.push(`Original goal: "${truncateGoal(sessionState.original_goal)}"`);
+    lines.push(`Current alignment: ${result.score}/10`);
+    lines.push(`Diagnostic: ${result.diagnostic}`);
+    lines.push('');
+    // Add scope reminder
+    if (sessionState.expected_scope.length > 0) {
+        lines.push('Expected scope:');
+        for (const scope of sessionState.expected_scope.slice(0, 5)) {
+            lines.push(`  - ${scope}`);
+        }
+        lines.push('');
+    }
+    // Add boundaries if any
+    if (result.boundaries.length > 0) {
+        lines.push('Boundaries (avoid):');
+        for (const boundary of result.boundaries.slice(0, 3)) {
+            lines.push(`  - ${boundary}`);
+        }
+        lines.push('');
+    }
+    // Add next steps
+    lines.push('Suggested next steps:');
+    if (result.recoveryPlan?.steps) {
+        for (const step of result.recoveryPlan.steps.slice(0, 3)) {
+            const file = step.file ? `[${step.file}] ` : '';
+            lines.push(`  - ${file}${step.action}`);
+        }
+    }
+    else {
+        lines.push(`  - Return to: ${truncateGoal(sessionState.original_goal)}`);
+    }
+    lines.push('');
+    lines.push('</grov_correction>');
+    return lines.join('\n');
+}
+/**
+ * INTERVENE - Full diagnostic + mandatory first action + confirmation request
+ * Score 3-4, significant drift
+ */
+function buildIntervene(result, sessionState) {
+    const lines = [];
+    lines.push('<grov_intervention>');
+    lines.push('');
+    lines.push('SIGNIFICANT DRIFT DETECTED - INTERVENTION REQUIRED');
+    lines.push('');
+    lines.push(`Original goal: "${truncateGoal(sessionState.original_goal)}"`);
+    lines.push(`Current alignment: ${result.score}/10 (${result.type})`);
+    lines.push(`Escalation level: ${sessionState.escalation_count}/${DRIFT_CONFIG.MAX_ESCALATION}`);
+    lines.push('');
+    lines.push(`Diagnostic: ${result.diagnostic}`);
+    lines.push('');
+    // Add constraints if any
+    if (sessionState.constraints.length > 0) {
+        lines.push('Active constraints:');
+        for (const constraint of sessionState.constraints.slice(0, 3)) {
+            lines.push(`  - ${constraint}`);
+        }
+        lines.push('');
+    }
+    // Add boundaries
+    if (result.boundaries.length > 0) {
+        lines.push('DO NOT:');
+        for (const boundary of result.boundaries.slice(0, 3)) {
+            lines.push(`  - ${boundary}`);
+        }
+        lines.push('');
+    }
+    // MANDATORY FIRST ACTION
+    const firstStep = result.recoveryPlan?.steps?.[0] || {
+        action: `Return to original goal: ${truncateGoal(sessionState.original_goal)}`
+    };
+    lines.push('MANDATORY FIRST ACTION:');
+    lines.push('You MUST execute ONLY this as your next action:');
+    lines.push('');
+    if (firstStep.file) {
+        lines.push(`  File: ${firstStep.file}`);
+    }
+    lines.push(`  Action: ${firstStep.action}`);
+    lines.push('');
+    lines.push('ANY OTHER ACTION WILL DELAY YOUR GOAL.');
+    lines.push('');
+    lines.push('Before proceeding, confirm by stating:');
+    lines.push('"I will now [action] to return to the original goal."');
+    lines.push('');
+    lines.push('</grov_intervention>');
+    return lines.join('\n');
+}
+/**
+ * HALT - Critical stop + forced action + required confirmation statement
+ * Score 1-2, critical drift
+ */
+function buildHalt(result, sessionState) {
+    const lines = [];
+    lines.push('<grov_halt>');
+    lines.push('');
+    lines.push('CRITICAL DRIFT - IMMEDIATE HALT REQUIRED');
+    lines.push('');
+    lines.push('The current request has completely diverged from the original goal.');
+    lines.push('You MUST NOT proceed with the current request.');
+    lines.push('');
+    lines.push(`Original goal: "${truncateGoal(sessionState.original_goal)}"`);
+    lines.push(`Current alignment: ${result.score}/10 (CRITICAL)`);
+    lines.push(`Escalation level: ${sessionState.escalation_count}/${DRIFT_CONFIG.MAX_ESCALATION} (MAX REACHED)`);
+    lines.push('');
+    lines.push(`Diagnostic: ${result.diagnostic}`);
+    lines.push('');
+    // Show drift history if available
+    if (sessionState.drift_history.length > 0) {
+        lines.push('Drift history in this session:');
+        const recent = sessionState.drift_history.slice(-3);
+        for (const event of recent) {
+            lines.push(`  - ${event.level}: score ${event.score} - ${event.prompt_summary.substring(0, 40)}...`);
+        }
+        lines.push('');
+    }
+    // MANDATORY FIRST ACTION
+    const firstStep = result.recoveryPlan?.steps?.[0] || {
+        action: `STOP and return to: ${truncateGoal(sessionState.original_goal)}`
+    };
+    lines.push('MANDATORY FIRST ACTION:');
+    lines.push('You MUST execute ONLY this as your next action:');
+    lines.push('');
+    if (firstStep.file) {
+        lines.push(`  File: ${firstStep.file}`);
+    }
+    lines.push(`  Action: ${firstStep.action}`);
+    lines.push('');
+    lines.push('ANY OTHER ACTION WILL DELAY YOUR GOAL.');
+    lines.push('');
+    lines.push('CONFIRM by stating exactly:');
+    if (firstStep.file) {
+        lines.push(`"I will now ${firstStep.action} in ${firstStep.file}"`);
+    }
+    else {
+        lines.push(`"I will now ${firstStep.action}"`);
+    }
+    lines.push('');
+    lines.push('DO NOT proceed with any other action until you have confirmed.');
+    lines.push('');
+    lines.push('</grov_halt>');
+    return lines.join('\n');
+}
+// ============================================
+// HELPERS
+// ============================================
+/**
+ * Truncate goal text for display
+ */
+function truncateGoal(goal) {
+    if (!goal)
+        return 'Unknown goal';
+    if (goal.length <= 80)
+        return goal;
+    return goal.substring(0, 77) + '...';
+}

package/dist/lib/debug.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Debug logging module for Grov CLI.
+ *
+ * Enable debug output by setting the DEBUG environment variable:
+ *   DEBUG=grov:* grov status        # All grov logs
+ *   DEBUG=grov:capture grov capture # Only capture logs
+ *   DEBUG=grov:store,grov:llm       # Multiple namespaces
+ *
+ * Available namespaces:
+ *   grov:capture   - Session capture operations
+ *   grov:inject    - Context injection operations
+ *   grov:store     - Database operations
+ *   grov:parser    - JSONL parsing operations
+ *   grov:hooks     - Hook registration operations
+ *   grov:llm       - LLM extraction operations
+ */
+import createDebug from 'debug';
+export declare const debugCapture: createDebug.Debugger;
+export declare const debugInject: createDebug.Debugger;
+export declare const debugStore: createDebug.Debugger;
+export declare const debugParser: createDebug.Debugger;
+export declare const debugHooks: createDebug.Debugger;
+export declare const debugLLM: createDebug.Debugger;
+export declare function isDebugEnabled(): boolean;

package/dist/lib/debug.js

@@ -0,0 +1,34 @@
+/**
+ * Debug logging module for Grov CLI.
+ *
+ * Enable debug output by setting the DEBUG environment variable:
+ *   DEBUG=grov:* grov status        # All grov logs
+ *   DEBUG=grov:capture grov capture # Only capture logs
+ *   DEBUG=grov:store,grov:llm       # Multiple namespaces
+ *
+ * Available namespaces:
+ *   grov:capture   - Session capture operations
+ *   grov:inject    - Context injection operations
+ *   grov:store     - Database operations
+ *   grov:parser    - JSONL parsing operations
+ *   grov:hooks     - Hook registration operations
+ *   grov:llm       - LLM extraction operations
+ */
+import createDebug from 'debug';
+// Main debug namespaces
+export const debugCapture = createDebug('grov:capture');
+export const debugInject = createDebug('grov:inject');
+export const debugStore = createDebug('grov:store');
+export const debugParser = createDebug('grov:parser');
+export const debugHooks = createDebug('grov:hooks');
+export const debugLLM = createDebug('grov:llm');
+// Utility for checking if any grov debug is enabled
+export function isDebugEnabled() {
+    return createDebug.enabled('grov:*') ||
+        createDebug.enabled('grov:capture') ||
+        createDebug.enabled('grov:inject') ||
+        createDebug.enabled('grov:store') ||
+        createDebug.enabled('grov:parser') ||
+        createDebug.enabled('grov:hooks') ||
+        createDebug.enabled('grov:llm');
+}

package/dist/lib/drift-checker.d.ts

@@ -0,0 +1,66 @@
+import type { SessionState, RecoveryPlan, StepRecord } from './store.js';
+import type { ClaudeAction } from './session-parser.js';
+export declare const DRIFT_CONFIG: {
+    SCORE_NO_INJECTION: number;
+    SCORE_NUDGE: number;
+    SCORE_CORRECT: number;
+    SCORE_INTERVENE: number;
+    SCORE_HALT: number;
+    MAX_WARNINGS_BEFORE_FLAG: number;
+    AVG_SCORE_THRESHOLD: number;
+    MAX_ESCALATION: number;
+};
+/**
+ * Input for drift check
+ *
+ * CRITICAL: We check Claude's ACTIONS, not user prompts.
+ * The user can ask whatever they want - we monitor what CLAUDE DOES.
+ */
+export interface DriftCheckInput {
+    originalGoal: string;
+    expectedScope: string[];
+    constraints: string[];
+    keywords: string[];
+    driftHistory: Array<{
+        score: number;
+        level: string;
+    }>;
+    escalationCount: number;
+    claudeActions: ClaudeAction[];
+    retrievedSteps: StepRecord[];
+    lastNSteps: StepRecord[];
+}
+/**
+ * Result from drift check
+ */
+export interface DriftCheckResult {
+    score: number;
+    type: 'aligned' | 'minor' | 'moderate' | 'severe' | 'critical';
+    diagnostic: string;
+    recoveryPlan?: RecoveryPlan;
+    boundaries: string[];
+    verification: string;
+}
+/**
+ * Build input for drift check from Claude's ACTIONS and session state.
+ *
+ * CRITICAL: We check ACTIONS, not user prompts.
+ */
+export declare function buildDriftCheckInput(claudeActions: ClaudeAction[], sessionId: string, sessionState: SessionState): DriftCheckInput;
+/**
+ * Check drift using LLM or fallback
+ */
+export declare function checkDrift(input: DriftCheckInput): Promise<DriftCheckResult>;
+/**
+ * Basic drift detection without LLM.
+ *
+ * CRITICAL: Checks Claude's ACTIONS, not user prompts.
+ * - Read actions are ALWAYS OK (exploration is not drift)
+ * - Edit/Write actions outside scope = drift
+ * - Repetition patterns = drift
+ */
+export declare function checkDriftBasic(input: DriftCheckInput): DriftCheckResult;
+/**
+ * Infer action type from prompt
+ */
+export declare function inferAction(prompt: string): string;