@db-lyon/flowkit 0.12.0 → 0.13.0

package/docs/api-reference.md

@@ -1,430 +1,458 @@
-# API reference
-
-Complete reference for all public exports from `@db-lyon/flowkit`.
-
-## Config
-
-*Import from `@db-lyon/flowkit` or `@db-lyon/flowkit/config`*
-
-### `loadConfig(options)`
-
-Load, layer, and validate YAML configuration files.
-
-```typescript
-function loadConfig<T extends z.ZodType>(
-  options: LoadConfigOptions<T>,
-): LoadedConfig<z.infer<T>>
-```
-
-**`LoadConfigOptions<T>`**
-
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| `filename` | `string` | yes | Primary config filename (e.g., `'app.yml'`) |
-| `schema` | `z.ZodType` | yes | Zod schema applied after merging all layers |
-| `defaults` | `unknown` | no | Built-in defaults merged under the project file |
-| `env` | `string` | no | Environment name — loads `{base}.{env}.{ext}` overlay |
-| `envVar` | `string` | no | Env var to read environment name from when `env` is not passed |
-| `configDir` | `string` | no | Directory to search (default: `process.cwd()`) |
-
-**`LoadedConfig<T>`**
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `config` | `T` | The validated, merged configuration object |
-| `configDir` | `string` | The directory the config was loaded from |
-
----
-
-### `findConfigFile(filename, startDir?)`
-
-Walk up parent directories looking for a file by name.
-
-```typescript
-function findConfigFile(filename: string, startDir?: string): string
-```
-
-Returns the absolute path. Throws if not found.
-
----
-
-### `loadRawYaml(filePath)`
-
-Parse a YAML file and return the raw result (no schema validation).
-
-```typescript
-function loadRawYaml(filePath: string): unknown
-```
-
----
-
-### `deepMerge(base, override)`
-
-Recursively merge two values. Objects merge key-by-key, arrays replace (unless `__merge: 'append'`), scalars override, `null` nullifies, `undefined` is a no-op.
-
-```typescript
-function deepMerge(base: unknown, override: unknown): unknown
-```
-
----
-
-### Zod schemas
-
-| Schema | Validates |
-|--------|-----------|
-| `TaskOptionsSchema` | `Record<string, unknown>` |
-| `TaskDefinitionSchema` | Task definition object |
-| `FlowStepSchema` | Single flow step (task xor flow) |
-| `FlowDefinitionSchema` | Flow with description and steps |
-| `EngineConfigSchema` | Top-level config with `tasks` and `flows` |
-
----
-
-### Config types
-
-```typescript
-type TaskOptions = Record<string, unknown>;
-
-type TaskDefinition = {
-  class_path: string;
-  description?: string;
-  group?: string;
-  options: TaskOptions;  // defaults to {}
-};
-
-type FlowStep = {
-  task?: string;
-  flow?: string;
-  options?: TaskOptions;
-};
-
-type FlowDefinition = {
-  description: string;
-  steps: Record<string, FlowStep>;
-};
-
-type EngineConfig = {
-  tasks: Record<string, TaskDefinition>;
-  flows: Record<string, FlowDefinition>;
-};
-```
-
----
-
-## Task
-
-*Import from `@db-lyon/flowkit` or `@db-lyon/flowkit/task`*
-
-### `BaseTask<TOpts>`
-
-Abstract base class for all tasks.
-
-```typescript
-abstract class BaseTask<TOpts = Record<string, unknown>> {
-  protected ctx: TaskContext;
-  protected options: TOpts;
-  protected logger: Logger;
-
-  constructor(ctx: TaskContext, options: TOpts);
-
-  abstract get taskName(): string;
-  abstract execute(): Promise<TaskResult>;
-  protected validate(): void;
-  async run(): Promise<TaskResult>;
-}
-```
-
-| Method | Description |
-|--------|-------------|
-| `taskName` | (getter) Human-readable name for logging |
-| `execute()` | Perform the task's work. Return a `TaskResult`. |
-| `validate()` | Optional. Called before `execute()`. Throw to abort. |
-| `run()` | Lifecycle wrapper: validate → execute → catch errors → add duration. Called by the flow runner. |
-
----
-
-### `TaskContext`
-
-```typescript
-interface TaskContext {
-  logger?: Logger;
-  [key: string]: unknown;
-}
-```
-
-Shared context passed to every task. Add any properties you need (database connections, API clients, etc.).
-
----
-
-### `TaskResult`
-
-```typescript
-interface TaskResult {
-  success: boolean;
-  data?: Record<string, unknown>;
-  error?: Error;
-  duration?: number;  // milliseconds, set by run()
-}
-```
-
----
-
-### `ShellTask`
-
-Built-in task that executes shell commands via `execSync`.
-
-```typescript
-class ShellTask extends BaseTask<ShellTaskOptions> {
-  get taskName(): string;       // "shell:{command}"
-  protected validate(): void;   // requires command
-  async execute(): Promise<TaskResult>;
-}
-```
-
-**`ShellTaskOptions`**
-
-| Field | Type | Default | Description |
-|-------|------|---------|-------------|
-| `command` | `string` | (required) | Shell command to execute |
-| `cwd` | `string` | `undefined` | Working directory |
-| `timeout` | `number` | `300000` | Timeout in milliseconds (5 min) |
-
-**Success result:** `data.output` contains trimmed stdout.
-
-**Failure result:** `data.exitCode`, `data.stderr`, `data.stdout`.
-
----
-
-### `TaskRegistry`
-
-Registry that maps names and class paths to task constructors.
-
-```typescript
-class TaskRegistry {
-  register(name: string, ctor: TaskConstructor): this;
-  registerClassPath(classPath: string, ctor: TaskConstructor): this;
-  registerAll(entries: Record<string, TaskConstructor>): this;
-  registerClassPaths(entries: Record<string, TaskConstructor>): this;
-  async resolve(classPathOrName: string): Promise<TaskConstructor>;
-  async create(
-    classPathOrName: string,
-    ctx: TaskContext,
-    options: Record<string, unknown>,
-  ): Promise<BaseTask>;
-  listRegistered(): string[];
-}
-```
-
-| Method | Description |
-|--------|-------------|
-| `register(name, ctor)` | Register by short name |
-| `registerClassPath(path, ctor)` | Register by dotted class path |
-| `registerAll(entries)` | Bulk register by short name |
-| `registerClassPaths(entries)` | Bulk register by class path |
-| `resolve(nameOrPath)` | Look up a constructor. Falls back to dynamic filesystem import. |
-| `create(nameOrPath, ctx, opts)` | Resolve + instantiate in one call |
-| `listRegistered()` | Return all registered names and class paths |
-
-**`TaskConstructor`**
-
-```typescript
-type TaskConstructor = new (
-  ctx: TaskContext,
-  options: Record<string, unknown>,
-) => BaseTask;
-```
-
----
-
-## Flow
-
-*Import from `@db-lyon/flowkit` or `@db-lyon/flowkit/flow`*
-
-### `FlowRunner`
-
-Orchestration engine that executes flows.
-
-```typescript
-class FlowRunner {
-  constructor(config: FlowRunnerConfig);
-  async run(options: FlowRunOptions): Promise<FlowRunResult>;
-  resolveExecutionPlan(
-    flow: FlowDefinition,
-    skipSet: Set<string>,
-  ): PlanStep[];
-}
-```
-
----
-
-### `FlowRunnerConfig`
-
-```typescript
-interface FlowRunnerConfig {
-  tasks: Record<string, TaskDefinition>;
-  flows: Record<string, FlowDefinition>;
-  registry: TaskRegistry;
-  context: TaskContext;
-  hooks?: FlowRunnerHooks;
-  logger?: Logger;
-}
-```
-
----
-
-### `FlowRunOptions`
-
-```typescript
-interface FlowRunOptions {
-  flowName: string;       // name of the flow to execute
-  skip?: string[];        // task names or step numbers to skip
-  plan?: boolean;         // return plan without executing
-}
-```
-
----
-
-### `FlowRunResult`
-
-```typescript
-interface FlowRunResult {
-  success: boolean;
-  steps: FlowStepResult[];
-  duration: number;       // total milliseconds
-  error?: Error;          // first error that caused failure
-}
-```
-
----
-
-### `FlowStepResult`
-
-```typescript
-interface FlowStepResult {
-  stepNumber: number;
-  type: 'task' | 'flow';
-  name: string;
-  result?: TaskResult;
-  skipped: boolean;
-  duration: number;       // milliseconds
-}
-```
-
----
-
-### `PlanStep`
-
-Represents a step in the execution plan (returned by plan mode or passed to hooks).
-
-```typescript
-interface PlanStep {
-  stepNumber: number;
-  type: 'task' | 'flow';
-  name: string;
-  skipped: boolean;
-  options?: Record<string, unknown>;
-}
-```
-
----
-
-### `FlowRunnerHooks`
-
-```typescript
-interface FlowRunnerHooks {
-  beforeRun?(flowName: string, plan: PlanStep[]): Promise<void>;
-  afterRun?(result: FlowRunResult): Promise<void>;
-  beforeStep?(step: PlanStep): Promise<void>;
-  afterStep?(step: PlanStep, result: FlowStepResult): Promise<void>;
-  onStepError?(
-    step: PlanStep,
-    error: Error,
-    completed: FlowStepResult[],
-  ): Promise<void>;
-}
-```
-
-| Hook | Fires | Scope |
-|------|-------|-------|
-| `beforeRun` | Once before execution starts | Top-level flow only |
-| `afterRun` | Once after execution completes | Top-level flow only |
-| `beforeStep` | Before each step executes | All steps (including nested) |
-| `afterStep` | After each step completes | All steps (including nested) |
-| `onStepError` | When a step fails | All steps (including nested) |
-
----
-
-## DAG
-
-*Import from `@db-lyon/flowkit` or `@db-lyon/flowkit/dag`*
-
-### `topologicalSort(nodes)`
-
-Sort a directed acyclic graph in dependency order (dependencies first).
-
-```typescript
-function topologicalSort<T>(nodes: DagNode<T>[]): DagNode<T>[]
-```
-
-Throws `CircularDependencyError` if the graph has cycles. Throws `MissingDependencyError` if a node references a dependency that doesn't exist.
-
----
-
-### `DagNode<T>`
-
-```typescript
-interface DagNode<T = unknown> {
-  id: string;
-  dependencies: string[];
-  data: T;
-}
-```
-
----
-
-### `CircularDependencyError`
-
-```typescript
-class CircularDependencyError extends Error {
-  cycle: string[];  // e.g., ['a', 'b', 'c', 'a']
-}
-```
-
----
-
-### `MissingDependencyError`
-
-```typescript
-class MissingDependencyError extends Error {
-  nodeId: string;     // the node that has the bad dependency
-  missingDep: string; // the dependency that doesn't exist
-}
-```
-
----
-
-## Logger
-
-*Import from `@db-lyon/flowkit`*
-
-### `Logger` interface
-
-```typescript
-interface Logger {
-  debug(...args: unknown[]): void;
-  info(...args: unknown[]): void;
-  warn(...args: unknown[]): void;
-  error(...args: unknown[]): void;
-  child(bindings: Record<string, unknown>): Logger;
-}
-```
-
-Compatible with pino, winston, and similar structured loggers.
-
-### `noopLogger`
-
-A silent logger that discards all output. Used as the default when no logger is provided.
-
-```typescript
-const noopLogger: Logger;
-```
+# API reference
+
+Complete reference for all public exports from `@db-lyon/flowkit`.
+
+## Config
+
+*Import from `@db-lyon/flowkit` or `@db-lyon/flowkit/config`*
+
+### `loadConfig(options)`
+
+Load, layer, and validate YAML configuration files.
+
+```typescript
+function loadConfig<T extends z.ZodType>(
+  options: LoadConfigOptions<T>,
+): LoadedConfig<z.infer<T>>
+```
+
+**`LoadConfigOptions<T>`**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `filename` | `string` | yes | Primary config filename (e.g., `'app.yml'`) |
+| `schema` | `z.ZodType` | yes | Zod schema applied after merging all layers |
+| `defaults` | `unknown` | no | Built-in defaults merged under the project file |
+| `env` | `string` | no | Environment name — loads `{base}.{env}.{ext}` overlay |
+| `envVar` | `string` | no | Env var to read environment name from when `env` is not passed |
+| `configDir` | `string` | no | Directory to search (default: `process.cwd()`) |
+
+**`LoadedConfig<T>`**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `config` | `T` | The validated, merged configuration object |
+| `configDir` | `string` | The directory the config was loaded from |
+
+---
+
+### `findConfigFile(filename, startDir?)`
+
+Walk up parent directories looking for a file by name.
+
+```typescript
+function findConfigFile(filename: string, startDir?: string): string
+```
+
+Returns the absolute path. Throws if not found.
+
+---
+
+### `loadRawYaml(filePath)`
+
+Parse a YAML file and return the raw result (no schema validation).
+
+```typescript
+function loadRawYaml(filePath: string): unknown
+```
+
+---
+
+### `deepMerge(base, override)`
+
+Recursively merge two values. Objects merge key-by-key, arrays replace (unless `__merge: 'append'`), scalars override, `null` nullifies, `undefined` is a no-op.
+
+```typescript
+function deepMerge(base: unknown, override: unknown): unknown
+```
+
+---
+
+### Zod schemas
+
+| Schema | Validates |
+|--------|-----------|
+| `TaskOptionsSchema` | `Record<string, unknown>` |
+| `TaskDefinitionSchema` | Task definition object |
+| `FlowStepSchema` | Single flow step (task xor flow) |
+| `FlowDefinitionSchema` | Flow with description and steps |
+| `EngineConfigSchema` | Top-level config with `tasks` and `flows` |
+
+---
+
+### Config types
+
+```typescript
+type TaskOptions = Record<string, unknown>;
+
+type TaskDefinition = {
+  class_path: string;
+  description?: string;
+  group?: string;
+  options: TaskOptions;  // defaults to {}
+};
+
+type FlowStep = {
+  task?: string;
+  flow?: string;
+  options?: TaskOptions;
+};
+
+type FlowDefinition = {
+  description: string;
+  steps: Record<string, FlowStep>;
+};
+
+type EngineConfig = {
+  tasks: Record<string, TaskDefinition>;
+  flows: Record<string, FlowDefinition>;
+};
+```
+
+---
+
+## Task
+
+*Import from `@db-lyon/flowkit` or `@db-lyon/flowkit/task`*
+
+### `BaseTask<TOpts>`
+
+Abstract base class for all tasks.
+
+```typescript
+abstract class BaseTask<TOpts = Record<string, unknown>> {
+  protected ctx: TaskContext;
+  protected options: TOpts;
+  protected logger: Logger;
+
+  constructor(ctx: TaskContext, options: TOpts);
+
+  abstract get taskName(): string;
+  abstract execute(): Promise<TaskResult>;
+  protected validate(): void;
+  async run(): Promise<TaskResult>;
+}
+```
+
+| Method | Description |
+|--------|-------------|
+| `taskName` | (getter) Human-readable name for logging |
+| `execute()` | Perform the task's work. Return a `TaskResult`. |
+| `validate()` | Optional. Called before `execute()`. Throw to abort. |
+| `run()` | Lifecycle wrapper: validate → execute → catch errors → add duration. Called by the flow runner. |
+
+---
+
+### `TaskContext`
+
+```typescript
+interface TaskContext {
+  logger?: Logger;
+  [key: string]: unknown;
+}
+```
+
+Shared context passed to every task. Add any properties you need (database connections, API clients, etc.).
+
+---
+
+### `TaskResult`
+
+```typescript
+interface TaskResult {
+  success: boolean;
+  data?: Record<string, unknown>;
+  error?: Error;
+  duration?: number;  // milliseconds, set by run()
+}
+```
+
+---
+
+### `ShellTask`
+
+Built-in task that executes shell commands through the platform shell with
+streamed stdout and stderr.
+
+```typescript
+class ShellTask extends BaseTask<ShellTaskOptions> {
+  get taskName(): string;       // "shell:{command}"
+  protected validate(): void;   // requires command
+  async execute(): Promise<TaskResult>;
+}
+```
+
+**`ShellTaskOptions`**
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `command` | `string` | (required) | Shell command to execute |
+| `cwd` | `string` | `undefined` | Working directory |
+| `timeout` | `number` | `300000` | Timeout in milliseconds (5 min) |
+| `signal` | `AbortSignal` | `undefined` | Cancels this individual programmatic invocation; not representable in YAML |
+
+**Success result:** `data.output` contains trimmed stdout.
+
+**Failure result:** `data.exitCode`, `data.stderr`, `data.stdout`.
+
+When `signal` is already aborted, no shell process is launched and the task
+returns the normal failed result with `Shell command cancelled`. An abort during
+execution requests termination of the spawned shell process. On Windows,
+Flowkit makes a best-effort `taskkill /T /F` request for that invocation's
+shell PID and falls back to direct shell termination only if that request
+fails or the three-second terminal deadline expires. On POSIX,
+signal-bearing invocations run in a dedicated process group. Flowkit requests
+`SIGTERM`, allows 250ms for cooperative cleanup, and then escalates the group
+to `SIGKILL`. Neither approach guarantees termination of descendants that have
+escaped the managed process tree or group; callers must not treat the returned
+result as proof of complete descendant termination.
+
+For signal-bearing invocations, Flowkit waits for the spawned shell to close
+after requesting termination. If the operating system does not report closure
+within one second on POSIX or three seconds on Windows, it returns the
+cancellation or timeout result with the output captured so far; that bounded
+fallback requests force termination and releases Flowkit's Node handles for
+the root shell and any Windows `taskkill` helper, but is not confirmation that
+either process, or any escaped descendant, has
+exited. POSIX
+signal-bearing invocations are in a separate process group, so terminal Ctrl+C
+does not reach them automatically; cancel through the supplied `AbortSignal`.
+
+Trailing stdout and stderr fragments are captured once. This corrects the
+duplicate final-partial-line output in earlier releases.
+
+---
+
+### `TaskRegistry`
+
+Registry that maps names and class paths to task constructors.
+
+```typescript
+class TaskRegistry {
+  register(name: string, ctor: TaskConstructor): this;
+  registerClassPath(classPath: string, ctor: TaskConstructor): this;
+  registerAll(entries: Record<string, TaskConstructor>): this;
+  registerClassPaths(entries: Record<string, TaskConstructor>): this;
+  async resolve(classPathOrName: string): Promise<TaskConstructor>;
+  async create(
+    classPathOrName: string,
+    ctx: TaskContext,
+    options: Record<string, unknown>,
+  ): Promise<BaseTask>;
+  listRegistered(): string[];
+}
+```
+
+| Method | Description |
+|--------|-------------|
+| `register(name, ctor)` | Register by short name |
+| `registerClassPath(path, ctor)` | Register by dotted class path |
+| `registerAll(entries)` | Bulk register by short name |
+| `registerClassPaths(entries)` | Bulk register by class path |
+| `resolve(nameOrPath)` | Look up a constructor. Falls back to dynamic filesystem import. |
+| `create(nameOrPath, ctx, opts)` | Resolve + instantiate in one call |
+| `listRegistered()` | Return all registered names and class paths |
+
+**`TaskConstructor`**
+
+```typescript
+type TaskConstructor = new (
+  ctx: TaskContext,
+  options: Record<string, unknown>,
+) => BaseTask;
+```
+
+---
+
+## Flow
+
+*Import from `@db-lyon/flowkit` or `@db-lyon/flowkit/flow`*
+
+### `FlowRunner`
+
+Orchestration engine that executes flows.
+
+```typescript
+class FlowRunner {
+  constructor(config: FlowRunnerConfig);
+  async run(options: FlowRunOptions): Promise<FlowRunResult>;
+  resolveExecutionPlan(
+    flow: FlowDefinition,
+    skipSet: Set<string>,
+  ): PlanStep[];
+}
+```
+
+---
+
+### `FlowRunnerConfig`
+
+```typescript
+interface FlowRunnerConfig {
+  tasks: Record<string, TaskDefinition>;
+  flows: Record<string, FlowDefinition>;
+  registry: TaskRegistry;
+  context: TaskContext;
+  hooks?: FlowRunnerHooks;
+  logger?: Logger;
+}
+```
+
+---
+
+### `FlowRunOptions`
+
+```typescript
+interface FlowRunOptions {
+  flowName: string;       // name of the flow to execute
+  skip?: string[];        // task names or step numbers to skip
+  plan?: boolean;         // return plan without executing
+}
+```
+
+---
+
+### `FlowRunResult`
+
+```typescript
+interface FlowRunResult {
+  success: boolean;
+  steps: FlowStepResult[];
+  duration: number;       // total milliseconds
+  error?: Error;          // first error that caused failure
+}
+```
+
+---
+
+### `FlowStepResult`
+
+```typescript
+interface FlowStepResult {
+  stepNumber: number;
+  type: 'task' | 'flow';
+  name: string;
+  result?: TaskResult;
+  skipped: boolean;
+  duration: number;       // milliseconds
+}
+```
+
+---
+
+### `PlanStep`
+
+Represents a step in the execution plan (returned by plan mode or passed to hooks).
+
+```typescript
+interface PlanStep {
+  stepNumber: number;
+  type: 'task' | 'flow';
+  name: string;
+  skipped: boolean;
+  options?: Record<string, unknown>;
+}
+```
+
+---
+
+### `FlowRunnerHooks`
+
+```typescript
+interface FlowRunnerHooks {
+  beforeRun?(flowName: string, plan: PlanStep[]): Promise<void>;
+  afterRun?(result: FlowRunResult): Promise<void>;
+  beforeStep?(step: PlanStep): Promise<void>;
+  afterStep?(step: PlanStep, result: FlowStepResult): Promise<void>;
+  onStepError?(
+    step: PlanStep,
+    error: Error,
+    completed: FlowStepResult[],
+  ): Promise<void>;
+}
+```
+
+| Hook | Fires | Scope |
+|------|-------|-------|
+| `beforeRun` | Once before execution starts | Top-level flow only |
+| `afterRun` | Once after execution completes | Top-level flow only |
+| `beforeStep` | Before each step executes | All steps (including nested) |
+| `afterStep` | After each step completes | All steps (including nested) |
+| `onStepError` | When a step fails | All steps (including nested) |
+
+---
+
+## DAG
+
+*Import from `@db-lyon/flowkit` or `@db-lyon/flowkit/dag`*
+
+### `topologicalSort(nodes)`
+
+Sort a directed acyclic graph in dependency order (dependencies first).
+
+```typescript
+function topologicalSort<T>(nodes: DagNode<T>[]): DagNode<T>[]
+```
+
+Throws `CircularDependencyError` if the graph has cycles. Throws `MissingDependencyError` if a node references a dependency that doesn't exist.
+
+---
+
+### `DagNode<T>`
+
+```typescript
+interface DagNode<T = unknown> {
+  id: string;
+  dependencies: string[];
+  data: T;
+}
+```
+
+---
+
+### `CircularDependencyError`
+
+```typescript
+class CircularDependencyError extends Error {
+  cycle: string[];  // e.g., ['a', 'b', 'c', 'a']
+}
+```
+
+---
+
+### `MissingDependencyError`
+
+```typescript
+class MissingDependencyError extends Error {
+  nodeId: string;     // the node that has the bad dependency
+  missingDep: string; // the dependency that doesn't exist
+}
+```
+
+---
+
+## Logger
+
+*Import from `@db-lyon/flowkit`*
+
+### `Logger` interface
+
+```typescript
+interface Logger {
+  debug(...args: unknown[]): void;
+  info(...args: unknown[]): void;
+  warn(...args: unknown[]): void;
+  error(...args: unknown[]): void;
+  child(bindings: Record<string, unknown>): Logger;
+}
+```
+
+Compatible with pino, winston, and similar structured loggers.
+
+### `noopLogger`
+
+A silent logger that discards all output. Used as the default when no logger is provided.
+
+```typescript
+const noopLogger: Logger;
+```