@ai-dev-methodologies/rlp-desk 0.7.4 → 0.8.0

package/src/node/reporting/campaign-reporting.mjs

@@ -0,0 +1,257 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+
+const execFileAsync = promisify(execFile);
+const REQUIRED_ANALYTICS_FIELDS = [
+  'iter',
+  'us_id',
+  'worker_model',
+  'worker_engine',
+  'verdict',
+  'duration',
+  'timestamp',
+];
+
+async function exists(targetPath) {
+  try {
+    await fs.access(targetPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function asDate(value) {
+  if (value instanceof Date) {
+    return value;
+  }
+
+  return value ? new Date(value) : new Date();
+}
+
+function formatElapsedSeconds(from, to) {
+  const elapsedMs = Math.max(0, asDate(to).getTime() - asDate(from).getTime());
+  return `${Math.floor(elapsedMs / 1000)}s`;
+}
+
+function analyticsVersionPath(targetPath, version) {
+  return targetPath.replace(/\.jsonl$/u, `-v${version}.jsonl`);
+}
+
+function reportVersionPath(targetPath, version) {
+  return targetPath.replace(/\.md$/u, `-v${version}.md`);
+}
+
+async function versionFile(targetPath, nextPathForVersion) {
+  if (!(await exists(targetPath))) {
+    return null;
+  }
+
+  let version = 1;
+  while (await exists(nextPathForVersion(targetPath, version))) {
+    version += 1;
+  }
+
+  const versionedPath = nextPathForVersion(targetPath, version);
+  await fs.rename(targetPath, versionedPath);
+  return versionedPath;
+}
+
+async function readJsonIfExists(targetPath) {
+  if (!(await exists(targetPath))) {
+    return null;
+  }
+
+  return JSON.parse(await fs.readFile(targetPath, 'utf8'));
+}
+
+async function readAnalytics(analyticsFile) {
+  if (!(await exists(analyticsFile))) {
+    return [];
+  }
+
+  const content = await fs.readFile(analyticsFile, 'utf8');
+  return content
+    .split('\n')
+    .filter(Boolean)
+    .map((line) => JSON.parse(line));
+}
+
+function extractObjective(prdContent) {
+  const match = prdContent.match(/^## Objective\s*([\s\S]*?)(?:^## |\s*$)/m);
+  return match?.[1]?.trim() ?? '(PRD objective not found)';
+}
+
+function extractUsList(prdContent) {
+  return [...prdContent.matchAll(/^## (US-\d{3}):/gm)].map((match) => match[1]);
+}
+
+function summarizeUsStatus(usList, status) {
+  const verified = new Set(status.verified_us ?? []);
+  return usList.length === 0
+    ? ['- None']
+    : usList.map((usId) => `- ${usId}: ${verified.has(usId) ? 'verified' : 'pending'}`);
+}
+
+function summarizeVerificationResults(records) {
+  return records.length === 0
+    ? ['- None']
+    : records.map((record) => `- iter ${record.iter}: ${record.us_id} -> ${record.verdict}`);
+}
+
+async function summarizeIssues(reportDir) {
+  const entries = await fs.readdir(reportDir, { withFileTypes: true }).catch(() => []);
+  const fixContracts = entries
+    .filter((entry) => entry.isFile() && /^iter-\d+\.fix-contract\.md$/u.test(entry.name))
+    .map((entry) => `- ${entry.name}`)
+    .sort();
+
+  return fixContracts.length > 0 ? fixContracts : ['- None'];
+}
+
+function summarizeCost(records) {
+  if (records.length === 0) {
+    return ['- No cost data available', '- Total duration: 0s'];
+  }
+
+  const totalDuration = records.reduce((sum, record) => sum + Number(record.duration ?? 0), 0);
+  return [
+    `- Iteration records: ${records.length}`,
+    `- Total duration: ${totalDuration}s`,
+  ];
+}
+
+async function defaultGitDiffProvider({ cwd }) {
+  try {
+    const { stdout } = await execFileAsync('git', ['diff', '--stat', 'HEAD'], { cwd });
+    return stdout.trim();
+  } catch {
+    return '(git diff unavailable)';
+  }
+}
+
+export async function prepareCampaignAnalytics({ analyticsFile, statusFile }) {
+  await fs.mkdir(path.dirname(analyticsFile), { recursive: true });
+  if (!(await exists(analyticsFile))) {
+    return null;
+  }
+
+  if (await exists(statusFile)) {
+    return null;
+  }
+
+  return versionFile(analyticsFile, analyticsVersionPath);
+}
+
+export async function appendCampaignAnalytics(analyticsFile, record) {
+  for (const field of REQUIRED_ANALYTICS_FIELDS) {
+    if (record[field] === undefined || record[field] === null || record[field] === '') {
+      throw new Error(`analytics record is missing required field: ${field}`);
+    }
+  }
+
+  await fs.mkdir(path.dirname(analyticsFile), { recursive: true });
+  await fs.appendFile(analyticsFile, `${JSON.stringify(record)}\n`, 'utf8');
+}
+
+export async function generateCampaignReport({
+  slug,
+  reportFile,
+  prdFile,
+  statusFile,
+  analyticsFile,
+  now = new Date(),
+  gitDiffProvider = defaultGitDiffProvider,
+  svSummary = 'N/A — --with-self-verification not enabled',
+}) {
+  await fs.mkdir(path.dirname(reportFile), { recursive: true });
+  await versionFile(reportFile, reportVersionPath);
+
+  const prdContent = (await fs.readFile(prdFile, 'utf8').catch(() => ''));
+  const status = (await readJsonIfExists(statusFile)) ?? {
+    slug,
+    iteration: 0,
+    max_iterations: 100,
+    phase: 'idle',
+    verified_us: [],
+    consecutive_failures: 0,
+  };
+  const records = await readAnalytics(analyticsFile);
+  const usList = extractUsList(prdContent);
+  const issues = await summarizeIssues(path.dirname(reportFile));
+  const filesChanged = await gitDiffProvider({ cwd: path.dirname(path.dirname(path.dirname(reportFile))) });
+  const terminalState = String(status.phase ?? 'timeout').toUpperCase();
+  const elapsed = status.started_at_utc
+    ? formatElapsedSeconds(status.started_at_utc, now)
+    : '0s';
+
+  const lines = [
+    `# Campaign Report: ${slug}`,
+    '',
+    `Generated: ${asDate(now).toISOString()} | Status: ${terminalState} | Iterations: ${status.iteration ?? 0}`,
+    '',
+    '## Objective',
+    extractObjective(prdContent),
+    '',
+    '## Execution Summary',
+    `- Terminal state: ${terminalState}`,
+    `- Iterations run: ${status.iteration ?? 0}`,
+    `- Elapsed: ${elapsed}`,
+    '',
+    '## US Status',
+    ...summarizeUsStatus(usList, status),
+    '',
+    '## Verification Results',
+    ...summarizeVerificationResults(records),
+    '',
+    '## Issues Encountered',
+    ...issues,
+    '',
+    '## Cost & Performance',
+    ...summarizeCost(records),
+    '',
+    '## SV Summary',
+    svSummary,
+    '',
+    '## Files Changed',
+    '```',
+    filesChanged || '(no changes)',
+    '```',
+    'Note: Files Changed may include pre-existing uncommitted changes if the campaign started in a dirty worktree.',
+    '',
+  ];
+
+  await fs.writeFile(reportFile, `${lines.join('\n')}\n`, 'utf8');
+}
+
+export async function readStatus(slug, options = {}) {
+  const rootDir = path.resolve(options.rootDir ?? process.cwd());
+  const statusFile = path.join(rootDir, '.claude', 'ralph-desk', 'logs', slug, 'runtime', 'status.json');
+
+  if (!(await exists(statusFile))) {
+    return `No active campaign for ${slug}.`;
+  }
+
+  let status;
+  try {
+    status = JSON.parse(await fs.readFile(statusFile, 'utf8'));
+  } catch {
+    return `Campaign: ${slug}\nstatus.json is corrupt.`;
+  }
+
+  const updatedAt = status.updated_at_utc ?? status.started_at_utc ?? asDate(options.now).toISOString();
+  const elapsed = formatElapsedSeconds(updatedAt, options.now ?? new Date());
+  const verifiedUs = (status.verified_us ?? []).join(', ') || 'none';
+
+  return [
+    `Campaign: ${slug}`,
+    `Iteration: ${status.iteration ?? 0} / ${status.max_iterations ?? 100}`,
+    `Phase: ${status.phase ?? 'unknown'}`,
+    `Worker Model: ${status.worker_model ?? 'unknown'} | Verifier: ${status.verifier_model ?? 'unknown'} (per-US) / ${status.final_verifier_model ?? 'unknown'} (final)`,
+    `Verified US: ${verifiedUs}`,
+    `Consecutive Failures: ${status.consecutive_failures ?? 0}`,
+    `Updated: ${updatedAt} (elapsed: ${elapsed})`,
+  ].join('\n');
+}

package/src/node/run.mjs

@@ -0,0 +1,234 @@
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { initCampaign } from './init/campaign-initializer.mjs';
+import { readStatus } from './reporting/campaign-reporting.mjs';
+import { run as runCampaignMain } from './runner/campaign-main-loop.mjs';
+
+const RUN_DEFAULTS = {
+  mode: 'agent',
+  workerModel: 'haiku',
+  verifierModel: 'sonnet',
+  finalVerifierModel: 'opus',
+  consensusMode: 'off',
+  consensusModel: 'gpt-5.4:medium',
+  finalConsensusModel: 'gpt-5.4:high',
+  verifyMode: 'per-us',
+  cbThreshold: 6,
+  maxIterations: 100,
+  iterTimeout: 600,
+  debug: false,
+  lockWorkerModel: false,
+  autonomous: false,
+  withSelfVerification: false,
+};
+
+function write(stream, value) {
+  stream.write(value.endsWith('\n') ? value : `${value}\n`);
+}
+
+function buildHelpText() {
+  return [
+    'Usage:',
+    '  node src/node/run.mjs <command> [args] [options]',
+    '',
+    'Commands:',
+    '  brainstorm <description>     Plan before init (not implemented in the Node rewrite yet)',
+    '  init <slug> [objective]      Create project scaffold',
+    '  run <slug> [options]         Run loop (agent=LLM leader, tmux=shell leader)',
+    '  status <slug>                Show loop status',
+    '  logs <slug> [N]              Show iteration log (not implemented in the Node rewrite yet)',
+    '  clean <slug> [--kill-session] Reset for re-run (not implemented in the Node rewrite yet)',
+    '  resume <slug>                Resume loop (not implemented in the Node rewrite yet)',
+    '',
+    'Run Options:',
+    '  --mode agent|tmux',
+    '  --worker-model MODEL',
+    '  --lock-worker-model',
+    '  --verifier-model MODEL',
+    '  --final-verifier-model MODEL',
+    '  --consensus off|all|final-only',
+    '  --consensus-model MODEL',
+    '  --final-consensus-model MODEL',
+    '  --verify-mode per-us|batch',
+    '  --cb-threshold N',
+    '  --max-iter N',
+    '  --iter-timeout N',
+    '  --debug',
+    '  --autonomous',
+    '  --with-self-verification',
+    '  --help',
+  ].join('\n');
+}
+
+function consumeValue(args, index, flag) {
+  const value = args[index + 1];
+  if (!value || value.startsWith('--')) {
+    throw new Error(`missing value for ${flag}`);
+  }
+  return value;
+}
+
+function parseInteger(value, flag) {
+  const parsed = Number.parseInt(value, 10);
+  if (!Number.isInteger(parsed) || parsed < 0) {
+    throw new Error(`${flag} must be a non-negative integer`);
+  }
+  return parsed;
+}
+
+function parseRunOptions(args, cwd) {
+  const options = {
+    rootDir: cwd,
+    ...RUN_DEFAULTS,
+  };
+
+  for (let index = 0; index < args.length; index += 1) {
+    const token = args[index];
+    switch (token) {
+      case '--mode':
+        options.mode = consumeValue(args, index, token);
+        index += 1;
+        break;
+      case '--worker-model':
+        options.workerModel = consumeValue(args, index, token);
+        index += 1;
+        break;
+      case '--lock-worker-model':
+        options.lockWorkerModel = true;
+        break;
+      case '--verifier-model':
+        options.verifierModel = consumeValue(args, index, token);
+        index += 1;
+        break;
+      case '--final-verifier-model':
+        options.finalVerifierModel = consumeValue(args, index, token);
+        index += 1;
+        break;
+      case '--consensus':
+        options.consensusMode = consumeValue(args, index, token);
+        index += 1;
+        break;
+      case '--consensus-model':
+        options.consensusModel = consumeValue(args, index, token);
+        index += 1;
+        break;
+      case '--final-consensus-model':
+        options.finalConsensusModel = consumeValue(args, index, token);
+        index += 1;
+        break;
+      case '--verify-mode':
+        options.verifyMode = consumeValue(args, index, token);
+        index += 1;
+        break;
+      case '--cb-threshold':
+        options.cbThreshold = parseInteger(consumeValue(args, index, token), token);
+        index += 1;
+        break;
+      case '--max-iter':
+        options.maxIterations = parseInteger(consumeValue(args, index, token), token);
+        index += 1;
+        break;
+      case '--iter-timeout':
+        options.iterTimeout = parseInteger(consumeValue(args, index, token), token);
+        index += 1;
+        break;
+      case '--debug':
+        options.debug = true;
+        break;
+      case '--autonomous':
+        options.autonomous = true;
+        break;
+      case '--with-self-verification':
+        options.withSelfVerification = true;
+        break;
+      default:
+        throw new Error(`unknown option: ${token}`);
+    }
+  }
+
+  return options;
+}
+
+async function runInit(args, deps) {
+  if (args.length === 0 || args[0] === '--help') {
+    write(deps.stdout, 'Usage: node src/node/run.mjs init <slug> [objective]');
+    return 0;
+  }
+
+  const slug = args[0];
+  const objective = args.slice(1).join(' ').trim() || 'TBD - fill in the objective';
+  await deps.initCampaign(slug, objective, { rootDir: deps.cwd });
+  write(deps.stdout, `Initialized ${slug} in ${path.join(deps.cwd, '.claude', 'ralph-desk')}`);
+  return 0;
+}
+
+async function runStatusCommand(args, deps) {
+  if (args.length === 0 || args[0] === '--help') {
+    write(deps.stdout, 'Usage: node src/node/run.mjs status <slug>');
+    return 0;
+  }
+
+  write(deps.stdout, await deps.readStatus(args[0], { rootDir: deps.cwd }));
+  return 0;
+}
+
+async function runRunCommand(args, deps) {
+  if (args.length === 0) {
+    throw new Error('run requires a slug');
+  }
+
+  if (args[0] === '--help') {
+    write(deps.stdout, buildHelpText());
+    return 0;
+  }
+
+  const slug = args[0];
+  const options = parseRunOptions(args.slice(1), deps.cwd);
+  await deps.runCampaign(slug, options);
+  write(deps.stdout, `Campaign started for ${slug}`);
+  return 0;
+}
+
+export async function main(argv = process.argv.slice(2), overrides = {}) {
+  const deps = {
+    cwd: overrides.cwd ?? process.cwd(),
+    stdout: overrides.stdout ?? process.stdout,
+    stderr: overrides.stderr ?? process.stderr,
+    initCampaign: overrides.initCampaign ?? initCampaign,
+    readStatus: overrides.readStatus ?? readStatus,
+    runCampaign: overrides.runCampaign ?? runCampaignMain,
+  };
+
+  try {
+    if (argv.length === 0 || argv[0] === '--help' || argv[0] === '-h') {
+      write(deps.stdout, buildHelpText());
+      return 0;
+    }
+
+    const [command, ...rest] = argv;
+    switch (command) {
+      case 'init':
+        return await runInit(rest, deps);
+      case 'run':
+        return await runRunCommand(rest, deps);
+      case 'status':
+        return await runStatusCommand(rest, deps);
+      case 'brainstorm':
+      case 'logs':
+      case 'clean':
+      case 'resume':
+        throw new Error(`${command} is not implemented in the Node rewrite yet`);
+      default:
+        throw new Error(`unknown command: ${command}. Run with --help to see available commands.`);
+    }
+  } catch (error) {
+    write(deps.stderr, error.message);
+    return 1;
+  }
+}
+
+if (process.argv[1] && path.basename(process.argv[1]) === path.basename(fileURLToPath(import.meta.url))) {
+  const exitCode = await main();
+  process.exitCode = exitCode;
+}