@davidorex/pi-workflows 0.1.0

package/src/types.ts

@@ -0,0 +1,195 @@
+// ── Workflow Spec (parsed from YAML) ──
+
+export interface WorkflowSpec {
+  name: string;
+  description: string;
+  version?: string;
+  input?: Record<string, unknown>;       // JSON Schema object
+  output?: Record<string, unknown>;      // JSON Schema object
+  triggerTurn?: boolean;                  // default: true
+  completion?: CompletionSpec;           // controls post-completion message to main LLM
+  steps: Record<string, StepSpec>;       // ordered (YAML preserves insertion order)
+  artifacts?: Record<string, ArtifactSpec>; // persistent files written after workflow completion
+  // Set by discovery, not by YAML:
+  source: "user" | "project";
+  filePath: string;
+}
+
+export interface ArtifactSpec {
+  path: string;                          // destination path, may contain ${{ }} expressions
+  from: string;                          // ${{ }} expression for the data source
+  schema?: string;                       // optional JSON Schema to validate before writing
+}
+
+export interface RetryConfig {
+  maxAttempts?: number;                  // default 1 (no retry). Total attempts, not retries.
+  onExhausted?: 'fail' | 'skip';        // default 'fail'
+  steeringMessage?: string;             // optional custom steering text for retries (agent steps only)
+}
+
+export interface StepSpec {
+  agent?: string;                        // optional — not needed for gate/transform steps
+  model?: string;                        // model override
+  input?: Record<string, unknown>;       // values may contain ${{ }} expressions
+  output?: StepOutputSpec;
+  when?: string;                         // ${{ }} expression, evaluated as truthy/falsy
+  timeout?: { seconds: number };
+  retry?: RetryConfig;                   // per-step retry config
+  loop?: LoopSpec;
+  gate?: GateSpec;
+  transform?: TransformSpec;
+  parallel?: Record<string, StepSpec>;   // named sub-steps to run concurrently
+  pause?: string | boolean;              // pause step — string is message to display, true = pause with no message
+  command?: string;                      // shell command to run (captures stdout as output)
+  forEach?: string;                      // ${{ }} expression resolving to an array
+  as?: string;                           // variable name to bind each element (default: "item")
+  workflow?: string;                     // phase 6 — not yet supported
+}
+// Note: exactly one of agent, gate, transform, loop, or parallel must be set.
+// workflow is phase 6.
+
+export interface LoopSpec {
+  maxAttempts: number;                   // max iterations (required)
+  attempts?: string;                     // ${{ }} expression overriding maxAttempts at runtime
+  steps: Record<string, StepSpec>;       // steps to execute each iteration
+  onExhausted?: StepSpec;               // step to run if all attempts fail
+}
+
+export interface GateSpec {
+  check: string;                         // shell command to run
+  onPass?: "continue" | "break";         // default: "continue" (proceed to next step)
+  onFail?: "continue" | "break" | "fail"; // default: "fail" (stop the workflow)
+}
+
+export interface TransformSpec {
+  /**
+   * A mapping of output field names to ${{ }} expressions.
+   * The result is an object with each field resolved.
+   * No LLM invocation — pure data transformation.
+   */
+  mapping: Record<string, unknown>;
+}
+
+export interface StepOutputSpec {
+  format?: "json" | "text";              // default: "text"
+  schema?: string;                       // path to JSON Schema file, relative to workflow spec
+  path?: string;                         // output file path — may contain ${{ }} expressions
+}
+
+// ── Agent Spec (loaded from .md frontmatter or .agent.yaml) ──
+
+export interface AgentSpec {
+  name: string;
+  description?: string;
+  role?: string;                         // sensor | reasoning | action | quality
+  systemPrompt?: string;                 // compiled system prompt (from template rendering)
+  promptTemplate?: string;               // system prompt template path
+  taskTemplate?: string;                 // task prompt template path
+  model?: string;
+  thinking?: string;
+  tools?: string[];
+  extensions?: string[];
+  skills?: string[];
+  output?: string;                       // output file path
+  inputSchema?: Record<string, unknown>; // JSON Schema for input
+  outputFormat?: "json" | "text";        // what the agent produces
+  outputSchema?: string;                 // path to output JSON Schema
+}
+
+// ── Execution State ──
+
+export interface ExecutionState {
+  input: unknown;
+  steps: Record<string, StepResult>;
+  status: "running" | "completed" | "failed" | "paused";
+  loop?: LoopState;                      // set when inside a loop
+  // Resume support:
+  workflowName?: string;       // which workflow this run belongs to
+  specVersion?: string;        // workflow spec version at time of run
+  startedAt?: string;          // ISO timestamp of run start
+  updatedAt?: string;          // ISO timestamp of last state write
+}
+
+export interface LoopState {
+  stepName: string;                      // name of the loop step
+  iteration: number;                     // current iteration (0-based)
+  maxAttempts: number;
+  priorAttempts: LoopAttempt[];          // results from previous iterations
+}
+
+export interface LoopAttempt {
+  iteration: number;
+  steps: Record<string, StepResult>;     // results of all steps in this iteration
+}
+
+export interface StepResult {
+  step: string;
+  agent: string;
+  status: "completed" | "failed" | "skipped";
+  output?: unknown;                      // parsed structured output (if schema-bound)
+  textOutput?: string;                   // raw text from last assistant message
+  outputPath?: string;                   // absolute path to persisted output JSON
+  sessionLog?: string;                   // path to session log file
+  usage: StepUsage;
+  durationMs: number;
+  error?: string;                        // error message if failed
+  truncated?: boolean;                   // true if stdout exceeded MAX_STDOUT_BYTES and data was lost
+  warnings?: string[];                   // non-fatal issues encountered during step execution
+  attempt?: number;                      // which attempt this result is from (1-based)
+  totalAttempts?: number;                // total attempts made
+  priorErrors?: string[];                // error messages from prior failed attempts
+}
+
+export interface StepUsage {
+  input: number;
+  output: number;
+  cacheRead: number;
+  cacheWrite: number;
+  cost: number;
+  turns: number;
+}
+
+// ── Workflow Result (returned to caller) ──
+
+export interface WorkflowResult {
+  workflow: string;
+  runId: string;
+  status: "completed" | "failed" | "paused";
+  steps: Record<string, StepResult>;
+  output?: unknown;                      // final workflow output (last step's output, or explicit)
+  totalUsage: StepUsage;
+  totalDurationMs: number;
+  runDir: string;                        // absolute path to .pi/workflow-runs/<name>/runs/<run-id>/
+  artifacts?: Record<string, string>;    // name → absolute path of written artifact files
+}
+
+// ── Completion Spec ──
+
+export interface CompletionSpec {
+  message?: string;                      // LLM instruction text (may contain ${{ }} expressions)
+  include?: string[];                    // expression paths to resolve and attach as data
+  template?: string;                     // full template with ${{ }} (mutually exclusive with message)
+}
+
+// ── Expression Scope (what ${{ }} expressions resolve against) ──
+
+export interface ExpressionScope {
+  input: unknown;
+  steps: Record<string, StepResult>;
+  [key: string]: unknown;  // allows use as Record<string, unknown>
+}
+
+// ── Completion Scope (wider scope for completion templates) ──
+
+export interface CompletionScope {
+  input: unknown;
+  steps: Record<string, StepResult>;
+  totalUsage: StepUsage;
+  totalDurationMs: number;
+  runDir: string;
+  runId: string;
+  workflow: string;
+  status: "completed" | "failed";
+  output?: unknown;
+  [key: string]: unknown;  // allows use as Record<string, unknown>
+}

package/src/verifier-schema.test.ts

@@ -0,0 +1,226 @@
+import { describe, it } from "node:test";
+import assert from "node:assert";
+import path from "node:path";
+import { validateFromFile } from "@davidorex/pi-project/src/schema-validator.ts";
+
+const schemaPath = path.resolve(import.meta.dirname, "..", "schemas", "verifier-output.schema.json");
+
+function validVerifierOutput() {
+  return {
+    status: "passed",
+    score: "3/3",
+    truths: [
+      { truth: "Tests pass", status: "verified", evidence: "npm test exited 0" },
+      { truth: "File exists", status: "verified", evidence: "ls confirmed" },
+      { truth: "Schema valid", status: "verified", evidence: "ajv validates" },
+    ],
+    criteria_results: [
+      {
+        criterion: "All tests pass",
+        verify_method: "command",
+        status: "passed",
+        expected_outcome: "exit code 0",
+        actual_outcome: "exit code 0",
+        evidence: "npm test output: 3 passing",
+      },
+      {
+        criterion: "File structure correct",
+        verify_method: "inspect",
+        status: "passed",
+        evidence: "All expected files present",
+      },
+      {
+        criterion: "UI renders correctly",
+        verify_method: "inspect",
+        status: "skipped",
+        evidence: "Requires visual inspection",
+      },
+    ],
+  };
+}
+
+describe("verifier-output schema validation", () => {
+  it("validates a complete verifier output", () => {
+    const data = validVerifierOutput();
+    const result = validateFromFile(schemaPath, data, "test");
+    assert.deepStrictEqual(result, data);
+  });
+
+  it("validates with all optional fields present", () => {
+    const data = {
+      ...validVerifierOutput(),
+      artifacts: [
+        { path: "src/index.ts", status: "verified", exists: true, substantive: true, wired: true, details: "Main entry point" },
+        { path: "src/missing.ts", status: "missing", exists: false },
+      ],
+      requirements_coverage: [
+        { requirement_id: "REQ-001", status: "satisfied", supporting_truths: ["Tests pass"] },
+        { requirement_id: "REQ-002", status: "needs_human" },
+      ],
+      human_verification: [
+        { name: "UI layout", test: "Open browser and check layout", expected: "Grid renders correctly", why_human: "Requires visual inspection" },
+      ],
+      gaps: [
+        { truth: "Performance benchmark", status: "failed", reason: "No benchmark data available" },
+      ],
+    };
+    const result = validateFromFile(schemaPath, data, "test");
+    assert.ok(result);
+  });
+
+  it("validates with empty optional arrays", () => {
+    const data = {
+      ...validVerifierOutput(),
+      artifacts: [],
+      requirements_coverage: [],
+      human_verification: [],
+      gaps: [],
+    };
+    const result = validateFromFile(schemaPath, data, "test");
+    assert.ok(result);
+  });
+
+  it("rejects missing required field: status", () => {
+    const data = validVerifierOutput();
+    delete (data as any).status;
+    assert.throws(
+      () => validateFromFile(schemaPath, data, "test"),
+      (err: any) => err.message.includes("Validation failed"),
+    );
+  });
+
+  it("rejects missing required field: score", () => {
+    const data = validVerifierOutput();
+    delete (data as any).score;
+    assert.throws(
+      () => validateFromFile(schemaPath, data, "test"),
+      (err: any) => err.message.includes("Validation failed"),
+    );
+  });
+
+  it("rejects missing required field: truths", () => {
+    const data = validVerifierOutput();
+    delete (data as any).truths;
+    assert.throws(
+      () => validateFromFile(schemaPath, data, "test"),
+      (err: any) => err.message.includes("Validation failed"),
+    );
+  });
+
+  it("rejects missing required field: criteria_results", () => {
+    const data = validVerifierOutput();
+    delete (data as any).criteria_results;
+    assert.throws(
+      () => validateFromFile(schemaPath, data, "test"),
+      (err: any) => err.message.includes("Validation failed"),
+    );
+  });
+
+  it("rejects invalid status enum value", () => {
+    const data = validVerifierOutput();
+    data.status = "invalid_status" as any;
+    assert.throws(
+      () => validateFromFile(schemaPath, data, "test"),
+      (err: any) => err.message.includes("Validation failed"),
+    );
+  });
+
+  it("rejects invalid truth status enum value", () => {
+    const data = validVerifierOutput();
+    data.truths[0].status = "bad_status" as any;
+    assert.throws(
+      () => validateFromFile(schemaPath, data, "test"),
+      (err: any) => err.message.includes("Validation failed"),
+    );
+  });
+
+  it("rejects invalid verify_method enum value", () => {
+    const data = validVerifierOutput();
+    data.criteria_results[0].verify_method = "magic" as any;
+    assert.throws(
+      () => validateFromFile(schemaPath, data, "test"),
+      (err: any) => err.message.includes("Validation failed"),
+    );
+  });
+
+  it("rejects invalid criteria_results status enum value", () => {
+    const data = validVerifierOutput();
+    data.criteria_results[0].status = "invalid" as any;
+    assert.throws(
+      () => validateFromFile(schemaPath, data, "test"),
+      (err: any) => err.message.includes("Validation failed"),
+    );
+  });
+
+  it("rejects invalid artifact status enum value", () => {
+    const data = {
+      ...validVerifierOutput(),
+      artifacts: [{ path: "test.ts", status: "unknown" }],
+    };
+    assert.throws(
+      () => validateFromFile(schemaPath, data, "test"),
+      (err: any) => err.message.includes("Validation failed"),
+    );
+  });
+});
+
+describe("plan-breakdown schema validation", () => {
+  const planSchemaPath = path.resolve(import.meta.dirname, "..", "schemas", "plan-breakdown.schema.json");
+
+  it("validates a valid plan breakdown", () => {
+    const data = {
+      plans: [
+        {
+          name: "implement-auth",
+          intent: "Add authentication",
+          tasks: ["Create auth module", "Add login endpoint"],
+          acceptance_criteria: ["Login works", "Tests pass"],
+          files_to_change: ["src/auth.ts"],
+          context_needed: ["existing user model"],
+          parallel_group: "core",
+        },
+      ],
+    };
+    const result = validateFromFile(planSchemaPath, data, "test");
+    assert.ok(result);
+  });
+
+  it("rejects missing required plan fields", () => {
+    const data = { plans: [{ name: "test" }] };
+    assert.throws(
+      () => validateFromFile(planSchemaPath, data, "test"),
+      (err: any) => err.message.includes("Validation failed"),
+    );
+  });
+});
+
+describe("execution-results schema validation", () => {
+  const execSchemaPath = path.resolve(import.meta.dirname, "..", "schemas", "execution-results.schema.json");
+
+  it("validates a valid execution result", () => {
+    const data = {
+      status: "complete",
+      tasks: [
+        { name: "implement feature", status: "done", files_modified: ["src/index.ts"], commit_hash: "abc123", notes: "Done" },
+      ],
+      decisions: [
+        { id: "D-001", decision: "Use ESM", rationale: "Modern standard", status: "decided" },
+      ],
+      issues: [
+        { severity: "info", description: "Minor lint warning" },
+      ],
+      test_count: 42,
+      commit_hash: "abc123",
+    };
+    const result = validateFromFile(execSchemaPath, data, "test");
+    assert.ok(result);
+  });
+
+  it("rejects invalid status enum", () => {
+    const data = { status: "unknown", tasks: [] };
+    assert.throws(
+      () => validateFromFile(execSchemaPath, data, "test"),
+      (err: any) => err.message.includes("Validation failed"),
+    );
+  });
+});

package/src/workflow-discovery.test.ts

@@ -0,0 +1,105 @@
+import { describe, it } from "node:test";
+import assert from "node:assert";
+import { discoverWorkflows, findWorkflow } from "./workflow-discovery.ts";
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+
+// Use a nonexistent dir as builtinDir so tests don't pick up real demo workflows
+const NO_BUILTINS = path.join(os.tmpdir(), "wf-no-builtins-nonexistent");
+
+describe("discoverWorkflows", () => {
+  it("discovers workflows from project directory", () => {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "wf-test-"));
+    const wfDir = path.join(tmpDir, ".pi", "workflows");
+    fs.mkdirSync(wfDir, { recursive: true });
+    fs.writeFileSync(
+      path.join(wfDir, "test.workflow.yaml"),
+      "name: test\nsteps:\n  s:\n    agent: a",
+    );
+
+    const specs = discoverWorkflows(tmpDir, NO_BUILTINS);
+    assert.strictEqual(specs.length, 1);
+    assert.strictEqual(specs[0].name, "test");
+    assert.strictEqual(specs[0].source, "project");
+
+    fs.rmSync(tmpDir, { recursive: true });
+  });
+
+  it("returns empty array when no workflow directories exist", () => {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "wf-test-"));
+    const specs = discoverWorkflows(tmpDir, NO_BUILTINS);
+    assert.strictEqual(specs.length, 0);
+    fs.rmSync(tmpDir, { recursive: true });
+  });
+
+  it("skips invalid specs with warning (no throw)", () => {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "wf-test-"));
+    const wfDir = path.join(tmpDir, ".pi", "workflows");
+    fs.mkdirSync(wfDir, { recursive: true });
+    fs.writeFileSync(path.join(wfDir, "bad.workflow.yaml"), "not: valid: workflow");
+    fs.writeFileSync(
+      path.join(wfDir, "good.workflow.yaml"),
+      "name: good\nsteps:\n  s:\n    agent: a",
+    );
+
+    const specs = discoverWorkflows(tmpDir, NO_BUILTINS);
+    assert.strictEqual(specs.length, 1);
+    assert.strictEqual(specs[0].name, "good");
+
+    fs.rmSync(tmpDir, { recursive: true });
+  });
+
+  it("project specs shadow user specs with same name", () => {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "wf-test-"));
+    const projectDir = path.join(tmpDir, ".pi", "workflows");
+    fs.mkdirSync(projectDir, { recursive: true });
+    fs.writeFileSync(
+      path.join(projectDir, "shared.workflow.yaml"),
+      "name: shared\ndescription: project version\nsteps:\n  s:\n    agent: a",
+    );
+
+    const specs = discoverWorkflows(tmpDir, NO_BUILTINS);
+    assert.strictEqual(specs.length, 1);
+    assert.strictEqual(specs[0].source, "project");
+
+    fs.rmSync(tmpDir, { recursive: true });
+  });
+
+  it("discovers builtin demo workflows", () => {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "wf-test-"));
+    const demoDir = path.resolve(import.meta.dirname, "..", "workflows");
+
+    const specs = discoverWorkflows(tmpDir, demoDir);
+    assert.ok(specs.length > 0, "should find at least one demo workflow");
+
+    const names = specs.map((s) => s.name);
+    assert.ok(names.includes("typed-analysis"), "should find typed-analysis demo");
+
+    fs.rmSync(tmpDir, { recursive: true });
+  });
+});
+
+describe("findWorkflow", () => {
+  it("finds a workflow by name", () => {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "wf-test-"));
+    const wfDir = path.join(tmpDir, ".pi", "workflows");
+    fs.mkdirSync(wfDir, { recursive: true });
+    fs.writeFileSync(
+      path.join(wfDir, "bugfix.workflow.yaml"),
+      "name: bugfix\nsteps:\n  s:\n    agent: a",
+    );
+
+    const spec = findWorkflow("bugfix", tmpDir, NO_BUILTINS);
+    assert.ok(spec);
+    assert.strictEqual(spec.name, "bugfix");
+
+    fs.rmSync(tmpDir, { recursive: true });
+  });
+
+  it("returns undefined for unknown workflow", () => {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "wf-test-"));
+    assert.strictEqual(findWorkflow("nonexistent", tmpDir, NO_BUILTINS), undefined);
+    fs.rmSync(tmpDir, { recursive: true });
+  });
+});

package/src/workflow-discovery.ts

@@ -0,0 +1,113 @@
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import type { WorkflowSpec } from "./types.ts";
+import { parseWorkflowSpec } from "./workflow-spec.ts";
+
+/**
+ * Discover all workflow specs from project, user, and builtin directories.
+ *
+ * Scans (highest priority first):
+ *   1. .pi/workflows/             (project-level, source: "project")
+ *   2. ~/.pi/agent/workflows/     (user-level, source: "user")
+ *   3. <package>/workflows/       (builtin workflows, source: "user")
+ *
+ * Higher-priority specs shadow lower-priority specs with the same name.
+ *
+ * @param cwd - current working directory (project root)
+ * @param builtinDir - optional path to builtin workflows (defaults to workflows/ relative to package root)
+ * @returns Array of parsed WorkflowSpec objects. Specs that fail parsing are
+ *          skipped with a warning (logged to stderr), not thrown.
+ */
+export function discoverWorkflows(cwd: string, builtinDir?: string): WorkflowSpec[] {
+  const projectDir = path.join(cwd, ".pi", "workflows");
+  const userDir = path.join(os.homedir(), ".pi", "agent", "workflows");
+  const demoDir = builtinDir ?? path.resolve(import.meta.dirname, "..", "workflows");
+
+  const projectSpecs = scanDirectory(projectDir, "project");
+  const userSpecs = scanDirectory(userDir, "user");
+  const builtinSpecs = scanDirectory(demoDir, "user");
+
+  // Deduplicate: project > user > builtin (last write wins, so add lowest priority first)
+  const byName = new Map<string, WorkflowSpec>();
+
+  for (const spec of builtinSpecs) {
+    byName.set(spec.name, spec);
+  }
+  for (const spec of userSpecs) {
+    byName.set(spec.name, spec);
+  }
+  for (const spec of projectSpecs) {
+    byName.set(spec.name, spec);
+  }
+
+  // Return sorted by name
+  const result = Array.from(byName.values());
+  result.sort((a, b) => a.name.localeCompare(b.name));
+  return result;
+}
+
+/**
+ * Find a workflow by name from discovered workflows.
+ * Returns undefined if not found.
+ */
+export function findWorkflow(name: string, cwd: string, builtinDir?: string): WorkflowSpec | undefined {
+  const specs = discoverWorkflows(cwd, builtinDir);
+  return specs.find((s) => s.name === name);
+}
+
+/**
+ * Scan a directory for *.workflow.yaml files and parse them.
+ * Non-recursive. Returns parsed specs; logs warnings for parse failures.
+ */
+function scanDirectory(dirPath: string, source: "user" | "project"): WorkflowSpec[] {
+  if (!fs.existsSync(dirPath)) {
+    return [];
+  }
+
+  let entries: string[];
+  try {
+    entries = fs.readdirSync(dirPath);
+  } catch {
+    return [];
+  }
+
+  const specs: WorkflowSpec[] = [];
+
+  for (const entry of entries) {
+    if (!entry.endsWith(".workflow.yaml")) {
+      continue;
+    }
+
+    const filePath = path.join(dirPath, entry);
+
+    // Only process files, not directories
+    let stat: fs.Stats;
+    try {
+      stat = fs.statSync(filePath);
+    } catch {
+      continue;
+    }
+    if (!stat.isFile()) {
+      continue;
+    }
+
+    let content: string;
+    try {
+      content = fs.readFileSync(filePath, "utf-8");
+    } catch {
+      console.error(`[pi-workflows] Warning: skipping ${filePath}: could not read file`);
+      continue;
+    }
+
+    try {
+      const spec = parseWorkflowSpec(content, filePath, source);
+      specs.push(spec);
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      console.error(`[pi-workflows] Warning: skipping ${filePath}: ${msg}`);
+    }
+  }
+
+  return specs;
+}