@davidorex/pi-workflows 0.1.0

package/src/step-transform.ts

@@ -0,0 +1,47 @@
+/**
+ * Transform step executor — produces output by resolving expressions in a mapping.
+ * No LLM call, no subprocess, no shell command — pure expression resolution.
+ */
+import type { TransformSpec, StepResult } from "./types.ts";
+import { resolveExpressions } from "./expression.ts";
+import { zeroUsage } from "./step-shared.ts";
+import { persistStepOutput } from "./output.ts";
+
+/**
+ * Execute a transform step: produces output by resolving expressions in the mapping.
+ * No LLM call, no subprocess, no shell command — pure expression resolution.
+ */
+export function executeTransform(
+  transform: TransformSpec,
+  stepName: string,
+  scope: Record<string, unknown>,
+  runDir?: string,
+  outputPath?: string,
+): StepResult {
+  const startTime = Date.now();
+  try {
+    const output = resolveExpressions(transform.mapping, scope);
+    const result: StepResult = {
+      step: stepName,
+      agent: "transform",
+      status: "completed",
+      output,
+      textOutput: JSON.stringify(output, null, 2),
+      usage: zeroUsage(),
+      durationMs: Date.now() - startTime,
+    };
+    if (runDir) {
+      result.outputPath = persistStepOutput(runDir, stepName, output, undefined, outputPath);
+    }
+    return result;
+  } catch (err) {
+    return {
+      step: stepName,
+      agent: "transform",
+      status: "failed",
+      usage: zeroUsage(),
+      durationMs: Date.now() - startTime,
+      error: err instanceof Error ? err.message : String(err),
+    };
+  }
+}

package/src/template-integration.test.ts

@@ -0,0 +1,72 @@
+import { describe, it } from "node:test";
+import assert from "node:assert";
+import { createTemplateEnv, renderTemplateFile } from "./template.ts";
+import path from "node:path";
+import fs from "node:fs";
+import os from "node:os";
+
+describe("analyzer template inheritance", () => {
+  const builtinDir = path.resolve(import.meta.dirname, "..", "templates");
+
+  it("structure analyzer inherits base and overrides blocks", () => {
+    const env = createTemplateEnv("/nonexistent", builtinDir);
+    const result = renderTemplateFile(env, "analyzers/structure.md", {});
+    assert.ok(result.includes("code structure analyst"));
+    assert.ok(result.includes("Architecture"));
+    assert.ok(result.includes("Module boundaries"));
+    assert.ok(!result.includes("Test coverage"));
+  });
+
+  it("quality analyzer inherits base and overrides blocks", () => {
+    const env = createTemplateEnv("/nonexistent", builtinDir);
+    const result = renderTemplateFile(env, "analyzers/quality.md", {});
+    assert.ok(result.includes("code quality analyst"));
+    assert.ok(result.includes("Test coverage"));
+    assert.ok(!result.includes("Architecture"));
+  });
+
+  it("pattern analyzer inherits base and overrides blocks", () => {
+    const env = createTemplateEnv("/nonexistent", builtinDir);
+    const result = renderTemplateFile(env, "analyzers/patterns.md", {});
+    assert.ok(result.includes("design pattern analyst"));
+    assert.ok(result.includes("Design patterns"));
+    assert.ok(result.includes("Anti-patterns"));
+  });
+
+  it("all three produce different output from the same base", () => {
+    const env = createTemplateEnv("/nonexistent", builtinDir);
+    const s = renderTemplateFile(env, "analyzers/structure.md", {});
+    const q = renderTemplateFile(env, "analyzers/quality.md", {});
+    const p = renderTemplateFile(env, "analyzers/patterns.md", {});
+    // All contain the shared preamble pattern
+    assert.ok(s.includes("Given an exploration summary"));
+    assert.ok(q.includes("Given an exploration summary"));
+    assert.ok(p.includes("Given an exploration summary"));
+    // But different identities
+    assert.ok(s.includes("structure"));
+    assert.ok(q.includes("quality"));
+    assert.ok(p.includes("pattern"));
+  });
+
+  it("project template shadows builtin", () => {
+    const tmpProject = fs.mkdtempSync(path.join(os.tmpdir(), "pi-tmpl-proj-"));
+    const projectTemplates = path.join(tmpProject, ".pi", "templates", "analyzers");
+    fs.mkdirSync(projectTemplates, { recursive: true });
+
+    fs.writeFileSync(path.join(projectTemplates, "structure.md"), [
+      '{% extends "analyzers/base-analyzer.md" %}',
+      "{% block identity %}You are a CUSTOM structure analyst.{% endblock %}",
+      "{% block checklist %}",
+      "1. **Custom**: Project-specific check",
+      "{% endblock %}",
+    ].join("\n"));
+
+    const env = createTemplateEnv(tmpProject, builtinDir);
+    const result = renderTemplateFile(env, "analyzers/structure.md", {});
+    assert.ok(result.includes("CUSTOM structure analyst"));
+    assert.ok(result.includes("Project-specific check"));
+    assert.ok(!result.includes("Module boundaries"));
+
+    fs.rmSync(tmpProject, { recursive: true });
+  });
+});

package/src/template.test.ts

@@ -0,0 +1,162 @@
+import { describe, it } from "node:test";
+import assert from "node:assert";
+import { createTemplateEnv, renderTemplate, renderTemplateFile } from "./template.ts";
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+
+describe("renderTemplate", () => {
+  it("renders variable substitution", () => {
+    const env = createTemplateEnv("/nonexistent");
+    const result = renderTemplate(env, "Hello {{ name }}, you are {{ role }}", { name: "Alice", role: "analyst" });
+    assert.strictEqual(result, "Hello Alice, you are analyst");
+  });
+
+  it("passes through plain text unchanged", () => {
+    const env = createTemplateEnv("/nonexistent");
+    const result = renderTemplate(env, "No templates here. Just markdown.", {});
+    assert.strictEqual(result, "No templates here. Just markdown.");
+  });
+
+  it("renders if/else conditionals", () => {
+    const env = createTemplateEnv("/nonexistent");
+    const tmpl = "{% if verbose %}Detailed output{% else %}Brief output{% endif %}";
+    assert.strictEqual(renderTemplate(env, tmpl, { verbose: true }), "Detailed output");
+    assert.strictEqual(renderTemplate(env, tmpl, { verbose: false }), "Brief output");
+  });
+
+  it("renders for loops", () => {
+    const env = createTemplateEnv("/nonexistent");
+    const tmpl = "{% for item in items %}- {{ item }}\n{% endfor %}";
+    const result = renderTemplate(env, tmpl, { items: ["a", "b", "c"] });
+    assert.ok(result.includes("- a"));
+    assert.ok(result.includes("- b"));
+    assert.ok(result.includes("- c"));
+  });
+
+  it("handles undefined variables gracefully (empty string)", () => {
+    const env = createTemplateEnv("/nonexistent");
+    const result = renderTemplate(env, "Hello {{ name }}", {});
+    assert.strictEqual(result, "Hello ");
+  });
+
+  it("preserves ${{ }} workflow expressions (not interpreted)", () => {
+    const env = createTemplateEnv("/nonexistent");
+    const result = renderTemplate(env, "Use ${{ steps.explore.output }}", {});
+    assert.strictEqual(result, "Use ${{ steps.explore.output }}");
+  });
+
+  it("renders nested object access", () => {
+    const env = createTemplateEnv("/nonexistent");
+    const result = renderTemplate(env, "File: {{ context.file }}", { context: { file: "main.ts" } });
+    assert.strictEqual(result, "File: main.ts");
+  });
+});
+
+describe("renderTemplateFile", () => {
+  it("renders a template file from the search path", () => {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-tmpl-test-"));
+    fs.writeFileSync(path.join(tmpDir, "test.md"), "Hello {{ name }}");
+
+    const env = createTemplateEnv("/nonexistent", tmpDir);
+    const result = renderTemplateFile(env, "test.md", { name: "World" });
+    assert.strictEqual(result, "Hello World");
+
+    fs.rmSync(tmpDir, { recursive: true });
+  });
+
+  it("supports {% extends %} inheritance", () => {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-tmpl-test-"));
+
+    fs.writeFileSync(path.join(tmpDir, "base.md"), [
+      "# {{ title }}",
+      "{% block intro %}Default intro{% endblock %}",
+      "{% block body %}Default body{% endblock %}",
+    ].join("\n"));
+
+    fs.writeFileSync(path.join(tmpDir, "child.md"), [
+      '{% extends "base.md" %}',
+      "{% block body %}Custom body for {{ focus }}{% endblock %}",
+    ].join("\n"));
+
+    const env = createTemplateEnv("/nonexistent", tmpDir);
+    const result = renderTemplateFile(env, "child.md", { title: "Report", focus: "security" });
+    assert.ok(result.includes("# Report"), "should render parent title");
+    assert.ok(result.includes("Default intro"), "should inherit intro block");
+    assert.ok(result.includes("Custom body for security"), "should override body block");
+    assert.ok(!result.includes("Default body"), "should NOT include default body");
+
+    fs.rmSync(tmpDir, { recursive: true });
+  });
+
+  it("supports {% include %}", () => {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-tmpl-test-"));
+
+    fs.writeFileSync(path.join(tmpDir, "fragment.md"), "This is a reusable fragment.");
+    fs.writeFileSync(path.join(tmpDir, "main.md"), [
+      "# Main",
+      '{% include "fragment.md" %}',
+      "End.",
+    ].join("\n"));
+
+    const env = createTemplateEnv("/nonexistent", tmpDir);
+    const result = renderTemplateFile(env, "main.md", {});
+    assert.ok(result.includes("# Main"));
+    assert.ok(result.includes("This is a reusable fragment."));
+    assert.ok(result.includes("End."));
+
+    fs.rmSync(tmpDir, { recursive: true });
+  });
+
+  it("supports {% macro %}", () => {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-tmpl-test-"));
+
+    fs.writeFileSync(path.join(tmpDir, "macros.md"), [
+      "{% macro greeting(name) %}Hello, {{ name }}!{% endmacro %}",
+    ].join("\n"));
+    fs.writeFileSync(path.join(tmpDir, "main.md"), [
+      '{% from "macros.md" import greeting %}',
+      "{{ greeting('Alice') }}",
+      "{{ greeting('Bob') }}",
+    ].join("\n"));
+
+    const env = createTemplateEnv("/nonexistent", tmpDir);
+    const result = renderTemplateFile(env, "main.md", {});
+    assert.ok(result.includes("Hello, Alice!"));
+    assert.ok(result.includes("Hello, Bob!"));
+
+    fs.rmSync(tmpDir, { recursive: true });
+  });
+
+  it("project templates shadow builtin templates", () => {
+    const builtinDir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-tmpl-builtin-"));
+    const projectDir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-tmpl-project-"));
+
+    const projectTemplates = path.join(projectDir, ".pi", "templates");
+    fs.mkdirSync(projectTemplates, { recursive: true });
+
+    fs.writeFileSync(path.join(builtinDir, "shared.md"), "BUILTIN version");
+    fs.writeFileSync(path.join(projectTemplates, "shared.md"), "PROJECT version");
+
+    const env = createTemplateEnv(projectDir, builtinDir);
+    const result = renderTemplateFile(env, "shared.md", {});
+    assert.strictEqual(result, "PROJECT version");
+
+    fs.rmSync(builtinDir, { recursive: true });
+    fs.rmSync(projectDir, { recursive: true });
+  });
+});
+
+describe("createTemplateEnv", () => {
+  it("creates an environment that renders plain text unchanged", () => {
+    const env = createTemplateEnv("/nonexistent");
+    const result = renderTemplate(env, "Just plain text", {});
+    assert.strictEqual(result, "Just plain text");
+  });
+
+  it("works when no template directories exist", () => {
+    const env = createTemplateEnv("/definitely/does/not/exist");
+    const result = renderTemplate(env, "Still works: {{ x }}", { x: 42 });
+    assert.strictEqual(result, "Still works: 42");
+  });
+});

package/src/template.ts

@@ -0,0 +1,92 @@
+/**
+ * Nunjucks template rendering for agent prompts.
+ * Provides three-tier template resolution (project > user > builtin)
+ * and renders agent system prompts with step input as context.
+ */
+import nunjucks from "nunjucks";
+import path from "node:path";
+import os from "node:os";
+import fs from "node:fs";
+
+/**
+ * Create a Nunjucks environment with three-tier template resolution.
+ *
+ * Search order (first match wins):
+ *   1. .pi/templates/           (project-level)
+ *   2. ~/.pi/agent/templates/   (user-level)
+ *   3. <package>/templates/     (builtin)
+ *
+ * Autoescape is disabled — we're rendering markdown, not HTML.
+ *
+ * @param cwd - project root directory
+ * @param builtinDir - optional path to builtin templates (defaults to templates/ relative to package root)
+ */
+export function createTemplateEnv(cwd: string, builtinDir?: string): nunjucks.Environment {
+  const projectDir = path.join(cwd, ".pi", "templates");
+  const userDir = path.join(os.homedir(), ".pi", "agent", "templates");
+  const defaultBuiltinDir = builtinDir ?? path.resolve(import.meta.dirname, "..", "templates");
+
+  // Nunjucks FileSystemLoader searches directories in order — first match wins.
+  // Only include directories that exist to avoid noisy warnings.
+  const searchPaths: string[] = [];
+  if (fs.existsSync(projectDir)) searchPaths.push(projectDir);
+  if (fs.existsSync(userDir)) searchPaths.push(userDir);
+  if (fs.existsSync(defaultBuiltinDir)) searchPaths.push(defaultBuiltinDir);
+
+  // If no template directories exist, use a no-op loader — plain text passes through.
+  const loader = searchPaths.length > 0
+    ? new nunjucks.FileSystemLoader(searchPaths)
+    : undefined;
+
+  return new nunjucks.Environment(loader, {
+    autoescape: false,
+    throwOnUndefined: false,
+  });
+}
+
+/** Sentinel used to protect ${{ }} workflow expressions from Nunjucks rendering. */
+const WORKFLOW_EXPR_PLACEHOLDER = "\x00__PI_WORKFLOW_EXPR__";
+
+/**
+ * Render a template string through Nunjucks.
+ *
+ * Used for agent system prompts (the markdown body after frontmatter).
+ * The context object contains the step's resolved input fields as top-level keys.
+ *
+ * Workflow expressions (${{ }}) are protected from Nunjucks interpretation
+ * by escaping them before rendering and restoring them after.
+ *
+ * @param env - Nunjucks environment (from createTemplateEnv)
+ * @param templateStr - the template text to render
+ * @param context - variables available in the template
+ * @returns rendered string
+ */
+export function renderTemplate(env: nunjucks.Environment, templateStr: string, context: Record<string, unknown>): string {
+  // Protect ${{ }} workflow expressions from Nunjucks
+  const escaped = templateStr.replace(/\$\{\{/g, WORKFLOW_EXPR_PLACEHOLDER);
+  const rendered = env.renderString(escaped, context);
+  return rendered.replace(new RegExp(escapeRegExp(WORKFLOW_EXPR_PLACEHOLDER), "g"), "${{");
+}
+
+/** Escape special regex characters in a string. */
+function escapeRegExp(s: string): string {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+/**
+ * Render a named template file through Nunjucks.
+ *
+ * Used when an agent spec references a template by path:
+ *   prompt:
+ *     system: analyzers/base-analyzer.md
+ *
+ * The file is resolved through the three-tier search (project > user > builtin).
+ *
+ * @param env - Nunjucks environment
+ * @param templateName - relative path to the template file
+ * @param context - variables available in the template
+ * @returns rendered string
+ */
+export function renderTemplateFile(env: nunjucks.Environment, templateName: string, context: Record<string, unknown>): string {
+  return env.render(templateName, context);
+}

package/src/test-helpers.ts

@@ -0,0 +1,51 @@
+/**
+ * Shared test helpers — mock factories for ctx, pi, and workflow specs.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import type { WorkflowSpec, StepSpec } from "./types.ts";
+
+/**
+ * Create a mock extension context for testing.
+ */
+export function mockCtx(cwd: string) {
+  return {
+    cwd,
+    hasUI: false,
+    ui: {
+      setWidget: () => {},
+      notify: () => {},
+      setStatus: () => {},
+    },
+  } as any;
+}
+
+/**
+ * Create a mock pi API for testing.
+ */
+export function mockPi() {
+  const messages: any[] = [];
+  return {
+    sendMessage: (msg: any, opts: any) => messages.push({ msg, opts }),
+    _messages: messages,
+  } as any;
+}
+
+/**
+ * Create a minimal WorkflowSpec for testing.
+ * A fresh temp directory is created for filePath.
+ */
+export function makeSpec(
+  overrides: Partial<WorkflowSpec> & { steps: Record<string, StepSpec> },
+): WorkflowSpec {
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "wf-test-"));
+  return {
+    name: "test-workflow",
+    description: "Test workflow",
+    version: "1",
+    source: "project" as const,
+    filePath: path.join(tmpDir, "test.workflow.yaml"),
+    ...overrides,
+  };
+}