pi-cicd 1.0.0

package/src/headless/answer-injector.ts

@@ -0,0 +1,98 @@
+/**
+ * pi-ci — Answer injection from a JSON file.
+ *
+ * When Pi encounters an interactive prompt in CI mode, it consults an
+ * answers file for a pre-supplied response.
+ */
+
+import type { AnswerEntry, AnswerFile } from "../types.ts";
+
+/**
+ * Read and validate an answers JSON file.
+ *
+ * - Returns an empty array if the file cannot be read.
+ * - Skips entries that are missing `match` or `answer` fields.
+ * - Throws on invalid JSON.
+ */
+export async function loadAnswers(filePath: string): Promise<AnswerEntry[]> {
+  let text: string;
+  try {
+    text = await Bun.file(filePath).text();
+  } catch {
+    return [];
+  }
+
+  const raw: unknown = JSON.parse(text);
+
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+    throw new Error(`Answers file must contain a JSON object with an "answers" array`);
+  }
+
+  const obj = raw as Record<string, unknown>;
+  if (!Array.isArray(obj.answers)) {
+    throw new Error(`Answers file must contain an "answers" array`);
+  }
+
+  const entries: AnswerEntry[] = [];
+  for (const item of obj.answers) {
+    if (
+      typeof item === "object" &&
+      item !== null &&
+      typeof (item as Record<string, unknown>).match === "string" &&
+      typeof (item as Record<string, unknown>).answer === "string"
+    ) {
+      entries.push(item as AnswerEntry);
+    }
+    // Silently skip malformed entries
+  }
+
+  return entries;
+}
+
+/**
+ * Synchronous variant that reads from a string (useful for testing).
+ */
+export function parseAnswers(jsonText: string): AnswerEntry[] {
+  const raw: unknown = JSON.parse(jsonText);
+
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+    throw new Error(`Answers file must contain a JSON object with an "answers" array`);
+  }
+
+  const obj = raw as Record<string, unknown>;
+  if (!Array.isArray(obj.answers)) {
+    throw new Error(`Answers file must contain an "answers" array`);
+  }
+
+  const entries: AnswerEntry[] = [];
+  for (const item of obj.answers) {
+    if (
+      typeof item === "object" &&
+      item !== null &&
+      typeof (item as Record<string, unknown>).match === "string" &&
+      typeof (item as Record<string, unknown>).answer === "string"
+    ) {
+      entries.push(item as AnswerEntry);
+    }
+  }
+
+  return entries;
+}
+
+/**
+ * Find a matching answer for the given prompt using substring matching.
+ *
+ * Returns the first answer whose `match` is found as a substring of `prompt`,
+ * or `undefined` if no match is found.
+ */
+export function matchAnswer(
+  entries: AnswerEntry[],
+  prompt: string,
+): string | undefined {
+  for (const entry of entries) {
+    if (prompt.includes(entry.match)) {
+      return entry.answer;
+    }
+  }
+  return undefined;
+}

package/src/headless/exit-codes.ts

@@ -0,0 +1,32 @@
+/**
+ * pi-ci — Exit code resolution helpers.
+ */
+
+import { EXIT_CODES, type ExitCode } from "../types.ts";
+
+/**
+ * Map a symbolic status string to a numeric exit code.
+ *
+ * Unknown / unexpected statuses resolve to ERROR (1).
+ */
+export function resolveExitCode(status: string): ExitCode {
+  switch (status) {
+    case "success":
+      return EXIT_CODES.SUCCESS;
+    case "error":
+    case "timeout":
+      return EXIT_CODES.ERROR;
+    case "blocked":
+      return EXIT_CODES.BLOCKED;
+    case "cancelled":
+      return EXIT_CODES.CANCELLED;
+    case "needs_input":
+    case "needs-input":
+      return EXIT_CODES.NEEDS_INPUT;
+    default:
+      return EXIT_CODES.ERROR;
+  }
+}
+
+export { EXIT_CODES };
+export type { ExitCode };

package/src/headless/idle-detector.ts

@@ -0,0 +1,76 @@
+/**
+ * pi-ci — Idle timeout detection.
+ *
+ * If no activity is detected within the configured timeout, the callback fires.
+ */
+
+export interface IdleDetectorOptions {
+  /** Timeout in milliseconds. Default: 15 000. */
+  idleTimeoutMs?: number;
+  /** Called when the idle timeout is reached. */
+  onTimeout: () => void;
+}
+
+const DEFAULT_IDLE_TIMEOUT_MS = 15_000;
+
+export class IdleDetector {
+  private readonly idleTimeoutMs: number;
+  private readonly onTimeout: () => void;
+  private timer: ReturnType<typeof setTimeout> | null = null;
+  private _running = false;
+  private _fired = false;
+
+  constructor(options: IdleDetectorOptions) {
+    this.idleTimeoutMs = options.idleTimeoutMs ?? DEFAULT_IDLE_TIMEOUT_MS;
+    this.onTimeout = options.onTimeout;
+  }
+
+  /** Whether the detector is currently running. */
+  get running(): boolean {
+    return this._running;
+  }
+
+  /** Whether the timeout has already fired. */
+  get fired(): boolean {
+    return this._fired;
+  }
+
+  /** Start the idle timer. Safe to call multiple times (no-op if already running). */
+  start(): void {
+    if (this._running) return;
+    this._running = true;
+    this._fired = false;
+    this.scheduleTimer();
+  }
+
+  /** Reset the idle timer. If not running, this is a no-op. */
+  reset(): void {
+    if (!this._running) return;
+    this.clearTimer();
+    this.scheduleTimer();
+  }
+
+  /** Stop the idle timer. */
+  stop(): void {
+    this._running = false;
+    this._fired = false;
+    this.clearTimer();
+  }
+
+  private scheduleTimer(): void {
+    this.timer = setTimeout(() => {
+      if (this._running) {
+        this._running = false;
+        this._fired = true;
+        this.onTimeout();
+      }
+    }, this.idleTimeoutMs);
+  }
+
+  private clearTimer(): void {
+    if (this.timer !== null) {
+      clearTimeout(this.timer);
+      this.timer = null;
+    }
+  }
+}

package/src/headless/jsonl-stream.ts

@@ -0,0 +1,90 @@
+/**
+ * pi-ci — JSONL event stream utilities.
+ *
+ * Writes CI events as single-line JSON to a writable stream and provides
+ * type-guard helpers for event discrimination.
+ */
+
+import type { Writable } from "node:stream";
+import type {
+  CIEvent,
+  CIStartEvent,
+  CIProgressEvent,
+  CIEditEvent,
+  CITestEvent,
+  CICostEvent,
+  CIEndEvent,
+} from "../types.ts";
+
+// ---------------------------------------------------------------------------
+// Write helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Ensure an event has a timestamp, injecting `now` if missing.
+ */
+function ensureTimestamp<T extends CIEvent>(event: T): T & { timestamp: string } {
+  if (!event.timestamp) {
+    return { ...event, timestamp: new Date().toISOString() };
+  }
+  return event as T & { timestamp: string };
+}
+
+/**
+ * Serialise a CI event and write it as a single JSONL line to the stream.
+ */
+export function writeCIEvent(stream: Writable, event: CIEvent): void {
+  const stamped = ensureTimestamp(event);
+  stream.write(JSON.stringify(stamped) + "\n");
+}
+
+// ---------------------------------------------------------------------------
+// Event emitter (collects events for reporting)
+// ---------------------------------------------------------------------------
+
+export class CIEventCollector {
+  private readonly events: CIEvent[] = [];
+
+  /** Record an event. Auto-fills timestamp if missing. */
+  emit(event: CIEvent): void {
+    this.events.push(ensureTimestamp(event));
+  }
+
+  /** Return all collected events in order. */
+  all(): CIEvent[] {
+    return [...this.events];
+  }
+
+  /** Reset the collector. */
+  clear(): void {
+    this.events.length = 0;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Type guards
+// ---------------------------------------------------------------------------
+
+export function isCIStartEvent(e: CIEvent): e is CIStartEvent {
+  return e.type === "ci_start";
+}
+
+export function isCIProgressEvent(e: CIEvent): e is CIProgressEvent {
+  return e.type === "ci_progress";
+}
+
+export function isCIEditEvent(e: CIEvent): e is CIEditEvent {
+  return e.type === "ci_edit";
+}
+
+export function isCITestEvent(e: CIEvent): e is CITestEvent {
+  return e.type === "ci_test";
+}
+
+export function isCICostEvent(e: CIEvent): e is CICostEvent {
+  return e.type === "ci_cost";
+}
+
+export function isCIEndEvent(e: CIEvent): e is CIEndEvent {
+  return e.type === "ci_end";
+}

package/src/headless/orchestrator.ts

@@ -0,0 +1,206 @@
+/**
+ * pi-ci — Headless orchestrator.
+ *
+ * Ties together exit codes, answer injection, idle detection, and JSONL
+ * streaming into a single execution loop.
+ */
+
+import type { ExitCode, CIEvent, CIOptions } from "../types.ts";
+import { EXIT_CODES } from "../types.ts";
+import { resolveExitCode } from "./exit-codes.ts";
+import { matchAnswer, type AnswerEntry } from "./answer-injector.ts";
+import { IdleDetector } from "./idle-detector.ts";
+import { CIEventCollector, writeCIEvent } from "./jsonl-stream.ts";
+import type { Writable } from "node:stream";
+
+export interface OrchestratorResult {
+  exitCode: ExitCode;
+  events: CIEvent[];
+  durationMs: number;
+}
+
+export interface OrchestratorHooks {
+  /** Called for each step of execution. Return a status string to signal completion. */
+  executeStep: (
+    prompt: string,
+    injectAnswer: (question: string) => string | undefined,
+  ) => Promise<StepResult>;
+  /** Optional writable for JSONL streaming. */
+  outputStream?: Writable;
+}
+
+export interface StepResult {
+  status: string;
+  edits?: { file: string; lines_added: number; lines_removed: number }[];
+  tests?: { command: string; passed: number; failed: number }[];
+  cost?: { tokens: { input: number; output: number }; cost_usd: number };
+}
+
+const RESTART_CONFIG = {
+  baseDelayMs: 5_000,
+  maxDelayMs: 30_000,
+  backoffMultiplier: 2,
+};
+
+export class HeadlessOrchestrator {
+  private readonly collector = new CIEventCollector();
+  private readonly answers: AnswerEntry[];
+  private readonly idleTimeoutMs: number;
+  private readonly maxRetries: number;
+  private readonly hooks: OrchestratorHooks;
+
+  constructor(
+    answers: AnswerEntry[],
+    options: CIOptions,
+    hooks: OrchestratorHooks,
+  ) {
+    this.answers = answers;
+    this.idleTimeoutMs = options.idleTimeoutMs ?? 15_000;
+    this.maxRetries = options.maxRetries ?? 3;
+    this.hooks = hooks;
+  }
+
+  /**
+   * Run the orchestrator loop.
+   *
+   * 1. Emit ci_start
+   * 2. Execute steps via the hook, checking for answer injection
+   * 3. On idle timeout → retry with exponential backoff
+   * 4. Emit ci_end with the resolved exit code
+   */
+  async run(prompt: string, mode: "single" | "plan"): Promise<OrchestratorResult> {
+    const startTime = Date.now();
+
+    const startEvent: CIEvent = {
+      type: "ci_start",
+      timestamp: new Date().toISOString(),
+      task: prompt,
+      mode,
+    };
+    this.emit(startEvent);
+
+    let lastExitCode: ExitCode = EXIT_CODES.ERROR;
+    let retries = 0;
+
+    while (retries <= this.maxRetries) {
+      const result = await this.runAttempt(prompt);
+      lastExitCode = result;
+
+      if (lastExitCode === EXIT_CODES.SUCCESS) break;
+      if (lastExitCode === EXIT_CODES.BLOCKED || lastExitCode === EXIT_CODES.CANCELLED) break;
+
+      // Retry on error/timeout
+      retries++;
+      if (retries <= this.maxRetries) {
+        const delay = Math.min(
+          RESTART_CONFIG.baseDelayMs *
+            Math.pow(RESTART_CONFIG.backoffMultiplier, retries - 1),
+          RESTART_CONFIG.maxDelayMs,
+        );
+        await sleep(delay);
+      }
+    }
+
+    const durationMs = Date.now() - startTime;
+    const endEvent: CIEvent = {
+      type: "ci_end",
+      timestamp: new Date().toISOString(),
+      exit_code: lastExitCode,
+      duration_ms: durationMs,
+    };
+    this.emit(endEvent);
+
+    return {
+      exitCode: lastExitCode,
+      events: this.collector.all(),
+      durationMs,
+    };
+  }
+
+  /**
+   * Single attempt: run with idle detection.
+   */
+  private async runAttempt(prompt: string): Promise<ExitCode> {
+    return new Promise<ExitCode>((resolve) => {
+      let settled = false;
+
+      const idle = new IdleDetector({
+        idleTimeoutMs: this.idleTimeoutMs,
+        onTimeout: () => {
+          if (!settled) {
+            settled = true;
+            resolve(EXIT_CODES.TIMEOUT);
+          }
+        },
+      });
+
+      const injectAnswer = (question: string): string | undefined => {
+        idle.reset();
+        return matchAnswer(this.answers, question);
+      };
+
+      idle.start();
+
+      this.hooks
+        .executeStep(prompt, injectAnswer)
+        .then((stepResult) => {
+          if (!settled) {
+            settled = true;
+            idle.stop();
+
+            // Emit detail events
+            if (stepResult.edits) {
+              for (const edit of stepResult.edits) {
+                this.emit({
+                  type: "ci_edit",
+                  timestamp: new Date().toISOString(),
+                  file: edit.file,
+                  lines_added: edit.lines_added,
+                  lines_removed: edit.lines_removed,
+                });
+              }
+            }
+            if (stepResult.tests) {
+              for (const t of stepResult.tests) {
+                this.emit({
+                  type: "ci_test",
+                  timestamp: new Date().toISOString(),
+                  command: t.command,
+                  passed: t.passed,
+                  failed: t.failed,
+                });
+              }
+            }
+            if (stepResult.cost) {
+              this.emit({
+                type: "ci_cost",
+                timestamp: new Date().toISOString(),
+                tokens: stepResult.cost.tokens,
+                cost_usd: stepResult.cost.cost_usd,
+              });
+            }
+
+            resolve(resolveExitCode(stepResult.status));
+          }
+        })
+        .catch(() => {
+          if (!settled) {
+            settled = true;
+            idle.stop();
+            resolve(EXIT_CODES.ERROR);
+          }
+        });
+    });
+  }
+
+  private emit(event: CIEvent): void {
+    this.collector.emit(event);
+    if (this.hooks.outputStream) {
+      writeCIEvent(this.hooks.outputStream, event);
+    }
+  }
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((r) => setTimeout(r, ms));
+}

package/src/tools/ci_status.ts

@@ -0,0 +1,137 @@
+/**
+ * pi-ci — /ci status command handler.
+ *
+ * Shows the status of the current or last CI run.
+ */
+
+import { CIEventCollector } from "../headless/jsonl-stream.ts";
+import { generateReport } from "../ci/report.ts";
+import type { CIEvent, CIEndEvent, ExitCode } from "../types.ts";
+import { isCIEndEvent } from "../headless/jsonl-stream.ts";
+
+export interface CIRunRecord {
+  id: string;
+  startTime: string;
+  events: CIEvent[];
+  exitCode?: ExitCode;
+  durationMs?: number;
+}
+
+/**
+ * Simple in-memory registry of CI runs (for the status command).
+ */
+const runRegistry = new Map<string, CIRunRecord>();
+
+/**
+ * Register a CI run for status lookups.
+ */
+export function registerRun(record: CIRunRecord): void {
+  runRegistry.set(record.id, record);
+}
+
+/**
+ * Clear all registered runs (useful for testing).
+ */
+export function clearRuns(): void {
+  runRegistry.clear();
+}
+
+/**
+ * Get a specific run by ID (prefix match supported).
+ */
+export function getRun(id: string): CIRunRecord | undefined {
+  // Exact match first
+  if (runRegistry.has(id)) {
+    return runRegistry.get(id);
+  }
+  // Prefix match
+  for (const [key, value] of runRegistry) {
+    if (key.startsWith(id)) {
+      return value;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Handle the /ci status command.
+ *
+ * Returns a human-readable status string.
+ */
+export function ciStatusHandler(args: unknown): string {
+  const runId = typeof args === "string" ? args : undefined;
+
+  if (runId) {
+    const run = getRun(runId);
+    if (!run) {
+      return `No CI run found matching: ${runId}`;
+    }
+    return formatRunStatus(run);
+  }
+
+  // Show all runs
+  if (runRegistry.size === 0) {
+    return "No CI runs found.";
+  }
+
+  const lines: string[] = [];
+  for (const run of runRegistry.values()) {
+    lines.push(formatRunStatus(run));
+    lines.push("");
+  }
+  return lines.join("\n").trimEnd();
+}
+
+function formatRunStatus(run: CIRunRecord): string {
+  const lines: string[] = [];
+  lines.push(`Run:       ${run.id}`);
+  lines.push(`Started:   ${run.startTime}`);
+
+  const endEvent = run.events.find((e): e is CIEndEvent => isCIEndEvent(e));
+  if (endEvent) {
+    lines.push(`Exit Code: ${endEvent.exit_code}`);
+    lines.push(`Duration:  ${(endEvent.duration_ms / 1000).toFixed(1)}s`);
+
+    const status =
+      endEvent.exit_code === 0
+        ? "SUCCESS"
+        : endEvent.exit_code === 10
+          ? "BLOCKED"
+          : endEvent.exit_code === 11
+            ? "CANCELLED"
+            : "ERROR";
+    lines.push(`Status:    ${status}`);
+  } else {
+    lines.push("Status:    RUNNING");
+  }
+
+  return lines.join("\n");
+}
+
+/**
+ * Create a CI run tracker that collects events and registers the run.
+ */
+export function createRunTracker(runId: string): {
+  collector: CIEventCollector;
+  finalize: () => CIRunRecord;
+} {
+  const collector = new CIEventCollector();
+  const startTime = new Date().toISOString();
+
+  return {
+    collector,
+    finalize() {
+      const events = collector.all();
+      const endEvent = events.find((e): e is CIEndEvent => isCIEndEvent(e));
+      const record: CIRunRecord = {
+        id: runId,
+        startTime,
+        events,
+        exitCode: endEvent?.exit_code,
+        durationMs: endEvent?.duration_ms,
+      };
+      registerRun(record);
+      return record;
+    },
+  };
+}