create-interview-cockpit 0.17.3 → 0.19.0

package/template/server/src/gha-runner.ts

@@ -0,0 +1,793 @@
+import fs from "fs/promises";
+import path from "path";
+import { randomUUID } from "crypto";
+import { spawn } from "child_process";
+import * as storage from "./storage.js";
+
+// ─── Types ───────────────────────────────────────────────────────────────
+
+interface GithubActionsLabWorkspace {
+  version: 1;
+  label: string;
+  activeFile: string;
+  files: Record<string, string>;
+  defaultEvent?: string;
+  defaultWorkflow?: string;
+}
+
+type OutputKind = "stdout" | "stderr" | "info";
+
+// Status a job can be in across the lifecycle of one act run.
+// `pending`   — declared in the workflow YAML but not yet started
+// `running`   — act has emitted its first line for this job
+// `success`   — act printed "Job succeeded" (or run finished cleanly while job was running)
+// `failed`    — act printed "Job failed" (or run finished non-zero while job was running)
+// `skipped`   — act printed a skip line
+export type GhaJobStatus =
+  | "pending"
+  | "running"
+  | "success"
+  | "failed"
+  | "skipped";
+
+export interface GhaStepSnapshot {
+  // Step name as printed by act (e.g. "Checkout repo").
+  name: string;
+  // "Main" for normal steps, "Pre"/"Post" for action lifecycle hooks.
+  phase: "Main" | "Pre" | "Post";
+  status: GhaJobStatus;
+  startedAt?: string;
+  endedAt?: string;
+  durationMs?: number;
+  // Captured raw lines that appeared between this step's start and its
+  // terminal marker. Capped per-step so a runaway step can't bloat the
+  // metadata file.
+  log?: string;
+}
+
+export interface GhaJobSnapshot {
+  // Job key as `act` prints it inside the [workflow/job] prefix.
+  // For matrix jobs this includes the matrix instance suffix.
+  name: string;
+  // Workflow display name from the prefix (left of the slash).
+  workflow?: string;
+  status: GhaJobStatus;
+  startedAt?: string;
+  endedAt?: string;
+  durationMs?: number;
+  // Per-step lifecycle parsed from act's `⭐ Run` / `✅ Success` markers.
+  steps?: GhaStepSnapshot[];
+}
+
+export type GhaStreamMessage =
+  | { type: "output"; kind: OutputKind; text: string }
+  | { type: "job"; job: GhaJobSnapshot }
+  | { type: "complete"; runId: string; exitCode: number; durationMs: number }
+  | { type: "error"; error: string };
+
+// ─── Constants & guards ──────────────────────────────────────────────────
+
+const MAX_FILE_COUNT = 60;
+const MAX_TOTAL_SOURCE_BYTES = 1_000_000;
+const MAX_LOG_CHARS = 400_000;
+const SOURCE_MANIFEST = ".gha-source-files.json";
+
+// `act` accepts these events; we restrict to common ones so the console
+// can't be used to run arbitrary subcommands.
+const ALLOWED_EVENTS = new Set([
+  "push",
+  "pull_request",
+  "workflow_dispatch",
+  "release",
+  "schedule",
+  "issues",
+  "issue_comment",
+]);
+
+// Only these top-level `act` flags are honored from console input.
+// Long-form is preferred to keep parsing simple.
+const ALLOWED_ACT_FLAGS = new Set([
+  "-l",
+  "--list",
+  "-n",
+  "--dryrun",
+  "-W",
+  "--workflows",
+  "-j",
+  "--job",
+  "-e",
+  "--eventpath",
+  "--container-architecture",
+  "-P",
+  "--platform",
+  "--rm",
+  "--verbose",
+  "-v",
+]);
+
+// ─── Utilities ───────────────────────────────────────────────────────────
+
+function getGhaRunsDir(): string {
+  return path.resolve(storage.getContextFilesDir(), "..", "gha-runs");
+}
+
+function getGhaSessionsDir(): string {
+  return path.resolve(storage.getContextFilesDir(), "..", "gha-sessions");
+}
+
+function stripAnsi(text: string): string {
+  return text.replace(/\x1b\[[0-9;]*[A-Za-z]/g, "");
+}
+
+function appendLog(buffer: string, chunk: string): string {
+  if (!chunk || buffer.length >= MAX_LOG_CHARS) return buffer;
+  const remaining = MAX_LOG_CHARS - buffer.length;
+  if (chunk.length <= remaining) return buffer + chunk;
+  return `${buffer}${chunk.slice(0, remaining)}\n[log truncated]\n`;
+}
+
+function sanitizeKey(value: string): string {
+  return value.replace(/[^a-zA-Z0-9_-]/g, "-").slice(0, 120) || "session";
+}
+
+function assertSafeRelativePath(filePath: string, label: string): void {
+  if (!filePath || path.isAbsolute(filePath) || filePath.includes("..")) {
+    throw new Error(`${label} must stay within the workspace`);
+  }
+  // Reject any path that escapes via symlink-style tricks
+  if (filePath.startsWith("/") || /^[a-zA-Z]:[\\/]/.test(filePath)) {
+    throw new Error(`${label} must be a relative path`);
+  }
+}
+
+function parseWorkspace(input: unknown): GithubActionsLabWorkspace {
+  if (!input || typeof input !== "object") {
+    throw new Error("workspace payload is required");
+  }
+  const candidate = input as Partial<GithubActionsLabWorkspace> & {
+    files?: Record<string, unknown>;
+  };
+  if (!candidate.files || typeof candidate.files !== "object") {
+    throw new Error("workspace.files must be provided");
+  }
+  const files = Object.fromEntries(
+    Object.entries(candidate.files)
+      .filter(
+        (entry): entry is [string, string] =>
+          typeof entry[0] === "string" && typeof entry[1] === "string",
+      )
+      .map(([name, content]) => [name.trim(), content]),
+  );
+  const fileNames = Object.keys(files).filter(Boolean);
+  if (fileNames.length === 0) {
+    throw new Error("workspace must contain at least one file");
+  }
+  if (fileNames.length > MAX_FILE_COUNT) {
+    throw new Error(`workspace exceeds the ${MAX_FILE_COUNT} file limit`);
+  }
+  let totalBytes = 0;
+  for (const name of fileNames) {
+    assertSafeRelativePath(name, "Workspace file path");
+    totalBytes += Buffer.byteLength(files[name], "utf8");
+  }
+  if (totalBytes > MAX_TOTAL_SOURCE_BYTES) {
+    throw new Error("workspace source exceeds the allowed size limit");
+  }
+  return {
+    version: 1,
+    label:
+      typeof candidate.label === "string" && candidate.label.trim()
+        ? candidate.label.trim()
+        : "GitHub Actions Lab",
+    activeFile:
+      typeof candidate.activeFile === "string" && files[candidate.activeFile]
+        ? candidate.activeFile
+        : fileNames[0],
+    defaultEvent:
+      typeof candidate.defaultEvent === "string"
+        ? candidate.defaultEvent
+        : undefined,
+    defaultWorkflow:
+      typeof candidate.defaultWorkflow === "string"
+        ? candidate.defaultWorkflow
+        : undefined,
+    files,
+  };
+}
+
+// ─── File materialization ───────────────────────────────────────────────
+
+async function writeWorkspaceFiles(
+  workspaceDir: string,
+  workspace: GithubActionsLabWorkspace,
+): Promise<void> {
+  await fs.mkdir(workspaceDir, { recursive: true });
+  await Promise.all(
+    Object.entries(workspace.files).map(async ([name, content]) => {
+      const target = path.join(workspaceDir, name);
+      const targetDir = path.dirname(target);
+      const rel = path.relative(workspaceDir, target);
+      // Defense in depth: make sure the resolved target stays under workspaceDir.
+      if (rel.startsWith("..") || path.isAbsolute(rel)) {
+        throw new Error(`Refusing to write file outside workspace: ${name}`);
+      }
+      await fs.mkdir(targetDir, { recursive: true });
+      await fs.writeFile(target, content, "utf8");
+    }),
+  );
+}
+
+async function readJsonFile(filePath: string): Promise<unknown | undefined> {
+  try {
+    const raw = await fs.readFile(filePath, "utf8");
+    return JSON.parse(raw);
+  } catch {
+    return undefined;
+  }
+}
+
+async function syncWorkspaceToSession(
+  sessionKey: string,
+  workspace: GithubActionsLabWorkspace,
+): Promise<string> {
+  const sessionDir = path.join(getGhaSessionsDir(), sanitizeKey(sessionKey));
+  const workspaceDir = path.join(sessionDir, "workspace");
+  const manifestPath = path.join(sessionDir, SOURCE_MANIFEST);
+  await fs.mkdir(sessionDir, { recursive: true });
+
+  const previous = await readJsonFile(manifestPath);
+  const previousFiles = Array.isArray(previous)
+    ? previous.filter((item): item is string => typeof item === "string")
+    : [];
+  const nextFiles = Object.keys(workspace.files);
+
+  await Promise.all(
+    previousFiles
+      .filter((fileName) => !nextFiles.includes(fileName))
+      .map(async (fileName) => {
+        try {
+          await fs.unlink(path.join(workspaceDir, fileName));
+        } catch {
+          // ignore
+        }
+      }),
+  );
+  await writeWorkspaceFiles(workspaceDir, workspace);
+  await fs.writeFile(manifestPath, JSON.stringify(nextFiles, null, 2), "utf8");
+  return workspaceDir;
+}
+
+// ─── Command parsing ────────────────────────────────────────────────────
+
+function splitCommand(command: string): string[] {
+  const tokens: string[] = [];
+  let current = "";
+  let quote: '"' | "'" | null = null;
+  let escape = false;
+  for (const char of command.trim()) {
+    if (escape) {
+      current += char;
+      escape = false;
+      continue;
+    }
+    if (char === "\\") {
+      escape = true;
+      continue;
+    }
+    if (quote) {
+      if (char === quote) quote = null;
+      else current += char;
+      continue;
+    }
+    if (char === '"' || char === "'") {
+      quote = char;
+      continue;
+    }
+    if (/\s/.test(char)) {
+      if (current) {
+        tokens.push(current);
+        current = "";
+      }
+      continue;
+    }
+    current += char;
+  }
+  if (quote) throw new Error("Command has an unclosed quote");
+  if (current) tokens.push(current);
+  return tokens;
+}
+
+interface ParsedActCommand {
+  event: string | null; // null when -l is used (just listing)
+  args: string[];
+  displayCommand: string;
+}
+
+function parseActCommand(command: string): ParsedActCommand {
+  const tokens = splitCommand(command);
+  if (tokens.length === 0) throw new Error("Type a command to run");
+  if (tokens[0] !== "act") {
+    throw new Error(
+      "Only 'act' commands are supported in this lab. Try: act -l, act push, act workflow_dispatch -j greet, act -n",
+    );
+  }
+
+  const rest = tokens.slice(1);
+  let event: string | null = null;
+  const args: string[] = [];
+  let i = 0;
+
+  // First non-flag token is treated as the event name (matching real act CLI).
+  while (i < rest.length) {
+    const tok = rest[i];
+    if (!tok.startsWith("-")) {
+      if (event !== null) {
+        throw new Error(`Unexpected positional argument: ${tok}`);
+      }
+      if (!ALLOWED_EVENTS.has(tok)) {
+        throw new Error(
+          `Event '${tok}' is not allowed. Allowed: ${Array.from(ALLOWED_EVENTS).join(", ")}`,
+        );
+      }
+      event = tok;
+      args.push(tok);
+      i += 1;
+      continue;
+    }
+
+    // Flag handling — only the allow-listed flags are accepted.
+    // Support `--flag=value`, `--flag value`, and short flags.
+    const eq = tok.indexOf("=");
+    const flagName = eq === -1 ? tok : tok.slice(0, eq);
+    if (!ALLOWED_ACT_FLAGS.has(flagName)) {
+      throw new Error(`Flag '${flagName}' is not allowed in the act console`);
+    }
+    args.push(tok);
+
+    // Flags that take a value
+    const takesValue = new Set([
+      "-W",
+      "--workflows",
+      "-j",
+      "--job",
+      "-e",
+      "--eventpath",
+      "--container-architecture",
+      "-P",
+      "--platform",
+    ]);
+    if (takesValue.has(flagName) && eq === -1) {
+      const next = rest[i + 1];
+      if (!next || next.startsWith("-")) {
+        throw new Error(`Flag '${flagName}' requires a value`);
+      }
+      // For workflow/eventpath, keep it inside workspace
+      if (flagName === "-W" || flagName === "--workflows") {
+        assertSafeRelativePath(next, "workflow path");
+      }
+      if (flagName === "-e" || flagName === "--eventpath") {
+        assertSafeRelativePath(next, "event path");
+      }
+      args.push(next);
+      i += 2;
+      continue;
+    }
+    i += 1;
+  }
+
+  return {
+    event,
+    args,
+    displayCommand: `$ act ${args.join(" ")}\n`.replace(/\s+\n$/, "\n"),
+  };
+}
+
+// ─── Run ─────────────────────────────────────────────────────────────────
+
+interface RunInput {
+  questionId?: string;
+  fileId?: string;
+  label?: string;
+  command: string;
+  workspace: unknown;
+  onMessage?: (message: GhaStreamMessage) => void;
+}
+
+export interface GhaRunMetadata {
+  id: string;
+  fileId?: string;
+  questionId?: string;
+  label: string;
+  command: string;
+  status: "completed" | "failed";
+  startedAt: string;
+  completedAt: string;
+  durationMs: number;
+  exitCode: number;
+  error?: string;
+  // Parsed live from act's stdout; lets the UI render a job DAG with
+  // pending/running/success/failed boxes instead of just raw text.
+  jobs?: GhaJobSnapshot[];
+  // Captured for the History tab so users can group runs by workflow.
+  event?: string;
+  workflow?: string;
+}
+
+// ─── act output → job snapshot parser ───────────────────────────────────
+//
+// act prints every line for a given job with a `[<workflow>/<job>]` prefix,
+// e.g.:
+//   [CI/greet      ] 🚀  Start  image=catthehacker/ubuntu:act-latest
+//   [CI/greet      ]   ✅  Success - Set up job
+//   [CI/greet      ] 🏁  Job succeeded
+//   [CI/build-1    ] 🏁  Job failed
+// We watch for the first line per job (→ running), and the "Job succeeded /
+// Job failed / Job skipped" markers. Anything still running when act exits
+// is finalised based on the process exit code.
+const JOB_PREFIX_RE = /^\[([^\]/]+)\/([^\]]+)\]\s*(.*)$/;
+// act prints `⭐ Run Main <step name>` to mark a step boundary. The emoji is
+// optional in some act versions / when colour is stripped, so the regex
+// tolerates either form.
+const STEP_START_RE = /(?:⭐\s*)?Run\s+(Main|Pre|Post)\s+(.+?)\s*$/;
+// And one of these for the terminal marker:
+//   ✅  Success - Main <name>
+//   ❌  Failure - Main <name>
+//   ⏭  Skipped - Main <name>   (also ⚠)
+const STEP_END_RE =
+  /(?:[✅❌⏭⚠]\s*)?(Success|Failure|Skipped)\s*-\s*(Main|Pre|Post)\s+(.+?)\s*$/;
+const MAX_STEP_LOG_CHARS = 8_000;
+
+class JobTracker {
+  private readonly jobs = new Map<string, GhaJobSnapshot>();
+  private leftover = "";
+
+  constructor(private readonly onUpdate: (job: GhaJobSnapshot) => void) {}
+
+  feed(text: string): void {
+    const combined = this.leftover + text;
+    const lines = combined.split(/\r?\n/);
+    this.leftover = lines.pop() ?? "";
+    for (const line of lines) this.processLine(line);
+  }
+
+  flush(): void {
+    if (this.leftover) {
+      this.processLine(this.leftover);
+      this.leftover = "";
+    }
+  }
+
+  finalize(exitCode: number): void {
+    const fallback: GhaJobStatus = exitCode === 0 ? "success" : "failed";
+    const endedAt = new Date().toISOString();
+    for (const job of this.jobs.values()) {
+      // Close any still-open step first so the UI doesn't show a stuck
+      // "running" spinner inside a finished job.
+      if (job.steps) {
+        for (const step of job.steps) {
+          if (step.status === "running") {
+            step.status = fallback;
+            step.endedAt = endedAt;
+            if (step.startedAt) {
+              step.durationMs =
+                new Date(endedAt).getTime() -
+                new Date(step.startedAt).getTime();
+            }
+          }
+        }
+      }
+      if (job.status === "running") {
+        job.status = fallback;
+        job.endedAt = endedAt;
+        if (job.startedAt) {
+          job.durationMs =
+            new Date(endedAt).getTime() - new Date(job.startedAt).getTime();
+        }
+        this.onUpdate({ ...job });
+      }
+    }
+  }
+
+  snapshot(): GhaJobSnapshot[] {
+    return Array.from(this.jobs.values()).map((job) => ({
+      ...job,
+      steps: job.steps?.map((s) => ({ ...s })),
+    }));
+  }
+
+  private processLine(line: string): void {
+    const match = JOB_PREFIX_RE.exec(line);
+    if (!match) return;
+    const workflow = match[1].trim();
+    const jobName = match[2].trim();
+    const rest = match[3] ?? "";
+    if (!jobName) return;
+
+    const existing = this.jobs.get(jobName);
+    const now = new Date().toISOString();
+    const job: GhaJobSnapshot = existing
+      ? { ...existing, steps: existing.steps ? [...existing.steps] : [] }
+      : {
+          name: jobName,
+          workflow,
+          status: "running",
+          startedAt: now,
+          steps: [],
+        };
+
+    let touched = !existing; // first sighting always counts as an update
+
+    // ── Step boundaries ──
+    const stepStart = STEP_START_RE.exec(rest);
+    const stepEnd = STEP_END_RE.exec(rest);
+    if (stepEnd) {
+      const phase = stepEnd[2] as "Main" | "Pre" | "Post";
+      const name = stepEnd[3];
+      const status: GhaJobStatus =
+        stepEnd[1] === "Success"
+          ? "success"
+          : stepEnd[1] === "Failure"
+            ? "failed"
+            : "skipped";
+      const step =
+        job.steps?.find((s) => s.phase === phase && s.name === name) ?? null;
+      if (step) {
+        step.status = status;
+        step.endedAt = now;
+        if (step.startedAt) {
+          step.durationMs =
+            new Date(now).getTime() - new Date(step.startedAt).getTime();
+        }
+      } else {
+        // End without a matching start (act sometimes elides start lines
+        // for fast steps). Synthesize a zero-duration entry so the UI
+        // still shows the step.
+        job.steps?.push({ name, phase, status, endedAt: now });
+      }
+      touched = true;
+    } else if (stepStart) {
+      const phase = stepStart[1] as "Main" | "Pre" | "Post";
+      const name = stepStart[2];
+      // De-dupe: if a previous run already opened this same step, just
+      // restart it (matrix jobs share the parser instance per name).
+      const existingStep = job.steps?.find(
+        (s) => s.phase === phase && s.name === name && s.status === "running",
+      );
+      if (!existingStep) {
+        job.steps?.push({
+          name,
+          phase,
+          status: "running",
+          startedAt: now,
+          log: "",
+        });
+      }
+      touched = true;
+    } else if (job.steps && job.steps.length) {
+      // Non-marker content → belongs to the currently running step (if any),
+      // so the user can drill into the per-step log just like GitHub.
+      const current = [...job.steps]
+        .reverse()
+        .find((s) => s.status === "running");
+      if (current && rest.trim()) {
+        const stripped = rest.replace(/^[|\s]+/, "");
+        const next = `${current.log ?? ""}${stripped}\n`;
+        current.log =
+          next.length > MAX_STEP_LOG_CHARS
+            ? next.slice(0, MAX_STEP_LOG_CHARS) + "\n[step log truncated]\n"
+            : next;
+      }
+    }
+
+    // ── Job terminal markers — act always prints these once per job. ──
+    if (/Job succeeded\b/i.test(rest)) {
+      job.status = "success";
+      job.endedAt = now;
+      touched = true;
+    } else if (/Job failed\b/i.test(rest)) {
+      job.status = "failed";
+      job.endedAt = now;
+      touched = true;
+    } else if (/Job skipped\b/i.test(rest)) {
+      job.status = "skipped";
+      job.endedAt = now;
+      touched = true;
+    } else if (!existing) {
+      job.status = "running";
+    }
+
+    if (job.startedAt && job.endedAt) {
+      job.durationMs =
+        new Date(job.endedAt).getTime() - new Date(job.startedAt).getTime();
+    }
+
+    if (!touched) {
+      // Pure mid-step log line — we already mutated the step buffer above,
+      // but we still want the UI to refresh so the step log grows live.
+      this.jobs.set(jobName, job);
+      this.onUpdate({ ...job, steps: job.steps?.map((s) => ({ ...s })) });
+      return;
+    }
+
+    this.jobs.set(jobName, job);
+    this.onUpdate({ ...job, steps: job.steps?.map((s) => ({ ...s })) });
+  }
+}
+
+// ─── Run history listing ────────────────────────────────────────────────
+
+export interface GhaRunListOptions {
+  questionId?: string;
+  fileId?: string;
+  limit?: number;
+}
+
+async function readRunMetadata(
+  runId: string,
+): Promise<GhaRunMetadata | undefined> {
+  const file = path.join(getGhaRunsDir(), runId, "metadata.json");
+  const raw = await readJsonFile(file);
+  if (!raw || typeof raw !== "object") return undefined;
+  return raw as GhaRunMetadata;
+}
+
+export async function listGhaRuns(
+  options: GhaRunListOptions = {},
+): Promise<GhaRunMetadata[]> {
+  const dir = getGhaRunsDir();
+  let entries: string[] = [];
+  try {
+    entries = await fs.readdir(dir);
+  } catch (err: any) {
+    if (err?.code === "ENOENT") return [];
+    throw err;
+  }
+  const limit = Math.max(1, Math.min(options.limit ?? 50, 200));
+  const results: GhaRunMetadata[] = [];
+  for (const entry of entries) {
+    const meta = await readRunMetadata(entry);
+    if (!meta) continue;
+    if (options.fileId && meta.fileId !== options.fileId) continue;
+    if (options.questionId && meta.questionId !== options.questionId) continue;
+    results.push(meta);
+  }
+  results.sort((a, b) => (a.startedAt < b.startedAt ? 1 : -1));
+  return results.slice(0, limit);
+}
+
+export interface GhaRunDetails extends GhaRunMetadata {
+  log: string;
+}
+
+export async function getGhaRun(runId: string): Promise<GhaRunDetails> {
+  const meta = await readRunMetadata(runId);
+  if (!meta) throw new Error("Run not found");
+  let log = "";
+  try {
+    log = await fs.readFile(
+      path.join(getGhaRunsDir(), runId, "run.log"),
+      "utf8",
+    );
+  } catch {
+    // log file may have been pruned; surface metadata only
+  }
+  return { ...meta, log };
+}
+
+export async function streamGhaCommand(
+  input: RunInput,
+): Promise<GhaRunMetadata> {
+  const workspace = parseWorkspace(input.workspace);
+
+  const parsed = parseActCommand(input.command);
+  const sessionKey =
+    input.fileId ?? input.questionId ?? `draft-${randomUUID()}`;
+  const runId = randomUUID();
+  const startedAt = new Date().toISOString();
+  const runDir = path.join(getGhaRunsDir(), runId);
+  const workspaceDir = await syncWorkspaceToSession(sessionKey, workspace);
+  await fs.mkdir(runDir, { recursive: true });
+
+  let logs = "";
+  let status: "completed" | "failed" = "completed";
+  let errorMessage: string | undefined;
+  let exitCode = 0;
+
+  const emit = (msg: GhaStreamMessage) => input.onMessage?.(msg);
+  emit({ type: "output", kind: "info", text: parsed.displayCommand });
+
+  // Track per-job status from act's prefixed stdout/stderr lines so the
+  // client can render a live DAG in addition to the raw console.
+  const tracker = new JobTracker((job) => emit({ type: "job", job }));
+
+  const child = spawn("act", parsed.args, {
+    cwd: workspaceDir,
+    env: {
+      ...process.env,
+      // Avoid TTY-only progress spinners — they spam control codes through SSE
+      ACT_LOG_LEVEL: process.env.ACT_LOG_LEVEL || "info",
+      // Disable pager-like output
+      NO_COLOR: "1",
+    },
+  });
+
+  await new Promise<void>((resolve) => {
+    let settled = false;
+    const finish = () => {
+      if (settled) return;
+      settled = true;
+      resolve();
+    };
+    child.stdout.on("data", (chunk: Buffer) => {
+      const text = stripAnsi(chunk.toString());
+      logs = appendLog(logs, text);
+      tracker.feed(text);
+      emit({ type: "output", kind: "stdout", text });
+    });
+    child.stderr.on("data", (chunk: Buffer) => {
+      const text = stripAnsi(chunk.toString());
+      logs = appendLog(logs, text);
+      tracker.feed(text);
+      emit({ type: "output", kind: "stderr", text });
+    });
+    child.on("error", (err: NodeJS.ErrnoException) => {
+      status = "failed";
+      exitCode = 1;
+      if (err.code === "ENOENT") {
+        errorMessage =
+          "`act` is not installed on this machine. Install it with `brew install act` (macOS) or follow https://github.com/nektos/act#installation, then click Run again.";
+      } else {
+        errorMessage = err.message;
+      }
+      const text = `\n[error] ${errorMessage}\n`;
+      logs = appendLog(logs, text);
+      emit({ type: "output", kind: "stderr", text });
+      finish();
+    });
+    child.on("close", (code) => {
+      exitCode = typeof code === "number" ? code : 1;
+      if (exitCode !== 0) {
+        status = "failed";
+        errorMessage = errorMessage || `act exited with code ${exitCode}`;
+      }
+      finish();
+    });
+  });
+
+  // Drain any partial line buffered by the tracker before we finalise.
+  tracker.flush();
+  tracker.finalize(exitCode);
+
+  const completedAt = new Date().toISOString();
+  const durationMs =
+    new Date(completedAt).getTime() - new Date(startedAt).getTime();
+
+  const metadata: GhaRunMetadata = {
+    id: runId,
+    ...(input.fileId ? { fileId: input.fileId } : {}),
+    ...(input.questionId ? { questionId: input.questionId } : {}),
+    label: input.label?.trim() || workspace.label,
+    command: parsed.displayCommand.replace(/^\$\s*/, "").trim(),
+    status,
+    startedAt,
+    completedAt,
+    durationMs,
+    exitCode,
+    ...(errorMessage ? { error: errorMessage } : {}),
+    jobs: tracker.snapshot(),
+    ...(parsed.event ? { event: parsed.event } : {}),
+    ...(workspace.defaultWorkflow
+      ? { workflow: workspace.defaultWorkflow }
+      : {}),
+  };
+
+  await fs.writeFile(
+    path.join(runDir, "metadata.json"),
+    JSON.stringify(metadata, null, 2),
+    "utf8",
+  );
+  await fs.writeFile(path.join(runDir, "run.log"), logs, "utf8");
+
+  emit({ type: "complete", runId, exitCode, durationMs });
+  return metadata;
+}