gsd-pi 2.41.0-dev.cac69f9 → 2.42.0-dev.97e9e30

package/src/resources/extensions/gsd/run-manager.ts

@@ -0,0 +1,180 @@
+/**
+ * run-manager.ts — Create and list isolated workflow run directories.
+ *
+ * Each run lives under `.gsd/workflow-runs/<name>/<timestamp>/` and contains:
+ * - DEFINITION.yaml — frozen snapshot of the workflow definition at run-creation time
+ * - GRAPH.yaml — initialized step graph with all steps pending
+ * - PARAMS.json — (optional) parameter overrides used for this run
+ *
+ * Observability:
+ * - All run state is on disk in human-readable YAML/JSON — inspectable with cat/less.
+ * - `listRuns()` returns structured metadata including step counts and overall status.
+ * - Timestamp directory names are filesystem-safe (ISO with hyphens replacing colons).
+ * - Errors include the full path context for diagnosis.
+ */
+
+import { mkdirSync, writeFileSync, existsSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { stringify } from "yaml";
+import { loadDefinition, substituteParams } from "./definition-loader.js";
+import { initializeGraph, writeGraph, readGraph } from "./graph.js";
+import type { WorkflowDefinition } from "./definition-loader.js";
+import type { WorkflowGraph } from "./graph.js";
+
+// ─── Types ───────────────────────────────────────────────────────────────
+
+export interface RunMetadata {
+  /** Workflow definition name. */
+  name: string;
+  /** Filesystem-safe timestamp string used as dir name. */
+  timestamp: string;
+  /** Full path to the run directory. */
+  runDir: string;
+  /** Step counts derived from GRAPH.yaml. */
+  steps: { total: number; completed: number; pending: number; active: number };
+  /** Overall status derived from step states. */
+  status: "pending" | "running" | "complete";
+}
+
+// ─── Constants ───────────────────────────────────────────────────────────
+
+const RUNS_DIR = "workflow-runs";
+const DEFS_DIR = "workflow-defs";
+
+// ─── Helpers ─────────────────────────────────────────────────────────────
+
+/**
+ * Generate a filesystem-safe timestamp: `YYYY-MM-DDTHH-MM-SS`.
+ * Replaces colons with hyphens so the string is safe as a directory name
+ * on all platforms (Windows forbids colons in paths).
+ */
+function makeTimestamp(date: Date = new Date()): string {
+  return date.toISOString().replace(/:/g, "-").replace(/\.\d{3}Z$/, "");
+}
+
+/**
+ * Derive overall status from a graph's step statuses.
+ */
+function deriveStatus(graph: WorkflowGraph): "pending" | "running" | "complete" {
+  const hasActive = graph.steps.some((s) => s.status === "active");
+  const allDone = graph.steps.every(
+    (s) => s.status === "complete" || s.status === "expanded",
+  );
+  if (allDone) return "complete";
+  if (hasActive) return "running";
+  return "pending";
+}
+
+// ─── Public API ──────────────────────────────────────────────────────────
+
+/**
+ * Create a new isolated run directory for a workflow definition.
+ *
+ * 1. Loads the definition from `<basePath>/.gsd/workflow-defs/<defName>.yaml`
+ * 2. Applies parameter substitution if overrides are provided
+ * 3. Creates `<basePath>/.gsd/workflow-runs/<defName>/<timestamp>/`
+ * 4. Writes frozen DEFINITION.yaml, initialized GRAPH.yaml, and optional PARAMS.json
+ *
+ * @param basePath — project root directory
+ * @param defName — definition filename (without .yaml extension)
+ * @param overrides — optional parameter overrides (merged with definition defaults)
+ * @returns Full path to the created run directory
+ * @throws Error if the definition file doesn't exist or is invalid
+ */
+export function createRun(
+  basePath: string,
+  defName: string,
+  overrides?: Record<string, string>,
+): string {
+  const defsDir = join(basePath, ".gsd", DEFS_DIR);
+
+  // Load and validate the definition
+  const rawDef = loadDefinition(defsDir, defName);
+
+  // Apply parameter substitution if overrides provided
+  const def: WorkflowDefinition = overrides
+    ? substituteParams(rawDef, overrides)
+    : substituteParams(rawDef); // still resolve default params if any
+
+  // Create the run directory
+  const timestamp = makeTimestamp();
+  const runDir = join(basePath, ".gsd", RUNS_DIR, defName, timestamp);
+  mkdirSync(runDir, { recursive: true });
+
+  // Freeze the definition as DEFINITION.yaml
+  writeFileSync(join(runDir, "DEFINITION.yaml"), stringify(def), "utf-8");
+
+  // Initialize and write GRAPH.yaml
+  const graph = initializeGraph(def);
+  writeGraph(runDir, graph);
+
+  // Write PARAMS.json if overrides were provided
+  if (overrides && Object.keys(overrides).length > 0) {
+    writeFileSync(
+      join(runDir, "PARAMS.json"),
+      JSON.stringify(overrides, null, 2),
+      "utf-8",
+    );
+  }
+
+  return runDir;
+}
+
+/**
+ * List existing workflow runs with metadata.
+ *
+ * Scans `<basePath>/.gsd/workflow-runs/` for run directories. Each run's
+ * GRAPH.yaml is read to derive step counts and overall status.
+ *
+ * @param basePath — project root directory
+ * @param defName — optional filter: only list runs for this definition name
+ * @returns Array of run metadata, sorted newest-first within each definition
+ */
+export function listRuns(basePath: string, defName?: string): RunMetadata[] {
+  const runsRoot = join(basePath, ".gsd", RUNS_DIR);
+  if (!existsSync(runsRoot)) return [];
+
+  const results: RunMetadata[] = [];
+
+  // Get workflow name directories
+  const nameDirs = defName ? [defName] : readdirSync(runsRoot).filter((entry) => {
+    const full = join(runsRoot, entry);
+    return statSync(full).isDirectory();
+  });
+
+  for (const name of nameDirs) {
+    const nameDir = join(runsRoot, name);
+    if (!existsSync(nameDir)) continue;
+
+    const timestamps = readdirSync(nameDir).filter((entry) => {
+      const full = join(nameDir, entry);
+      return statSync(full).isDirectory();
+    });
+
+    // Sort newest-first (ISO strings sort lexicographically)
+    timestamps.sort().reverse();
+
+    for (const ts of timestamps) {
+      const runDir = join(nameDir, ts);
+      try {
+        const graph = readGraph(runDir);
+        const total = graph.steps.length;
+        const completed = graph.steps.filter((s) => s.status === "complete").length;
+        const pending = graph.steps.filter((s) => s.status === "pending").length;
+        const active = graph.steps.filter((s) => s.status === "active").length;
+
+        results.push({
+          name,
+          timestamp: ts,
+          runDir,
+          steps: { total, completed, pending, active },
+          status: deriveStatus(graph),
+        });
+      } catch {
+        // Skip runs with invalid/missing GRAPH.yaml
+      }
+    }
+  }
+
+  return results;
+}

package/src/resources/extensions/gsd/tests/bundled-workflow-defs.test.ts

@@ -0,0 +1,180 @@
+/**
+ * Bundled workflow definition validation tests.
+ *
+ * Verifies that every example YAML in src/resources/skills/create-workflow/templates/
+ * passes validateDefinition() from definition-loader.ts with { valid: true, errors: [] }.
+ *
+ * Also validates scaffold template and structural properties of each example
+ * (step counts, feature usage) to guard against accidental regressions.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { parse } from "yaml";
+
+import { validateDefinition } from "../definition-loader.ts";
+
+// ─── Path resolution ─────────────────────────────────────────────────────
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+// Navigate from tests/ → extensions/gsd/ → extensions/ → resources/ → skills/create-workflow/templates/
+const templatesDir = join(
+  __dirname,
+  "..",
+  "..",
+  "..",
+  "skills",
+  "create-workflow",
+  "templates",
+);
+
+function loadYaml(filename: string): unknown {
+  const raw = readFileSync(join(templatesDir, filename), "utf-8");
+  return parse(raw);
+}
+
+// ─── Scaffold template ──────────────────────────────────────────────────
+
+test("scaffold template (workflow-definition.yaml) passes validation", () => {
+  const parsed = loadYaml("workflow-definition.yaml");
+  const result = validateDefinition(parsed);
+  assert.equal(result.valid, true, `Scaffold invalid: ${result.errors.join("; ")}`);
+  assert.equal(result.errors.length, 0);
+});
+
+// ─── blog-post-pipeline.yaml ────────────────────────────────────────────
+
+test("blog-post-pipeline.yaml passes validation", () => {
+  const parsed = loadYaml("blog-post-pipeline.yaml");
+  const result = validateDefinition(parsed);
+  assert.equal(result.valid, true, `Invalid: ${result.errors.join("; ")}`);
+  assert.equal(result.errors.length, 0);
+});
+
+test("blog-post-pipeline.yaml: 3 steps, context_from, params, content-heuristic", () => {
+  const parsed = loadYaml("blog-post-pipeline.yaml") as Record<string, unknown>;
+  const steps = parsed.steps as Array<Record<string, unknown>>;
+
+  // 3 steps
+  assert.equal(steps.length, 3, "Expected 3 steps");
+
+  // params defined
+  assert.ok(parsed.params, "Expected params to be defined");
+  const params = parsed.params as Record<string, string>;
+  assert.ok("topic" in params, "Expected 'topic' param");
+  assert.ok("audience" in params, "Expected 'audience' param");
+
+  // At least one step uses context_from
+  const hasContextFrom = steps.some(
+    (s) => Array.isArray(s.context_from) && s.context_from.length > 0,
+  );
+  assert.ok(hasContextFrom, "Expected at least one step with context_from");
+
+  // All steps use content-heuristic verify
+  for (const step of steps) {
+    const verify = step.verify as Record<string, unknown> | undefined;
+    assert.ok(verify, `Step "${step.id}" missing verify`);
+    assert.equal(verify.policy, "content-heuristic", `Step "${step.id}" should use content-heuristic`);
+  }
+});
+
+// ─── code-audit.yaml ────────────────────────────────────────────────────
+
+test("code-audit.yaml passes validation", () => {
+  const parsed = loadYaml("code-audit.yaml");
+  const result = validateDefinition(parsed);
+  assert.equal(result.valid, true, `Invalid: ${result.errors.join("; ")}`);
+  assert.equal(result.errors.length, 0);
+});
+
+test("code-audit.yaml: iterate with capture group and shell-command verify", () => {
+  const parsed = loadYaml("code-audit.yaml") as Record<string, unknown>;
+  const steps = parsed.steps as Array<Record<string, unknown>>;
+
+  // Find step with iterate
+  const iterateStep = steps.find((s) => s.iterate != null);
+  assert.ok(iterateStep, "Expected a step with iterate config");
+
+  const iterate = iterateStep.iterate as Record<string, unknown>;
+  assert.equal(typeof iterate.source, "string", "iterate.source must be a string");
+  assert.equal(typeof iterate.pattern, "string", "iterate.pattern must be a string");
+
+  // Pattern has a capture group
+  const pattern = iterate.pattern as string;
+  assert.ok(/\((?!\?)/.test(pattern), "iterate.pattern must contain a capture group");
+
+  // Pattern is valid regex
+  assert.doesNotThrow(() => new RegExp(pattern), "iterate.pattern must be valid regex");
+
+  // Has shell-command verify
+  const verify = iterateStep.verify as Record<string, unknown>;
+  assert.equal(verify.policy, "shell-command");
+  assert.equal(typeof verify.command, "string");
+});
+
+// ─── release-checklist.yaml ─────────────────────────────────────────────
+
+test("release-checklist.yaml passes validation", () => {
+  const parsed = loadYaml("release-checklist.yaml");
+  const result = validateDefinition(parsed);
+  assert.equal(result.valid, true, `Invalid: ${result.errors.join("; ")}`);
+  assert.equal(result.errors.length, 0);
+});
+
+test("release-checklist.yaml: diamond dependencies and human-review", () => {
+  const parsed = loadYaml("release-checklist.yaml") as Record<string, unknown>;
+  const steps = parsed.steps as Array<Record<string, unknown>>;
+
+  // 4 steps
+  assert.equal(steps.length, 4, "Expected 4 steps");
+
+  // Diamond pattern: two steps depend on the same parent
+  const changelog = steps.find((s) => s.id === "changelog");
+  const versionBump = steps.find((s) => s.id === "version-bump");
+  const testSuite = steps.find((s) => s.id === "test-suite");
+  const publish = steps.find((s) => s.id === "publish");
+
+  assert.ok(changelog, "Expected 'changelog' step");
+  assert.ok(versionBump, "Expected 'version-bump' step");
+  assert.ok(testSuite, "Expected 'test-suite' step");
+  assert.ok(publish, "Expected 'publish' step");
+
+  // Both version-bump and test-suite depend on changelog
+  const vbReqs = versionBump.requires as string[];
+  const tsReqs = testSuite.requires as string[];
+  assert.ok(vbReqs.includes("changelog"), "version-bump should require changelog");
+  assert.ok(tsReqs.includes("changelog"), "test-suite should require changelog");
+
+  // publish depends on both (diamond join)
+  const pubReqs = publish.requires as string[];
+  assert.ok(pubReqs.includes("version-bump"), "publish should require version-bump");
+  assert.ok(pubReqs.includes("test-suite"), "publish should require test-suite");
+
+  // publish uses human-review
+  const verify = publish.verify as Record<string, unknown>;
+  assert.equal(verify.policy, "human-review");
+});
+
+// ─── Cross-cutting: no path traversal in produces ───────────────────────
+
+test("no produces path contains '..'", () => {
+  const files = [
+    "blog-post-pipeline.yaml",
+    "code-audit.yaml",
+    "release-checklist.yaml",
+  ];
+
+  for (const file of files) {
+    const parsed = loadYaml(file) as Record<string, unknown>;
+    const steps = parsed.steps as Array<Record<string, unknown>>;
+    for (const step of steps) {
+      const produces = (step.produces as string[]) ?? [];
+      for (const p of produces) {
+        assert.ok(!p.includes(".."), `${file} step "${step.id}" produces path contains '..': ${p}`);
+      }
+    }
+  }
+});

package/src/resources/extensions/gsd/tests/commands-workflow-custom.test.ts

@@ -0,0 +1,283 @@
+/**
+ * commands-workflow-custom.test.ts — Tests for `/gsd workflow` subcommands
+ * and catalog completions.
+ *
+ * Uses real temp directories with actual definition YAML files.
+ */
+
+import { describe, it, afterEach, before } from "node:test";
+import assert from "node:assert/strict";
+import {
+  mkdtempSync,
+  rmSync,
+  mkdirSync,
+  writeFileSync,
+  existsSync,
+} from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+import { getGsdArgumentCompletions, TOP_LEVEL_SUBCOMMANDS } from "../commands/catalog.ts";
+
+// ─── Helpers ─────────────────────────────────────────────────────────────
+
+const tmpDirs: string[] = [];
+let savedCwd: string;
+
+function makeTmpBase(): string {
+  const dir = mkdtempSync(join(tmpdir(), "wf-cmd-test-"));
+  tmpDirs.push(dir);
+  return dir;
+}
+
+afterEach(() => {
+  // Restore cwd if changed during tests
+  if (savedCwd && process.cwd() !== savedCwd) {
+    process.chdir(savedCwd);
+  }
+  for (const d of tmpDirs) {
+    try { rmSync(d, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 }); } catch { /* Windows EPERM */ }
+  }
+  tmpDirs.length = 0;
+});
+
+before(() => {
+  savedCwd = process.cwd();
+});
+
+function createMockCtx() {
+  const notifications: { message: string; level: string }[] = [];
+  return {
+    notifications,
+    ui: {
+      notify(message: string, level: string) {
+        notifications.push({ message, level });
+      },
+      custom: async () => {},
+    },
+    shutdown: async () => {},
+    sessionManager: {
+      getSessionFile: () => null,
+    },
+  };
+}
+
+function createMockPi() {
+  return {
+    registerCommand() {},
+    registerTool() {},
+    registerShortcut() {},
+    on() {},
+    sendMessage() {},
+  };
+}
+
+/** Write a minimal valid workflow definition YAML to the expected location. */
+function writeDefinition(basePath: string, name: string, content: string): void {
+  const defsDir = join(basePath, ".gsd", "workflow-defs");
+  mkdirSync(defsDir, { recursive: true });
+  writeFileSync(join(defsDir, `${name}.yaml`), content, "utf-8");
+}
+
+const SIMPLE_DEF = `
+version: 1
+name: test-workflow
+description: A test workflow
+steps:
+  - id: step-1
+    name: First Step
+    prompt: Do step 1
+    requires: []
+    produces: []
+`;
+
+const INVALID_DEF = `
+version: 2
+name: bad-workflow
+steps: []
+`;
+
+// ─── Catalog Registration ────────────────────────────────────────────────
+
+describe("workflow catalog registration", () => {
+  it("workflow appears in TOP_LEVEL_SUBCOMMANDS", () => {
+    const entry = TOP_LEVEL_SUBCOMMANDS.find((c) => c.cmd === "workflow");
+    assert.ok(entry, "workflow should be in TOP_LEVEL_SUBCOMMANDS");
+    assert.ok(entry!.desc.includes("new"), "description should mention new");
+    assert.ok(entry!.desc.includes("run"), "description should mention run");
+  });
+
+  it("getGsdArgumentCompletions('workflow ') returns six subcommands", () => {
+    const completions = getGsdArgumentCompletions("workflow ");
+    const labels = completions.map((c: any) => c.label);
+    for (const sub of ["new", "run", "list", "validate", "pause", "resume"]) {
+      assert.ok(labels.includes(sub), `missing completion: ${sub}`);
+    }
+    assert.equal(labels.length, 6, "should have exactly 6 subcommands");
+  });
+
+  it("getGsdArgumentCompletions('workflow r') filters to run and resume", () => {
+    const completions = getGsdArgumentCompletions("workflow r");
+    const labels = completions.map((c: any) => c.label);
+    assert.ok(labels.includes("run"), "should include run");
+    assert.ok(labels.includes("resume"), "should include resume");
+    assert.ok(!labels.includes("list"), "should not include list");
+  });
+
+  it("getGsdArgumentCompletions('workflow run ') returns definition names", () => {
+    const base = makeTmpBase();
+    writeDefinition(base, "deploy-pipeline", SIMPLE_DEF);
+    writeDefinition(base, "test-suite", SIMPLE_DEF);
+
+    // Change cwd so the completion scanner can find `.gsd/workflow-defs/`
+    process.chdir(base);
+
+    const completions = getGsdArgumentCompletions("workflow run ");
+    const labels = completions.map((c: any) => c.label);
+    assert.ok(labels.includes("deploy-pipeline"), "should include deploy-pipeline");
+    assert.ok(labels.includes("test-suite"), "should include test-suite");
+  });
+
+  it("getGsdArgumentCompletions('workflow validate ') returns definition names", () => {
+    const base = makeTmpBase();
+    writeDefinition(base, "my-workflow", SIMPLE_DEF);
+
+    process.chdir(base);
+
+    const completions = getGsdArgumentCompletions("workflow validate ");
+    const labels = completions.map((c: any) => c.label);
+    assert.ok(labels.includes("my-workflow"), "should include my-workflow");
+  });
+
+  it("getGsdArgumentCompletions('workflow run d') filters by prefix", () => {
+    const base = makeTmpBase();
+    writeDefinition(base, "deploy-pipeline", SIMPLE_DEF);
+    writeDefinition(base, "test-suite", SIMPLE_DEF);
+
+    process.chdir(base);
+
+    const completions = getGsdArgumentCompletions("workflow run d");
+    const labels = completions.map((c: any) => c.label);
+    assert.ok(labels.includes("deploy-pipeline"), "should include deploy-pipeline");
+    assert.ok(!labels.includes("test-suite"), "should not include test-suite");
+  });
+});
+
+// ─── Command Handler Tests ───────────────────────────────────────────────
+
+describe("workflow command handler", () => {
+  // Dynamically import the handler so module-level side effects
+  // don't break when auto.ts pulls in heavy runtime deps.
+  // We test the pure routing logic by calling handleWorkflowCommand directly.
+
+  async function callHandler(trimmed: string) {
+    const { handleWorkflowCommand } = await import("../commands/handlers/workflow.ts");
+    const ctx = createMockCtx();
+    const pi = createMockPi();
+    const handled = await handleWorkflowCommand(trimmed, ctx as any, pi as any);
+    return { handled, notifications: ctx.notifications };
+  }
+
+  it("bare '/gsd workflow' shows usage", async () => {
+    const { handled, notifications } = await callHandler("workflow");
+    assert.ok(handled, "should be handled");
+    assert.ok(
+      notifications.some((n) => n.message.includes("Usage: /gsd workflow")),
+      "should show usage",
+    );
+  });
+
+  it("'/gsd workflow new' shows skill invocation message", async () => {
+    const { handled, notifications } = await callHandler("workflow new");
+    assert.ok(handled, "should be handled");
+    assert.ok(
+      notifications.some((n) => n.message.includes("create-workflow")),
+      "should mention create-workflow skill",
+    );
+  });
+
+  it("'/gsd workflow run' without name shows usage warning", async () => {
+    const { handled, notifications } = await callHandler("workflow run");
+    assert.ok(handled, "should be handled");
+    assert.ok(
+      notifications.some((n) => n.level === "warning" && n.message.includes("Usage")),
+      "should show usage warning",
+    );
+  });
+
+  it("'/gsd workflow run nonexistent' shows error for missing definition", async () => {
+    const { handled, notifications } = await callHandler("workflow run nonexistent-def-12345");
+    assert.ok(handled, "should be handled");
+    assert.ok(
+      notifications.some((n) => n.level === "error" && n.message.includes("not found")),
+      "should show definition-not-found error",
+    );
+  });
+
+  it("'/gsd workflow validate' without name shows usage warning", async () => {
+    const { handled, notifications } = await callHandler("workflow validate");
+    assert.ok(handled, "should be handled");
+    assert.ok(
+      notifications.some((n) => n.level === "warning" && n.message.includes("Usage")),
+      "should show usage warning",
+    );
+  });
+
+  it("'/gsd workflow validate nonexistent' shows definition not found", async () => {
+    const { handled, notifications } = await callHandler("workflow validate nonexistent-def-12345");
+    assert.ok(handled, "should be handled");
+    assert.ok(
+      notifications.some((n) => n.level === "error" && n.message.includes("not found")),
+      "should show not-found error",
+    );
+  });
+
+  it("'/gsd workflow pause' without custom engine shows warning", async () => {
+    const { handled, notifications } = await callHandler("workflow pause");
+    assert.ok(handled, "should be handled");
+    assert.ok(
+      notifications.some((n) => n.level === "warning"),
+      "should show warning when no custom workflow is running",
+    );
+  });
+
+  it("'/gsd workflow resume' without custom engine shows warning", async () => {
+    const { handled, notifications } = await callHandler("workflow resume");
+    assert.ok(handled, "should be handled");
+    assert.ok(
+      notifications.some((n) => n.level === "warning"),
+      "should show warning when no custom workflow to resume",
+    );
+  });
+
+  it("'/gsd workflow unknown-sub' shows unknown subcommand", async () => {
+    const { handled, notifications } = await callHandler("workflow blurble");
+    assert.ok(handled, "should be handled");
+    assert.ok(
+      notifications.some((n) => n.message.includes("Unknown workflow subcommand")),
+      "should show unknown subcommand message",
+    );
+  });
+
+  it("'/gsd workflow list' with no runs shows empty message", async () => {
+    const { handled, notifications } = await callHandler("workflow list");
+    assert.ok(handled, "should be handled");
+    assert.ok(
+      notifications.some((n) => n.message.includes("No workflow runs found")),
+      "should show no runs message",
+    );
+  });
+
+  it("non-workflow commands are not intercepted by custom workflow routing", async () => {
+    const { handleWorkflowCommand } = await import("../commands/handlers/workflow.ts");
+    const ctx = createMockCtx();
+    const pi = createMockPi();
+    // "queue" does not start with "workflow" so the custom routing should not handle it.
+    // The function may still handle it via its existing dev-workflow routing, but it
+    // should not be captured by the custom workflow `if` block.
+    // We verify this by checking that a clearly non-workflow command like "somethingelse"
+    // returns false (unhandled).
+    const handled = await handleWorkflowCommand("somethingelse", ctx as any, pi as any);
+    assert.equal(handled, false, "non-workflow commands should return false");
+  });
+});