anvil-dev-framework 0.1.7 → 0.1.9

package/global/tools/anvil-memory/src/__tests__/ccs/test-utils.ts

@@ -0,0 +1,340 @@
+/**
+ * CCS Test Utilities
+ *
+ * Shared helpers for Context Checkpoint System (CCS) end-to-end testing.
+ * Provides utilities for Ralph state management, hook execution, and fixtures.
+ */
+
+import { mkdirSync, rmSync, writeFileSync, existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+import { tmpdir } from 'os';
+
+/**
+ * Project root directory (anvil-dev-framework)
+ */
+export const PROJECT_ROOT = join(__dirname, '../../../../../..');
+
+/**
+ * Path to the global hooks directory
+ */
+export const HOOKS_DIR = join(PROJECT_ROOT, 'global/hooks');
+
+/**
+ * Path to the global lib directory
+ */
+export const LIB_DIR = join(PROJECT_ROOT, 'global/lib');
+
+/**
+ * CCS threshold constants matching ralph_context_monitor.py
+ */
+export const CCS_THRESHOLDS = {
+  L1: 70,
+  L2: 85,
+  L3: 95,
+} as const;
+
+/**
+ * Result from running a hook subprocess
+ */
+export interface HookResult {
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+}
+
+/**
+ * Context history entry structure
+ */
+export interface ContextHistoryEntry {
+  iteration: number;
+  peak_percent: number;
+  checkpoint: boolean;
+  level?: string;
+  timestamp?: string;
+}
+
+/**
+ * Context checkpoint structure
+ */
+export interface ContextCheckpoint {
+  active: boolean;
+  level: string;
+  percent_at_checkpoint: number;
+  timestamp: string;
+  handoff_file?: string;
+}
+
+/**
+ * Ralph state file structure
+ */
+export interface RalphState {
+  mode: 'ralph' | 'manual';
+  session_id: string;
+  iteration: number;
+  started_at: string;
+  status: 'running' | 'checkpointed' | 'completed' | 'failed';
+  task_list?: string[];
+  completed_tasks?: string[];
+  checkpoint_active?: boolean;
+  context_history?: ContextHistoryEntry[];
+  context_checkpoint?: ContextCheckpoint;
+  handoff_file?: string;
+  linear_issue?: string;
+  // Circuit breaker fields (used by ralph_stop.sh)
+  no_change_count?: number;
+  last_diff_hash?: string;
+}
+
+/**
+ * Context window data structure from Claude Code
+ */
+export interface ContextWindowData {
+  context_window: {
+    current_usage: {
+      input_tokens: number;
+      output_tokens: number;
+      cache_read_input_tokens: number;
+      cache_creation_input_tokens: number;
+    };
+    context_window_size: number;
+  };
+}
+
+/**
+ * Creates a temporary test directory for CCS tests.
+ * Returns path and cleanup function.
+ */
+export function createTestDir(prefix = 'ccs-test'): {
+  path: string;
+  cleanup: () => void;
+} {
+  const path = join(tmpdir(), `${prefix}-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+  mkdirSync(path, { recursive: true });
+
+  return {
+    path,
+    cleanup: () => {
+      try {
+        rmSync(path, { recursive: true, force: true });
+      } catch {
+        // Ignore cleanup errors
+      }
+    },
+  };
+}
+
+/**
+ * Creates a Ralph state file in the specified directory
+ */
+export function createRalphStateFile(dir: string, state: Partial<RalphState>): string {
+  const stateDir = join(dir, '.claude');
+  mkdirSync(stateDir, { recursive: true });
+
+  const statePath = join(stateDir, 'ralph-state.json');
+  const fullState: RalphState = {
+    mode: 'ralph',
+    session_id: `test-${Date.now()}`,
+    iteration: 1,
+    started_at: new Date().toISOString(),
+    status: 'running',
+    ...state,
+  };
+
+  writeFileSync(statePath, JSON.stringify(fullState, null, 2));
+  return statePath;
+}
+
+/**
+ * Reads a Ralph state file from the specified directory
+ */
+export function readRalphStateFile(dir: string): RalphState | null {
+  const statePath = join(dir, '.claude', 'ralph-state.json');
+  if (!existsSync(statePath)) {
+    return null;
+  }
+  try {
+    return JSON.parse(readFileSync(statePath, 'utf-8'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Creates context window data at a specific percentage
+ */
+export function createContextData(percent: number, windowSize = 200000): ContextWindowData {
+  // Calculate tokens to achieve target percentage
+  // percent = (input_tokens + cache_creation_input_tokens) / context_window_size * 100
+  const targetTokens = Math.floor((percent / 100) * windowSize);
+
+  return {
+    context_window: {
+      current_usage: {
+        input_tokens: targetTokens,
+        output_tokens: 0,
+        cache_read_input_tokens: 0,
+        cache_creation_input_tokens: 0,
+      },
+      context_window_size: windowSize,
+    },
+  };
+}
+
+/**
+ * Runs a Python hook as a subprocess with stdin input
+ */
+export async function runPythonHook(
+  hookPath: string,
+  input: ContextWindowData | Record<string, unknown>,
+  options?: {
+    cwd?: string;
+    env?: Record<string, string>;
+  }
+): Promise<HookResult> {
+  const inputJson = JSON.stringify(input);
+  const env = { ...process.env, ...options?.env };
+
+  const proc = Bun.spawn(['python3', hookPath], {
+    stdin: new Blob([inputJson]),
+    stdout: 'pipe',
+    stderr: 'pipe',
+    cwd: options?.cwd ?? PROJECT_ROOT,
+    env,
+  });
+
+  const stdout = await new Response(proc.stdout).text();
+  const stderr = await new Response(proc.stderr).text();
+  await proc.exited;
+
+  // Use 128 for signal termination (Unix convention), -1 for unknown failures
+  const exitCode = proc.exitCode ?? (proc.signalCode ? 128 : -1);
+  return {
+    stdout: stdout.trim(),
+    stderr: stderr.trim(),
+    exitCode,
+  };
+}
+
+/**
+ * Runs a Bash hook as a subprocess
+ */
+export async function runBashHook(
+  hookPath: string,
+  options?: {
+    cwd?: string;
+    env?: Record<string, string>;
+    stdin?: string;
+  }
+): Promise<HookResult> {
+  const env = { ...process.env, ...options?.env };
+
+  const proc = Bun.spawn(['bash', hookPath], {
+    stdin: options?.stdin ? new Blob([options.stdin]) : undefined,
+    stdout: 'pipe',
+    stderr: 'pipe',
+    cwd: options?.cwd ?? PROJECT_ROOT,
+    env,
+  });
+
+  const stdout = await new Response(proc.stdout).text();
+  const stderr = await new Response(proc.stderr).text();
+  await proc.exited;
+
+  // Use 128 for signal termination (Unix convention), -1 for unknown failures
+  const exitCode = proc.exitCode ?? (proc.signalCode ? 128 : -1);
+  return {
+    stdout: stdout.trim(),
+    stderr: stderr.trim(),
+    exitCode,
+  };
+}
+
+/**
+ * Parses CCS output signals from hook stdout
+ *
+ * Signals have format: CCS_<TYPE>|<LEVEL>|<PERCENT>|<MESSAGE>
+ */
+export function parseCCSSignal(stdout: string): {
+  type: 'WARNING' | 'CHECKPOINT_TRIGGERED' | 'EMERGENCY_STOP' | null;
+  level: string;
+  percent: number;
+  message: string;
+} | null {
+  const signalPatterns = [
+    /CCS_WARNING\|(\w+)\|(\d+)\|(.+)/,
+    /CCS_CHECKPOINT_TRIGGERED\|(\w+)\|(\d+)\|(.+)/,
+    /CCS_EMERGENCY_STOP\|(\w+)\|(\d+)\|(.+)/,
+  ];
+
+  for (const line of stdout.split('\n')) {
+    for (const pattern of signalPatterns) {
+      const match = line.match(pattern);
+      if (match) {
+        const type = line.startsWith('CCS_WARNING')
+          ? 'WARNING'
+          : line.startsWith('CCS_CHECKPOINT')
+          ? 'CHECKPOINT_TRIGGERED'
+          : 'EMERGENCY_STOP';
+        return {
+          type,
+          level: match[1]!,
+          percent: parseInt(match[2]!, 10),
+          message: match[3]!,
+        };
+      }
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Checks if jq is available on the system (needed for some bash hooks)
+ */
+export async function isJqAvailable(): Promise<boolean> {
+  try {
+    const proc = Bun.spawn(['which', 'jq'], {
+      stdout: 'pipe',
+      stderr: 'pipe',
+    });
+    await proc.exited;
+    return proc.exitCode === 0;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Creates a sample handoff document for testing
+ */
+export function createHandoffFile(dir: string, content?: string): string {
+  const handoffDir = join(dir, '.claude', 'handoffs');
+  mkdirSync(handoffDir, { recursive: true });
+
+  const timestamp = new Date().toISOString().slice(0, 16).replace('T', '-').replace(':', '');
+  const handoffPath = join(handoffDir, `${timestamp}.md`);
+
+  const defaultContent = `# Session Handoff
+
+## Context at Checkpoint
+- Context: 87%
+- Iteration: 3
+
+## Current Task
+Working on feature implementation
+
+## Completed Items
+- Item 1
+- Item 2
+
+## Remaining Items
+- Item 3
+- Item 4
+
+## Next Steps
+Continue with Item 3
+`;
+
+  writeFileSync(handoffPath, content ?? defaultContent);
+  return handoffPath;
+}

package/global/tools/anvil-memory/src/__tests__/commands.test.ts

@@ -16,6 +16,7 @@ import { handleSearch, parseSearchArgs } from '../commands/search';
 import { handleGet, parseGetArgs } from '../commands/get';
 import { handleCheckpoint, parseCheckpointArgs } from '../commands/checkpoint';
 import { handleRalphIteration, parseRalphIterationArgs } from '../commands/ralph-iteration';
+import { handleContext, parseContextArgs } from '../commands/context';
 import { AnvilMemoryDb } from '../db';
 import type { Observation, Session, Checkpoint, RalphIteration } from '../types';
 
@@ -57,6 +58,14 @@ interface RalphIterationResultData {
   observation?: Observation;
 }
 
+interface ContextResultData {
+  count: number;
+  format: string;
+  estimatedTokens?: number;
+  observations?: Observation[];
+  content?: string;
+}
+
 // Test database path
 const TEST_DB_DIR = join(tmpdir(), 'anvil-memory-cmd-tests');
 const getTestDbPath = () => join(TEST_DB_DIR, `cmd-test-${Date.now()}-${Math.random().toString(36).slice(2)}.db`);
@@ -866,6 +875,208 @@ describe('ralph-iteration command', () => {
   });
 });
 
+describe('context command', () => {
+  let testDbPath: string;
+
+  beforeAll(async () => {
+    if (!existsSync(TEST_DB_DIR)) {
+      mkdirSync(TEST_DB_DIR, { recursive: true });
+    }
+    testDbPath = getTestDbPath();
+    await handleInit(['--path', testDbPath]);
+
+    // Add test observations
+    await handleObserve([
+      '--type', 'discovery',
+      '--title', 'SQLite FTS5 implementation',
+      '--content', 'Full-text search with Porter stemmer',
+      '--project', 'anvil-memory',
+      '--path', testDbPath,
+    ]);
+
+    await handleObserve([
+      '--type', 'bugfix',
+      '--title', 'Fixed database connection leak',
+      '--content', 'Resolved connection leak issue in production',
+      '--project', 'anvil-memory',
+      '--path', testDbPath,
+    ]);
+
+    await handleObserve([
+      '--type', 'feature',
+      '--title', 'Authentication system',
+      '--content', 'JWT-based auth implementation for API',
+      '--project', 'other-project',
+      '--path', testDbPath,
+    ]);
+
+    await handleObserve([
+      '--type', 'decision',
+      '--title', 'Chose SQLite over PostgreSQL',
+      '--content', 'Selected SQLite for simplicity and portability',
+      '--project', 'anvil-memory',
+      '--path', testDbPath,
+    ]);
+  });
+
+  afterAll(() => {
+    cleanupDb(testDbPath);
+  });
+
+  test('parseContextArgs parses --limit option', () => {
+    const opts = parseContextArgs(['--limit', '10']);
+    expect(opts.limit).toBe(10);
+  });
+
+  test('parseContextArgs parses --format option', () => {
+    const opts = parseContextArgs(['--format', 'markdown']);
+    expect(opts.format).toBe('markdown');
+  });
+
+  test('parseContextArgs parses --format json', () => {
+    const opts = parseContextArgs(['--format', 'json']);
+    expect(opts.format).toBe('json');
+  });
+
+  test('parseContextArgs parses --max-tokens option', () => {
+    const opts = parseContextArgs(['--max-tokens', '2000']);
+    expect(opts.maxTokens).toBe(2000);
+  });
+
+  test('parseContextArgs parses --project option', () => {
+    const opts = parseContextArgs(['--project', 'test-project']);
+    expect(opts.project).toBe('test-project');
+  });
+
+  test('parseContextArgs parses --types option', () => {
+    const opts = parseContextArgs(['--types', 'bugfix,feature,discovery']);
+    expect(opts.types).toEqual(['bugfix', 'feature', 'discovery']);
+  });
+
+  test('parseContextArgs parses --include-sessions option', () => {
+    const opts = parseContextArgs(['--include-sessions']);
+    expect(opts.includeSessions).toBe(true);
+  });
+
+  test('parseContextArgs defaults to inject format', () => {
+    const opts = parseContextArgs([]);
+    expect(opts.format).toBe('inject');
+  });
+
+  test('parseContextArgs defaults to limit 20', () => {
+    const opts = parseContextArgs([]);
+    expect(opts.limit).toBe(20);
+  });
+
+  test('handleContext returns observations in inject format by default', async () => {
+    const result = await handleContext(['--path', testDbPath]);
+
+    expect(result.success).toBe(true);
+    expect(result.message).toContain('Recent Context from Anvil Memory');
+    expect(result.message).toContain('Index');
+    expect(result.message).toContain('Legend');
+  });
+
+  test('handleContext inject format includes observation IDs', async () => {
+    const result = await handleContext(['--path', testDbPath]);
+
+    expect(result.success).toBe(true);
+    expect(result.message).toMatch(/#\d+/); // Should have IDs like #1, #2, etc.
+  });
+
+  test('handleContext inject format includes type emojis', async () => {
+    const result = await handleContext(['--path', testDbPath]);
+
+    expect(result.success).toBe(true);
+    // Should include at least one emoji from our test data
+    expect(result.message).toMatch(/🔴|🟣|🔵|⚖️/);
+  });
+
+  test('handleContext returns JSON format', async () => {
+    const result = await handleContext(['--format', 'json', '--path', testDbPath]);
+    const data = result.data as ContextResultData;
+
+    expect(result.success).toBe(true);
+    expect(data?.count).toBeGreaterThan(0);
+    expect(data?.format).toBe('json');
+    expect(data?.observations).toBeDefined();
+    expect(Array.isArray(data?.observations)).toBe(true);
+  });
+
+  test('handleContext returns markdown format', async () => {
+    const result = await handleContext(['--format', 'markdown', '--path', testDbPath]);
+
+    expect(result.success).toBe(true);
+    expect(result.message).toContain('# Session Context');
+    expect(result.message).toContain('Generated:');
+  });
+
+  test('handleContext respects --limit option', async () => {
+    const result = await handleContext(['--format', 'json', '--limit', '2', '--path', testDbPath]);
+    const data = result.data as ContextResultData;
+
+    expect(result.success).toBe(true);
+    expect(data?.observations?.length).toBeLessThanOrEqual(2);
+  });
+
+  test('handleContext filters by --project', async () => {
+    const result = await handleContext(['--format', 'json', '--project', 'anvil-memory', '--path', testDbPath]);
+    const data = result.data as ContextResultData;
+
+    expect(result.success).toBe(true);
+    expect(data?.count).toBeGreaterThan(0);
+    expect(data?.observations?.every((o) => o.project === 'anvil-memory')).toBe(true);
+  });
+
+  test('handleContext filters by --types', async () => {
+    const result = await handleContext(['--format', 'json', '--types', 'bugfix', '--path', testDbPath]);
+    const data = result.data as ContextResultData;
+
+    expect(result.success).toBe(true);
+    if (data?.count > 0) {
+      expect(data?.observations?.every((o) => o.type === 'bugfix')).toBe(true);
+    }
+  });
+
+  test('handleContext handles empty results', async () => {
+    const result = await handleContext(['--format', 'json', '--types', 'handoff', '--path', testDbPath]);
+    const data = result.data as ContextResultData;
+
+    expect(result.success).toBe(true);
+    expect(data?.count).toBe(0);
+  });
+
+  test('handleContext includes token estimate in inject format', async () => {
+    const result = await handleContext(['--path', testDbPath]);
+
+    expect(result.success).toBe(true);
+    expect(result.message).toMatch(/\d+ observations loaded/);
+    expect(result.message).toMatch(/estimated \d+ tokens/);
+  });
+
+  test('handleContext truncates with --max-tokens', async () => {
+    // Get full output first
+    const fullResult = await handleContext(['--format', 'markdown', '--path', testDbPath]);
+    const fullLength = (fullResult.message || '').length;
+
+    // Get truncated output with very small token limit
+    const truncatedResult = await handleContext(['--format', 'markdown', '--max-tokens', '50', '--path', testDbPath]);
+    const truncatedLength = (truncatedResult.message || '').length;
+
+    expect(truncatedResult.success).toBe(true);
+    // Truncated should be smaller than full (50 tokens ≈ 200 chars)
+    expect(truncatedLength).toBeLessThan(fullLength);
+    expect(truncatedResult.message).toContain('Truncated');
+  });
+
+  test('handleContext fails when database does not exist', async () => {
+    const result = await handleContext(['--path', '/tmp/nonexistent-db-12345.db']);
+
+    expect(result.success).toBe(false);
+    expect(result.error).toContain('Database not found');
+  });
+});
+
 describe('Command error handling', () => {
   test('observe fails when database does not exist', async () => {
     const result = await handleObserve([
@@ -891,4 +1102,11 @@ describe('Command error handling', () => {
     expect(result.success).toBe(false);
     expect(result.error).toContain('Database not found');
   });
+
+  test('context fails when database does not exist', async () => {
+    const result = await handleContext(['--path', '/tmp/nonexistent-db-12345.db']);
+
+    expect(result.success).toBe(false);
+    expect(result.error).toContain('Database not found');
+  });
 });