aiwcli 0.11.1 → 0.12.1

package/dist/templates/cc-native/_cc-native/lib-ts/reviewers/agent.ts

@@ -1,21 +1,16 @@
 /**
  * Agent-based plan reviewer with multi-provider support.
- * Routes to Claude or Codex CLI based on agent.provider field.
+ * Routes to provider-specific implementations (Claude, Codex, Gemini).
  * See cc-native-plan-review-spec.md §4.10
  */
 
-import * as fs from "node:fs";
-import * as os from "node:os";
-import * as path from "node:path";
-import { logDebug, logInfo, logWarn, logError } from "../../../_shared/lib-ts/base/logger.js";
-import { getInternalSubprocessEnv, findExecutable, execFileAsync } from "../../../_shared/lib-ts/base/subprocess-utils.js";
-import { parseCliOutput } from "../cli-output-parser.js";
-import { parseJsonMaybe, coerceToReview } from "../json-parser.js";
-import { debugLog, debugRaw } from "../debug.js";
+import { logWarn } from "../../../_shared/lib-ts/base/logger.js";
 import type { AgentConfig, ReviewerResult, ReviewOptions } from "../types.js";
-import { AGENT_REVIEW_PROMPT_PREFIX } from "../types.js";
-import { makeResult } from "./types.js";
+import { ClaudeAgent } from "./providers/claude-agent.js";
+import { CodexAgent } from "./providers/codex-agent.js";
+import { GeminiAgent } from "./providers/gemini-agent.js";
 import type { Reviewer } from "./types.js";
+import { makeResult } from "./types.js";
 
 /**
  * Agent reviewer — runs a CLI instance with a custom persona.
@@ -52,224 +47,28 @@ export async function runAgentReview(
   contextPath?: string,
   sessionName = "unknown",
 ): Promise<ReviewerResult> {
-  if (agent.provider === "codex") {
-    return runAgentReviewCodex(plan, agent, schema, timeout, contextPath, sessionName);
-  }
-  // Default: Claude (existing implementation)
-  return runAgentReviewClaude(plan, agent, schema, timeout, contextPath, sessionName);
-}
-
-/**
- * Run a single Claude Code agent to review the plan.
- */
-async function runAgentReviewClaude(
-  plan: string,
-  agent: AgentConfig,
-  schema: Record<string, unknown>,
-  timeout: number,
-  contextPath?: string,
-  sessionName = "unknown",
-): Promise<ReviewerResult> {
-  const claudePath = findExecutable("claude");
-  if (!claudePath) {
-    logWarn(agent.name, "Claude CLI not found on PATH");
-    return makeResult(agent.name, false, "skip", {}, "", "claude CLI not found on PATH");
-  }
-
-  logDebug(agent.name, `Found Claude CLI at: ${claudePath}`);
-
-  const prompt = `IMMEDIATELY call StructuredOutput with your review of the plan below.
-Do NOT output any text before calling StructuredOutput.
-
-PLAN:
-<<<
-${plan}
->>>
-`;
-
-  const schemaJson = JSON.stringify(schema);
-  const cmdArgs = [
-    "--model", agent.model,
-    "--output-format", "json",
-    "--json-schema", schemaJson,
-    "--max-turns", "3",
-    "--setting-sources", "",
-    "-p",
-  ];
-
-  if (agent.system_prompt) {
-    const fullPrompt = AGENT_REVIEW_PROMPT_PREFIX + "\n\n---\n\n" + agent.system_prompt;
-    cmdArgs.push("--system-prompt", fullPrompt);
-  }
-
-  logInfo(agent.name, `Running Claude with model: ${agent.model}, timeout: ${timeout}s`);
-
-  const env = getInternalSubprocessEnv();
-
-  const result = await execFileAsync(claudePath, cmdArgs, {
-    input: prompt,
-    timeout: timeout * 1000,
-    env: env as Record<string, string>,
-    maxBuffer: 10 * 1024 * 1024,
-    shell: process.platform === "win32",
-  });
-
-  if (result.killed || result.signal === "SIGTERM") {
-    logWarn(agent.name, `Claude TIMEOUT after ${timeout}s`);
-    return makeResult(agent.name, false, "error", {}, "", `${agent.name} timed out after ${timeout}s`);
-  }
-
-  const raw = result.stdout.trim();
-  const err = result.stderr.trim();
-
-  if (!raw && !err && result.exitCode !== 0) {
-    logError(agent.name, `Process exited with code ${result.exitCode} and no output`);
-    return makeResult(agent.name, false, "error", {}, "", `${agent.name} failed to run (exit ${result.exitCode})`);
-  }
-
-  logDebug(agent.name, `Exit code: ${result.exitCode}`);
-  logDebug(agent.name, `stdout length: ${raw.length} chars`);
-  if (err) logDebug(agent.name, `stderr: ${err.slice(0, 500)}`);
-
-  // Debug logging
-  if (contextPath) {
-    debugRaw(contextPath, sessionName, `agent:${agent.name}`, "stdout", raw);
-    if (err) {
-      debugRaw(contextPath, sessionName, `agent:${agent.name}`, "stderr", err);
-    }
-    debugLog(contextPath, sessionName, `agent:${agent.name}`, "subprocess_info", {
-      exit_code: result.exitCode,
-      stdout_len: raw.length,
-      stderr_len: err.length,
-      model: agent.model,
-      provider: "claude",
-      timeout,
-    });
-  }
-
-  if (raw) logDebug(agent.name, `stdout preview: ${raw.slice(0, 500)}`);
-
-  const obj = parseCliOutput(raw, ["verdict", "summary"]);
-
-  if (contextPath) {
-    debugLog(contextPath, sessionName, `agent:${agent.name}`, "parsed_result", {
-      parsed_keys: obj ? Object.keys(obj) : null,
-      verdict: obj?.verdict ?? null,
-      has_summary: obj ? Boolean(obj.summary) : false,
-      issues_count: obj && Array.isArray(obj.issues) ? (obj.issues as unknown[]).length : 0,
-    });
-  }
-
-  if (obj) {
-    logInfo(agent.name, `Parsed JSON successfully, verdict: ${obj.verdict ?? "N/A"}`);
-  } else {
-    logWarn(agent.name, "Failed to parse JSON from output");
-  }
-
-  const [ok, verdict, norm] = coerceToReview(
-    obj as Record<string, unknown> | null,
-    "Retry or check agent configuration.",
-  );
-
-  return makeResult(agent.name, ok, verdict, norm, raw, err);
-}
-
-/**
- * Run a single Codex CLI agent to review the plan.
- * Adapts the codex.ts reviewer pattern for agent-based review with persona.
- */
-async function runAgentReviewCodex(
-  plan: string,
-  agent: AgentConfig,
-  schema: Record<string, unknown>,
-  timeout: number,
-  contextPath?: string,
-  sessionName = "unknown",
-): Promise<ReviewerResult> {
-  const codexPath = findExecutable("codex");
-  if (!codexPath) {
-    logWarn(agent.name, "Codex CLI not found on PATH, skipping");
-    return makeResult(agent.name, false, "skip", {}, "", "codex CLI not found on PATH");
-  }
-
-  // Codex has no --system-prompt flag, so we prepend the agent persona to stdin.
-  const fullPrompt = [
-    AGENT_REVIEW_PROMPT_PREFIX,
-    "---",
-    agent.system_prompt || "",
-    "---",
-    `Return ONLY a JSON object matching this schema:\n${JSON.stringify(schema)}`,
-    "",
-    "PLAN:",
-    "<<<",
-    plan,
-    ">>>",
-  ].join("\n\n");
-
-  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), `codex-agent-${agent.name}-`));
-
   try {
-    const schemaPath = path.join(tmpDir, "schema.json");
-    const outPath = path.join(tmpDir, "output.json");
-    fs.writeFileSync(schemaPath, JSON.stringify(schema, null, 2), "utf-8");
-
-    const cmdArgs = ["exec", "--sandbox", "read-only"];
-    if (agent.model) cmdArgs.push("--model", agent.model);
-    cmdArgs.push("--output-schema", schemaPath, "-o", outPath, "-");
-
-    logInfo(agent.name, `Running Codex with model: ${agent.model}, timeout: ${timeout}s`);
-
-    const result = await execFileAsync(codexPath, cmdArgs, {
-      input: fullPrompt,
-      timeout: timeout * 1000,
-      maxBuffer: 10 * 1024 * 1024,
-      shell: process.platform === "win32",
-    });
-
-    if (result.killed || result.signal === "SIGTERM") {
-      logWarn(agent.name, `Codex TIMEOUT after ${timeout}s`);
-      return makeResult(agent.name, false, "error", {}, "", `${agent.name} (codex) timed out after ${timeout}s`);
+    let reviewer;
+
+    switch (agent.provider) {
+      case "codex": {
+        reviewer = new CodexAgent(agent, schema, timeout, contextPath, sessionName);
+        break;
+      }
+      case "gemini": {
+        reviewer = new GeminiAgent(agent, schema, timeout, contextPath, sessionName);
+        break;
+      }
+      case "claude":
+      default: {
+        reviewer = new ClaudeAgent(agent, schema, timeout, contextPath, sessionName);
+        break;
+      }
     }
 
-    if (!result.stdout && !result.stderr && !fs.existsSync(outPath) && result.exitCode !== 0) {
-      logError(agent.name, `Codex exited with code ${result.exitCode} and no output`);
-      return makeResult(agent.name, false, "error", {}, "", `${agent.name} (codex) failed (exit ${result.exitCode})`);
-    }
-
-    // Read output: prefer temp file, fallback to stdout
-    let raw = "";
-    if (fs.existsSync(outPath)) {
-      raw = fs.readFileSync(outPath, "utf-8");
-    }
-    const err = result.stderr.trim();
-
-    // Debug logging
-    if (contextPath) {
-      debugRaw(contextPath, sessionName, `agent:${agent.name}`, "stdout", raw || result.stdout);
-      if (err) debugRaw(contextPath, sessionName, `agent:${agent.name}`, "stderr", err);
-      debugLog(contextPath, sessionName, `agent:${agent.name}`, "subprocess_info", {
-        exit_code: result.exitCode,
-        stdout_len: (raw || result.stdout).length,
-        stderr_len: err.length,
-        model: agent.model,
-        provider: "codex",
-        timeout,
-      });
-    }
-
-    // Parse output
-    const obj = parseJsonMaybe(raw) ?? parseJsonMaybe(result.stdout);
-    const [ok, verdict, norm] = coerceToReview(
-      obj,
-      "Retry or check Codex CLI auth/config.",
-    );
-
-    return makeResult(agent.name, ok, verdict, norm, raw || result.stdout, err);
-  } finally {
-    try {
-      fs.rmSync(tmpDir, { recursive: true, force: true });
-    } catch (e) {
-      logDebug(agent.name, `Failed to cleanup temp dir ${tmpDir}: ${e}`);
-    }
+    return await reviewer.review(plan);
+  } catch (error) {
+    logWarn(agent.name, `Unexpected error creating reviewer: ${error}`);
+    return makeResult(agent.name, false, "error", {}, "", `Failed: ${error}`);
   }
 }

package/dist/templates/cc-native/_cc-native/lib-ts/reviewers/base/base-agent.ts

@@ -0,0 +1,217 @@
+/**
+ * Abstract base class for CLI-based agent reviewers.
+ * Implements template method pattern for subprocess execution flow.
+ * Provider-specific implementations (Claude, Codex, Gemini) extend this class.
+ */
+
+import { logDebug, logInfo, logWarn, logError } from "../../../../_shared/lib-ts/base/logger.js";
+import { getInternalSubprocessEnv, findExecutable, execFileAsync } from "../../../../_shared/lib-ts/base/subprocess-utils.js";
+import { debugLog, debugRaw } from "../../debug.js";
+import type { AgentConfig } from "../../types.js";
+
+/** Result from execFileAsync */
+export interface ExecResult {
+  stdout: string;
+  stderr: string;
+  exitCode: number | null;
+  signal: string | null;
+  killed: boolean;
+}
+
+/**
+ * Abstract base class for all CLI agent subprocess invocations.
+ * Parameterized over return type T — ReviewerResult for reviewers,
+ * OrchestratorResult for the orchestrator.
+ * Subclasses implement provider-specific details.
+ */
+export abstract class BaseCliAgent<T> {
+  protected agent: AgentConfig;
+  protected contextPath?: string;
+  protected schema: Record<string, unknown>;
+  protected sessionName: string;
+  protected timeout: number;
+
+  constructor(
+    agent: AgentConfig,
+    schema: Record<string, unknown>,
+    timeout: number,
+    contextPath?: string,
+    sessionName = "unknown",
+  ) {
+    this.agent = agent;
+    this.schema = schema;
+    this.timeout = timeout;
+    this.contextPath = contextPath;
+    this.sessionName = sessionName;
+  }
+
+  /** Build the command-line arguments for the CLI */
+  protected abstract buildCliArgs(): string[];
+
+  // ─── Abstract Methods (Subclass Implements) ────────────────────────────
+
+  /** Build the stdin prompt for the CLI */
+  protected abstract buildPrompt(plan: string): string;
+
+  /** Optional cleanup after subprocess execution */
+  protected async cleanup(): Promise<void> {
+    // Default: no-op. Subclasses override if needed (e.g., Codex temp files).
+  }
+
+  /** Coerce parsed JSON into the result type T */
+  protected abstract coerceResult(obj: Record<string, unknown> | null, raw: string, err: string): T;
+
+  /** Extract stdout/stderr from subprocess result. Override for file-based output (Codex). */
+  protected extractOutput(result: ExecResult): { raw: string; err: string } {
+    return {
+      raw: result.stdout.trim(),
+      err: result.stderr.trim(),
+    };
+  }
+
+  /** Find the CLI executable. Override for custom search logic. */
+  protected findCli(): string | null {
+    return findExecutable(this.getCliName());
+  }
+
+  // ─── Template Methods (Subclass Can Override) ──────────────────────────
+
+  /** Get the CLI executable name (e.g., "claude", "codex") */
+  protected abstract getCliName(): string;
+
+  /** Get default error message for coerceToReview */
+  protected getDefaultErrorMessage(): string {
+    return `Retry or check ${this.getCliName()} configuration.`;
+  }
+
+  /** Handle non-zero exit with no output */
+  protected handleExitError(result: ExecResult): T {
+    const msg = `${this.agent.name} failed to run (exit ${result.exitCode})`;
+    logError(this.agent.name, `Process exited with code ${result.exitCode} and no output`);
+    return this.makeErrorResult("error", msg);
+  }
+
+  /** Handle timeout scenario */
+  protected handleTimeout(): T {
+    const msg = `${this.getCliName()} TIMEOUT after ${this.timeout}s`;
+    logWarn(this.agent.name, msg);
+    return this.makeErrorResult("error", `${this.agent.name} timed out after ${this.timeout}s`);
+  }
+
+  // ─── Shared Infrastructure ──────────────────────────────────────────────
+
+  /** Log parsed JSON result */
+  protected logParsedResult(obj: Record<string, unknown> | null): void {
+    if (this.contextPath && obj) {
+      debugLog(this.contextPath, this.sessionName, `agent:${this.agent.name}`, "parsed_result", {
+        parsed_keys: Object.keys(obj),
+        verdict: obj.verdict ?? null,
+        has_summary: Boolean(obj.summary),
+        issues_count: Array.isArray(obj.issues) ? (obj.issues as unknown[]).length : 0,
+      });
+    }
+
+    if (obj) {
+      logInfo(this.agent.name, `Parsed JSON successfully, verdict: ${obj.verdict ?? "N/A"}`);
+    } else {
+      logWarn(this.agent.name, "Failed to parse JSON from output");
+    }
+  }
+
+  /** Log subprocess execution results */
+  protected logSubprocessResult(result: ExecResult, raw: string, err: string): void {
+    logDebug(this.agent.name, `Exit code: ${result.exitCode}`);
+    logDebug(this.agent.name, `stdout length: ${raw.length} chars`);
+    if (err) logDebug(this.agent.name, `stderr: ${err.slice(0, 500)}`);
+
+    // Debug logging
+    if (this.contextPath) {
+      debugRaw(this.contextPath, this.sessionName, `agent:${this.agent.name}`, "stdout", raw);
+      if (err) {
+        debugRaw(this.contextPath, this.sessionName, `agent:${this.agent.name}`, "stderr", err);
+      }
+      debugLog(this.contextPath, this.sessionName, `agent:${this.agent.name}`, "subprocess_info", {
+        exit_code: result.exitCode,
+        stdout_len: raw.length,
+        stderr_len: err.length,
+        model: this.agent.model,
+        provider: this.agent.provider,
+        timeout: this.timeout,
+      });
+    }
+
+    if (raw) logDebug(this.agent.name, `stdout preview: ${raw.slice(0, 500)}`);
+  }
+
+  /** Construct a T for error/skip/timeout scenarios. Subclasses define shape. */
+  protected abstract makeErrorResult(type: "skip" | "error", message: string): T;
+
+  /** Create skip result when CLI not found */
+  protected makeSkipResult(reason: string): T {
+    logWarn(this.agent.name, reason);
+    return this.makeErrorResult("skip", reason);
+  }
+
+  /** Parse JSON from CLI output */
+  protected abstract parseOutput(raw: string, result: ExecResult): Record<string, unknown> | null;
+
+  /**
+   * Template method - orchestrates the review flow.
+   * Subclasses override abstract methods to customize behavior.
+   */
+  async review(plan: string): Promise<T> {
+    // 1. Find CLI executable
+    const cliPath = this.findCli();
+    if (!cliPath) {
+      return this.makeSkipResult(`${this.getCliName()} CLI not found on PATH`);
+    }
+
+    logDebug(this.agent.name, `Found ${this.getCliName()} CLI at: ${cliPath}`);
+
+    // 2. Build prompt and args (provider-specific)
+    const prompt = this.buildPrompt(plan);
+    const args = this.buildCliArgs();
+
+    logInfo(this.agent.name, `Running ${this.getCliName()} with model: ${this.agent.model}, timeout: ${this.timeout}s`);
+
+    // 3. Execute subprocess
+    const env = getInternalSubprocessEnv();
+    const result = await execFileAsync(cliPath, args, {
+      input: prompt,
+      timeout: this.timeout * 1000,
+      env: env as Record<string, string>,
+      maxBuffer: 10 * 1024 * 1024,
+      shell: process.platform === "win32",
+    });
+
+    // 4. Handle timeout
+    if (result.killed || result.signal === "SIGTERM") {
+      return this.handleTimeout();
+    }
+
+    // 5. Extract output (provider-specific)
+    const { raw, err } = this.extractOutput(result);
+
+    // 6. Handle exit errors
+    if (!raw && !err && result.exitCode !== 0) {
+      return this.handleExitError(result);
+    }
+
+    // 7. Log subprocess results
+    this.logSubprocessResult(result, raw, err);
+
+    // 8. Parse JSON output (provider-specific)
+    const obj = this.parseOutput(raw, result);
+
+    // 9. Log parsed result
+    this.logParsedResult(obj);
+
+    // 10. Coerce to result type T (provider-specific)
+    const coerced = this.coerceResult(obj, raw, err);
+
+    // 11. Cleanup (optional override)
+    await this.cleanup();
+
+    return coerced;
+  }
+}

package/dist/templates/cc-native/_cc-native/lib-ts/reviewers/index.ts

@@ -4,7 +4,9 @@
  */
 
 export { AgentReviewer, runAgentReview } from "./agent.js";
-export { CodexReviewer, runCodexReview } from "./codex.js";
-export { GeminiReviewer, runGeminiReview } from "./gemini.js";
+export { BaseCliAgent } from "./base/base-agent.js";
+export { ClaudeAgent } from "./providers/claude-agent.js";
+export { CodexAgent } from "./providers/codex-agent.js";
+export { GeminiAgent } from "./providers/gemini-agent.js";
 export type { Reviewer, ReviewerResult, ReviewOptions } from "./types.js";
 export { makeResult } from "./types.js";

package/dist/templates/cc-native/_cc-native/lib-ts/reviewers/providers/claude-agent.ts

@@ -0,0 +1,65 @@
+/**
+ * Claude CLI agent reviewer implementation.
+ * Uses claude CLI with --json-schema and --system-prompt flags.
+ */
+
+import { shellQuoteWin } from "../../../../_shared/lib-ts/base/subprocess-utils.js";
+import { parseCliOutput } from "../../cli-output-parser.js";
+import { coerceToReview } from "../../json-parser.js";
+import type { ReviewerResult } from "../../types.js";
+import { BaseCliAgent } from "../base/base-agent.js";
+import { AGENT_REVIEW_PROMPT_PREFIX } from "../schemas.js";
+import { makeResult } from "../types.js";
+
+/**
+ * Claude CLI-based agent reviewer.
+ * Extends BaseCliAgent with Claude-specific prompt and argument handling.
+ */
+export class ClaudeAgent extends BaseCliAgent<ReviewerResult> {
+  protected buildCliArgs(): string[] {
+    const schemaJson = JSON.stringify(this.schema);
+    const cmdArgs = [
+      "--model", this.agent.model,
+      "--output-format", "json",
+      "--json-schema", shellQuoteWin(schemaJson),
+      "--max-turns", "3",
+      "--setting-sources", process.platform === "win32" ? '""' : "",
+      "-p",
+    ];
+
+    if (this.agent.system_prompt) {
+      const fullPrompt = AGENT_REVIEW_PROMPT_PREFIX + "\n\n---\n\n" + this.agent.system_prompt;
+      cmdArgs.push("--system-prompt", shellQuoteWin(fullPrompt));
+    }
+
+    return cmdArgs;
+  }
+
+  protected buildPrompt(plan: string): string {
+    return `IMMEDIATELY call StructuredOutput with your review of the plan below.
+Do NOT output any text before calling StructuredOutput.
+
+PLAN:
+<<<
+${plan}
+>>>
+`;
+  }
+
+  protected coerceResult(obj: Record<string, unknown> | null, raw: string, err: string): ReviewerResult {
+    const [ok, verdict, norm] = coerceToReview(obj, this.getDefaultErrorMessage());
+    return makeResult(this.agent.name, ok, verdict, norm, raw, err);
+  }
+
+  protected getCliName(): string {
+    return "claude";
+  }
+
+  protected makeErrorResult(type: "skip" | "error", message: string): ReviewerResult {
+    return makeResult(this.agent.name, false, type, {}, "", message);
+  }
+
+  protected parseOutput(raw: string, _result: unknown): Record<string, unknown> | null {
+    return parseCliOutput(raw, ["verdict", "summary"]);
+  }
+}