@davidorex/pi-workflows 0.2.0 → 0.3.0

package/src/state.test.ts

@@ -1,192 +0,0 @@
-import { describe, it } from "node:test";
-import assert from "node:assert";
-import {
-  generateRunId, initRunDir, writeState, readState,
-  writeStepOutput, writeMetrics, buildResult, formatResult, aggregateUsage,
-} from "./state.ts";
-import fs from "node:fs";
-import path from "node:path";
-import os from "node:os";
-import type { ExecutionState, WorkflowSpec, StepResult, StepUsage } from "./types.ts";
-
-describe("generateRunId", () => {
-  it("includes workflow name", () => {
-    const id = generateRunId("bugfix");
-    assert.ok(id.startsWith("bugfix-"));
-  });
-
-  it("generates unique IDs", () => {
-    const a = generateRunId("test");
-    const b = generateRunId("test");
-    assert.notStrictEqual(a, b);
-  });
-});
-
-describe("initRunDir", () => {
-  it("creates directory structure under workflow name", () => {
-    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "wf-state-"));
-    const runDir = initRunDir(tmpDir, "test-wf", "test-run-1");
-
-    assert.ok(fs.existsSync(runDir));
-    assert.ok(runDir.includes(path.join("test-wf", "runs", "test-run-1")));
-    assert.ok(fs.existsSync(path.join(runDir, "sessions")));
-    assert.ok(fs.existsSync(path.join(runDir, "outputs")));
-
-    fs.rmSync(tmpDir, { recursive: true });
-  });
-});
-
-describe("writeState / readState", () => {
-  it("round-trips execution state", () => {
-    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "wf-state-"));
-    const runDir = path.join(tmpDir, "run");
-    fs.mkdirSync(runDir, { recursive: true });
-
-    const state: ExecutionState = {
-      input: { description: "test" },
-      steps: {},
-      status: "running",
-    };
-
-    writeState(runDir, state);
-    const loaded = readState(runDir);
-    assert.deepStrictEqual(loaded, state);
-
-    fs.rmSync(tmpDir, { recursive: true });
-  });
-
-  it("returns null for nonexistent state", () => {
-    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "wf-state-"));
-    assert.strictEqual(readState(tmpDir), null);
-    fs.rmSync(tmpDir, { recursive: true });
-  });
-});
-
-describe("aggregateUsage", () => {
-  it("sums usage across steps", () => {
-    const usage = (n: number): StepUsage => ({
-      input: n * 100, output: n * 50, cacheRead: 0, cacheWrite: 0,
-      cost: n * 0.01, turns: n,
-    });
-    const steps: Record<string, StepResult> = {
-      a: { step: "a", agent: "x", status: "completed", usage: usage(1), durationMs: 1000 },
-      b: { step: "b", agent: "y", status: "completed", usage: usage(2), durationMs: 2000 },
-    };
-    const total = aggregateUsage(steps);
-    assert.strictEqual(total.input, 300);
-    assert.strictEqual(total.output, 150);
-    assert.strictEqual(total.turns, 3);
-    assert.ok(Math.abs(total.cost - 0.03) < 0.001);
-  });
-});
-
-describe("formatResult", () => {
-  it("includes workflow name and step summary", () => {
-    const result = buildResult(
-      { name: "test", steps: { s: { agent: "a" } } } as WorkflowSpec,
-      "test-run-1",
-      "/tmp/run",
-      {
-        input: {},
-        steps: {
-          s: {
-            step: "s", agent: "a", status: "completed",
-            textOutput: "done",
-            usage: { input: 100, output: 50, cacheRead: 0, cacheWrite: 0, cost: 0.01, turns: 1 },
-            durationMs: 5000,
-          },
-        },
-        status: "completed",
-      },
-      "completed",
-    );
-    const text = formatResult(result);
-    assert.ok(text.includes("test"));
-    assert.ok(text.includes("completed"));
-    assert.ok(text.includes("$0.01") || text.includes("0.01"));
-  });
-});
-
-describe("writeState error handling", () => {
-  it("throws with context when write fails", (t) => {
-    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "wf-state-err-"));
-    t.after(() => {
-      try { fs.chmodSync(tmpDir, 0o755); } catch { /* ignore */ }
-      fs.rmSync(tmpDir, { recursive: true, force: true });
-    });
-
-    // Make directory read-only
-    fs.chmodSync(tmpDir, 0o444);
-
-    const state: ExecutionState = {
-      input: {},
-      steps: {},
-      status: "running",
-    };
-
-    assert.throws(
-      () => writeState(tmpDir, state),
-      (err: Error) => {
-        return err.message.includes("Failed to write workflow state")
-          && err.message.includes("running");
-      },
-    );
-  });
-
-  it("cleans up tmp file on rename failure", (t) => {
-    // Verify that after a write failure, no .state.json.tmp remains.
-    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "wf-state-err-"));
-    t.after(() => {
-      try { fs.chmodSync(tmpDir, 0o755); } catch { /* ignore */ }
-      fs.rmSync(tmpDir, { recursive: true, force: true });
-    });
-
-    fs.chmodSync(tmpDir, 0o444);
-
-    try {
-      writeState(tmpDir, { input: {}, steps: {}, status: "running" });
-    } catch { /* expected */ }
-
-    // Verify no tmp file leaked (may not exist if writeFileSync itself failed)
-    const tmpPath = path.join(tmpDir, ".state.json.tmp");
-    // Restore permissions to check
-    try { fs.chmodSync(tmpDir, 0o755); } catch { /* ignore */ }
-    assert.strictEqual(fs.existsSync(tmpPath), false);
-  });
-
-  it("error message includes the file path", (t) => {
-    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "wf-state-err-"));
-    t.after(() => {
-      try { fs.chmodSync(tmpDir, 0o755); } catch { /* ignore */ }
-      fs.rmSync(tmpDir, { recursive: true, force: true });
-    });
-
-    fs.chmodSync(tmpDir, 0o444);
-
-    try {
-      writeState(tmpDir, { input: {}, steps: {}, status: "completed" });
-      assert.fail("Should have thrown");
-    } catch (err) {
-      assert.ok(err instanceof Error);
-      assert.ok(err.message.includes("state.json"));
-      assert.ok(err.message.includes("completed"));
-    }
-  });
-});
-
-describe("writeMetrics error handling", () => {
-  it("does not throw when write fails", (t) => {
-    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "wf-metrics-err-"));
-    t.after(() => {
-      try { fs.chmodSync(tmpDir, 0o755); } catch { /* ignore */ }
-      fs.rmSync(tmpDir, { recursive: true, force: true });
-    });
-
-    fs.chmodSync(tmpDir, 0o444);
-
-    // Should not throw
-    assert.doesNotThrow(() => {
-      writeMetrics(tmpDir, {});
-    });
-  });
-});

package/src/state.ts

@@ -1,254 +0,0 @@
-import fs from "node:fs";
-import path from "node:path";
-import crypto from "node:crypto";
-import type { ExecutionState, WorkflowResult, WorkflowSpec, StepResult, StepUsage } from "./types.ts";
-import { formatDuration, formatCost } from "./format.ts";
-import { WORKFLOWS_DIR } from "./workflows-dir.ts";
-
-/**
- * Generate a unique run ID.
- * Format: <workflow-name>-<yyyymmdd>-<hhmmss>-<4 hex chars>
- * Example: "bugfix-20260312-214041-a3f2"
- */
-export function generateRunId(workflowName: string): string {
-  const now = new Date();
-  const yyyy = now.getFullYear().toString();
-  const mm = (now.getMonth() + 1).toString().padStart(2, "0");
-  const dd = now.getDate().toString().padStart(2, "0");
-  const hh = now.getHours().toString().padStart(2, "0");
-  const min = now.getMinutes().toString().padStart(2, "0");
-  const ss = now.getSeconds().toString().padStart(2, "0");
-  const hex = crypto.randomBytes(2).toString("hex");
-  return `${workflowName}-${yyyy}${mm}${dd}-${hh}${min}${ss}-${hex}`;
-}
-
-/**
- * Initialize the run directory structure.
- * Creates:
- *   .workflows/runs/<workflowName>/runs/<runId>/
- *   .workflows/runs/<workflowName>/runs/<runId>/sessions/
- *   .workflows/runs/<workflowName>/runs/<runId>/outputs/
- *
- * Each workflow owns a directory under .workflows/runs/<name>/.
- * Run state goes in runs/<runId>/; artifacts live at the workflow level.
- *
- * @param cwd - project root
- * @param workflowName - name of the workflow
- * @param runId - unique run identifier
- * @returns absolute path to the run directory
- */
-export function initRunDir(cwd: string, workflowName: string, runId: string): string {
-  const runDir = path.join(cwd, WORKFLOWS_DIR, "runs", workflowName, "runs", runId);
-  fs.mkdirSync(path.join(runDir, "sessions"), { recursive: true });
-  fs.mkdirSync(path.join(runDir, "outputs"), { recursive: true });
-  return runDir;
-}
-
-/**
- * Get the workflow output directory (parent of runs/).
- * This is where artifacts are written.
- *
- * @param cwd - project root
- * @param workflowName - name of the workflow
- * @returns absolute path to .workflows/runs/<workflowName>/
- */
-export function getWorkflowDir(cwd: string, workflowName: string): string {
-  return path.join(cwd, WORKFLOWS_DIR, "runs", workflowName);
-}
-
-/**
- * Write execution state to state.json in the run directory.
- * Overwrites on each call (not append).
- * Uses atomic write: write to .state.json.tmp, then fs.renameSync to state.json.
- */
-export function writeState(runDir: string, state: ExecutionState): void {
-  state.updatedAt = new Date().toISOString();
-  const tmpPath = path.join(runDir, ".state.json.tmp");
-  const finalPath = path.join(runDir, "state.json");
-  try {
-    fs.writeFileSync(tmpPath, JSON.stringify(state, null, 2), "utf-8");
-    fs.renameSync(tmpPath, finalPath);
-  } catch (err) {
-    // Best-effort cleanup of partial tmp file
-    try { fs.unlinkSync(tmpPath); } catch { /* ignore cleanup failure */ }
-    const msg = err instanceof Error ? err.message : String(err);
-    throw new Error(
-      `Failed to write workflow state to ${finalPath} (status: ${state.status}): ${msg}`,
-    );
-  }
-}
-
-/**
- * Read execution state from state.json.
- * Returns null if file doesn't exist.
- */
-export function readState(runDir: string): ExecutionState | null {
-  const statePath = path.join(runDir, "state.json");
-  try {
-    const content = fs.readFileSync(statePath, "utf-8");
-    return JSON.parse(content) as ExecutionState;
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Write a step's structured output to outputs/<stepName>.json.
- */
-export function writeStepOutput(runDir: string, stepName: string, output: unknown): void {
-  const outputPath = path.join(runDir, "outputs", `${stepName}.json`);
-  fs.writeFileSync(outputPath, JSON.stringify(output, null, 2), "utf-8");
-}
-
-/**
- * Write aggregated metrics to metrics.json.
- */
-export function writeMetrics(runDir: string, steps: Record<string, StepResult>): void {
-  const total = aggregateUsage(steps);
-  const totalDurationMs = Object.values(steps).reduce((sum, s) => sum + s.durationMs, 0);
-  const metrics = {
-    totalUsage: total,
-    totalDurationMs,
-    steps: Object.fromEntries(
-      Object.entries(steps).map(([name, s]) => [name, { usage: s.usage, durationMs: s.durationMs }]),
-    ),
-  };
-  try {
-    fs.writeFileSync(path.join(runDir, "metrics.json"), JSON.stringify(metrics, null, 2), "utf-8");
-  } catch (err) {
-    const msg = err instanceof Error ? err.message : String(err);
-    process.stderr.write(
-      `[pi-workflows] Warning: failed to write metrics to ${runDir}/metrics.json: ${msg}\n`,
-    );
-  }
-}
-
-/**
- * Aggregate usage across all steps.
- */
-export function aggregateUsage(steps: Record<string, StepResult>): StepUsage {
-  const total: StepUsage = {
-    input: 0,
-    output: 0,
-    cacheRead: 0,
-    cacheWrite: 0,
-    cost: 0,
-    turns: 0,
-  };
-  for (const step of Object.values(steps)) {
-    if (step.usage) {
-      total.input += step.usage.input;
-      total.output += step.usage.output;
-      total.cacheRead += step.usage.cacheRead;
-      total.cacheWrite += step.usage.cacheWrite;
-      total.cost += step.usage.cost;
-      total.turns += step.usage.turns;
-    }
-  }
-  return total;
-}
-
-/**
- * Build a WorkflowResult from execution state.
- * Aggregates usage across steps, computes total duration,
- * sets output to the last completed step's output (or explicit workflow output if defined).
- */
-export function buildResult(
-  spec: WorkflowSpec,
-  runId: string,
-  runDir: string,
-  state: ExecutionState,
-  status: "completed" | "failed" | "paused",
-): WorkflowResult {
-  const totalUsage = aggregateUsage(state.steps);
-  const totalDurationMs = Object.values(state.steps).reduce((sum, s) => sum + s.durationMs, 0);
-
-  // Determine output: last completed step's output
-  let output: unknown = undefined;
-  const stepNames = Object.keys(spec.steps);
-  for (let i = stepNames.length - 1; i >= 0; i--) {
-    const stepName = stepNames[i];
-    const stepResult = state.steps[stepName];
-    if (stepResult && stepResult.status === "completed") {
-      output = stepResult.output ?? stepResult.textOutput;
-      break;
-    }
-  }
-
-  return {
-    workflow: spec.name,
-    runId,
-    status,
-    steps: state.steps,
-    output,
-    totalUsage,
-    totalDurationMs,
-    runDir,
-  };
-}
-
-/**
- * Format a WorkflowResult as human-readable text for injection into the conversation.
- */
-export function formatResult(result: WorkflowResult): string {
-  const stepEntries = Object.values(result.steps);
-  const totalSteps = stepEntries.length;
-  const completedSteps = stepEntries.filter((s) => s.status === "completed").length;
-  const duration = formatDuration(result.totalDurationMs);
-  const cost = formatCost(result.totalUsage.cost);
-
-  const lines: string[] = [];
-
-  if (result.status === "completed") {
-    lines.push(`Workflow '${result.workflow}' completed (${totalSteps} steps, ${duration}, ${cost})`);
-  } else if (result.status === "paused") {
-    lines.push(
-      `Workflow '${result.workflow}' paused (${completedSteps}/${totalSteps} steps completed, ${duration}, ${cost})`,
-    );
-  } else {
-    // Find the failed step name
-    const failedStep = stepEntries.find((s) => s.status === "failed");
-    const failedName = failedStep ? failedStep.step : "unknown";
-    lines.push(
-      `Workflow '${result.workflow}' failed at step '${failedName}' (${completedSteps}/${totalSteps} steps, ${duration}, ${cost})`,
-    );
-  }
-
-  lines.push("");
-  lines.push("Steps:");
-
-  for (const step of stepEntries) {
-    const stepDuration = formatDuration(step.durationMs);
-    const stepCost = formatCost(step.usage.cost);
-
-    if (step.status === "completed") {
-      lines.push(`  \u2713 ${step.step}  ${stepDuration}  ${stepCost}  (${step.usage.turns} turns)`);
-    } else if (step.status === "failed") {
-      const errorPreview = step.error || "Unknown error";
-      lines.push(`  \u2717 ${step.step}  ${stepDuration}  ${stepCost}  ${errorPreview}`);
-    } else {
-      // skipped
-      lines.push(`  \u00b7 ${step.step}`);
-    }
-  }
-
-  if (result.status === "completed") {
-    lines.push("");
-    lines.push(
-      `Total: ${result.totalUsage.input} input + ${result.totalUsage.output} output tokens, ${cost}`,
-    );
-  }
-
-  if (result.artifacts && Object.keys(result.artifacts).length > 0) {
-    lines.push("");
-    lines.push("Artifacts:");
-    for (const [name, artifactPath] of Object.entries(result.artifacts)) {
-      lines.push(`  ${name} \u2192 ${artifactPath}`);
-    }
-  }
-
-  lines.push("");
-  lines.push(`Session logs: ${result.runDir}/sessions/`);
-
-  return lines.join("\n");
-}