pi-cicd 1.0.0

package/AGENTS.md

@@ -0,0 +1,25 @@
+# pi-ci Development Notes
+
+Pi extension for headless CI mode.
+
+## Rules
+
+- Keep `index.ts` minimal; re-export from `src/` modules.
+- Avoid `any`; use `unknown` plus validation.
+- After code changes, run `npm test` from `pi-ci/` unless explicitly told not to.
+
+## Important commands
+
+```bash
+npm test
+npm run typecheck
+```
+
+## Important paths
+
+- `index.ts` — extension entry point
+- `src/headless/` — core headless mode (exit codes, answers, idle, JSONL, orchestrator)
+- `src/ci/` — CI pipeline, PR creation, test runner, reports
+- `src/tools/` — /ci status command
+- `src/config.ts` — configuration loading
+- `test/unit/` — unit tests

package/index.ts

@@ -0,0 +1,52 @@
+/**
+ * pi-ci — Pi extension entry point.
+ *
+ * Registers the /ci status command and CI lifecycle hooks.
+ */
+
+import type { CIEvent, CIOptions, ExitCode } from "./src/types.ts";
+import { EXIT_CODES } from "./src/types.ts";
+import {
+  ciStatusHandler,
+  createRunTracker,
+  clearRuns,
+  registerRun,
+  type CIRunRecord,
+} from "./src/tools/ci_status.ts";
+import { CIPipeline, type PipelineResult } from "./src/ci/pipeline.ts";
+import { generateReport } from "./src/ci/report.ts";
+
+// Re-export for consumers
+export { EXIT_CODES } from "./src/types.ts";
+export { resolveExitCode } from "./src/headless/exit-codes.ts";
+export { loadAnswers, matchAnswer, parseAnswers } from "./src/headless/answer-injector.ts";
+export { IdleDetector } from "./src/headless/idle-detector.ts";
+export { CIEventCollector, writeCIEvent } from "./src/headless/jsonl-stream.ts";
+export { HeadlessOrchestrator } from "./src/headless/orchestrator.ts";
+export { CIPipeline } from "./src/ci/pipeline.ts";
+export { createPR, detectBaseBranch } from "./src/ci/pr-creator.ts";
+export { parseTestResults } from "./src/ci/test-runner.ts";
+export { generateReport } from "./src/ci/report.ts";
+export { ciStatusHandler, registerRun, clearRuns, createRunTracker } from "./src/tools/ci_status.ts";
+export { loadCiConfig, DEFAULT_CONFIG } from "./src/config.ts";
+export type { PiCiConfig } from "./src/config.ts";
+
+/**
+ * Extension API type (minimal — avoids hard dep on pi-coding-agent types).
+ */
+interface ExtensionAPI {
+  registerCommand?: (name: string, handler: (args: unknown) => string | Promise<string>) => void;
+  on?: (event: string, handler: (...args: unknown[]) => void) => void;
+}
+
+/**
+ * Default export — Pi extension registration.
+ */
+export default function piCiExtension(pi: ExtensionAPI): void {
+  // Register /ci status command
+  if (pi.registerCommand) {
+    pi.registerCommand("ci", (args: unknown) => {
+      return ciStatusHandler(args);
+    });
+  }
+}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "pi-cicd",
+  "version": "1.0.0",
+  "description": "Pi extension for headless CI mode with structured exit codes, answer injection, and pipeline automation",
+  "author": "baphuongna",
+  "license": "MIT",
+  "type": "module",
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-coding-agent",
+    "ci",
+    "headless",
+    "automation"
+  ],
+  "files": [
+    "*.ts",
+    "src/**/*.ts",
+    "README.md",
+    "AGENTS.md",
+    "tsconfig.json"
+  ],
+  "scripts": {
+    "check": "npm run typecheck && npm test",
+    "typecheck": "tsc --noEmit",
+    "test": "node --experimental-strip-types --test --test-concurrency=1 --test-timeout=30000 test/unit/*.test.ts"
+  },
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "peerDependencies": {
+    "@mariozechner/pi-coding-agent": "*"
+  },
+  "peerDependenciesMeta": {
+    "@mariozechner/pi-coding-agent": {
+      "optional": true
+    }
+  }
+}

package/src/ci/pipeline.ts

@@ -0,0 +1,130 @@
+/**
+ * pi-ci — CI pipeline wrapper.
+ *
+ * Provides single, plan, review, and supervised execution modes.
+ */
+
+import type { CIEvent, CIOptions, CIPipelineMode, ExitCode, TestSummary } from "../types.ts";
+import { EXIT_CODES } from "../types.ts";
+import { HeadlessOrchestrator, type OrchestratorHooks } from "../headless/orchestrator.ts";
+import { loadAnswers } from "../headless/answer-injector.ts";
+import { parseTestResults } from "./test-runner.ts";
+import { generateReport } from "./report.ts";
+
+export interface PipelineResult {
+  exitCode: ExitCode;
+  events: CIEvent[];
+  report: string;
+  testSummary?: TestSummary;
+}
+
+export class CIPipeline {
+  private readonly options: CIOptions;
+  private readonly hooks: OrchestratorHooks;
+
+  constructor(options: CIOptions, hooks: OrchestratorHooks) {
+    this.options = options;
+    this.hooks = hooks;
+  }
+
+  /**
+   * Execute the pipeline in the configured mode.
+   */
+  async execute(): Promise<PipelineResult> {
+    switch (this.options.mode) {
+      case "single":
+        return this.executeSingle();
+      case "plan":
+        return this.executePlan();
+      case "review":
+        return this.executeReview();
+      case "supervised":
+        return this.executeSupervised();
+      default:
+        throw new Error(`Unknown CI pipeline mode: ${this.options.mode as string}`);
+    }
+  }
+
+  /**
+   * Single task mode — run one prompt to completion.
+   */
+  private async executeSingle(): Promise<PipelineResult> {
+    const answers = await this.loadAnswers();
+    const orchestrator = new HeadlessOrchestrator(answers, this.options, this.hooks);
+    const result = await orchestrator.run(this.options.prompt, "single");
+
+    return {
+      exitCode: result.exitCode,
+      events: result.events,
+      report: generateReport(result.events),
+    };
+  }
+
+  /**
+   * Plan mode — execute steps from a plan file.
+   *
+   * Each step becomes a sequential orchestrator invocation. If any step fails,
+   * the pipeline stops.
+   */
+  private async executePlan(): Promise<PipelineResult> {
+    const allEvents: CIEvent[] = [];
+    let finalExitCode: ExitCode = EXIT_CODES.SUCCESS;
+    let totalDuration = 0;
+
+    // Plan steps are provided via the executeStep hook — the orchestrator
+    // iterates over steps internally.
+    const answers = await this.loadAnswers();
+    const orchestrator = new HeadlessOrchestrator(answers, this.options, this.hooks);
+    const result = await orchestrator.run(this.options.prompt, "plan");
+
+    allEvents.push(...result.events);
+    finalExitCode = result.exitCode;
+    totalDuration = result.durationMs;
+
+    return {
+      exitCode: finalExitCode,
+      events: allEvents,
+      report: generateReport(allEvents),
+    };
+  }
+
+  /**
+   * PR review mode — review a PR by number.
+   */
+  private async executeReview(): Promise<PipelineResult> {
+    const answers = await this.loadAnswers();
+    const orchestrator = new HeadlessOrchestrator(answers, this.options, this.hooks);
+    const prompt = this.options.prNumber
+      ? `Review PR #${this.options.prNumber}`
+      : this.options.prompt;
+    const result = await orchestrator.run(prompt, "single");
+
+    return {
+      exitCode: result.exitCode,
+      events: result.events,
+      report: generateReport(result.events),
+    };
+  }
+
+  /**
+   * Supervised mode — stdin/stdout forwarding for an external orchestrator.
+   */
+  private async executeSupervised(): Promise<PipelineResult> {
+    const answers = await this.loadAnswers();
+    const orchestrator = new HeadlessOrchestrator(answers, this.options, this.hooks);
+    const result = await orchestrator.run(this.options.prompt, "single");
+
+    return {
+      exitCode: result.exitCode,
+      events: result.events,
+      report: generateReport(result.events),
+    };
+  }
+
+  private async loadAnswers() {
+    if (this.options.answersFile) {
+      return loadAnswers(this.options.answersFile);
+    }
+    return [];
+  }
+}

package/src/ci/pr-creator.ts

@@ -0,0 +1,74 @@
+/**
+ * pi-ci — PR creation via the GitHub CLI (`gh`).
+ *
+ * Wraps `gh pr create` with structured error handling.
+ */
+
+import { execFile } from "node:child_process";
+import type { PROptions, PRResult } from "../types.ts";
+
+/**
+ * Create a pull request using the `gh` CLI.
+ *
+ * Throws if `gh` is not installed or the command fails.
+ */
+export async function createPR(options: PROptions): Promise<PRResult> {
+  const args = ["pr", "create", "--title", options.title];
+
+  if (options.body) {
+    args.push("--body", options.body);
+  }
+  if (options.base) {
+    args.push("--base", options.base);
+  }
+  if (options.head) {
+    args.push("--head", options.head);
+  }
+  if (options.draft) {
+    args.push("--draft");
+  }
+  for (const label of options.labels ?? []) {
+    args.push("--label", label);
+  }
+
+  const output = await runGh(args);
+
+  // Parse the PR URL from the output
+  const urlMatch = output.match(/https:\/\/github\.com\/[^\s]+\/pull\/(\d+)/);
+  if (!urlMatch) {
+    throw new Error(`Failed to parse PR URL from gh output: ${output}`);
+  }
+
+  return {
+    url: urlMatch[0],
+    number: parseInt(urlMatch[1], 10),
+  };
+}
+
+/**
+ * Detect the default (base) branch for the current repository.
+ */
+export async function detectBaseBranch(): Promise<string> {
+  const output = await runGh(["repo", "view", "--json", "defaultBranchRef", "--jq", ".defaultBranchRef.name"]);
+  return output.trim() || "main";
+}
+
+/**
+ * Execute a `gh` command and return stdout.
+ */
+function runGh(args: string[]): Promise<string> {
+  return new Promise((resolve, reject) => {
+    execFile("gh", args, { timeout: 60_000 }, (err, stdout, stderr) => {
+      if (err) {
+        const message = stderr?.trim() || err.message;
+        if (err.code === "ENOENT") {
+          reject(new Error("gh CLI is not installed. Install it from https://cli.github.com"));
+        } else {
+          reject(new Error(`gh ${args.join(" ")} failed: ${message}`));
+        }
+        return;
+      }
+      resolve(stdout);
+    });
+  });
+}

package/src/ci/report.ts

@@ -0,0 +1,65 @@
+/**
+ * pi-ci — CI report generation.
+ *
+ * Produces JSONL or human-readable summary reports from collected CI events.
+ */
+
+import type { CIEvent, CIEndEvent, CICostEvent, CITestEvent } from "../types.ts";
+import { isCIEndEvent, isCICostEvent, isCITestEvent } from "../headless/jsonl-stream.ts";
+
+export interface ReportOptions {
+  format: "jsonl" | "summary";
+}
+
+/**
+ * Generate a report from a list of CI events.
+ */
+export function generateReport(events: CIEvent[], options?: ReportOptions): string {
+  const format = options?.format ?? "jsonl";
+
+  if (format === "summary") {
+    return generateSummary(events);
+  }
+
+  // JSONL: one event per line
+  return events.map((e) => JSON.stringify(e)).join("\n");
+}
+
+/**
+ * Generate a human-readable summary.
+ */
+function generateSummary(events: CIEvent[]): string {
+  const lines: string[] = ["=== CI Run Summary ===", ""];
+
+  let totalTestsPassed = 0;
+  let totalTestsFailed = 0;
+  let totalCostUsd = 0;
+  let exitCode = -1;
+  let durationMs = 0;
+
+  for (const event of events) {
+    if (isCITestEvent(event)) {
+      totalTestsPassed += event.passed;
+      totalTestsFailed += event.failed;
+    }
+    if (isCICostEvent(event)) {
+      totalCostUsd += event.cost_usd;
+    }
+    if (isCIEndEvent(event)) {
+      exitCode = event.exit_code;
+      durationMs = event.duration_ms;
+    }
+  }
+
+  lines.push(`Exit Code: ${exitCode}`);
+  lines.push(`Duration:  ${(durationMs / 1000).toFixed(1)}s`);
+  lines.push(`Tests:     ${totalTestsPassed} passed, ${totalTestsFailed} failed`);
+  if (totalCostUsd > 0) {
+    lines.push(`Cost:      $${totalCostUsd.toFixed(4)}`);
+  }
+
+  const status = exitCode === 0 ? "SUCCESS" : exitCode === 10 ? "BLOCKED" : exitCode === 11 ? "CANCELLED" : "ERROR";
+  lines.push(`Status:    ${status}`);
+
+  return lines.join("\n");
+}

package/src/ci/test-runner.ts

@@ -0,0 +1,129 @@
+/**
+ * pi-ci — Test result parsing for TAP, Jest, and Vitest output formats.
+ */
+
+import type { TestSummary } from "../types.ts";
+
+export type TestOutputFormat = "tap" | "jest" | "vitest";
+
+/**
+ * Parse test output and return a summary.
+ */
+export function parseTestResults(output: string, format: TestOutputFormat): TestSummary {
+  if (!output || !output.trim()) {
+    return { passed: 0, failed: 0, total: 0, duration_ms: 0 };
+  }
+
+  switch (format) {
+    case "tap":
+      return parseTap(output);
+    case "jest":
+      return parseJest(output);
+    case "vitest":
+      return parseVitest(output);
+    default:
+      return { passed: 0, failed: 0, total: 0, duration_ms: 0 };
+  }
+}
+
+/**
+ * Parse TAP (Test Anything Protocol) output.
+ *
+ * Example:
+ *   1..5
+ *   ok 1 - first test
+ *   not ok 2 - failing test
+ *   ok 3 - third test
+ */
+function parseTap(output: string): TestSummary {
+  let passed = 0;
+  let failed = 0;
+
+  const lines = output.split("\n");
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (trimmed.startsWith("ok ")) {
+      passed++;
+    } else if (trimmed.startsWith("not ok ")) {
+      failed++;
+    }
+  }
+
+  return {
+    passed,
+    failed,
+    total: passed + failed,
+    duration_ms: 0, // TAP doesn't have standard duration
+  };
+}
+
+/**
+ * Parse Jest-style test output.
+ *
+ * Looks for patterns like:
+ *   Tests:       5 passed, 2 failed, 7 total
+ *   Time:        3.456 s
+ */
+function parseJest(output: string): TestSummary {
+  let passed = 0;
+  let failed = 0;
+  let total = 0;
+  let durationMs = 0;
+
+  // Match test summary line
+  const testMatch = output.match(
+    /Tests:\s*(\d+)\s*passed(?:,\s*(\d+)\s*failed)?(?:,\s*(\d+)\s*total)?/,
+  );
+  if (testMatch) {
+    passed = parseInt(testMatch[1], 10);
+    failed = parseInt(testMatch[2] || "0", 10);
+    total = parseInt(testMatch[3] || String(passed + failed), 10);
+  } else {
+    // Fallback: count individual test lines
+    const passMatches = output.match(/✓|PASS/g);
+    const failMatches = output.match(/✕|FAIL/g);
+    passed = passMatches?.length ?? 0;
+    failed = failMatches?.length ?? 0;
+    total = passed + failed;
+  }
+
+  // Match time
+  const timeMatch = output.match(/Time:\s*([\d.]+)\s*s/);
+  if (timeMatch) {
+    durationMs = Math.round(parseFloat(timeMatch[1]) * 1000);
+  }
+
+  return { passed, failed, total, duration_ms: durationMs };
+}
+
+/**
+ * Parse Vitest-style test output.
+ *
+ * Looks for patterns like:
+ *   Tests  5 passed | 2 failed (7)
+ *   Duration  3.45s
+ */
+function parseVitest(output: string): TestSummary {
+  let passed = 0;
+  let failed = 0;
+  let total = 0;
+  let durationMs = 0;
+
+  // Match test summary line: "Tests  5 passed | 2 failed (7)"
+  const testMatch = output.match(
+    /Tests\s+(\d+)\s+passed(?:\s*\|\s*(\d+)\s+failed)?(?:\s*\((\d+)\))?/,
+  );
+  if (testMatch) {
+    passed = parseInt(testMatch[1], 10);
+    failed = parseInt(testMatch[2] || "0", 10);
+    total = parseInt(testMatch[3] || String(passed + failed), 10);
+  }
+
+  // Match duration: "Duration  3.45s"
+  const durMatch = output.match(/Duration\s+([\d.]+)s/);
+  if (durMatch) {
+    durationMs = Math.round(parseFloat(durMatch[1]) * 1000);
+  }
+
+  return { passed, failed, total, duration_ms: durationMs };
+}

package/src/config.ts

@@ -0,0 +1,99 @@
+/**
+ * pi-ci — Configuration loading and defaults.
+ *
+ * Reads `.pi/pi-ci.json` from the given directory (or cwd) and merges with defaults.
+ */
+
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+
+export interface PiCiReportConfig {
+  format: "jsonl" | "summary";
+  includeCost: boolean;
+  includeEdits: boolean;
+  includeTests: boolean;
+}
+
+export interface PiCiExitCodeConfig {
+  success: number;
+  error: number;
+  blocked: number;
+  cancelled: number;
+  needsInput: number;
+}
+
+export interface PiCiConfig {
+  enabled: boolean;
+  idleTimeoutMs: number;
+  maxRetries: number;
+  retryBackoffMaxMs: number;
+  exitCodes: PiCiExitCodeConfig;
+  report: PiCiReportConfig;
+}
+
+const DEFAULT_CONFIG: PiCiConfig = {
+  enabled: true,
+  idleTimeoutMs: 15_000,
+  maxRetries: 3,
+  retryBackoffMaxMs: 30_000,
+  exitCodes: {
+    success: 0,
+    error: 1,
+    blocked: 10,
+    cancelled: 11,
+    needsInput: 12,
+  },
+  report: {
+    format: "jsonl",
+    includeCost: true,
+    includeEdits: true,
+    includeTests: true,
+  },
+};
+
+/**
+ * Load pi-ci configuration from `.pi/pi-ci.json` (if present) merged with defaults.
+ */
+export async function loadCiConfig(cwd?: string): Promise<PiCiConfig> {
+  const dir = cwd ?? process.cwd();
+  const configPath = join(dir, ".pi", "pi-ci.json");
+
+  let text: string;
+  try {
+    text = await readFile(configPath, "utf-8");
+  } catch {
+    return { ...DEFAULT_CONFIG };
+  }
+
+  const raw: unknown = JSON.parse(text);
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+    return { ...DEFAULT_CONFIG };
+  }
+
+  const user = raw as Record<string, unknown>;
+  return {
+    enabled: typeof user.enabled === "boolean" ? user.enabled : DEFAULT_CONFIG.enabled,
+    idleTimeoutMs:
+      typeof user.idleTimeoutMs === "number" ? user.idleTimeoutMs : DEFAULT_CONFIG.idleTimeoutMs,
+    maxRetries:
+      typeof user.maxRetries === "number" ? user.maxRetries : DEFAULT_CONFIG.maxRetries,
+    retryBackoffMaxMs:
+      typeof user.retryBackoffMaxMs === "number"
+        ? user.retryBackoffMaxMs
+        : DEFAULT_CONFIG.retryBackoffMaxMs,
+    exitCodes: {
+      ...DEFAULT_CONFIG.exitCodes,
+      ...(typeof user.exitCodes === "object" && user.exitCodes !== null
+        ? (user.exitCodes as Partial<PiCiExitCodeConfig>)
+        : {}),
+    },
+    report: {
+      ...DEFAULT_CONFIG.report,
+      ...(typeof user.report === "object" && user.report !== null
+        ? (user.report as Partial<PiCiReportConfig>)
+        : {}),
+    },
+  };
+}
+
+export { DEFAULT_CONFIG };