agentic-orchestrator 0.1.0

package/apps/control-plane/src/core/gates.ts

@@ -0,0 +1,361 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { runCommand, type CommandResult } from './git.js';
+import { ensureDir, nowIso } from './fs.js';
+
+export interface CoverageMetrics {
+  line: number;
+  branch: number;
+  details: Record<string, number>;
+}
+
+export interface ParserConfig {
+  type: 'none' | 'lcov' | 'junit_xml' | 'jacoco_xml' | 'cobertura_xml' | string;
+  path?: string;
+}
+
+export interface GateThresholds {
+  coverage_line_min: number;
+  coverage_branch_min: number;
+  coverage_line_target: number;
+  coverage_branch_target: number;
+}
+
+export interface GateStep {
+  name: string;
+  cmd: string[];
+  cwd?: string;
+  env?: Record<string, string>;
+  timeout_seconds?: number;
+}
+
+export interface GateProfile {
+  modes?: Record<string, GateStep[]>;
+  parsers?: {
+    coverage?: ParserConfig;
+  };
+  thresholds?: Partial<GateThresholds>;
+}
+
+export interface PolicyShape {
+  execution: {
+    retry_policy: {
+      transient_max_retries: number;
+      transient_error_codes: number[];
+    };
+    env_allowlist: string[];
+    default_step_timeout_seconds: number;
+  };
+  testing: {
+    coverage: {
+      minimums: { line: number; branch: number };
+      targets: { line: number; branch: number };
+    };
+  };
+}
+
+export interface CoverageParserStrategy {
+  readonly type: string;
+  parse(content: string): CoverageMetrics;
+}
+
+class LcovCoverageParser implements CoverageParserStrategy {
+  readonly type = 'lcov';
+
+  parse(content: string): CoverageMetrics {
+    const linesFound = Number(content.match(/^LF:(\d+)/m)?.[1] ?? 0);
+    const linesHit = Number(content.match(/^LH:(\d+)/m)?.[1] ?? 0);
+    const branchesFound = Number(content.match(/^BRF:(\d+)/m)?.[1] ?? 0);
+    const branchesHit = Number(content.match(/^BRH:(\d+)/m)?.[1] ?? 0);
+
+    return {
+      line: linesFound > 0 ? linesHit / linesFound : 1,
+      branch: branchesFound > 0 ? branchesHit / branchesFound : 1,
+      details: { linesFound, linesHit, branchesFound, branchesHit }
+    };
+  }
+}
+
+class JunitXmlCoverageParser implements CoverageParserStrategy {
+  readonly type = 'junit_xml';
+
+  parse(content: string): CoverageMetrics {
+    const tests = Number(content.match(/tests="(\d+)"/)?.[1] ?? 0);
+    const failures = Number(content.match(/failures="(\d+)"/)?.[1] ?? 0);
+    const errors = Number(content.match(/errors="(\d+)"/)?.[1] ?? 0);
+    const passRate = tests > 0 ? (tests - failures - errors) / tests : 1;
+    return { line: passRate, branch: passRate, details: { tests, failures, errors } };
+  }
+}
+
+class JacocoXmlCoverageParser implements CoverageParserStrategy {
+  readonly type = 'jacoco_xml';
+
+  parse(content: string): CoverageMetrics {
+    const lineMatch = content.match(/<counter type="LINE" missed="(\d+)" covered="(\d+)"/);
+    const branchMatch = content.match(/<counter type="BRANCH" missed="(\d+)" covered="(\d+)"/);
+    const lineMissed = Number(lineMatch?.[1] ?? 0);
+    const lineCovered = Number(lineMatch?.[2] ?? 0);
+    const branchMissed = Number(branchMatch?.[1] ?? 0);
+    const branchCovered = Number(branchMatch?.[2] ?? 0);
+    return {
+      line: lineCovered + lineMissed > 0 ? lineCovered / (lineCovered + lineMissed) : 1,
+      branch: branchCovered + branchMissed > 0 ? branchCovered / (branchCovered + branchMissed) : 1,
+      details: { lineMissed, lineCovered, branchMissed, branchCovered }
+    };
+  }
+}
+
+class CoberturaXmlCoverageParser implements CoverageParserStrategy {
+  readonly type = 'cobertura_xml';
+
+  parse(content: string): CoverageMetrics {
+    const lineRate = Number(content.match(/line-rate="([0-9.]+)"/)?.[1] ?? 1);
+    const branchRate = Number(content.match(/branch-rate="([0-9.]+)"/)?.[1] ?? 1);
+    return {
+      line: lineRate,
+      branch: branchRate,
+      details: { lineRate, branchRate }
+    };
+  }
+}
+
+export class CoverageParserRegistry {
+  private readonly strategies: Map<string, CoverageParserStrategy>;
+
+  constructor(strategies: CoverageParserStrategy[]) {
+    this.strategies = new Map(strategies.map((strategy) => [strategy.type, strategy]));
+  }
+
+  parse(parserConfig: ParserConfig | undefined, content: string): CoverageMetrics | null {
+    if (!parserConfig || parserConfig.type === 'none') {
+      return null;
+    }
+
+    const strategy = this.strategies.get(parserConfig.type);
+    if (!strategy) {
+      throw new Error(`unsupported_parser:${parserConfig.type}`);
+    }
+    return strategy.parse(content);
+  }
+}
+
+export class CoverageThresholdPolicy {
+  merge(policy: PolicyShape, profileThresholds: Partial<GateThresholds> = {}): GateThresholds {
+    return {
+      coverage_line_min: Math.max(policy.testing.coverage.minimums.line, profileThresholds.coverage_line_min ?? 0),
+      coverage_branch_min: Math.max(policy.testing.coverage.minimums.branch, profileThresholds.coverage_branch_min ?? 0),
+      coverage_line_target: Math.max(policy.testing.coverage.targets.line, profileThresholds.coverage_line_target ?? 0),
+      coverage_branch_target: Math.max(policy.testing.coverage.targets.branch, profileThresholds.coverage_branch_target ?? 0)
+    };
+  }
+}
+
+function pickAllowedEnv(envAllowlist: string[] = []): NodeJS.ProcessEnv {
+  const env: NodeJS.ProcessEnv = {};
+  for (const key of envAllowlist) {
+    if (Object.prototype.hasOwnProperty.call(process.env, key)) {
+      env[key] = process.env[key];
+    }
+  }
+  return env;
+}
+
+export async function parseCoverage(parserConfig: ParserConfig | undefined, worktreePath: string): Promise<CoverageMetrics | null> {
+  if (!parserConfig || parserConfig.type === 'none') {
+    return null;
+  }
+
+  const coveragePath = path.join(worktreePath, parserConfig.path ?? '');
+  const content = await fs.readFile(coveragePath, 'utf8');
+
+  return defaultCoverageParserRegistry.parse(parserConfig, content);
+}
+
+export class GateExecutionService {
+  private readonly thresholdPolicy: CoverageThresholdPolicy;
+
+  constructor(thresholdPolicy: CoverageThresholdPolicy) {
+    this.thresholdPolicy = thresholdPolicy;
+  }
+
+  async runMode({
+    featureId,
+    mode,
+    profileName,
+    profile,
+    policy,
+    worktreePath,
+    logDirectory,
+    evidenceDirectory
+  }: {
+    featureId: string;
+    mode: string;
+    profileName: string;
+    profile: GateProfile;
+    policy: PolicyShape;
+    worktreePath: string;
+    logDirectory: string;
+    evidenceDirectory: string;
+  }): Promise<Record<string, unknown>> {
+    const modeSteps = profile.modes?.[mode];
+    if (!Array.isArray(modeSteps)) {
+      throw new Error(`unknown_gate_profile_or_mode:${profileName}/${mode}`);
+    }
+
+    await ensureDir(logDirectory);
+    await ensureDir(evidenceDirectory);
+
+    const retryPolicy = policy.execution.retry_policy;
+    const env = pickAllowedEnv(policy.execution.env_allowlist);
+    const stepResults: Array<Record<string, unknown>> = [];
+    let overall = 'pass';
+
+    for (const step of modeSteps) {
+      const timeoutSeconds = Number(step.timeout_seconds ?? policy.execution.default_step_timeout_seconds);
+      const stepLogPath = path.join(
+        logDirectory,
+        `${Date.now()}-${mode}-${step.name.replaceAll(/[^a-zA-Z0-9_-]/g, '_')}.log`
+      );
+
+      let attempts = 0;
+      let lastResult: CommandResult = { code: 1, signal: null, stdout: '', stderr: '', timeout: false };
+      const maxAttempts = retryPolicy.transient_max_retries + 1;
+
+      while (attempts < maxAttempts) {
+        attempts += 1;
+        const result = await runCommand(step.cmd[0], step.cmd.slice(1), {
+          cwd: step.cwd ? path.join(worktreePath, step.cwd) : worktreePath,
+          env: { ...env, ...step.env },
+          timeoutMs: timeoutSeconds * 1000
+        });
+
+        lastResult = result;
+        const logText = [
+          `# feature=${featureId} mode=${mode} step=${step.name} attempt=${attempts}`,
+          `# cmd=${JSON.stringify(step.cmd)}`,
+          `# exit=${result.code} timeout=${result.timeout}`,
+          '',
+          '## stdout',
+          result.stdout,
+          '',
+          '## stderr',
+          result.stderr
+        ].join('\n');
+        await fs.writeFile(stepLogPath, `${logText}\n`, 'utf8');
+
+        if (result.timeout || result.code === 0) {
+          break;
+        }
+
+        const isTransient = retryPolicy.transient_error_codes.includes(result.code);
+        if (!isTransient) {
+          break;
+        }
+      }
+
+      const stepState = {
+        name: step.name,
+        cmd: step.cmd,
+        attempts,
+        exit_code: lastResult.code,
+        timeout: lastResult.timeout,
+        log_path: stepLogPath
+      };
+
+      stepResults.push(stepState);
+
+      if (lastResult.timeout || lastResult.code !== 0) {
+        overall = 'fail';
+        break;
+      }
+    }
+
+    const coverage = await parseCoverage(profile.parsers?.coverage, worktreePath).catch(() => null);
+    const thresholds = this.thresholdPolicy.merge(policy, profile.thresholds);
+
+    let coverageStatus = 'na';
+    let coverageFailure: Record<string, unknown> | null = null;
+    if (coverage) {
+      if (coverage.line < thresholds.coverage_line_min || coverage.branch < thresholds.coverage_branch_min) {
+        coverageStatus = 'fail';
+        overall = 'fail';
+        coverageFailure = {
+          line: coverage.line,
+          branch: coverage.branch,
+          min_line: thresholds.coverage_line_min,
+          min_branch: thresholds.coverage_branch_min
+        };
+      } else {
+        coverageStatus = 'pass';
+      }
+    }
+
+    const evidence = {
+      feature_id: featureId,
+      mode,
+      profile: profileName,
+      overall,
+      coverage_status: coverageStatus,
+      coverage,
+      coverage_failure: coverageFailure,
+      thresholds,
+      step_results: stepResults,
+      finished_at: nowIso()
+    };
+
+    const evidencePath = path.join(evidenceDirectory, `gate-${mode}-${Date.now()}.json`);
+    await fs.writeFile(evidencePath, `${JSON.stringify(evidence, null, 2)}\n`, 'utf8');
+    const latestPath = path.join(evidenceDirectory, `latest-${mode}.json`);
+    await fs.writeFile(latestPath, `${JSON.stringify(evidence, null, 2)}\n`, 'utf8');
+
+    return {
+      overall,
+      step_results: stepResults,
+      coverage,
+      coverage_status: coverageStatus,
+      evidence_path: evidencePath,
+      latest_path: latestPath,
+      thresholds
+    };
+  }
+}
+
+const defaultCoverageParserRegistry = new CoverageParserRegistry([
+  new LcovCoverageParser(),
+  new JunitXmlCoverageParser(),
+  new JacocoXmlCoverageParser(),
+  new CoberturaXmlCoverageParser()
+]);
+const defaultGateExecutionService = new GateExecutionService(new CoverageThresholdPolicy());
+
+export async function runGateMode({
+  featureId,
+  mode,
+  profileName,
+  profile,
+  policy,
+  worktreePath,
+  logDirectory,
+  evidenceDirectory
+}: {
+  featureId: string;
+  mode: string;
+  profileName: string;
+  profile: GateProfile;
+  policy: PolicyShape;
+  worktreePath: string;
+  logDirectory: string;
+  evidenceDirectory: string;
+}): Promise<Record<string, unknown>> {
+  return await defaultGateExecutionService.runMode({
+    featureId,
+    mode,
+    profileName,
+    profile,
+    policy,
+    worktreePath,
+    logDirectory,
+    evidenceDirectory
+  });
+}

package/apps/control-plane/src/core/git.ts

@@ -0,0 +1,115 @@
+import { spawn } from 'node:child_process';
+
+export interface RunCommandOptions {
+  cwd?: string;
+  env?: NodeJS.ProcessEnv;
+  stdin?: string;
+  timeoutMs?: number;
+}
+
+export interface CommandResult {
+  code: number;
+  signal: NodeJS.Signals | null;
+  stdout: string;
+  stderr: string;
+  timeout: boolean;
+}
+
+export interface CommandRunner {
+  run(cmd: string, args: string[], options?: RunCommandOptions): Promise<CommandResult>;
+}
+
+export interface GitClient {
+  runGit(repoRoot: string, args: string[], options?: RunCommandOptions): Promise<CommandResult>;
+}
+
+export class NodeCommandRunner implements CommandRunner {
+  async run(cmd: string, args: string[], options: RunCommandOptions = {}): Promise<CommandResult> {
+    return await new Promise((resolve) => {
+      let child;
+      let spawnError: Error | null = null;
+
+      try {
+        child = spawn(cmd, args, {
+          cwd: options.cwd,
+          env: options.env,
+          stdio: ['pipe', 'pipe', 'pipe']
+        });
+      } catch (err) {
+        spawnError = err as Error;
+        return resolve({
+          code: 127,
+          signal: null,
+          stdout: '',
+          stderr: spawnError.message,
+          timeout: false
+        });
+      }
+
+      let stdout = '';
+      let stderr = '';
+      let killedByTimeout = false;
+
+      child.stdout.on('data', (chunk: Buffer) => {
+        stdout += chunk.toString();
+      });
+
+      child.stderr.on('data', (chunk: Buffer) => {
+        stderr += chunk.toString();
+      });
+
+      child.on('error', (err: Error) => {
+        stderr += err.message;
+      });
+
+      if (options.stdin) {
+        child.stdin.write(options.stdin);
+      }
+      child.stdin.end();
+
+      let timeoutHandle: NodeJS.Timeout | undefined;
+      if (options.timeoutMs) {
+        timeoutHandle = setTimeout(() => {
+          killedByTimeout = true;
+          child.kill('SIGKILL');
+        }, options.timeoutMs);
+      }
+
+      child.on('close', (code, signal) => {
+        if (timeoutHandle) {
+          clearTimeout(timeoutHandle);
+        }
+        resolve({
+          code: code ?? (killedByTimeout ? 124 : 1),
+          signal,
+          stdout,
+          stderr,
+          timeout: killedByTimeout
+        });
+      });
+    });
+  }
+}
+
+export class NodeGitClient implements GitClient {
+  private readonly commandRunner: CommandRunner;
+
+  constructor(commandRunner: CommandRunner) {
+    this.commandRunner = commandRunner;
+  }
+
+  async runGit(repoRoot: string, args: string[], options: RunCommandOptions = {}): Promise<CommandResult> {
+    return await this.commandRunner.run('git', args, { ...options, cwd: options.cwd ?? repoRoot });
+  }
+}
+
+export const commandRunner: CommandRunner = new NodeCommandRunner();
+export const gitClient: GitClient = new NodeGitClient(commandRunner);
+
+export function runCommand(cmd: string, args: string[], options: RunCommandOptions = {}): Promise<CommandResult> {
+  return commandRunner.run(cmd, args, options);
+}
+
+export async function runGit(repoRoot: string, args: string[], options: RunCommandOptions = {}): Promise<CommandResult> {
+  return await gitClient.runGit(repoRoot, args, options);
+}