@harms-haus/pi-workflows 1.0.0

package/src/config/loading-parse.ts

@@ -0,0 +1,205 @@
+import { parse as yamlParse } from "yaml";
+import type { PhaseToolConfig } from "../types";
+
+// ── Types ──
+
+/** Shape of the raw YAML workflow data before validation. */
+export interface RawWorkflowYaml {
+  name?: unknown;
+  commandName?: unknown;
+  initialMessage?: unknown;
+  show?: unknown;
+  phases?: unknown;
+  loopable?: unknown;
+  sessionNamePrefix?: unknown;
+  sessionNameMaxLength?: unknown;
+  roleInstruction?: unknown;
+  advanceReminder?: unknown;
+  blockReasonTemplate?: unknown;
+  completionMessage?: unknown;
+  notDoneReminder?: unknown;
+}
+
+/** Parsed workflow data extracted from a workflow.yaml file. */
+export interface ParsedWorkflow {
+  name: string;
+  commandName: string;
+  initialMessage: string;
+  show?: "workflows";
+  loopable?: boolean;
+  sessionNamePrefix?: string;
+  sessionNameMaxLength?: number;
+  roleInstruction?: string;
+  advanceReminder?: string;
+  blockReasonTemplate?: string;
+  completionMessage?: string;
+  notDoneReminder?: string;
+  /** Raw phase entries from the YAML (string filenames or subworkflow ref objects). */
+  rawPhases: unknown[];
+}
+
+/** Parsed phase metadata extracted from a phase .md file's frontmatter. */
+export interface PhaseMetadata {
+  id: string;
+  name: string;
+  emoji: string;
+  instructions: string;
+  tools?: PhaseToolConfig;
+  availableProfiles?: string[];
+}
+
+// ── Workflow YAML Parsing ──
+
+/** Parse the YAML string and return it typed, or null if not a valid object. */
+function validateYamlObject(yamlContent: string, sourcePath: string): RawWorkflowYaml | null {
+  const parsed: unknown = yamlParse(yamlContent);
+  if (!parsed || typeof parsed !== "object") {
+    console.warn(`[pi-workflows] Invalid workflow.yaml in ${sourcePath}: not a valid YAML object`);
+    return null;
+  }
+  return parsed;
+}
+
+/** Extract the show field from parsed YAML. */
+function parseShowField(raw: RawWorkflowYaml): "workflows" | undefined {
+  return raw.show === "workflows" ? "workflows" : undefined;
+}
+
+/** Validate and extract required fields (name, commandName, initialMessage). */
+function extractRequiredFields(
+  raw: RawWorkflowYaml,
+  sourcePath: string,
+  show: "workflows" | undefined,
+): { name: string; commandName: string; initialMessage: string } | null {
+  if (typeof raw.name !== "string" || !raw.name) {
+    console.warn(`[pi-workflows] Missing or invalid "name" in ${sourcePath}`);
+    return null;
+  }
+
+  let commandName: string;
+  let initialMessage: string;
+
+  if (show === "workflows") {
+    commandName = typeof raw.commandName === "string" ? raw.commandName : "";
+    initialMessage = typeof raw.initialMessage === "string" ? raw.initialMessage : "";
+  } else {
+    if (typeof raw.commandName !== "string" || !raw.commandName) {
+      console.warn(`[pi-workflows] Missing or invalid "commandName" in ${sourcePath}`);
+      return null;
+    }
+    if (typeof raw.initialMessage !== "string" || !raw.initialMessage) {
+      console.warn(`[pi-workflows] Missing or invalid "initialMessage" in ${sourcePath}`);
+      return null;
+    }
+    commandName = raw.commandName;
+    initialMessage = raw.initialMessage;
+  }
+
+  return { name: raw.name, commandName, initialMessage };
+}
+
+/** Set optional string/number/boolean fields on the parsed workflow. */
+function setOptionalFields(raw: RawWorkflowYaml, target: ParsedWorkflow): void {
+  if (typeof raw.loopable === "boolean") target.loopable = raw.loopable;
+  if (typeof raw.sessionNamePrefix === "string") target.sessionNamePrefix = raw.sessionNamePrefix;
+  if (typeof raw.sessionNameMaxLength === "number")
+    target.sessionNameMaxLength = raw.sessionNameMaxLength;
+  if (typeof raw.roleInstruction === "string") target.roleInstruction = raw.roleInstruction;
+  if (typeof raw.advanceReminder === "string") target.advanceReminder = raw.advanceReminder;
+  if (typeof raw.blockReasonTemplate === "string")
+    target.blockReasonTemplate = raw.blockReasonTemplate;
+  if (typeof raw.completionMessage === "string") target.completionMessage = raw.completionMessage;
+  if (typeof raw.notDoneReminder === "string") target.notDoneReminder = raw.notDoneReminder;
+}
+
+/**
+ * Parse a workflow.yaml content string and extract all fields.
+ * Returns a ParsedWorkflow object with extracted fields, or null if invalid.
+ */
+export function parseWorkflowYaml(yamlContent: string, sourcePath: string): ParsedWorkflow | null {
+  const raw = validateYamlObject(yamlContent, sourcePath);
+  if (!raw) return null;
+
+  const show = parseShowField(raw);
+  const required = extractRequiredFields(raw, sourcePath, show);
+  if (!required) return null;
+
+  if (!Array.isArray(raw.phases) || raw.phases.length < 1) {
+    console.warn(`[pi-workflows] Missing or invalid "phases" array in ${sourcePath}`);
+    return null;
+  }
+
+  const result: ParsedWorkflow = {
+    ...required,
+    rawPhases: raw.phases,
+  };
+
+  if (show !== undefined) result.show = show;
+  setOptionalFields(raw, result);
+
+  return result;
+}
+
+// ── Phase Metadata Extraction ──
+
+/** Extract optional tools config from frontmatter.tools */
+function extractToolsConfig(toolsRaw: unknown): PhaseToolConfig | undefined {
+  if (!toolsRaw || typeof toolsRaw !== "object" || Array.isArray(toolsRaw)) {
+    return undefined;
+  }
+  const toolsConfig = toolsRaw as Record<string, unknown>;
+  const tools: PhaseToolConfig = {};
+
+  if (Array.isArray(toolsConfig.blacklist)) {
+    tools.blacklist = toolsConfig.blacklist.map(String);
+  }
+  if (Array.isArray(toolsConfig.whitelist)) {
+    tools.whitelist = toolsConfig.whitelist.map(String);
+  }
+
+  return tools.blacklist || tools.whitelist ? tools : undefined;
+}
+
+/** Extract optional available profiles from frontmatter.availableProfiles */
+function extractAvailableProfiles(profilesRaw: unknown): string[] | undefined {
+  if (!Array.isArray(profilesRaw)) return undefined;
+  return profilesRaw.map(String);
+}
+
+/**
+ * Extract phase metadata from a parsed frontmatter/YAML object.
+ * Returns a PhaseMetadata object, or null if required fields are missing.
+ */
+export function extractPhaseMetadata(phaseYaml: unknown, phaseId: string): PhaseMetadata | null {
+  if (!phaseYaml || typeof phaseYaml !== "object") {
+    console.warn(`[pi-workflows] Invalid frontmatter in phase ${phaseId}`);
+    return null;
+  }
+
+  const frontmatter = phaseYaml as Record<string, unknown>;
+
+  if (typeof frontmatter.id !== "string" || !frontmatter.id) {
+    console.warn(`[pi-workflows] Missing or invalid "id" in ${phaseId}`);
+    return null;
+  }
+  if (typeof frontmatter.name !== "string" || !frontmatter.name) {
+    console.warn(`[pi-workflows] Missing or invalid "name" in ${phaseId}`);
+    return null;
+  }
+  if (typeof frontmatter.emoji !== "string" || !frontmatter.emoji) {
+    console.warn(`[pi-workflows] Missing or invalid "emoji" in ${phaseId}`);
+    return null;
+  }
+
+  const metadata: PhaseMetadata = {
+    id: frontmatter.id,
+    name: frontmatter.name,
+    emoji: frontmatter.emoji,
+    instructions: "",
+  };
+
+  metadata.tools = extractToolsConfig(frontmatter.tools);
+  metadata.availableProfiles = extractAvailableProfiles(frontmatter.availableProfiles);
+
+  return metadata;
+}

package/src/config/loading-phases.ts

@@ -0,0 +1,78 @@
+import { readFileSync, realpathSync } from "node:fs";
+import { resolve, sep } from "node:path";
+import { parseFrontmatter } from "@earendil-works/pi-coding-agent";
+import type { PhaseDefinition } from "../types";
+import { extractPhaseMetadata } from "./loading-parse";
+
+// ── Path Safety ──
+
+/**
+ * Check that a phase file path does not escape the workflows root directory.
+ * Validates by resolving both the canonical root and the phase file path,
+ * then ensuring the phase path is a subpath of the root.
+ *
+ * @param phaseEntry - Relative phase filename from the YAML
+ * @param dirPath - Directory containing the workflow.yaml
+ * @param workflowsRoot - Parent directory containing all workflows
+ * @param yamlPath - Path to workflow.yaml (used in warning messages)
+ * @returns true if the path is safe, false otherwise
+ */
+export function checkPathSafety(
+  phaseEntry: string,
+  dirPath: string,
+  workflowsRoot: string,
+  yamlPath: string,
+): boolean {
+  const canonicalRoot = realpathSync(resolve(workflowsRoot));
+  const phaseFilePath = resolve(dirPath, phaseEntry);
+  try {
+    const canonicalPhase = realpathSync(phaseFilePath);
+    if (!canonicalPhase.startsWith(canonicalRoot + sep)) {
+      console.warn(
+        `[pi-workflows] Phase file path escapes workflows root: ${phaseEntry} in ${yamlPath}`,
+      );
+      return false;
+    }
+  } catch {
+    const resolvedPath = resolve(dirPath, phaseEntry);
+    if (!resolvedPath.startsWith(canonicalRoot + sep)) {
+      console.warn(
+        `[pi-workflows] Phase file path escapes workflows root: ${phaseEntry} in ${yamlPath}`,
+      );
+      return false;
+    }
+  }
+  return true;
+}
+
+// ── Phase Loading ──
+
+/**
+ * Load a phase definition from a markdown file with frontmatter.
+ *
+ * Expects the file to contain YAML frontmatter with required fields:
+ * `id`, `name`, `emoji`, and optional `tools` and `availableProfiles`.
+ * The body (after frontmatter) becomes the phase instructions.
+ *
+ * @param phasePath - Absolute path to the .md phase file
+ * @returns Parsed PhaseDefinition, or null if the file is invalid
+ */
+export function loadPhaseFromMarkdown(phasePath: string): PhaseDefinition | null {
+  const phaseContent = readFileSync(phasePath, "utf-8");
+  const { frontmatter, body } = parseFrontmatter(phaseContent);
+
+  const metadata = extractPhaseMetadata(frontmatter, phasePath);
+  if (!metadata) return null;
+
+  const phase: PhaseDefinition = {
+    id: metadata.id,
+    name: metadata.name,
+    emoji: metadata.emoji,
+    instructions: body.trim(),
+  };
+
+  if (metadata.tools) phase.tools = metadata.tools;
+  if (metadata.availableProfiles) phase.availableProfiles = metadata.availableProfiles;
+
+  return phase;
+}

package/src/config/loading-resolve.ts

@@ -0,0 +1,82 @@
+import type { WorkflowDefinition } from "../types";
+import { isSubworkflowRef } from "../types";
+import { detectCycles } from "./validation";
+
+// ── Post-processing helpers for loadWorkflows ──
+
+/** Remove entries with given keys from the record, returning a new record. */
+export function removeKeys(
+  record: Record<string, WorkflowDefinition>,
+  keys: Iterable<string>,
+): Record<string, WorkflowDefinition> {
+  const keySet = new Set(keys);
+  return Object.fromEntries(Object.entries(record).filter(([k]) => !keySet.has(k)));
+}
+
+/** Detect and remove workflow definitions with cyclic subworkflow references. */
+export function removeCycles(
+  valid: Record<string, WorkflowDefinition>,
+): Record<string, WorkflowDefinition> {
+  const cycleErrors = detectCycles(valid);
+  if (cycleErrors.length === 0) return valid;
+
+  const cycleKeys = new Set<string>();
+  for (const msg of cycleErrors) {
+    console.warn(`[pi-workflows] ${msg}`);
+    const match = msg.match(/^Cycle detected: (.+?)\. /);
+    if (match && match[1] !== undefined) {
+      for (const k of match[1].split(" → ")) {
+        cycleKeys.add(k);
+      }
+    }
+  }
+  return removeKeys(valid, cycleKeys);
+}
+
+/** Resolve subworkflow references, removing definitions with broken references. */
+export function resolveSubworkflowRefs(
+  valid: Record<string, WorkflowDefinition>,
+): Record<string, WorkflowDefinition> {
+  let current = valid;
+  let changed = true;
+  while (changed) {
+    changed = false;
+    const keysToRemove: string[] = [];
+    for (const [key, def] of Object.entries(current)) {
+      for (const phase of def.phases) {
+        if (isSubworkflowRef(phase) && phase.resolved === null) {
+          const targetDef = current[phase.workflowKey];
+          if (!(phase.workflowKey in current) || !targetDef) {
+            console.warn(
+              `[pi-workflows] Workflow "${key}" references non-existent subworkflow "${phase.workflowKey}". Skipping.`,
+            );
+            keysToRemove.push(key);
+            break;
+          }
+          phase.resolved = targetDef;
+        }
+      }
+    }
+    if (keysToRemove.length > 0) {
+      current = removeKeys(current, keysToRemove);
+      changed = true;
+    }
+  }
+  return current;
+}
+
+/** Warn about duplicate commandNames across workflows. */
+export function checkDuplicateCommandNames(valid: Record<string, WorkflowDefinition>): void {
+  const commandNameMap = new Map<string, string>();
+  for (const [key, def] of Object.entries(valid)) {
+    if (!def.commandName) continue;
+    const existing = commandNameMap.get(def.commandName);
+    if (existing) {
+      console.warn(
+        `[pi-workflows] Duplicate commandName "${def.commandName}" in workflows "${existing}" and "${key}". The first one found will be used.`,
+      );
+    } else {
+      commandNameMap.set(def.commandName, key);
+    }
+  }
+}

package/src/config/loading.ts

@@ -0,0 +1,202 @@
+import { readdirSync, readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import type { WorkflowDefinition, PhaseEntry } from "../types";
+import { validateWorkflowDefinition } from "./validation";
+import { parseWorkflowYaml } from "./loading-parse";
+import { checkPathSafety, loadPhaseFromMarkdown } from "./loading-phases";
+import {
+  removeCycles,
+  resolveSubworkflowRefs,
+  checkDuplicateCommandNames,
+} from "./loading-resolve";
+
+// ── Lookup ──
+
+/**
+ * Find a workflow by its commandName.
+ * Returns [key, definition] tuple or null.
+ */
+export function findWorkflowByCommandName(
+  workflows: Record<string, WorkflowDefinition>,
+  commandName: string,
+): [string, WorkflowDefinition] | null {
+  for (const [key, def] of Object.entries(workflows)) {
+    if (def.commandName === commandName) {
+      return [key, def];
+    }
+  }
+  return null;
+}
+
+// ── Phase Entry Loading ──
+
+/** Load a single phase entry (string filename or subworkflow reference). */
+function loadPhaseEntry(
+  phaseEntry: unknown,
+  dirPath: string,
+  workflowsRoot: string,
+  yamlPath: string,
+): PhaseEntry | null {
+  if (typeof phaseEntry === "string") {
+    if (!checkPathSafety(phaseEntry, dirPath, workflowsRoot, yamlPath)) return null;
+    const phasePath = join(dirPath, phaseEntry);
+    try {
+      return loadPhaseFromMarkdown(phasePath);
+    } catch (phaseErr) {
+      const msg = phaseErr instanceof Error ? phaseErr.message : String(phaseErr);
+      console.warn(`[pi-workflows] Failed to load phase file ${phasePath}: ${msg}`);
+      return null;
+    }
+  }
+
+  if (
+    typeof phaseEntry === "object" &&
+    phaseEntry !== null &&
+    typeof (phaseEntry as Record<string, unknown>).subworkflow === "string"
+  ) {
+    return {
+      subworkflow: true,
+      workflowKey: String((phaseEntry as Record<string, unknown>).subworkflow),
+      resolved: null,
+    };
+  }
+
+  console.warn(
+    `[pi-workflows] Invalid phase entry in ${yamlPath}: expected string or { subworkflow: key } object`,
+  );
+  return null;
+}
+
+/** Load all phase entries from raw phase data. */
+function loadPhases(
+  rawPhases: unknown[],
+  yamlPath: string,
+  dirPath: string,
+  workflowsRoot: string,
+): PhaseEntry[] | null {
+  const phases: PhaseEntry[] = [];
+  for (const entry of rawPhases) {
+    const phase = loadPhaseEntry(entry, dirPath, workflowsRoot, yamlPath);
+    if (phase === null) return null;
+    phases.push(phase);
+  }
+  return phases;
+}
+
+// ── Loading from Directory ──
+
+/**
+ * Load a single workflow from a directory containing workflow.yaml and phase .md files.
+ * Returns null if the directory is not a valid workflow directory.
+ */
+export function loadWorkflowFromDir(
+  dirPath: string,
+  workflowsRoot: string,
+): WorkflowDefinition | null {
+  const yamlPath = join(dirPath, "workflow.yaml");
+  if (!existsSync(yamlPath)) return null;
+
+  try {
+    const yamlContent = readFileSync(yamlPath, "utf-8");
+    const parsed = parseWorkflowYaml(yamlContent, dirPath);
+    if (!parsed) return null;
+
+    const phases = loadPhases(parsed.rawPhases, yamlPath, dirPath, workflowsRoot);
+    if (!phases) return null;
+
+    const workflow: WorkflowDefinition = {
+      name: parsed.name,
+      commandName: parsed.commandName,
+      initialMessage: parsed.initialMessage,
+      phases,
+    };
+
+    if (parsed.show !== undefined) workflow.show = parsed.show;
+    if (parsed.loopable !== undefined) workflow.loopable = parsed.loopable;
+    if (parsed.sessionNamePrefix !== undefined)
+      workflow.sessionNamePrefix = parsed.sessionNamePrefix;
+    if (parsed.sessionNameMaxLength !== undefined)
+      workflow.sessionNameMaxLength = parsed.sessionNameMaxLength;
+    if (parsed.roleInstruction !== undefined) workflow.roleInstruction = parsed.roleInstruction;
+    if (parsed.advanceReminder !== undefined) workflow.advanceReminder = parsed.advanceReminder;
+    if (parsed.blockReasonTemplate !== undefined)
+      workflow.blockReasonTemplate = parsed.blockReasonTemplate;
+    if (parsed.completionMessage !== undefined)
+      workflow.completionMessage = parsed.completionMessage;
+    if (parsed.notDoneReminder !== undefined) workflow.notDoneReminder = parsed.notDoneReminder;
+
+    return workflow;
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    console.warn(`[pi-workflows] Failed to load workflow from ${dirPath}: ${msg}`);
+    return null;
+  }
+}
+
+/**
+ * Scan a parent directory for workflow subdirectories and load each one.
+ * Returns a record keyed by directory name.
+ */
+export function loadWorkflowsFromDir(parentDir: string): Record<string, WorkflowDefinition> {
+  const definitions: Record<string, WorkflowDefinition> = {};
+
+  if (!existsSync(parentDir)) return definitions;
+
+  try {
+    const entries = readdirSync(parentDir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+
+      try {
+        const workflow = loadWorkflowFromDir(join(parentDir, entry.name), parentDir);
+        if (workflow) {
+          definitions[entry.name] = workflow;
+        }
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.warn(`[pi-workflows] Error loading workflow from ${entry.name}: ${msg}`);
+      }
+    }
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    console.warn(`[pi-workflows] Failed to read workflow directory ${parentDir}: ${msg}`);
+  }
+
+  return definitions;
+}
+
+// ── Loading ──
+
+/**
+ * Load workflow definitions from global and project-local workflow directories.
+ * Project definitions override global definitions with the same key.
+ * Invalid definitions are excluded with a console.warn.
+ */
+export function loadWorkflows(cwd?: string): Record<string, WorkflowDefinition> {
+  const agentDir = process.env.PI_CODING_AGENT_DIR ?? join(homedir(), ".pi", "agent");
+  const globalDir = join(agentDir, "workflows");
+  const projectDir = cwd ? join(cwd, ".pi", "workflows") : "";
+
+  const globalDefs = loadWorkflowsFromDir(globalDir);
+  const projectDefs = projectDir ? loadWorkflowsFromDir(projectDir) : {};
+
+  const merged: Record<string, WorkflowDefinition> = { ...globalDefs, ...projectDefs };
+
+  // Validate and filter
+  const valid: Record<string, WorkflowDefinition> = {};
+  for (const [key, def] of Object.entries(merged)) {
+    const err = validateWorkflowDefinition(key, def);
+    if (err) {
+      console.warn(`[pi-workflows] Skipping invalid workflow definition "${key}": ${err}`);
+    } else {
+      valid[key] = def;
+    }
+  }
+
+  let resolved = removeCycles(valid);
+  resolved = resolveSubworkflowRefs(resolved);
+  checkDuplicateCommandNames(resolved);
+
+  return resolved;
+}

package/src/config/templates.ts

@@ -0,0 +1,25 @@
+import type { PhaseDefinition } from "../types";
+
+// ── Template Resolution ──
+
+/**
+ * Replaces {varName} occurrences in template with values from vars.
+ * Unknown variables are left as-is.
+ */
+export function resolveTemplate(template: string, vars: Record<string, string>): string {
+  return template.replace(/\{(\w+)\}/g, (_match, key: string) => {
+    return Object.hasOwn(vars, key) ? (vars[key] as string) : `{${key}}`;
+  });
+}
+
+// ── Utility: get blocked/allowed tools for a phase ──
+
+export function getBlockedTools(phase: PhaseDefinition): string[] {
+  if (phase.tools?.blacklist) return [...phase.tools.blacklist];
+  return [];
+}
+
+export function getWhitelist(phase: PhaseDefinition): string[] | null {
+  if (phase.tools?.whitelist) return [...phase.tools.whitelist];
+  return null;
+}