@db-lyon/flowkit 0.12.0 → 0.14.0

package/docs/api-reference.md

@@ -171,7 +171,8 @@ interface TaskResult {
 
 ### `ShellTask`
 
-Built-in task that executes shell commands via `execSync`.
+Built-in task that executes shell commands through the platform shell with
+streamed stdout and stderr.
 
 ```typescript
 class ShellTask extends BaseTask<ShellTaskOptions> {
@@ -188,11 +189,38 @@ class ShellTask extends BaseTask<ShellTaskOptions> {
 | `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`
@@ -403,6 +431,116 @@ class MissingDependencyError extends Error {
 
 ---
 
+## Guard
+
+*Import from `@db-lyon/flowkit` or `@db-lyon/flowkit/guard`*
+
+A before/after pipeline around one host operation. See [guards.md](guards.md) for the guide.
+
+### `Guard<Ctx, TResult>`
+
+```typescript
+interface Guard<Ctx extends GuardContext = GuardContext, TResult = unknown> {
+  readonly name: string;
+  readonly order?: number;                                  // lower runs first, default 0
+  appliesTo?(ctx: Ctx): boolean | Promise<boolean>;         // default: always
+  before?(ctx: Ctx): Promise<void>;                         // throw to DENY
+  after?(ctx: Ctx, result: TResult): Promise<TResult | void>; // return to replace
+}
+```
+
+---
+
+### `GuardContext`
+
+The minimum a host context must provide. Extend it with whatever the operation carries.
+
+```typescript
+interface GuardContext {
+  meta: Map<string, unknown>;  // scratch space shared across guards for one operation
+}
+
+function guardContextBase(): GuardContext
+```
+
+---
+
+### `lazy(ctx, key, compute)`
+
+Wrap a computation so it runs at most once per operation, cached into `ctx.meta` under `key`.
+
+```typescript
+function lazy<T>(ctx: GuardContext, key: string, compute: () => T): () => T
+```
+
+---
+
+### `GuardRegistry<Ctx, TResult>`
+
+Ordered set of guards. Sorted on registration by `order`, then by name.
+
+```typescript
+class GuardRegistry<Ctx extends GuardContext = GuardContext, TResult = unknown> {
+  register(guard: Guard<Ctx, TResult>): this;
+  registerAll(guards: Iterable<Guard<Ctx, TResult>>): this;
+  list(): readonly Guard<Ctx, TResult>[];
+  names(): string[];
+  get size(): number;
+}
+```
+
+---
+
+### `runGuarded(ctx, registry, invoke)`
+
+Run one operation through the pipeline: `before` in order, `invoke`, `after` in reverse.
+
+```typescript
+function runGuarded<Ctx extends GuardContext, TResult>(
+  ctx: Ctx,
+  registry: GuardRegistry<Ctx, TResult>,
+  invoke: () => Promise<TResult>,
+): Promise<TResult>
+```
+
+Applicability resolves once, up front. A `before` throw denies the operation and propagates unchanged. With an empty registry this is exactly `invoke()`.
+
+---
+
+### `discoverTaskGuards(registry, options)`
+
+Build a `Guard` for every `guard.<name>.<before|after><Scope?>` task in a `TaskRegistry`.
+
+```typescript
+function discoverTaskGuards<Ctx extends GuardContext, TResult = unknown>(
+  registry: TaskRegistry,
+  options: DiscoverTaskGuardsOptions<Ctx, TResult>,
+): Guard<Ctx, TResult>[]
+
+interface DiscoverTaskGuardsOptions<Ctx extends GuardContext, TResult = unknown> {
+  scopes?: Record<string, (ctx: Ctx) => boolean | Promise<boolean>>;
+  contextFor(ctx: Ctx): TaskContext;
+  optionsFor(ctx: Ctx, result?: TResult): Record<string, unknown>;
+  onDeny?(info: GuardTaskFailure<Ctx>): Error;
+  onError?(info: GuardTaskFailure<Ctx>): Error;
+  onAfterFailure?(info: GuardTaskFailure<Ctx>): void;
+  logger?: Logger;
+}
+
+interface GuardTaskFailure<Ctx extends GuardContext> {
+  readonly guard: string;     // 'p4' for guard.p4.beforeWrite
+  readonly phase: string;     // 'beforeWrite'
+  readonly taskName: string;  // 'guard.p4.beforeWrite'
+  readonly ctx: Ctx;
+  readonly reason: string;
+  readonly cause?: Error;
+}
+```
+
+Throws at discovery if a task names a scope the host did not register.
+
+---
+
 ## Logger
 
 *Import from `@db-lyon/flowkit`*

package/docs/custom-tasks.md

@@ -187,7 +187,8 @@ The module must have either a `default` export or a named export matching the la
 
 ## Built-in: ShellTask
 
-`ShellTask` executes shell commands via `execSync`. Register it under any name you like:
+`ShellTask` executes shell commands through the platform shell and streams output.
+Register it under any name you like:
 
 ```typescript
 import { ShellTask } from '@db-lyon/flowkit';
@@ -221,9 +222,34 @@ tasks:
 | `command` | `string` | (required) | The shell command to execute |
 | `cwd` | `string` | `undefined` | Working directory |
 | `timeout` | `number` | `300000` (5 min) | Timeout in milliseconds |
+| `signal` | `AbortSignal` | `undefined` | Cancels one programmatic invocation; cannot be specified in YAML |
 
 On success, `result.data.output` contains the trimmed stdout. On failure, `result.data` includes `exitCode`, `stderr`, and `stdout`.
 
+Existing YAML consumers need no change. Programmatic callers that need
+cancellation pass an invocation-specific `AbortSignal` in the task options.
+After cancellation, Flowkit waits for the shell to close, with a bounded
+fallback if the operating system does not report closure (one second on POSIX,
+three seconds on Windows). That fallback does not guarantee all descendants
+have exited. At the deadline Flowkit requests force termination and releases
+its Node handles for the root shell and any Windows `taskkill` helper before
+returning. On POSIX,
+signal-bearing invocations use a dedicated process group: Flowkit requests
+`SIGTERM`, waits 250ms for cooperative cleanup, then escalates the group to
+`SIGKILL`. Terminal Ctrl+C is not delivered to that separate group, so use the
+supplied `AbortSignal` for cancellation.
+
+On Windows, Flowkit asks `taskkill /T /F` to terminate the shell tree and does
+not kill the shell while that traversal is in progress. If `taskkill` fails or
+the three-second deadline expires, Flowkit requests force termination and
+releases its Node handles for the root and helper. Windows and POSIX descendants that escape the managed process
+tree or process group may still survive; Node does not provide a portable
+guarantee of complete descendant termination.
+
+Trailing stdout and stderr fragments are captured once, including when no
+`signal` is supplied. This corrects the duplicate final-partial-line output in
+earlier releases.
+
 ## Listing registered tasks
 
 ```typescript

package/docs/guards.md

@@ -0,0 +1,133 @@
+# Guards
+
+A guard is a `before`/`after` pipeline around one host operation. It sits on a seam the host already has (an RPC call, a write, a command dispatch) and may veto that operation, act on it, or observe its result.
+
+The pipeline knows nothing about what any guard does. Access policy, source control checkout, audit logging, rate limiting and approval gating are all just guards.
+
+Guards are distinct from [`FlowRunnerHooks`](api-reference.md#flow), which fire around flow steps. A hook observes a step; a guard wraps one host operation and can deny it.
+
+```ts
+import { GuardRegistry, runGuarded, guardContextBase, lazy } from '@db-lyon/flowkit/guard';
+```
+
+## The context
+
+Flowkit requires only a scratch map. Everything else belongs to the host.
+
+```ts
+interface GuardContext {
+  readonly meta: Map<string, unknown>;
+}
+```
+
+Extend it with whatever your operation carries, and build it with `guardContextBase()`:
+
+```ts
+interface CallContext extends GuardContext {
+  readonly method: string;
+  readonly params: Record<string, unknown>;
+  /** Files this call will modify. Computed on demand. */
+  files(): string[];
+}
+
+function makeCallContext(method: string, params: Record<string, unknown>): CallContext {
+  const ctx = { ...guardContextBase(), method, params } as CallContext;
+  ctx.files = lazy(ctx, 'files', () => classify(method, params));
+  return ctx;
+}
+```
+
+`lazy(ctx, key, compute)` caches into `meta`, so enrichment that is expensive to compute and that most guards never consult costs nothing when it is ignored and is computed once when several guards want it.
+
+`meta` is also how guards talk to each other. A `before` hook can stash what it did and the matching `after` hook, or a later guard, can read it back.
+
+## Writing a guard
+
+```ts
+interface Guard<Ctx extends GuardContext, TResult> {
+  readonly name: string;
+  readonly order?: number;
+  appliesTo?(ctx: Ctx): boolean | Promise<boolean>;
+  before?(ctx: Ctx): Promise<void>;
+  after?(ctx: Ctx, result: TResult): Promise<TResult | void>;
+}
+```
+
+- **`before`** runs before the operation. Throw to deny it: the operation never happens and your error propagates unchanged, so the host's own error type survives.
+- **`after`** runs after a successful operation. Return a value to replace the result; return nothing to leave it alone.
+- **`appliesTo`** decides whether the guard participates at all. Default is always.
+- **`order`** sorts the chain, lower first. Ties break by name, so a registry built from an unordered source still runs deterministically.
+
+```ts
+const sourceControl: Guard<CallContext, unknown> = {
+  name: 'source-control',
+  order: 10,
+  appliesTo: (ctx) => ctx.files().length > 0,
+  before: async (ctx) => {
+    const denied = await checkout(ctx.files());
+    if (denied.length) throw new Error(`locked by another user: ${denied.join(', ')}`);
+  },
+};
+```
+
+## Running the pipeline
+
+```ts
+const guards = new GuardRegistry<CallContext, Result>().registerAll([sourceControl, audit]);
+
+async function call(method: string, params: Record<string, unknown>): Promise<Result> {
+  return runGuarded(makeCallContext(method, params), guards, () => transport.send(method, params));
+}
+```
+
+`before` hooks run in registration order, then `invoke`, then `after` hooks in reverse order, so a guard's two halves nest rather than interleave.
+
+Applicability resolves once, up front. A guard whose `before` changes the answer to its own `appliesTo` (a source-control guard that checks a file out, making it writable) still gets its `after` half.
+
+With an empty registry `runGuarded` is exactly `invoke()`, so it is safe to install on a seam before any guard exists.
+
+## Guards from tasks
+
+A host that already loads tasks from config or from plugins gets guards for free. Name a task `guard.<name>.<phase>` and `discoverTaskGuards` turns it into a guard. No separate activation concept is needed, because the task registry is already the list of everything the host was given.
+
+```yaml
+tasks:
+  guard.p4.beforeWrite:
+    class_path: ./guards/perforce.js
+  guard.audit.after:
+    class_path: ./guards/audit.js
+```
+
+`<phase>` is `before` or `after`, optionally suffixed with a scope the host declared:
+
+| Task name | Runs |
+| --- | --- |
+| `guard.audit.before` | before every operation |
+| `guard.audit.after` | after every successful operation |
+| `guard.p4.beforeWrite` | before an operation the `write` scope claims |
+
+```ts
+const guards = discoverTaskGuards<CallContext, Result>(taskRegistry, {
+  scopes: { write: (ctx) => ctx.files().length > 0 },
+  contextFor: (ctx) => ({ logger, registry: taskRegistry, transport: ctx.transport }),
+  optionsFor: (ctx, result) => ({
+    method: ctx.method,
+    params: ctx.params,
+    paths: ctx.files(),
+    ...(result !== undefined ? { result } : {}),
+  }),
+  onDeny: (info) => new PolicyError(`blocked (${info.ctx.method}): ${info.reason}`),
+});
+```
+
+`contextFor` is called per operation, so a guard can be bound to whatever the operation belongs to rather than to a single ambient target. A host driving several connections should hand each guard the one serving the call it is guarding.
+
+A scope named by a task but not registered by the host is an error at discovery time. A typo in a plugin's task name surfaces at startup rather than becoming a guard that silently runs on everything.
+
+### Denial and failure
+
+A `before` guard denies by returning `success: false` or by throwing. Both route to `onDeny`, because `BaseTask.run` turns an exception into a failed result: a guard that crashes denies the operation rather than waving it through, which is the safe direction for the thing standing between a caller and a mutation.
+
+`onError` is separate and narrower. It fires only when the guard task cannot be constructed at all, an unresolvable class path or a module that fails to import, where nothing about the operation was evaluated.
+
+An `after` guard observes the result and cannot replace it, since a task returns a `TaskResult` rather than the host's result type. A failure is reported through `onAfterFailure` instead of failing an operation that already happened. Reach for a hand-written `Guard` when you need an `after` hook that transforms the result.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@db-lyon/flowkit",
-  "version": "0.12.0",
+  "version": "0.14.0",
   "description": "YAML-configured task and flow orchestration engine",
   "type": "module",
   "main": "dist/index.js",
@@ -10,7 +10,8 @@
     "./config": "./dist/config/index.js",
     "./task": "./dist/task/index.js",
     "./flow": "./dist/flow/index.js",
-    "./dag": "./dist/dag/index.js"
+    "./dag": "./dist/dag/index.js",
+    "./guard": "./dist/guard/index.js"
   },
   "files": [
     "/dist",
@@ -20,6 +21,7 @@
     "build": "tsc -b",
     "prepublishOnly": "tsc -b",
     "test": "vitest run",
+    "test:package-api": "npm run build && tsc -p test/tsconfig.public-api.json",
     "test:watch": "vitest"
   },
   "keywords": [