anvil-dev-framework 0.1.6

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

@@ -0,0 +1,440 @@
+/**
+ * Ralph Stop Hook Tests
+ *
+ * Tests for ralph_stop.sh checkpoint handling and loop control.
+ * Verifies iteration logic, completion detection, circuit breakers,
+ * and CCS checkpoint integration.
+ */
+
+import { describe, test, expect, beforeEach, afterEach, beforeAll } from 'bun:test';
+import { existsSync } from 'fs';
+import {
+  TestStateManager,
+  runRalphStop,
+  isJqAvailable,
+} from './test-utils';
+import {
+  createMinimalRalphState,
+  createFullRalphState,
+  createCheckpointedState,
+  createLinearIntegratedState,
+  TRANSCRIPT_COMPLETE,
+  TRANSCRIPT_FATAL,
+  TRANSCRIPT_STUCK,
+} from './fixtures';
+
+describe('Ralph Stop Hook', () => {
+  let stateManager: TestStateManager;
+  let jqAvailable: boolean;
+
+  beforeAll(async () => {
+    jqAvailable = await isJqAvailable();
+  });
+
+  beforeEach(() => {
+    stateManager = new TestStateManager('ralph-stop');
+    stateManager.init();
+  });
+
+  afterEach(() => {
+    stateManager.cleanup();
+  });
+
+  describe('Non-Ralph Mode', () => {
+    test('exits silently without state file', async () => {
+      if (!jqAvailable) {
+        console.log('Skipping: jq not available');
+        return;
+      }
+
+      // Don't create any state file
+      const result = await runRalphStop(stateManager);
+
+      expect(result.exitCode).toBe(0);
+    });
+
+    test('does not create state file if not in Ralph mode', async () => {
+      if (!jqAvailable) {
+        console.log('Skipping: jq not available');
+        return;
+      }
+
+      await runRalphStop(stateManager);
+
+      expect(stateManager.stateExists()).toBe(false);
+    });
+  });
+
+  describe('Iteration Tracking', () => {
+    test('increments iteration counter', async () => {
+      if (!jqAvailable) {
+        console.log('Skipping: jq not available');
+        return;
+      }
+
+      stateManager.writeState(createMinimalRalphState({ iteration: 5 }));
+
+      await runRalphStop(stateManager);
+
+      const state = stateManager.readState();
+      expect(state.iteration).toBe(6);
+    });
+
+    test('initializes state if missing fields', async () => {
+      if (!jqAvailable) {
+        console.log('Skipping: jq not available');
+        return;
+      }
+
+      // Write minimal state
+      stateManager.writeState({});
+
+      await runRalphStop(stateManager);
+
+      const state = stateManager.readState();
+      expect(state.iteration).toBeDefined();
+    });
+  });
+
+  describe('Max Iterations Safety', () => {
+    test('exits with code 0 at max iterations', async () => {
+      if (!jqAvailable) {
+        console.log('Skipping: jq not available');
+        return;
+      }
+
+      stateManager.writeState(createMinimalRalphState({ iteration: 49 }));
+
+      const result = await runRalphStop(stateManager, { maxIterations: 50 });
+
+      expect(result.exitCode).toBe(0);
+      expect(result.stderr).toContain('Maximum iterations');
+    });
+
+    test('cleans up state at max iterations', async () => {
+      if (!jqAvailable) {
+        console.log('Skipping: jq not available');
+        return;
+      }
+
+      stateManager.writeState(createMinimalRalphState({ iteration: 49 }));
+
+      await runRalphStop(stateManager, { maxIterations: 50 });
+
+      // State file should be cleaned up
+      expect(stateManager.stateExists()).toBe(false);
+    });
+
+    test('continues loop before max iterations', async () => {
+      if (!jqAvailable) {
+        console.log('Skipping: jq not available');
+        return;
+      }
+
+      stateManager.writeState(createMinimalRalphState({ iteration: 10 }));
+
+      const result = await runRalphStop(stateManager, { maxIterations: 50 });
+
+      expect(result.exitCode).toBe(1); // Block exit
+      expect(result.stderr).toContain('restarting');
+    });
+
+    test('respects custom max iterations', async () => {
+      if (!jqAvailable) {
+        console.log('Skipping: jq not available');
+        return;
+      }
+
+      stateManager.writeState(createMinimalRalphState({ iteration: 9 }));
+
+      const result = await runRalphStop(stateManager, { maxIterations: 10 });
+
+      expect(result.exitCode).toBe(0);
+    });
+  });
+
+  describe('Completion Promise Detection', () => {
+    test('exits with code 0 on completion promise', async () => {
+      if (!jqAvailable) {
+        console.log('Skipping: jq not available');
+        return;
+      }
+
+      stateManager.writeState(createMinimalRalphState({ iteration: 5 }));
+
+      const result = await runRalphStop(stateManager, {
+        transcript: TRANSCRIPT_COMPLETE,
+      });
+
+      expect(result.exitCode).toBe(0);
+      expect(result.stderr).toContain('complete');
+    });
+
+    test('cleans up state on completion', async () => {
+      if (!jqAvailable) {
+        console.log('Skipping: jq not available');
+        return;
+      }
+
+      stateManager.writeState(createMinimalRalphState({ iteration: 5 }));
+
+      await runRalphStop(stateManager, {
+        transcript: TRANSCRIPT_COMPLETE,
+      });
+
+      expect(stateManager.stateExists()).toBe(false);
+    });
+  });
+
+  describe('Fatal Error Detection', () => {
+    test('exits with code 0 on fatal error', async () => {
+      if (!jqAvailable) {
+        console.log('Skipping: jq not available');
+        return;
+      }
+
+      stateManager.writeState(createMinimalRalphState({ iteration: 5 }));
+
+      const result = await runRalphStop(stateManager, {
+        transcript: TRANSCRIPT_FATAL,
+      });
+
+      expect(result.exitCode).toBe(0);
+      expect(result.stderr).toContain('error');
+    });
+
+    test('cleans up state on fatal error', async () => {
+      if (!jqAvailable) {
+        console.log('Skipping: jq not available');
+        return;
+      }
+
+      stateManager.writeState(createMinimalRalphState({ iteration: 5 }));
+
+      await runRalphStop(stateManager, {
+        transcript: TRANSCRIPT_FATAL,
+      });
+
+      expect(stateManager.stateExists()).toBe(false);
+    });
+  });
+
+  describe('Stuck Signal Detection', () => {
+    test('logs warning on stuck signals', async () => {
+      if (!jqAvailable) {
+        console.log('Skipping: jq not available');
+        return;
+      }
+
+      stateManager.writeState(createMinimalRalphState({ iteration: 5 }));
+
+      const result = await runRalphStop(stateManager, {
+        transcript: TRANSCRIPT_STUCK,
+      });
+
+      // Should warn but not exit
+      expect(result.stderr).toContain('Stuck');
+      expect(result.exitCode).toBe(1); // Still continues
+    });
+  });
+
+  describe('CCS Checkpoint Integration', () => {
+    test('restarts with exit code 1 on active checkpoint', async () => {
+      if (!jqAvailable) {
+        console.log('Skipping: jq not available');
+        return;
+      }
+
+      stateManager.writeState(createCheckpointedState('L2', 87));
+
+      const result = await runRalphStop(stateManager);
+
+      expect(result.exitCode).toBe(1); // Restart loop
+      expect(result.stderr).toContain('checkpoint');
+    });
+
+    test('detects active checkpoint in state', async () => {
+      if (!jqAvailable) {
+        console.log('Skipping: jq not available');
+        return;
+      }
+
+      stateManager.writeState(createCheckpointedState('L2', 87));
+
+      const result = await runRalphStop(stateManager);
+
+      // The checkpoint is detected (log message confirms this)
+      expect(result.stderr).toContain('CCS checkpoint detected');
+    });
+
+    test('attempts PROMPT.md generation for checkpoint resume', async () => {
+      if (!jqAvailable) {
+        console.log('Skipping: jq not available');
+        return;
+      }
+
+      stateManager.writeState(createCheckpointedState('L2', 87, {
+        task_name: 'Test Task',
+        todo_items: ['Item 1', 'Item 2'],
+      }));
+
+      const result = await runRalphStop(stateManager);
+
+      // Hook attempts to handle checkpoint (success depends on Python generator path)
+      expect(result.stderr).toContain('checkpoint');
+      // Note: PROMPT.md generation may fail in test env due to relative path resolution
+    });
+
+    test('handles L3 checkpoint same as L2', async () => {
+      if (!jqAvailable) {
+        console.log('Skipping: jq not available');
+        return;
+      }
+
+      stateManager.writeState(createCheckpointedState('L3', 96));
+
+      const result = await runRalphStop(stateManager);
+
+      expect(result.exitCode).toBe(1);
+      expect(result.stderr).toContain('checkpoint');
+    });
+  });
+
+  describe('Circuit Breaker', () => {
+    // Note: Circuit breaker tests are limited in isolated test env because
+    // they rely on actual git diff hashes. These tests verify the logic
+    // runs without crashing; full circuit breaker testing requires a git repo.
+
+    test('does not crash when checking git diff in non-repo', async () => {
+      if (!jqAvailable) {
+        console.log('Skipping: jq not available');
+        return;
+      }
+
+      stateManager.writeState(createMinimalRalphState({
+        iteration: 10,
+        no_change_count: 2,
+        last_diff_hash: 'abc123',
+      }));
+
+      const result = await runRalphStop(stateManager);
+
+      // Should complete without crashing
+      expect(typeof result.exitCode).toBe('number');
+    });
+
+    test('continues iteration when git is unavailable', async () => {
+      if (!jqAvailable) {
+        console.log('Skipping: jq not available');
+        return;
+      }
+
+      stateManager.writeState(createMinimalRalphState({
+        iteration: 5,
+        no_change_count: 0,
+      }));
+
+      const result = await runRalphStop(stateManager);
+
+      // Should continue (exit code 1) since no completion/max iter/fatal
+      expect(result.exitCode).toBe(1);
+    });
+  });
+
+  describe('Linear Integration', () => {
+    test('handles state with Linear integration enabled', async () => {
+      if (!jqAvailable) {
+        console.log('Skipping: jq not available');
+        return;
+      }
+
+      stateManager.writeState(createLinearIntegratedState());
+
+      const result = await runRalphStop(stateManager);
+
+      expect(result.exitCode).toBe(1); // Normal restart
+    });
+
+    test('does not crash with missing Linear fields', async () => {
+      if (!jqAvailable) {
+        console.log('Skipping: jq not available');
+        return;
+      }
+
+      stateManager.writeState(createMinimalRalphState({
+        linear_integration: { enabled: true },
+      }));
+
+      const result = await runRalphStop(stateManager);
+
+      expect(result.exitCode).toBe(1); // Should still work
+    });
+  });
+
+  describe('Error Handling', () => {
+    test('handles corrupted state file gracefully', async () => {
+      if (!jqAvailable) {
+        console.log('Skipping: jq not available');
+        return;
+      }
+
+      // Write invalid JSON
+      stateManager.writeFile('.claude/ralph-state.json', 'not valid json');
+
+      // Should not crash, but may have unexpected behavior
+      // The important thing is it doesn't hang
+      const result = await runRalphStop(stateManager);
+      expect(typeof result.exitCode).toBe('number');
+    });
+  });
+
+  describe('Logging', () => {
+    test('creates log entries when logging enabled', async () => {
+      if (!jqAvailable) {
+        console.log('Skipping: jq not available');
+        return;
+      }
+
+      stateManager.writeState(createMinimalRalphState({ iteration: 5 }));
+
+      await runRalphStop(stateManager, { enableLogging: true });
+
+      // Check if log file was created
+      expect(stateManager.fileExists('.claude/logs/ralph.log')).toBe(true);
+    });
+
+    test('does not create logs when logging disabled', async () => {
+      if (!jqAvailable) {
+        console.log('Skipping: jq not available');
+        return;
+      }
+
+      stateManager.writeState(createMinimalRalphState({ iteration: 5 }));
+
+      await runRalphStop(stateManager, { enableLogging: false });
+
+      expect(stateManager.fileExists('.claude/logs/ralph.log')).toBe(false);
+    });
+  });
+});
+
+describe('Ralph Stop Hook - jq Dependency', () => {
+  let stateManager: TestStateManager;
+
+  beforeEach(() => {
+    stateManager = new TestStateManager('ralph-stop-jq');
+    stateManager.init();
+  });
+
+  afterEach(() => {
+    stateManager.cleanup();
+  });
+
+  test('hook script exists', async () => {
+    const hookPath = '/Users/alexandercahiz/Projects/anvil-dev-framework/global/hooks/ralph_stop.sh';
+    expect(existsSync(hookPath)).toBe(true);
+  });
+
+  // Note: Testing missing jq is tricky because we can't easily uninstall it
+  // The hook handles this case by printing an error and exiting 0
+});

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

@@ -0,0 +1,252 @@
+/**
+ * CCS Test Utilities
+ *
+ * Shared helpers for Context Checkpoint System (CCS) end-to-end testing.
+ * Provides subprocess execution for Python and Bash hooks, state file
+ * management, and context simulation.
+ */
+
+import { mkdirSync, rmSync, writeFileSync, readFileSync, existsSync } from 'fs';
+import { join } from 'path';
+import { tmpdir } from 'os';
+
+// Project paths
+export const PROJECT_ROOT = join(__dirname, '../../../../../..');
+export const HOOKS_DIR = join(PROJECT_ROOT, 'global/hooks');
+export const LIB_DIR = join(PROJECT_ROOT, 'global/lib');
+
+/**
+ * Result from running a hook subprocess
+ */
+export interface HookResult {
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+}
+
+/**
+ * Test directory manager for isolated state files
+ */
+export class TestStateManager {
+  readonly baseDir: string;
+  readonly stateFile: string;
+  readonly claudeDir: string;
+
+  constructor(prefix = 'ccs-test') {
+    this.baseDir = join(tmpdir(), `${prefix}-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+    this.claudeDir = join(this.baseDir, '.claude');
+    this.stateFile = join(this.claudeDir, 'ralph-state.json');
+  }
+
+  /**
+   * Initialize the test directory structure
+   */
+  init(): void {
+    mkdirSync(this.claudeDir, { recursive: true });
+    mkdirSync(join(this.claudeDir, 'handoffs'), { recursive: true });
+    mkdirSync(join(this.claudeDir, 'logs'), { recursive: true });
+  }
+
+  /**
+   * Write a Ralph state file
+   */
+  writeState(state: object): void {
+    writeFileSync(this.stateFile, JSON.stringify(state, null, 2));
+  }
+
+  /**
+   * Read the current Ralph state file
+   */
+  readState(): Record<string, unknown> {
+    if (!existsSync(this.stateFile)) {
+      return {};
+    }
+    return JSON.parse(readFileSync(this.stateFile, 'utf-8'));
+  }
+
+  /**
+   * Check if state file exists
+   */
+  stateExists(): boolean {
+    return existsSync(this.stateFile);
+  }
+
+  /**
+   * Clean up all test files
+   */
+  cleanup(): void {
+    try {
+      rmSync(this.baseDir, { recursive: true, force: true });
+    } catch {
+      // Ignore cleanup errors
+    }
+  }
+
+  /**
+   * Write a file relative to the test base directory
+   */
+  writeFile(relativePath: string, content: string): void {
+    const fullPath = join(this.baseDir, relativePath);
+    mkdirSync(join(fullPath, '..'), { recursive: true });
+    writeFileSync(fullPath, content);
+  }
+
+  /**
+   * Read a file relative to the test base directory
+   */
+  readFile(relativePath: string): string {
+    return readFileSync(join(this.baseDir, relativePath), 'utf-8');
+  }
+
+  /**
+   * Check if a file exists relative to the test base directory
+   */
+  fileExists(relativePath: string): boolean {
+    return existsSync(join(this.baseDir, relativePath));
+  }
+}
+
+/**
+ * Run a Python hook as a subprocess
+ */
+export async function runPythonHook(
+  hookPath: string,
+  input: object,
+  options: {
+    cwd?: string;
+    env?: Record<string, string>;
+    args?: string[];
+  } = {}
+): Promise<HookResult> {
+  const inputJson = JSON.stringify(input);
+  const cwd = options.cwd ?? PROJECT_ROOT;
+  const args = options.args ?? [];
+
+  const proc = Bun.spawn(['python3', hookPath, ...args], {
+    stdin: new Blob([inputJson]),
+    stdout: 'pipe',
+    stderr: 'pipe',
+    cwd,
+    env: { ...process.env, ...options.env },
+  });
+
+  const stdout = await new Response(proc.stdout).text();
+  const stderr = await new Response(proc.stderr).text();
+  await proc.exited;
+
+  return {
+    stdout: stdout.trim(),
+    stderr: stderr.trim(),
+    exitCode: proc.exitCode ?? 0,
+  };
+}
+
+/**
+ * Run a Bash hook as a subprocess
+ */
+export async function runBashHook(
+  hookPath: string,
+  options: {
+    cwd?: string;
+    env?: Record<string, string>;
+    stdin?: string;
+  } = {}
+): Promise<HookResult> {
+  const cwd = options.cwd ?? PROJECT_ROOT;
+
+  const proc = Bun.spawn(['bash', hookPath], {
+    stdin: options.stdin ? new Blob([options.stdin]) : undefined,
+    stdout: 'pipe',
+    stderr: 'pipe',
+    cwd,
+    env: { ...process.env, ...options.env },
+  });
+
+  const stdout = await new Response(proc.stdout).text();
+  const stderr = await new Response(proc.stderr).text();
+  await proc.exited;
+
+  return {
+    stdout: stdout.trim(),
+    stderr: stderr.trim(),
+    exitCode: proc.exitCode ?? 0,
+  };
+}
+
+/**
+ * Run the context monitor Python hook
+ */
+export async function runContextMonitor(
+  input: object,
+  stateManager: TestStateManager
+): Promise<HookResult> {
+  const hookPath = join(HOOKS_DIR, 'ralph_context_monitor.py');
+  return runPythonHook(hookPath, input, {
+    cwd: stateManager.baseDir,
+    env: {
+      PYTHONPATH: LIB_DIR,
+    },
+  });
+}
+
+/**
+ * Run the ralph stop Bash hook
+ */
+export async function runRalphStop(
+  stateManager: TestStateManager,
+  options: {
+    maxIterations?: number;
+    transcript?: string;
+    enableLogging?: boolean;
+  } = {}
+): Promise<HookResult> {
+  const hookPath = join(HOOKS_DIR, 'ralph_stop.sh');
+  const stateRelPath = '.claude/ralph-state.json';
+
+  return runBashHook(hookPath, {
+    cwd: stateManager.baseDir,
+    env: {
+      RALPH_STATE_FILE: stateRelPath,
+      RALPH_MAX_ITERATIONS: String(options.maxIterations ?? 50),
+      RALPH_ENABLE_LOGGING: options.enableLogging ? 'true' : 'false',
+      CLAUDE_TRANSCRIPT: options.transcript ?? '',
+    },
+  });
+}
+
+/**
+ * Check if jq is available on the system
+ */
+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;
+  }
+}
+
+/**
+ * Check if Python 3 is available on the system
+ */
+export async function isPython3Available(): Promise<boolean> {
+  try {
+    const proc = Bun.spawn(['python3', '--version'], {
+      stdout: 'pipe',
+      stderr: 'pipe',
+    });
+    await proc.exited;
+    return proc.exitCode === 0;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Alias for isPython3Available for convenience
+ */
+export const isPythonAvailable = isPython3Available;