@yycholla/pi-dynamic-workflows 3.3.0

package/src/workflow-saved.ts

@@ -0,0 +1,180 @@
+/**
+ * Save and load reusable workflow commands.
+ */
+
+import { join } from "node:path";
+import {
+  ensureDir as ensureDirFs,
+  listJsonFilesSafe,
+  type PersistenceFsLayer,
+  readJsonWithBackupRecovery,
+  resolvePersistenceFs,
+  unlinkIfExistsSafe,
+  writeJsonAtomicWithBackup,
+} from "./fs-persistence.js";
+import { workflowProjectPaths, workflowUserSavedDir } from "./workflow-paths.js";
+
+export interface SavedWorkflow {
+  /** Command name (filename without extension). */
+  name: string;
+  /** Human-readable description. */
+  description: string;
+  /** The workflow script. */
+  script: string;
+  /** Optional parameter schema for parameterized workflows. */
+  parameters?: Record<string, { type: string; description?: string; required?: boolean; default?: unknown }>;
+  /** Where this workflow is saved. */
+  location: "project" | "user";
+  /** Full file path. */
+  path: string;
+  /** When it was saved. */
+  savedAt: string;
+}
+
+export interface WorkflowStorage {
+  /** Save a workflow. */
+  save(workflow: Omit<SavedWorkflow, "path" | "savedAt">, location?: "project" | "user"): SavedWorkflow;
+  /** Load a workflow by name. */
+  load(name: string): SavedWorkflow | null;
+  /** List all saved workflows. */
+  list(): SavedWorkflow[];
+  /** Delete a saved workflow. */
+  delete(name: string, location?: "project" | "user"): boolean;
+}
+
+export function isSafeSavedWorkflowName(name: string): boolean {
+  return (
+    name.length > 0 &&
+    name.length <= 128 &&
+    name.trim() === name &&
+    name !== "." &&
+    name !== ".." &&
+    !/[/\\\0]/.test(name)
+  );
+}
+
+export function assertSafeSavedWorkflowName(name: string): void {
+  if (!isSafeSavedWorkflowName(name)) {
+    throw new Error("Saved workflow name must be a non-empty path-safe name without slashes.");
+  }
+}
+
+export function createWorkflowStorage(cwd: string, fsOverride?: Partial<PersistenceFsLayer>): WorkflowStorage {
+  const fs = resolvePersistenceFs(fsOverride);
+  const paths = workflowProjectPaths(cwd);
+  const projectDir = paths.savedDir;
+  const legacyProjectDir = paths.legacySavedDir;
+  const userDir = workflowUserSavedDir();
+
+  const ensureDir = (dir: string) => ensureDirFs(fs, dir);
+
+  const workflowPath = (name: string, location: "project" | "user") => {
+    assertSafeSavedWorkflowName(name);
+    const dir = location === "project" ? projectDir : userDir;
+    return join(dir, `${name}.json`);
+  };
+  const legacyProjectWorkflowPath = (name: string) => {
+    assertSafeSavedWorkflowName(name);
+    return join(legacyProjectDir, `${name}.json`);
+  };
+
+  // Same atomic-write-with-backup + corrupt-file recovery contract as
+  // run-persistence.ts (see fs-persistence.ts) — a saved workflow is a
+  // user-authored artifact just as worth protecting from a crash mid-write
+  // or a truncated file as a run's resumable state is.
+  const loadFromFile = (path: string, location: "project" | "user"): SavedWorkflow | null => {
+    const data = readJsonWithBackupRecovery<Record<string, unknown>>(fs, path);
+    if (!data || typeof data !== "object" || !isSafeSavedWorkflowName((data as { name?: string }).name ?? "")) {
+      return null;
+    }
+    return {
+      ...(data as Omit<SavedWorkflow, "location" | "path">),
+      location,
+      path,
+    };
+  };
+
+  return {
+    save(workflow, location = "project") {
+      assertSafeSavedWorkflowName(workflow.name);
+      const dir = location === "project" ? projectDir : userDir;
+      ensureDir(dir);
+
+      const path = workflowPath(workflow.name, location);
+      const saved: SavedWorkflow = {
+        ...workflow,
+        location,
+        path,
+        savedAt: new Date().toISOString(),
+      };
+
+      writeJsonAtomicWithBackup(fs, path, saved);
+      return saved;
+    },
+
+    load(name: string): SavedWorkflow | null {
+      if (!isSafeSavedWorkflowName(name)) return null;
+      // Project takes precedence over user
+      const projectPath = workflowPath(name, "project");
+      const project = loadFromFile(projectPath, "project");
+      if (project) return project;
+
+      const legacyProject = loadFromFile(legacyProjectWorkflowPath(name), "project");
+      if (legacyProject) return legacyProject;
+
+      const userPath = workflowPath(name, "user");
+      return loadFromFile(userPath, "user");
+    },
+
+    list(): SavedWorkflow[] {
+      const workflows: SavedWorkflow[] = [];
+
+      const seen = new Set<string>();
+      const addDir = (dir: string, location: "project" | "user") => {
+        // A missing or unreadable directory (not yet created, deleted
+        // mid-race, permission-denied) degrades to "no files" here — same
+        // guard run-persistence.ts's list() uses — rather than throwing and
+        // taking down the whole listing over one bad storage location.
+        for (const file of listJsonFilesSafe(fs, dir)) {
+          const wf = loadFromFile(join(dir, file), location);
+          if (wf && !seen.has(wf.name)) {
+            seen.add(wf.name);
+            workflows.push(wf);
+          }
+        }
+      };
+
+      // Priority order mirrors load(): project > legacy project > user.
+      addDir(projectDir, "project");
+      addDir(legacyProjectDir, "project");
+      addDir(userDir, "user");
+
+      return workflows.sort((a, b) => a.name.localeCompare(b.name));
+    },
+
+    delete(name: string, location?: "project" | "user"): boolean {
+      if (!isSafeSavedWorkflowName(name)) return false;
+      const locations = location ? [location] : (["project", "user"] as const);
+      let deleted = false;
+
+      for (const loc of locations) {
+        const path = workflowPath(name, loc);
+        // Clean up the .bak sidecar too, mirroring run-persistence.ts's delete()
+        // (sidecar cleanup does not by itself count as "deleted the workflow").
+        unlinkIfExistsSafe(fs, `${path}.bak`);
+        if (unlinkIfExistsSafe(fs, path)) {
+          deleted = true;
+        }
+        if (loc === "project") {
+          const legacyPath = legacyProjectWorkflowPath(name);
+          unlinkIfExistsSafe(fs, `${legacyPath}.bak`);
+          if (unlinkIfExistsSafe(fs, legacyPath)) {
+            deleted = true;
+          }
+        }
+      }
+
+      return deleted;
+    },
+  };
+}

package/src/workflow-settings.ts

@@ -0,0 +1,194 @@
+/**
+ * User-level settings for pi-dynamic-workflows.
+ *
+ * Stored separately from Pi's own settings.json so extension preferences remain
+ * stable without depending on host-internal config shape.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { MAX_AGENT_RETRIES, MAX_CONCURRENCY, normalizeKeywordTriggerWord } from "./config.js";
+import { workflowHomeDir, workflowProjectPaths } from "./workflow-paths.js";
+
+export interface WorkflowSettings {
+  keywordTriggerEnabled?: boolean;
+  /** Literal keyword that arms workflows mode from interactive input. */
+  keywordTriggerWord?: string;
+  defaultAgentTimeoutMs?: number | null;
+  /**
+   * Default hard token budget applied to runs that don't pass their own
+   * `tokenBudget` (#68). null explicitly means "no budget" (useful in a
+   * project override to cancel a global budget); omitted also means no budget.
+   */
+  defaultTokenBudget?: number | null;
+  /** Default max concurrent agents per run. Clamped to the runtime maximum. */
+  defaultConcurrency?: number;
+  /** Default retry attempts after recoverable agent failures. */
+  defaultAgentRetries?: number;
+  /** Bottom task-panel display mode: "compact" (default, one line per run) | "detailed". */
+  progressPanelMode?: "compact" | "detailed";
+  /** Max agents shown per phase in detailed progress mode (default 8). */
+  progressPanelMaxAgents?: number;
+  /**
+   * Persist each workflow subagent transcript as a real pi session file under
+   * the standard sessions directory (~/.pi/agent/sessions/<encoded-cwd>/),
+   * keyed by the project cwd. Default false: subagent sessions stay in-memory
+   * and only the compacted history embedded in the run JSON survives.
+   */
+  persistAgentSessions?: boolean;
+  /**
+   * Character cap on a delivered background-run result's JSON-dump fallback
+   * before truncation (default 400). String results and `verdict`/`report`/
+   * `summary`/`synthesis` fields are never truncated.
+   */
+  deliveredResultMaxChars?: number;
+  /**
+   * Extra tool names to deny in workflow subagent sessions, on top of the
+   * always-on `workflow`/`workflow_control` defaults (#107). Use it to block
+   * other recursive-orchestration tools you have installed (e.g. a pi-subagents
+   * tool) so a subagent can't fan out through them.
+   */
+  excludeSubagentTools?: string[];
+}
+
+export interface WorkflowSettingsStore {
+  load(): WorkflowSettings;
+  save(settings: WorkflowSettings): void;
+}
+
+export interface WorkflowSettingsOptions {
+  /** Explicit settings path, primarily for tests and migrations. */
+  settingsPath?: string;
+  /** Project cwd whose project-level settings should override global settings. */
+  cwd?: string;
+  /** Explicit project settings path, primarily for tests. */
+  projectSettingsPath?: string;
+  /** Save destination when using saveWorkflowSettings with cwd. Default: global. */
+  scope?: "global" | "project";
+}
+
+/** Path to the user-level workflow settings JSON file (~/.pi/workflows/settings.json). */
+export function getWorkflowSettingsPath(): string {
+  return join(workflowHomeDir(), "settings.json");
+}
+
+/** Path to this project's optional workflow settings override. */
+export function getWorkflowProjectSettingsPath(cwd: string): string {
+  return workflowProjectPaths(cwd).settingsPath;
+}
+
+/** Load settings from disk. Missing, corrupt, or invalid files resolve to {}. */
+export function loadWorkflowSettings(settingsPathOrOptions?: string | WorkflowSettingsOptions): WorkflowSettings {
+  const options = normalizeOptions(settingsPathOrOptions);
+  const globalSettings = readSettings(options.settingsPath ?? getWorkflowSettingsPath());
+  const projectPath =
+    options.projectSettingsPath ?? (options.cwd ? getWorkflowProjectSettingsPath(options.cwd) : undefined);
+  if (!projectPath) return globalSettings;
+  return { ...globalSettings, ...readSettings(projectPath) };
+}
+
+/** Merge known settings into the user-level settings file. */
+export function saveWorkflowSettings(
+  settings: WorkflowSettings,
+  settingsPathOrOptions?: string | WorkflowSettingsOptions,
+): void {
+  const options = normalizeOptions(settingsPathOrOptions);
+  const projectPath =
+    options.projectSettingsPath ?? (options.cwd ? getWorkflowProjectSettingsPath(options.cwd) : undefined);
+  const path =
+    options.scope === "project" && projectPath ? projectPath : (options.settingsPath ?? getWorkflowSettingsPath());
+  const dir = dirname(path);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+
+  const existing = readObject(path);
+  writeFileSync(path, `${JSON.stringify({ ...existing, ...normalizeSettings(settings) }, null, 2)}\n`, "utf-8");
+}
+
+/** Save a global preference and update an existing project override if one is present. */
+export function saveWorkflowSettingsForCwd(settings: WorkflowSettings, cwd: string): void {
+  saveWorkflowSettings(settings);
+  const projectPath = getWorkflowProjectSettingsPath(cwd);
+  if (existsSync(projectPath)) {
+    saveWorkflowSettings(settings, { projectSettingsPath: projectPath, scope: "project" });
+  }
+}
+
+function normalizeOptions(settingsPathOrOptions?: string | WorkflowSettingsOptions): WorkflowSettingsOptions {
+  return typeof settingsPathOrOptions === "string"
+    ? { settingsPath: settingsPathOrOptions }
+    : (settingsPathOrOptions ?? {});
+}
+
+function readSettings(path: string): WorkflowSettings {
+  if (!existsSync(path)) return {};
+  try {
+    return normalizeSettings(JSON.parse(readFileSync(path, "utf-8")));
+  } catch {
+    return {};
+  }
+}
+
+function normalizeSettings(value: unknown): WorkflowSettings {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return {};
+  const raw = value as Record<string, unknown>;
+  const settings: WorkflowSettings = {};
+  if (typeof raw.keywordTriggerEnabled === "boolean") {
+    settings.keywordTriggerEnabled = raw.keywordTriggerEnabled;
+  }
+  const keywordTriggerWord = normalizeKeywordTriggerWord(raw.keywordTriggerWord);
+  if (keywordTriggerWord !== undefined) settings.keywordTriggerWord = keywordTriggerWord;
+  if (raw.defaultAgentTimeoutMs === null) {
+    settings.defaultAgentTimeoutMs = null;
+  } else if (
+    typeof raw.defaultAgentTimeoutMs === "number" &&
+    Number.isFinite(raw.defaultAgentTimeoutMs) &&
+    raw.defaultAgentTimeoutMs > 0
+  ) {
+    settings.defaultAgentTimeoutMs = raw.defaultAgentTimeoutMs;
+  }
+  if (raw.defaultTokenBudget === null) {
+    settings.defaultTokenBudget = null;
+  } else {
+    const defaultTokenBudget = normalizeInteger(raw.defaultTokenBudget, 1, Number.MAX_SAFE_INTEGER);
+    if (defaultTokenBudget !== undefined) settings.defaultTokenBudget = defaultTokenBudget;
+  }
+  const defaultConcurrency = normalizeInteger(raw.defaultConcurrency, 1, MAX_CONCURRENCY);
+  if (defaultConcurrency !== undefined) settings.defaultConcurrency = defaultConcurrency;
+  const defaultAgentRetries = normalizeInteger(raw.defaultAgentRetries, 0, MAX_AGENT_RETRIES);
+  if (defaultAgentRetries !== undefined) settings.defaultAgentRetries = defaultAgentRetries;
+  if (raw.progressPanelMode === "compact" || raw.progressPanelMode === "detailed") {
+    settings.progressPanelMode = raw.progressPanelMode;
+  }
+  if (
+    typeof raw.progressPanelMaxAgents === "number" &&
+    Number.isFinite(raw.progressPanelMaxAgents) &&
+    raw.progressPanelMaxAgents >= 1
+  ) {
+    settings.progressPanelMaxAgents = Math.min(1000, Math.floor(raw.progressPanelMaxAgents));
+  }
+  if (typeof raw.persistAgentSessions === "boolean") {
+    settings.persistAgentSessions = raw.persistAgentSessions;
+  }
+  const deliveredResultMaxChars = normalizeInteger(raw.deliveredResultMaxChars, 1, 1_000_000);
+  if (deliveredResultMaxChars !== undefined) settings.deliveredResultMaxChars = deliveredResultMaxChars;
+  if (Array.isArray(raw.excludeSubagentTools)) {
+    const names = raw.excludeSubagentTools.filter((t): t is string => typeof t === "string" && t.trim().length > 0);
+    if (names.length) settings.excludeSubagentTools = names;
+  }
+  return settings;
+}
+
+function normalizeInteger(value: unknown, min: number, max: number): number | undefined {
+  if (typeof value !== "number" || !Number.isFinite(value) || value < min) return undefined;
+  return Math.min(max, Math.floor(value));
+}
+
+function readObject(path: string): Record<string, unknown> {
+  if (!existsSync(path)) return {};
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf-8"));
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? (parsed as Record<string, unknown>) : {};
+  } catch {
+    return {};
+  }
+}