@wichayutdew/pi-workflows 0.3.0 → 1.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wichayutdew/pi-workflows",
-  "version": "0.3.0",
+  "version": "1.0.0",
   "description": "A declarative, pauseable workflow harness for Pi",
   "license": "MIT",
   "repository": {

package/src/command-names.ts

@@ -1,3 +1,6 @@
+/**
+ * Slash commands owned by the workflow harness.
+ */
 export const HARNESS_COMMAND_NAMES = [
   'workflow-abort',
   'workflow-list',
@@ -39,7 +42,10 @@ export const PI_BUILTIN_COMMAND_NAMES = [
   'trust',
 ] as const;
 
-export const RESERVED_COMMAND_NAMES = new Set<string>([
+/**
+ * Command names that workflow aliases may not shadow.
+ */
+export const RESERVED_COMMAND_NAMES: ReadonlySet<string> = new Set([
   ...HARNESS_COMMAND_NAMES,
   ...PI_BUILTIN_COMMAND_NAMES,
 ]);

package/src/commands.ts

@@ -1,74 +1,148 @@
 import type {
   ExtensionAPI,
   ExtensionCommandContext,
+  RegisteredCommand,
 } from '@earendil-works/pi-coding-agent';
 
-export interface WorkflowCommandController {
-  workflowIds(): string[];
-  list(ctx: ExtensionCommandContext): Promise<void>;
-  start(
+/**
+ * Workflow operations exposed to slash-command handlers.
+ */
+export type WorkflowCommandController = {
+  /** Returns loaded workflow IDs for command completion. */
+  readonly workflowIds: () => ReadonlyArray<string>;
+  /** Lists loaded workflows. */
+  readonly list: (context: ExtensionCommandContext) => Promise<void>;
+  /** Starts a workflow. */
+  readonly start: (
     workflowId: string,
     input: string,
-    ctx: ExtensionCommandContext,
-  ): Promise<void>;
-  pause(reason: string, ctx: ExtensionCommandContext): Promise<void>;
-  resume(ctx: ExtensionCommandContext): Promise<void>;
-  abort(reason: string, ctx: ExtensionCommandContext): Promise<void>;
-  reload(ctx: ExtensionCommandContext): Promise<void>;
-}
+    context: ExtensionCommandContext,
+  ) => Promise<void>;
+  /** Pauses the active workflow. */
+  readonly pause: (
+    reason: string,
+    context: ExtensionCommandContext,
+  ) => Promise<void>;
+  /** Resumes the paused workflow. */
+  readonly resume: (context: ExtensionCommandContext) => Promise<void>;
+  /** Aborts the active workflow. */
+  readonly abort: (
+    reason: string,
+    context: ExtensionCommandContext,
+  ) => Promise<void>;
+  /** Reloads workflow configuration. */
+  readonly reload: (context: ExtensionCommandContext) => Promise<void>;
+};
 
-function splitFirst(value: string): [string, string] {
-  const trimmed = value.trim();
-  const separator = trimmed.search(/\s/);
-  if (separator === -1) return [trimmed, ''];
-  return [trimmed.slice(0, separator), trimmed.slice(separator).trim()];
-}
+/**
+ * Declarative Pi command registration.
+ */
+export type HarnessCommand = {
+  readonly name: string;
+  readonly options: Omit<RegisteredCommand, 'name' | 'sourceInfo'>;
+};
 
-export function registerHarnessCommands(
-  pi: ExtensionAPI,
-  controller: WorkflowCommandController,
-): void {
-  pi.registerCommand('workflow-list', {
-    description: 'List loaded declarative workflows',
-    handler: async (_args, ctx) => controller.list(ctx),
-  });
+const splitFirst = (value: string): readonly [string, string] => {
+  const trimmedValue = value.trim();
+  const separatorIndex = trimmedValue.search(/\s/);
 
-  pi.registerCommand('workflow-start', {
+  return separatorIndex === -1
+    ? [trimmedValue, '']
+    : [
+        trimmedValue.slice(0, separatorIndex),
+        trimmedValue.slice(separatorIndex).trim(),
+      ];
+};
+
+const createStartCommand = (
+  controller: WorkflowCommandController,
+): HarnessCommand => ({
+  name: 'workflow-start',
+  options: {
     description: 'Start a workflow: /workflow-start <id> [input]',
     getArgumentCompletions: (prefix) => {
-      const items = controller
+      const completions = controller
         .workflowIds()
-        .filter((id) => id.startsWith(prefix))
-        .map((id) => ({ value: id, label: id }));
-      return items.length > 0 ? items : null;
+        .filter((workflowId) => workflowId.startsWith(prefix))
+        .map((workflowId) => ({
+          value: workflowId,
+          label: workflowId,
+        }));
+      return completions.length > 0 ? completions : null;
     },
-    handler: async (args, ctx) => {
+    handler: async (args, context) => {
       const [workflowId, input] = splitFirst(args);
       if (!workflowId) {
-        ctx.ui.notify('Usage: /workflow-start <id> [input]', 'warning');
+        context.ui.notify('Usage: /workflow-start <id> [input]', 'warning');
         return;
       }
-      await controller.start(workflowId, input, ctx);
+      await controller.start(workflowId, input, context);
     },
-  });
-
-  pi.registerCommand('workflow-pause', {
-    description: 'Pause the active workflow without losing its checkpoint',
-    handler: async (reason, ctx) => controller.pause(reason.trim(), ctx),
-  });
+  },
+});
 
-  pi.registerCommand('workflow-resume', {
-    description: 'Reload configuration and resume the paused workflow',
-    handler: async (_args, ctx) => controller.resume(ctx),
-  });
-
-  pi.registerCommand('workflow-abort', {
-    description: 'Abort the active workflow',
-    handler: async (reason, ctx) => controller.abort(reason.trim(), ctx),
-  });
+/**
+ * Creates the declarative command registrations for a workflow controller.
+ *
+ * @param controller - Injected workflow command operations.
+ * @returns Command names and Pi registration options.
+ */
+export function createHarnessCommands(
+  controller: WorkflowCommandController,
+): ReadonlyArray<HarnessCommand> {
+  return [
+    {
+      name: 'workflow-list',
+      options: {
+        description: 'List loaded declarative workflows',
+        handler: async (_args, context) => controller.list(context),
+      },
+    },
+    createStartCommand(controller),
+    {
+      name: 'workflow-pause',
+      options: {
+        description: 'Pause the active workflow without losing its checkpoint',
+        handler: async (reason, context) =>
+          controller.pause(reason.trim(), context),
+      },
+    },
+    {
+      name: 'workflow-resume',
+      options: {
+        description: 'Reload configuration and resume the paused workflow',
+        handler: async (_args, context) => controller.resume(context),
+      },
+    },
+    {
+      name: 'workflow-abort',
+      options: {
+        description: 'Abort the active workflow',
+        handler: async (reason, context) =>
+          controller.abort(reason.trim(), context),
+      },
+    },
+    {
+      name: 'workflow-reload',
+      options: {
+        description: 'Reload workflow files while no workflow is running',
+        handler: async (_args, context) => controller.reload(context),
+      },
+    },
+  ];
+}
 
-  pi.registerCommand('workflow-reload', {
-    description: 'Reload workflow files while no workflow is running',
-    handler: async (_args, ctx) => controller.reload(ctx),
-  });
+/**
+ * Registers all workflow commands with Pi.
+ *
+ * @param pi - Pi extension API used for registration.
+ * @param controller - Injected workflow command operations.
+ */
+export function registerHarnessCommands(
+  pi: ExtensionAPI,
+  controller: WorkflowCommandController,
+): void {
+  for (const command of createHarnessCommands(controller)) {
+    pi.registerCommand(command.name, command.options);
+  }
 }

package/src/config/catalog.ts

@@ -0,0 +1,162 @@
+import { join, resolve } from 'node:path';
+import { checkWorkflowAgainstCeiling } from './ceiling.ts';
+import { createDiagnostic } from './diagnostics.ts';
+import { loadSettings } from './load-settings.ts';
+import type {
+  ConfigLoader,
+  ConfigLoaderDependencies,
+  LoadCatalogOptions,
+} from './load-types.ts';
+import { loadWorkflowDirectory } from './load-workflows.ts';
+import type {
+  ConfigDiagnostic,
+  LoadedWorkflow,
+  PermissionCeiling,
+  WorkflowCatalog,
+  WorkflowSettings,
+} from './types.ts';
+
+type MutableCatalog = {
+  readonly workflows: Map<string, LoadedWorkflow>;
+  readonly commands: Map<string, string>;
+  readonly diagnostics: Array<ConfigDiagnostic>;
+};
+
+function addWorkflow(catalog: MutableCatalog, workflow: LoadedWorkflow): void {
+  const { id, command } = workflow.definition;
+  const existing = catalog.workflows.get(id);
+  if (existing) {
+    catalog.diagnostics.push(
+      createDiagnostic(
+        workflow.sourcePath,
+        `workflow id "${id}" already belongs to ${existing.sourcePath}; overrides are not allowed`,
+      ),
+    );
+    return;
+  }
+  const existingCommand = catalog.commands.get(command);
+  if (existingCommand) {
+    catalog.diagnostics.push(
+      createDiagnostic(
+        workflow.sourcePath,
+        `command "/${command}" already belongs to workflow "${existingCommand}"`,
+      ),
+    );
+    return;
+  }
+  catalog.workflows.set(id, workflow);
+  catalog.commands.set(command, id);
+}
+
+function defaultUserWorkflowDirectory(
+  dependencies: ConfigLoaderDependencies,
+): string {
+  const explicit = dependencies.environment
+    .getVariable('PI_WORKFLOWS_DIR')
+    ?.trim();
+  if (explicit) return resolve(explicit);
+  const agentDirectory =
+    dependencies.environment.getVariable('PI_CODING_AGENT_DIR')?.trim() ||
+    join(dependencies.environment.homeDirectory(), '.pi', 'agent');
+  return join(agentDirectory, 'workflows');
+}
+
+function requiredPermissionCeiling(
+  settings: WorkflowSettings,
+): PermissionCeiling {
+  if (!settings.permissionCeiling) {
+    throw new Error(
+      'validated settings must define a ceiling when project workflows are enabled',
+    );
+  }
+  return settings.permissionCeiling;
+}
+
+async function loadCatalog(
+  dependencies: ConfigLoaderDependencies,
+  options: LoadCatalogOptions,
+): Promise<WorkflowCatalog> {
+  const userDirectory = resolve(
+    options.userDirectory ?? defaultUserWorkflowDirectory(dependencies),
+  );
+  const settingsResult = await loadSettings(
+    dependencies.fileSystem,
+    userDirectory,
+  );
+  const state: MutableCatalog = {
+    workflows: new Map(),
+    commands: new Map(),
+    diagnostics: [...settingsResult.diagnostics],
+  };
+
+  const userResult = await loadWorkflowDirectory(
+    dependencies.fileSystem,
+    userDirectory,
+    'user',
+  );
+  state.diagnostics.push(...userResult.diagnostics);
+  userResult.workflows.forEach((workflow) => {
+    addWorkflow(state, workflow);
+  });
+
+  const projectDirectory = join(resolve(options.cwd), '.pi', 'workflows');
+  if (settingsResult.settings.allowProjectWorkflows) {
+    if (!options.projectTrusted) {
+      state.diagnostics.push(
+        createDiagnostic(
+          projectDirectory,
+          'project workflows were skipped because the project is not trusted',
+          'warning',
+        ),
+      );
+    } else {
+      const permissionCeiling = requiredPermissionCeiling(
+        settingsResult.settings,
+      );
+      const projectResult = await loadWorkflowDirectory(
+        dependencies.fileSystem,
+        projectDirectory,
+        'project',
+      );
+      state.diagnostics.push(...projectResult.diagnostics);
+      projectResult.workflows.forEach((workflow) => {
+        const ceilingErrors = checkWorkflowAgainstCeiling(
+          workflow.definition,
+          permissionCeiling,
+        );
+        if (ceilingErrors.length > 0) {
+          state.diagnostics.push(
+            ...ceilingErrors.map((message) =>
+              createDiagnostic(workflow.sourcePath, message),
+            ),
+          );
+          return;
+        }
+        addWorkflow(state, workflow);
+      });
+    }
+  }
+
+  return {
+    workflows: state.workflows,
+    settings: settingsResult.settings,
+    diagnostics: state.diagnostics,
+    userDirectory,
+    ...(settingsResult.settings.allowProjectWorkflows
+      ? { projectDirectory }
+      : {}),
+  };
+}
+
+/** Bind configuration loading to explicit filesystem and environment ports. */
+export function createConfigLoader(
+  dependencies: ConfigLoaderDependencies,
+): ConfigLoader {
+  return {
+    defaultUserWorkflowDirectory: () =>
+      defaultUserWorkflowDirectory(dependencies),
+    loadSettings: (userDirectory) =>
+      loadSettings(dependencies.fileSystem, userDirectory),
+    loadCatalog: (options) => loadCatalog(dependencies, options),
+  };
+}

package/src/config/ceiling.ts

@@ -2,12 +2,14 @@ import type {
   BashPermission,
   BashRule,
   PermissionCeiling,
+  StepSubagent,
+  SubagentPermissionCeiling,
   WorkflowDefinition,
 } from './types.ts';
 
 function selectorAllowed(
   requested: string,
-  ceiling: readonly string[],
+  ceiling: ReadonlyArray<string>,
 ): boolean {
   const separator = requested.indexOf('/');
   if (separator === -1) return ceiling.includes(requested);
@@ -39,123 +41,121 @@ function bashWithinCeiling(
   );
 }
 
+function turnBudgetErrors(
+  subagent: StepSubagent,
+  ceiling: SubagentPermissionCeiling,
+  path: string,
+): Array<string> {
+  if (!subagent.turnBudget) {
+    return [`${path}.turnBudget: required for a project workflow`];
+  }
+  return [
+    ...(subagent.turnBudget.maxTurns > ceiling.maxTurns
+      ? [`${path}.turnBudget.maxTurns: exceeds the user permission ceiling`]
+      : []),
+    ...((subagent.turnBudget.graceTurns ?? 0) > ceiling.maxGraceTurns
+      ? [`${path}.turnBudget.graceTurns: exceeds the user permission ceiling`]
+      : []),
+  ];
+}
+
+function toolBudgetErrors(
+  subagent: StepSubagent,
+  ceiling: SubagentPermissionCeiling,
+  path: string,
+): Array<string> {
+  if (!subagent.toolBudget) {
+    return [`${path}.toolBudget: required for a project workflow`];
+  }
+  return [
+    ...(subagent.toolBudget.hard > ceiling.maxToolCalls
+      ? [`${path}.toolBudget.hard: exceeds the user permission ceiling`]
+      : []),
+    ...(subagent.toolBudget.block !== '*'
+      ? [`${path}.toolBudget.block: must be "*" for a project workflow`]
+      : []),
+  ];
+}
+
+function subagentErrors(
+  subagent: StepSubagent | undefined,
+  ceiling: SubagentPermissionCeiling | undefined,
+  path: string,
+): Array<string> {
+  if (!subagent) return [];
+  if (!ceiling) {
+    return [`${path}: subagent execution exceeds the user permission ceiling`];
+  }
+  return [
+    ...(!ceiling.agents.includes(subagent.agent)
+      ? [
+          `${path}.agent: "${subagent.agent}" exceeds the user permission ceiling`,
+        ]
+      : []),
+    ...(!ceiling.contexts.includes(subagent.context)
+      ? [
+          `${path}.context: "${subagent.context}" exceeds the user permission ceiling`,
+        ]
+      : []),
+    ...(subagent.model && !ceiling.models.includes(subagent.model)
+      ? [
+          `${path}.model: "${subagent.model}" exceeds the user permission ceiling`,
+        ]
+      : []),
+    ...(subagent.timeoutMs > ceiling.maxTimeoutMs
+      ? [`${path}.timeoutMs: exceeds the user permission ceiling`]
+      : []),
+    ...(subagent.artifacts && !ceiling.artifacts
+      ? [`${path}.artifacts: exceeds the user permission ceiling`]
+      : []),
+    ...(subagent.retryToolFailures && !ceiling.retryToolFailures
+      ? [`${path}.retryToolFailures: exceeds the user permission ceiling`]
+      : []),
+    ...turnBudgetErrors(subagent, ceiling, path),
+    ...toolBudgetErrors(subagent, ceiling, path),
+  ];
+}
+
+/** Return every project-workflow permission that exceeds the user ceiling. */
 export function checkWorkflowAgainstCeiling(
   workflow: WorkflowDefinition,
   ceiling: PermissionCeiling,
-): string[] {
-  const errors: string[] = [];
-  for (const [stepId, step] of Object.entries(workflow.steps)) {
+): Array<string> {
+  return Object.entries(workflow.steps).flatMap(([stepId, step]) => {
     const path = `workflow.steps.${stepId}.permissions`;
-    const subagentPath = `workflow.steps.${stepId}.subagent`;
-    for (const tool of step.permissions.tools) {
-      if (!ceiling.tools.includes(tool)) {
-        errors.push(
-          `${path}.tools: "${tool}" exceeds the user permission ceiling`,
-        );
-      }
-    }
-    for (const selector of step.permissions.mcp) {
-      if (!selectorAllowed(selector, ceiling.mcp)) {
-        errors.push(
-          `${path}.mcp: "${selector}" exceeds the user permission ceiling`,
-        );
-      }
-    }
-    for (const extension of step.permissions.extensions) {
-      if (!ceiling.extensions.includes(extension)) {
-        errors.push(
-          `${path}.extensions: "${extension}" exceeds the user permission ceiling`,
-        );
-      }
-    }
-    for (const skill of step.permissions.skills) {
-      if (!ceiling.skills.includes(skill)) {
-        errors.push(
-          `${path}.skills: "${skill}" exceeds the user permission ceiling`,
-        );
-      }
-    }
-    if (!bashWithinCeiling(step.permissions.bash, ceiling.bash)) {
-      errors.push(`${path}.bash: exceeds the user permission ceiling`);
-    }
-    if (!step.subagent) continue;
-    if (!ceiling.subagent) {
-      errors.push(
-        `${subagentPath}: subagent execution exceeds the user permission ceiling`,
-      );
-      continue;
-    }
-    if (!ceiling.subagent.agents.includes(step.subagent.agent)) {
-      errors.push(
-        `${subagentPath}.agent: "${step.subagent.agent}" exceeds the user permission ceiling`,
-      );
-    }
-    if (!ceiling.subagent.contexts.includes(step.subagent.context)) {
-      errors.push(
-        `${subagentPath}.context: "${step.subagent.context}" exceeds the user permission ceiling`,
-      );
-    }
-    if (
-      step.subagent.model &&
-      !ceiling.subagent.models.includes(step.subagent.model)
-    ) {
-      errors.push(
-        `${subagentPath}.model: "${step.subagent.model}" exceeds the user permission ceiling`,
-      );
-    }
-    if (step.subagent.timeoutMs > ceiling.subagent.maxTimeoutMs) {
-      errors.push(
-        `${subagentPath}.timeoutMs: exceeds the user permission ceiling`,
-      );
-    }
-    if (step.subagent.artifacts && !ceiling.subagent.artifacts) {
-      errors.push(
-        `${subagentPath}.artifacts: exceeds the user permission ceiling`,
-      );
-    }
-    if (
-      step.subagent.retryToolFailures &&
-      !ceiling.subagent.retryToolFailures
-    ) {
-      errors.push(
-        `${subagentPath}.retryToolFailures: exceeds the user permission ceiling`,
-      );
-    }
-    if (!step.subagent.turnBudget) {
-      errors.push(
-        `${subagentPath}.turnBudget: required for a project workflow`,
-      );
-    } else {
-      if (step.subagent.turnBudget.maxTurns > ceiling.subagent.maxTurns) {
-        errors.push(
-          `${subagentPath}.turnBudget.maxTurns: exceeds the user permission ceiling`,
-        );
-      }
-      if (
-        (step.subagent.turnBudget.graceTurns ?? 0) >
-        ceiling.subagent.maxGraceTurns
-      ) {
-        errors.push(
-          `${subagentPath}.turnBudget.graceTurns: exceeds the user permission ceiling`,
-        );
-      }
-    }
-    if (!step.subagent.toolBudget) {
-      errors.push(
-        `${subagentPath}.toolBudget: required for a project workflow`,
-      );
-    } else {
-      if (step.subagent.toolBudget.hard > ceiling.subagent.maxToolCalls) {
-        errors.push(
-          `${subagentPath}.toolBudget.hard: exceeds the user permission ceiling`,
-        );
-      }
-      if (step.subagent.toolBudget.block !== '*') {
-        errors.push(
-          `${subagentPath}.toolBudget.block: must be "*" for a project workflow`,
-        );
-      }
-    }
-  }
-  return errors;
+    return [
+      ...step.permissions.tools
+        .filter((tool) => !ceiling.tools.includes(tool))
+        .map(
+          (tool) =>
+            `${path}.tools: "${tool}" exceeds the user permission ceiling`,
+        ),
+      ...step.permissions.mcp
+        .filter((selector) => !selectorAllowed(selector, ceiling.mcp))
+        .map(
+          (selector) =>
+            `${path}.mcp: "${selector}" exceeds the user permission ceiling`,
+        ),
+      ...step.permissions.extensions
+        .filter((extension) => !ceiling.extensions.includes(extension))
+        .map(
+          (extension) =>
+            `${path}.extensions: "${extension}" exceeds the user permission ceiling`,
+        ),
+      ...step.permissions.skills
+        .filter((skill) => !ceiling.skills.includes(skill))
+        .map(
+          (skill) =>
+            `${path}.skills: "${skill}" exceeds the user permission ceiling`,
+        ),
+      ...(!bashWithinCeiling(step.permissions.bash, ceiling.bash)
+        ? [`${path}.bash: exceeds the user permission ceiling`]
+        : []),
+      ...subagentErrors(
+        step.subagent,
+        ceiling.subagent,
+        `workflow.steps.${stepId}.subagent`,
+      ),
+    ];
+  });
 }

package/src/config/command-conflicts.ts

@@ -1,6 +1,6 @@
-interface CommandLike {
-  name: string;
-}
+type CommandLike = {
+  readonly name: string;
+};
 
 function isSuffixedInvocation(name: string, command: string): boolean {
   if (!name.startsWith(`${command}:`)) return false;
@@ -14,7 +14,7 @@ function isSuffixedInvocation(name: string, command: string): boolean {
  */
 export function hasRuntimeCommandConflict(
   command: string,
-  availableCommands: readonly CommandLike[],
+  availableCommands: ReadonlyArray<CommandLike>,
   ownedAliases: ReadonlySet<string>,
 ): boolean {
   if (

package/src/config/diagnostics.ts

@@ -0,0 +1,28 @@
+import type { ConfigDiagnostic } from './types.ts';
+
+/** Create one normalized configuration diagnostic. */
+export function createDiagnostic(
+  path: string,
+  message: string,
+  level: ConfigDiagnostic['level'] = 'error',
+): ConfigDiagnostic {
+  return { path, message, level };
+}
+
+/** Convert any caught value to a stable diagnostic message. */
+export function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+/** Read a Node-style string error code without asserting the caught value. */
+export function errorCode(error: unknown): string | undefined {
+  if (
+    typeof error !== 'object' ||
+    error === null ||
+    !('code' in error) ||
+    typeof error.code !== 'string'
+  ) {
+    return undefined;
+  }
+  return error.code;
+}