minimal-agent 0.1.9 → 0.2.0

package/plugins/ralph-wiggum/src/verificationGate.ts

@@ -0,0 +1,252 @@
+/**
+ * ============================================================
+ *  src/plugins/verificationGate.ts —— ralph-loop 的"完成验证门"
+ * ------------------------------------------------------------
+ *  Agent 输出 <promise>DONE</promise> 哨兵后，pluginRunner 跑这里的
+ *  checks。全部通过才真正退出循环；任一未通过则回 BUILD 继续干。
+ *
+ *  支持四种 check：
+ *    - shell:<cmd>                跨平台 spawn（Windows 走 cmd /c, 其余 bash -c）
+ *    - file_exists:<path>         fs.existsSync
+ *    - file_contains:<file>:<re>  正则匹配文件内容
+ *    - test_count:<min>           跑 `bun test`，从 stdout 解析 "N pass"
+ *
+ *  工作目录隔离：所有相对路径以 getWorkingDir() 为锚，子进程 cwd 也用它，
+ *  确保并行 session 不会互相串台。
+ * ============================================================
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import { spawn } from 'node:child_process';
+
+export interface Check {
+  type: 'shell' | 'file_contains' | 'file_exists' | 'test_count';
+  command?: string;
+  file?: string;
+  pattern?: string;
+  minCount?: number;
+  timeout?: number;
+}
+
+export interface CheckResult {
+  check: Check;
+  passed: boolean;
+  output: string;
+}
+
+export interface VerifyResult {
+  passed: boolean;
+  details: CheckResult[];
+  summary: string;
+}
+
+function parseVerifyArg(arg: string): Check | null {
+  const colonIdx = arg.indexOf(':');
+  if (colonIdx < 0) return null;
+
+  const type = arg.slice(0, colonIdx).trim().toLowerCase();
+  const value = arg.slice(colonIdx + 1).trim();
+
+  switch (type) {
+    case 'shell':
+      return { type: 'shell', command: value, timeout: 30_000 };
+    case 'file_exists':
+      return { type: 'file_exists', file: value };
+    case 'file_contains': {
+      const sep = value.indexOf(':');
+      if (sep < 0) return null;
+      return {
+        type: 'file_contains',
+        file: value.slice(0, sep),
+        pattern: value.slice(sep + 1),
+      };
+    }
+    case 'test_count': {
+      const count = parseInt(value, 10);
+      if (isNaN(count) || count < 0) return null;
+      return { type: 'test_count', minCount: count };
+    }
+    default:
+      return null;
+  }
+}
+
+export function parseVerifyArgs(args: string): Check[] {
+  const checks: Check[] = [];
+  const regex = /--verify\s+("[^"]*"|\S+)/gi;
+  let match;
+
+  while ((match = regex.exec(args)) !== null) {
+    const raw = match[1].replace(/^"|"$/g, '');
+    const check = parseVerifyArg(raw);
+    if (check) checks.push(check);
+  }
+
+  return checks;
+}
+
+interface ShellRunResult {
+  exitCode: number | null;
+  stdout: string;
+  stderr: string;
+  errored: boolean;
+}
+
+function runShell(command: string, timeout: number): Promise<ShellRunResult> {
+  return new Promise((resolve) => {
+    const isWin = process.platform === 'win32';
+    // 不显式传 cwd —— 继承 process.cwd()，main.tsx 已 chdir 到 workingDir，
+    // 而测试里直接用 process.cwd()，避免依赖 mock 的 getWorkingDir 造成串台
+    const child = isWin
+      ? spawn('cmd', ['/c', command], { timeout, env: process.env })
+      : spawn('bash', ['-c', command], { timeout, env: process.env });
+
+    let stdout = '';
+    let stderr = '';
+
+    child.stdout.on('data', (d: Buffer) => {
+      stdout += d.toString();
+    });
+    child.stderr.on('data', (d: Buffer) => {
+      stderr += d.toString();
+    });
+
+    child.on('error', () => {
+      resolve({ exitCode: null, stdout, stderr, errored: true });
+    });
+
+    child.on('close', (code) => {
+      resolve({ exitCode: code, stdout, stderr, errored: false });
+    });
+  });
+}
+
+export async function verifyShell(command: string, timeout: number): Promise<CheckResult> {
+  const r = await runShell(command, timeout);
+  if (r.errored) {
+    return {
+      check: { type: 'shell', command },
+      passed: false,
+      output: `执行失败`,
+    };
+  }
+  return {
+    check: { type: 'shell', command },
+    passed: r.exitCode === 0,
+    output: r.stdout.trim() || r.stderr.trim() || `exit code ${r.exitCode}`,
+  };
+}
+
+export function verifyFileExists(file: string): CheckResult {
+  const exists = existsSync(file);
+  return {
+    check: { type: 'file_exists', file },
+    passed: exists,
+    output: exists ? '文件存在' : `文件不存在: ${file}`,
+  };
+}
+
+export function verifyFileContains(file: string, pattern: string): CheckResult {
+  try {
+    const content = readFileSync(file, 'utf8');
+    const regex = new RegExp(pattern);
+    const matched = regex.test(content);
+
+    return {
+      check: { type: 'file_contains', file, pattern },
+      passed: matched,
+      output: matched ? `文件包含 "${pattern}"` : `文件不包含 "${pattern}"`,
+    };
+  } catch {
+    return {
+      check: { type: 'file_contains', file, pattern },
+      passed: false,
+      output: `无法读取文件: ${file}`,
+    };
+  }
+}
+
+async function verifyTestCount(minCount: number): Promise<CheckResult> {
+  const r = await runShell(`bun test`, 60_000);
+  // bun test 把进度打在 stderr，最终统计也常在 stderr，所以合并解析
+  const combined = `${r.stdout}\n${r.stderr}`;
+  if (r.errored) {
+    return {
+      check: { type: 'test_count', minCount },
+      passed: false,
+      output: '无法执行 bun test',
+    };
+  }
+
+  const matches = [...combined.matchAll(/(\d+)\s+pass/gi)];
+  const count = matches.length > 0 ? parseInt(matches[matches.length - 1][1], 10) : 0;
+  const passed = count >= minCount;
+
+  return {
+    check: { type: 'test_count', minCount },
+    passed,
+    output: `${count} pass (需要 >=${minCount})`,
+  };
+}
+
+export async function runVerification(checks: Check[]): Promise<VerifyResult> {
+  if (checks.length === 0) {
+    return { passed: true, details: [], summary: '无验证项' };
+  }
+
+  const results: CheckResult[] = [];
+
+  for (const check of checks) {
+    let result: CheckResult;
+
+    switch (check.type) {
+      case 'shell':
+        result = await verifyShell(check.command ?? '', check.timeout ?? 30_000);
+        break;
+      case 'file_exists':
+        result = verifyFileExists(check.file ?? '');
+        break;
+      case 'file_contains':
+        result = verifyFileContains(check.file ?? '', check.pattern ?? '');
+        break;
+      case 'test_count':
+        result = await verifyTestCount(check.minCount ?? 0);
+        break;
+      default:
+        result = {
+          check,
+          passed: false,
+          output: `未知验证类型: ${(check as { type: string }).type}`,
+        };
+    }
+
+    results.push(result);
+  }
+
+  const allPassed = results.every((r) => r.passed);
+  const failedNames = results.filter((r) => !r.passed).map((r) => formatCheckName(r.check));
+
+  let summary: string;
+  if (allPassed) {
+    summary = `✅ 全部通过 (${results.length}/${results.length})`;
+  } else {
+    summary = `❌ 验证未通过: ${failedNames.join(', ')}`;
+  }
+
+  return { passed: allPassed, details: results, summary };
+}
+
+function formatCheckName(check: Check): string {
+  switch (check.type) {
+    case 'shell':
+      return `shell(${(check.command ?? '').slice(0, 40)})`;
+    case 'file_exists':
+      return `exists(${check.file})`;
+    case 'file_contains':
+      return `contains(${check.file}:${check.pattern})`;
+    case 'test_count':
+      return `tests(>=${check.minCount})`;
+    default:
+      return check.type;
+  }
+}

package/plugins/ralph-wiggum/test/goalState.test.ts

@@ -0,0 +1,410 @@
+import { describe, expect, it } from 'bun:test';
+import { mkdirSync, rmSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { GoalState, Phase } from '../src/goalState.ts';
+
+function createTempDir(): string {
+  const dir = join(tmpdir(), `goalstate-test-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+  mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+function cleanup(dir: string): void {
+  try {
+    rmSync(dir, { recursive: true });
+  } catch {
+  }
+}
+
+describe('goalState', () => {
+  describe('init', () => {
+    it('创建所有状态文件', async () => {
+      const tmpDir = createTempDir();
+      try {
+        const gs = new GoalState(tmpDir);
+        await gs.init('Build a REST API', []);
+
+        expect(existsSync(join(tmpDir, '.minimal-agent', 'goal.md'))).toBe(true);
+        expect(existsSync(join(tmpDir, '.minimal-agent', 'completion.md'))).toBe(true);
+        expect(existsSync(join(tmpDir, '.minimal-agent', 'phase.md'))).toBe(true);
+        expect(existsSync(join(tmpDir, '.minimal-agent', 'progress.md'))).toBe(true);
+        expect(existsSync(join(tmpDir, '.minimal-agent', 'learnings.md'))).toBe(true);
+        expect(existsSync(join(tmpDir, '.minimal-agent', 'decisions.md'))).toBe(true);
+      } finally {
+        cleanup(tmpDir);
+      }
+    });
+
+    it('goal.md 包含目标文本', async () => {
+      const tmpDir = createTempDir();
+      try {
+        const gs = new GoalState(tmpDir);
+        await gs.init('Fix auth bug in login module', []);
+        expect(gs.goal).toContain('Fix auth bug');
+      } finally {
+        cleanup(tmpDir);
+      }
+    });
+
+    it('初始阶段为 PLAN', async () => {
+      const tmpDir = createTempDir();
+      try {
+        const gs = new GoalState(tmpDir);
+        await gs.init('Test goal', []);
+        expect(gs.currentPhase).toBe(Phase.PLAN);
+      } finally {
+        cleanup(tmpDir);
+      }
+    });
+
+    it('重复 init 不覆盖已有文件', async () => {
+      const tmpDir = createTempDir();
+      try {
+        const gs = new GoalState(tmpDir);
+        await gs.init('First goal', []);
+        await gs.init('Second goal', []);
+        expect(gs.goal).toContain('First goal');
+      } finally {
+        cleanup(tmpDir);
+      }
+    });
+  });
+
+  describe('phase management', () => {
+    it('PLAN → BUILD 合法切换', async () => {
+      const tmpDir = createTempDir();
+      try {
+        const gs = new GoalState(tmpDir);
+        await gs.init('Test', []);
+        await gs.setPhase(Phase.BUILD, 'plan_complete');
+        expect(gs.currentPhase).toBe(Phase.BUILD);
+      } finally {
+        cleanup(tmpDir);
+      }
+    });
+
+    it('setPhase 的 reason 是日志文本，不参与 FSM 校验', async () => {
+      const tmpDir = createTempDir();
+      try {
+        const gs = new GoalState(tmpDir);
+        await gs.init('Test', []);
+        // 用任意中文 reason，合法目标阶段仍应成功
+        await gs.setPhase(Phase.BUILD, '随便写的日志文本，不该被当成事件名');
+        expect(gs.currentPhase).toBe(Phase.BUILD);
+      } finally {
+        cleanup(tmpDir);
+      }
+    });
+
+    it('非法阶段切换抛出错误（基于目标阶段，与 reason 无关）', async () => {
+      const tmpDir = createTempDir();
+      try {
+        const gs = new GoalState(tmpDir);
+        await gs.init('Test', []);
+        // PLAN → VERIFY 在 PHASE_TRANSITIONS[PLAN] 的 values 中不存在
+        await expect(
+          gs.setPhase(Phase.VERIFY, '哪怕写一个看似合法的英文 event 名也不行'),
+        ).rejects.toThrow();
+      } finally {
+        cleanup(tmpDir);
+      }
+    });
+
+    it('forceSetPhase 允许任意切换', async () => {
+      const tmpDir = createTempDir();
+      try {
+        const gs = new GoalState(tmpDir);
+        await gs.init('Test', []);
+        await gs.forceSetPhase(Phase.HEAL, 'manual override');
+        expect(gs.currentPhase).toBe(Phase.HEAL);
+      } finally {
+        cleanup(tmpDir);
+      }
+    });
+  });
+
+  describe('progress log', () => {
+    it('追加进度日志', async () => {
+      const tmpDir = createTempDir();
+      try {
+        const gs = new GoalState(tmpDir);
+        await gs.init('Test', []);
+        await gs.appendProgress('Iteration 1: started');
+        await gs.appendProgress('Iteration 2: done');
+
+        const tail = gs.tailProgress(10);
+        expect(tail).toContain('Iteration 1: started');
+        expect(tail).toContain('Iteration 2: done');
+      } finally {
+        cleanup(tmpDir);
+      }
+    });
+
+    it('tailProgress 只返回最近 N 行', async () => {
+      const tmpDir = createTempDir();
+      try {
+        const gs = new GoalState(tmpDir);
+        await gs.init('Test', []);
+        for (let i = 0; i < 20; i++) {
+          await gs.appendProgress(`Line ${i}`);
+        }
+
+        const tail = gs.tailProgress(3);
+        const lines = tail.split('\n').filter(Boolean);
+        expect(lines.length).toBe(3);
+        expect(lines[0]).toContain('Line 17');
+      } finally {
+        cleanup(tmpDir);
+      }
+    });
+  });
+
+  describe('learnings', () => {
+    it('追加教训', async () => {
+      const tmpDir = createTempDir();
+      try {
+        const gs = new GoalState(tmpDir);
+        await gs.init('Test', []);
+        await gs.appendLearning('Always backup before modifying settings.py');
+        await gs.appendLearning('Use relative imports in routes/');
+
+        expect(gs.learnings).toContain('backup before modifying settings.py');
+        expect(gs.learnings).toContain('relative imports in routes/');
+      } finally {
+        cleanup(tmpDir);
+      }
+    });
+
+    it('空 learnings 返回空字符串', async () => {
+      const tmpDir = createTempDir();
+      try {
+        const gs = new GoalState(tmpDir);
+        await gs.init('Test', []);
+        expect(gs.learnings).toBe('');
+      } finally {
+        cleanup(tmpDir);
+      }
+    });
+
+    it('learnings 超过 20 行时只返回尾部 20 行（防 context 膨胀）', async () => {
+      const tmpDir = createTempDir();
+      try {
+        const gs = new GoalState(tmpDir);
+        await gs.init('Test', []);
+        for (let i = 0; i < 50; i++) {
+          await gs.appendLearning(`lesson-${i}`);
+        }
+
+        const tail = gs.learnings;
+        const lines = tail.split('\n').filter(Boolean);
+        expect(lines.length).toBe(20);
+        // 最早的应该已经被裁掉
+        expect(tail).not.toContain('lesson-0\n');
+        expect(tail).not.toContain('lesson-29\n');
+        // 最新一条仍在
+        expect(tail).toContain('lesson-49');
+      } finally {
+        cleanup(tmpDir);
+      }
+    });
+  });
+
+  describe('decision log', () => {
+    it('记录决策', async () => {
+      const tmpDir = createTempDir();
+      try {
+        const gs = new GoalState(tmpDir);
+        await gs.init('Test', []);
+        await gs.recordDecision(
+          { iteration: 5, phase: Phase.PLAN, summary: 'Auth implementation approach' },
+          ['JWT', 'Session', 'OAuth'],
+          'JWT',
+          'Single service, simpler for frontend',
+        );
+
+        const similar = gs.findSimilarDecisions(
+          { iteration: 10, phase: Phase.PLAN, summary: 'Auth implementation approach' },
+        );
+        expect(similar).toHaveLength(1);
+        expect(similar[0].chosen).toBe('JWT');
+      } finally {
+        cleanup(tmpDir);
+      }
+    });
+
+    it('无相似决策时返回空数组', async () => {
+      const tmpDir = createTempDir();
+      try {
+        const gs = new GoalState(tmpDir);
+        await gs.init('Test', []);
+        const similar = gs.findSimilarDecisions({
+          iteration: 1,
+          phase: Phase.PLAN,
+          summary: 'Database choice',
+        });
+        expect(similar).toHaveLength(0);
+      } finally {
+        cleanup(tmpDir);
+      }
+    });
+
+    it('summarizeDecisions 返回格式化摘要', async () => {
+      const tmpDir = createTempDir();
+      try {
+        const gs = new GoalState(tmpDir);
+        await gs.init('Test', []);
+        await gs.recordDecision(
+          { iteration: 3, phase: Phase.PLAN, summary: 'DB' },
+          ['PostgreSQL', 'MySQL', 'SQLite'],
+          'PostgreSQL',
+          'JSON support needed',
+        );
+
+        const summary = gs.summarizeDecisions(5);
+        expect(summary).toContain('PostgreSQL');
+        expect(summary).toContain('迭代 3');
+      } finally {
+        cleanup(tmpDir);
+      }
+    });
+  });
+
+  describe('composeContext', () => {
+    it('组装包含目标 + 阶段 + 本轮任务', async () => {
+      const tmpDir = createTempDir();
+      try {
+        const gs = new GoalState(tmpDir);
+        await gs.init('Build user auth module', []);
+        const ctx = gs.composeContext(5);
+
+        expect(ctx).toContain('不可变目标');
+        expect(ctx).toContain('Build user auth module');
+        expect(ctx).toContain('当前阶段: PLAN');
+        expect(ctx).toContain('本轮任务 (迭代 5)');
+      } finally {
+        cleanup(tmpDir);
+      }
+    });
+
+    it('composeContext 包含 learnings（如果有）', async () => {
+      const tmpDir = createTempDir();
+      try {
+        const gs = new GoalState(tmpDir);
+        await gs.init('Test', []);
+        await gs.appendLearning('Lesson one');
+
+        const ctx = gs.composeContext(1);
+        expect(ctx).toContain('关键教训');
+        expect(ctx).toContain('Lesson one');
+      } finally {
+        cleanup(tmpDir);
+      }
+    });
+
+    it('composeContext 不包含空的 learnings 块', async () => {
+      const tmpDir = createTempDir();
+      try {
+        const gs = new GoalState(tmpDir);
+        await gs.init('Test', []);
+
+        const ctx = gs.composeContext(1);
+        expect(ctx).not.toContain('关键教训');
+      } finally {
+        cleanup(tmpDir);
+      }
+    });
+  });
+
+  describe('cleanup', () => {
+    it('清理后文件不存在（await）', async () => {
+      const tmpDir = createTempDir();
+      try {
+        const gs = new GoalState(tmpDir);
+        await gs.init('Test', []);
+        await gs.cleanup();
+
+        expect(existsSync(join(tmpDir, '.minimal-agent', 'goal.md'))).toBe(false);
+      } finally {
+        cleanup(tmpDir);
+      }
+    });
+
+    it('清理后空目录也被删除（await）', async () => {
+      const tmpDir = createTempDir();
+      try {
+        const gs = new GoalState(tmpDir);
+        await gs.init('Test', []);
+        await gs.cleanup();
+
+        expect(existsSync(join(tmpDir, '.minimal-agent'))).toBe(false);
+      } finally {
+        cleanup(tmpDir);
+      }
+    });
+  });
+
+  describe('reset', () => {
+    it('reset 后旧目标被清除，新 init 写入新目标', async () => {
+      const tmpDir = createTempDir();
+      try {
+        const gs = new GoalState(tmpDir);
+        await gs.init('Old goal', []);
+        expect(gs.goal).toContain('Old goal');
+
+        await gs.reset();
+        expect(gs.goal).toBe('');
+
+        await gs.init('New goal', []);
+        expect(gs.goal).toContain('New goal');
+      } finally {
+        cleanup(tmpDir);
+      }
+    });
+  });
+
+  describe('sessionTag', () => {
+    it('不传 sessionTag 使用默认目录 .minimal-agent', async () => {
+      const tmpDir = createTempDir();
+      try {
+        const gs = new GoalState(tmpDir);
+        await gs.init('Test', []);
+
+        expect(existsSync(join(tmpDir, '.minimal-agent'))).toBe(true);
+        expect(existsSync(join(tmpDir, '.minimal-agent-session-a'))).toBe(false);
+      } finally {
+        cleanup(tmpDir);
+      }
+    });
+
+    it('传入 sessionTag 使用带 tag 的目录', async () => {
+      const tmpDir = createTempDir();
+      try {
+        const gs = new GoalState(tmpDir, 'session-a');
+        await gs.init('Test', []);
+
+        expect(existsSync(join(tmpDir, '.minimal-agent-session-a'))).toBe(true);
+        expect(existsSync(join(tmpDir, '.minimal-agent-session-a', 'goal.md'))).toBe(true);
+        expect(gs.goal).toContain('Test');
+      } finally {
+        cleanup(tmpDir);
+      }
+    });
+
+    it('不同 sessionTag 隔离状态', async () => {
+      const tmpDir = createTempDir();
+      try {
+        const gsA = new GoalState(tmpDir, 'alpha');
+        const gsB = new GoalState(tmpDir, 'beta');
+
+        await gsA.init('Goal Alpha', []);
+        await gsB.init('Goal Beta', []);
+
+        expect(gsA.goal).toContain('Goal Alpha');
+        expect(gsB.goal).toContain('Goal Beta');
+      } finally {
+        cleanup(tmpDir);
+      }
+    });
+  });
+});