@wichayutdew/pi-workflows 0.2.3 → 1.0.0

package/src/config/load-settings.ts

@@ -0,0 +1,37 @@
+import { join } from 'node:path';
+import { createDiagnostic, errorCode, errorMessage } from './diagnostics.ts';
+import type { ConfigFileSystem, LoadedSettings } from './load-types.ts';
+import { DEFAULT_SETTINGS } from './types.ts';
+import { validateSettings } from './validate.ts';
+import { parseYaml } from './yaml.ts';
+
+/** Load user settings through the injected filesystem boundary. */
+export async function loadSettings(
+  fileSystem: ConfigFileSystem,
+  userDirectory: string,
+): Promise<LoadedSettings> {
+  const path = join(userDirectory, 'settings.yaml');
+  try {
+    const text = await fileSystem.readTextFile(path);
+    const validation = validateSettings(parseYaml(text, 'settings'));
+    if (!validation.value) {
+      return {
+        settings: { ...DEFAULT_SETTINGS },
+        diagnostics: validation.errors.map((message) =>
+          createDiagnostic(path, message),
+        ),
+      };
+    }
+    return { settings: validation.value, diagnostics: [] };
+  } catch (error) {
+    if (errorCode(error) === 'ENOENT') {
+      return { settings: { ...DEFAULT_SETTINGS }, diagnostics: [] };
+    }
+    return {
+      settings: { ...DEFAULT_SETTINGS },
+      diagnostics: [
+        createDiagnostic(path, `cannot read settings: ${errorMessage(error)}`),
+      ],
+    };
+  }
+}

package/src/config/load-types.ts

@@ -0,0 +1,53 @@
+import type {
+  ConfigDiagnostic,
+  LoadedWorkflow,
+  WorkflowCatalog,
+  WorkflowSettings,
+} from './types.ts';
+
+export type LoadCatalogOptions = {
+  readonly cwd: string;
+  readonly projectTrusted: boolean;
+  readonly userDirectory?: string;
+};
+
+export type WorkflowDirectoryEntry = {
+  readonly name: string;
+  readonly isFile: () => boolean;
+};
+
+export type ConfigFileSystem = {
+  readonly readDirectory: (
+    path: string,
+  ) => Promise<ReadonlyArray<WorkflowDirectoryEntry>>;
+  readonly readTextFile: (path: string) => Promise<string>;
+  readonly realPath: (path: string) => Promise<string>;
+};
+
+export type ConfigEnvironment = {
+  readonly getVariable: (name: string) => string | undefined;
+  readonly homeDirectory: () => string;
+};
+
+export type ConfigLoaderDependencies = {
+  readonly fileSystem: ConfigFileSystem;
+  readonly environment: ConfigEnvironment;
+};
+
+export type LoadedDirectory = {
+  readonly workflows: ReadonlyArray<LoadedWorkflow>;
+  readonly diagnostics: ReadonlyArray<ConfigDiagnostic>;
+};
+
+export type LoadedSettings = {
+  readonly settings: WorkflowSettings;
+  readonly diagnostics: ReadonlyArray<ConfigDiagnostic>;
+};
+
+export type ConfigLoader = {
+  readonly defaultUserWorkflowDirectory: () => string;
+  readonly loadSettings: (userDirectory: string) => Promise<LoadedSettings>;
+  readonly loadCatalog: (
+    options: LoadCatalogOptions,
+  ) => Promise<WorkflowCatalog>;
+};

package/src/config/load-workflows.ts

@@ -0,0 +1,135 @@
+import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { digest } from '../digest.ts';
+import { createDiagnostic, errorCode, errorMessage } from './diagnostics.ts';
+import type { ConfigFileSystem, LoadedDirectory } from './load-types.ts';
+import type {
+  LoadedWorkflow,
+  WorkflowDefinition,
+  WorkflowSourceKind,
+} from './types.ts';
+import { validatePromptText, validateWorkflow } from './validate.ts';
+import { parseYaml } from './yaml.ts';
+
+async function readYamlFile(
+  fileSystem: ConfigFileSystem,
+  path: string,
+): Promise<unknown> {
+  return parseYaml(await fileSystem.readTextFile(path), 'workflow');
+}
+
+function isInside(root: string, candidate: string): boolean {
+  const pathFromRoot = relative(root, candidate);
+  return (
+    pathFromRoot === '' ||
+    (pathFromRoot !== '..' &&
+      !pathFromRoot.startsWith(`..${sep}`) &&
+      !isAbsolute(pathFromRoot))
+  );
+}
+
+async function loadPrompt(
+  fileSystem: ConfigFileSystem,
+  sourcePath: string,
+  definition: WorkflowDefinition,
+  stepId: string,
+): Promise<string> {
+  const prompt = definition.steps[stepId]?.prompt;
+  if (!prompt) throw new Error(`unknown step "${stepId}"`);
+  if ('inline' in prompt) return prompt.inline;
+
+  const sourceDirectory = await fileSystem.realPath(dirname(sourcePath));
+  const requestedPath = resolve(sourceDirectory, prompt.file);
+  if (!isInside(sourceDirectory, requestedPath)) {
+    throw new Error(`prompt file escapes workflow directory: ${prompt.file}`);
+  }
+
+  const actualPath = await fileSystem.realPath(requestedPath);
+  if (!isInside(sourceDirectory, actualPath)) {
+    throw new Error(
+      `prompt file symlink escapes workflow directory: ${prompt.file}`,
+    );
+  }
+  return fileSystem.readTextFile(actualPath);
+}
+
+async function loadWorkflowFile(
+  fileSystem: ConfigFileSystem,
+  sourcePath: string,
+  sourceKind: WorkflowSourceKind,
+): Promise<LoadedWorkflow> {
+  const validation = validateWorkflow(
+    await readYamlFile(fileSystem, sourcePath),
+  );
+  if (!validation.value) {
+    throw new Error(validation.errors.join('\n'));
+  }
+
+  const definition = validation.value;
+  const prompts: Record<string, string> = {};
+  for (const stepId of Object.keys(definition.steps)) {
+    const text = await loadPrompt(fileSystem, sourcePath, definition, stepId);
+    const promptErrors = validatePromptText(
+      text,
+      `workflow.steps.${stepId}.prompt`,
+    );
+    if (promptErrors.length > 0) {
+      throw new Error(promptErrors.join('\n'));
+    }
+    prompts[stepId] = text;
+  }
+
+  const stepDigests = Object.fromEntries(
+    Object.entries(definition.steps).map(([stepId, step]) => [
+      stepId,
+      digest({ step, prompt: prompts[stepId] }),
+    ]),
+  );
+  return {
+    definition,
+    prompts,
+    digest: digest({ definition, prompts }),
+    stepDigests,
+    sourcePath,
+    sourceKind,
+  };
+}
+
+/** Load and validate every workflow file in one source directory. */
+export async function loadWorkflowDirectory(
+  fileSystem: ConfigFileSystem,
+  directory: string,
+  sourceKind: WorkflowSourceKind,
+): Promise<LoadedDirectory> {
+  let entries: Awaited<ReturnType<ConfigFileSystem['readDirectory']>>;
+  try {
+    entries = await fileSystem.readDirectory(directory);
+  } catch (error) {
+    if (errorCode(error) === 'ENOENT') {
+      return { workflows: [], diagnostics: [] };
+    }
+    return {
+      workflows: [],
+      diagnostics: [
+        createDiagnostic(
+          directory,
+          `cannot read workflow directory: ${String(error)}`,
+        ),
+      ],
+    };
+  }
+
+  const files = entries
+    .filter((entry) => entry.isFile() && /\.workflow\.ya?ml$/i.test(entry.name))
+    .map((entry) => join(directory, entry.name))
+    .sort();
+  const workflows: Array<LoadedWorkflow> = [];
+  const diagnostics = [];
+  for (const path of files) {
+    try {
+      workflows.push(await loadWorkflowFile(fileSystem, path, sourceKind));
+    } catch (error) {
+      diagnostics.push(createDiagnostic(path, errorMessage(error)));
+    }
+  }
+  return { workflows, diagnostics };
+}

package/src/config/load.ts

@@ -1,321 +1,53 @@
 import { readdir, readFile, realpath } from 'node:fs/promises';
 import { homedir } from 'node:os';
-import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
-import { parseDocument } from 'yaml';
-import { digest } from '../digest.ts';
-import { checkWorkflowAgainstCeiling } from './ceiling.ts';
-import {
-  DEFAULT_SETTINGS,
-  type ConfigDiagnostic,
-  type LoadedWorkflow,
-  type WorkflowCatalog,
-  type WorkflowDefinition,
-  type WorkflowSettings,
-  type WorkflowSourceKind,
-} from './types.ts';
-import {
-  validatePromptText,
-  validateSettings,
-  validateWorkflow,
-} from './validate.ts';
-
-export interface LoadCatalogOptions {
-  cwd: string;
-  projectTrusted: boolean;
-  userDirectory?: string;
-}
-
-interface LoadedDirectory {
-  workflows: LoadedWorkflow[];
-  diagnostics: ConfigDiagnostic[];
-}
-
-function diagnostic(
-  path: string,
-  message: string,
-  level: ConfigDiagnostic['level'] = 'error',
-): ConfigDiagnostic {
-  return { path, message, level };
-}
-
-async function readYaml(
-  path: string,
-  kind: 'settings' | 'workflow',
-): Promise<unknown> {
-  const text = await readFile(path, 'utf8');
-  const document = parseDocument(text, {
-    customTags: [],
-    merge: false,
-    prettyErrors: true,
-    resolveKnownTags: false,
-    schema: 'core',
-    strict: true,
-    stringKeys: true,
-    uniqueKeys: true,
-    version: '1.2',
-  });
-  const issues = [...document.errors, ...document.warnings];
-  if (issues.length > 0) {
-    throw new Error(issues.map((issue) => issue.message).join('\n'));
-  }
-  if (
-    document.directives.yaml.explicit &&
-    document.directives.yaml.version !== '1.2'
-  ) {
-    throw new Error(`${kind} YAML must use version 1.2`);
-  }
-  return document.toJS({ maxAliasCount: 100 }) as unknown;
-}
-
-function isInside(root: string, candidate: string): boolean {
-  const pathFromRoot = relative(root, candidate);
-  return (
-    pathFromRoot === '' ||
-    (pathFromRoot !== '..' &&
-      !pathFromRoot.startsWith(`..${sep}`) &&
-      !isAbsolute(pathFromRoot))
-  );
-}
-
-async function loadPrompt(
-  sourcePath: string,
-  definition: WorkflowDefinition,
-  stepId: string,
-): Promise<string> {
-  const prompt = definition.steps[stepId]?.prompt;
-  if (!prompt) throw new Error(`unknown step "${stepId}"`);
-  if ('inline' in prompt) return prompt.inline;
-
-  const sourceDirectory = await realpath(dirname(sourcePath));
-  const requestedPath = resolve(sourceDirectory, prompt.file);
-  if (!isInside(sourceDirectory, requestedPath)) {
-    throw new Error(`prompt file escapes workflow directory: ${prompt.file}`);
-  }
-
-  const actualPath = await realpath(requestedPath);
-  if (!isInside(sourceDirectory, actualPath)) {
-    throw new Error(
-      `prompt file symlink escapes workflow directory: ${prompt.file}`,
-    );
-  }
-  return readFile(actualPath, 'utf8');
-}
-
-async function loadWorkflowFile(
-  sourcePath: string,
-  sourceKind: WorkflowSourceKind,
-): Promise<LoadedWorkflow> {
-  const raw = await readYaml(sourcePath, 'workflow');
-  const validation = validateWorkflow(raw);
-  if (!validation.value) {
-    throw new Error(validation.errors.join('\n'));
-  }
-
-  const definition = validation.value;
-  const prompts: Record<string, string> = {};
-  for (const stepId of Object.keys(definition.steps)) {
-    const text = await loadPrompt(sourcePath, definition, stepId);
-    const promptErrors = validatePromptText(
-      text,
-      `workflow.steps.${stepId}.prompt`,
-    );
-    if (promptErrors.length > 0) {
-      throw new Error(promptErrors.join('\n'));
-    }
-    prompts[stepId] = text;
-  }
-
-  const stepDigests = Object.fromEntries(
-    Object.entries(definition.steps).map(([stepId, step]) => [
-      stepId,
-      digest({ step, prompt: prompts[stepId] }),
-    ]),
-  );
-  return {
-    definition,
-    prompts,
-    digest: digest({ definition, prompts }),
-    stepDigests,
-    sourcePath,
-    sourceKind,
-  };
-}
-
-async function loadWorkflowDirectory(
-  directory: string,
-  sourceKind: WorkflowSourceKind,
-): Promise<LoadedDirectory> {
-  let entries;
-  try {
-    entries = await readdir(directory, { withFileTypes: true });
-  } catch (error) {
-    const code = (error as NodeJS.ErrnoException).code;
-    if (code === 'ENOENT') return { workflows: [], diagnostics: [] };
-    return {
-      workflows: [],
-      diagnostics: [
-        diagnostic(
-          directory,
-          `cannot read workflow directory: ${String(error)}`,
-        ),
-      ],
-    };
-  }
-
-  const workflows: LoadedWorkflow[] = [];
-  const diagnostics: ConfigDiagnostic[] = [];
-  const files = entries
-    .filter((entry) => entry.isFile() && /\.workflow\.ya?ml$/i.test(entry.name))
-    .map((entry) => join(directory, entry.name))
-    .sort();
-
-  for (const path of files) {
-    try {
-      workflows.push(await loadWorkflowFile(path, sourceKind));
-    } catch (error) {
-      diagnostics.push(
-        diagnostic(
-          path,
-          error instanceof Error ? error.message : String(error),
-        ),
-      );
-    }
-  }
-  return { workflows, diagnostics };
-}
-
-export async function loadSettings(userDirectory: string): Promise<{
-  settings: WorkflowSettings;
-  diagnostics: ConfigDiagnostic[];
-}> {
-  const path = join(userDirectory, 'settings.yaml');
-  try {
-    const validation = validateSettings(await readYaml(path, 'settings'));
-    if (!validation.value) {
-      return {
-        settings: DEFAULT_SETTINGS,
-        diagnostics: validation.errors.map((message) =>
-          diagnostic(path, message),
-        ),
-      };
-    }
-    return { settings: validation.value, diagnostics: [] };
-  } catch (error) {
-    const code = (error as NodeJS.ErrnoException).code;
-    if (code === 'ENOENT')
-      return { settings: DEFAULT_SETTINGS, diagnostics: [] };
-    return {
-      settings: DEFAULT_SETTINGS,
-      diagnostics: [
-        diagnostic(
-          path,
-          `cannot read settings: ${error instanceof Error ? error.message : String(error)}`,
-        ),
-      ],
-    };
-  }
-}
-
-function addWorkflow(
-  catalog: Map<string, LoadedWorkflow>,
-  commands: Map<string, string>,
-  workflow: LoadedWorkflow,
-  diagnostics: ConfigDiagnostic[],
-): void {
-  const id = workflow.definition.id;
-  const command = workflow.definition.command;
-  const existing = catalog.get(id);
-  if (existing) {
-    diagnostics.push(
-      diagnostic(
-        workflow.sourcePath,
-        `workflow id "${id}" already belongs to ${existing.sourcePath}; overrides are not allowed`,
-      ),
-    );
-    return;
-  }
-  const existingCommand = commands.get(command);
-  if (existingCommand) {
-    diagnostics.push(
-      diagnostic(
-        workflow.sourcePath,
-        `command "/${command}" already belongs to workflow "${existingCommand}"`,
-      ),
-    );
-    return;
-  }
-  catalog.set(id, workflow);
-  commands.set(command, id);
+import { createConfigLoader } from './catalog.ts';
+import type {
+  ConfigLoaderDependencies,
+  LoadCatalogOptions,
+  LoadedSettings,
+} from './load-types.ts';
+import type { WorkflowCatalog } from './types.ts';
+
+export type {
+  ConfigEnvironment,
+  ConfigFileSystem,
+  ConfigLoader,
+  ConfigLoaderDependencies,
+  LoadCatalogOptions,
+  LoadedSettings,
+  WorkflowDirectoryEntry,
+} from './load-types.ts';
+export { createConfigLoader } from './catalog.ts';
+
+const NODE_CONFIG_DEPENDENCIES = {
+  fileSystem: {
+    readDirectory: (path) => readdir(path, { withFileTypes: true }),
+    readTextFile: (path) => readFile(path, 'utf8'),
+    realPath: realpath,
+  },
+  environment: {
+    getVariable: (name) => process.env[name],
+    homeDirectory: homedir,
+  },
+} as const satisfies ConfigLoaderDependencies;
+
+const NODE_CONFIG_LOADER = createConfigLoader(NODE_CONFIG_DEPENDENCIES);
+
+/** Resolve the default user workflow directory from the process environment. */
+export function defaultUserWorkflowDirectory(): string {
+  return NODE_CONFIG_LOADER.defaultUserWorkflowDirectory();
 }
 
-export function defaultUserWorkflowDirectory(): string {
-  const explicit = process.env.PI_WORKFLOWS_DIR?.trim();
-  if (explicit) return resolve(explicit);
-  const agentDirectory =
-    process.env.PI_CODING_AGENT_DIR?.trim() || join(homedir(), '.pi', 'agent');
-  return join(agentDirectory, 'workflows');
+/** Load workflow settings from the given user directory. */
+export async function loadSettings(
+  userDirectory: string,
+): Promise<LoadedSettings> {
+  return NODE_CONFIG_LOADER.loadSettings(userDirectory);
 }
 
+/** Load the complete workflow catalog using the default Node.js adapters. */
 export async function loadCatalog(
   options: LoadCatalogOptions,
 ): Promise<WorkflowCatalog> {
-  const userDirectory = resolve(
-    options.userDirectory ?? defaultUserWorkflowDirectory(),
-  );
-  const diagnostics: ConfigDiagnostic[] = [];
-  const settingsResult = await loadSettings(userDirectory);
-  diagnostics.push(...settingsResult.diagnostics);
-
-  const catalog = new Map<string, LoadedWorkflow>();
-  const commands = new Map<string, string>();
-  const userResult = await loadWorkflowDirectory(userDirectory, 'user');
-  diagnostics.push(...userResult.diagnostics);
-  for (const workflow of userResult.workflows) {
-    addWorkflow(catalog, commands, workflow, diagnostics);
-  }
-
-  const projectDirectory = join(resolve(options.cwd), '.pi', 'workflows');
-  if (settingsResult.settings.allowProjectWorkflows) {
-    if (!options.projectTrusted) {
-      diagnostics.push(
-        diagnostic(
-          projectDirectory,
-          'project workflows were skipped because the project is not trusted',
-          'warning',
-        ),
-      );
-    } else {
-      const permissionCeiling = settingsResult.settings.permissionCeiling!;
-      const projectResult = await loadWorkflowDirectory(
-        projectDirectory,
-        'project',
-      );
-      diagnostics.push(...projectResult.diagnostics);
-      for (const workflow of projectResult.workflows) {
-        const ceilingErrors = checkWorkflowAgainstCeiling(
-          workflow.definition,
-          permissionCeiling,
-        );
-        if (ceilingErrors.length > 0) {
-          diagnostics.push(
-            ...ceilingErrors.map((message) =>
-              diagnostic(workflow.sourcePath, message),
-            ),
-          );
-          continue;
-        }
-        addWorkflow(catalog, commands, workflow, diagnostics);
-      }
-    }
-  }
-
-  return {
-    workflows: catalog,
-    settings: settingsResult.settings,
-    diagnostics,
-    userDirectory,
-    ...(settingsResult.settings.allowProjectWorkflows
-      ? { projectDirectory }
-      : {}),
-  };
+  return NODE_CONFIG_LOADER.loadCatalog(options);
 }