@eserstack/workflows 0.0.0-stage → 5.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/engine.js ADDED
@@ -0,0 +1,408 @@
1
+ // Copyright 2023-present Eser Ozvataf and other contributors. All rights reserved. Apache-2.0 license.
2
+ /**
3
+ * Workflow execution engine.
4
+ *
5
+ * Pure functions that run workflow pipelines. The engine itself performs
6
+ * no I/O — mutations are returned in results and the caller decides
7
+ * whether to apply them (via the `onMutations` callback).
8
+ *
9
+ * Uses `@eserstack/functions/task` for lazy composition and result-based
10
+ * error recovery.
11
+ *
12
+ * ```
13
+ * runWorkflow(workflow, registry, options)
14
+ * │
15
+ * ├─ For each step:
16
+ * │ ├─ resolveStep() → { name, options, continueOnError, timeout }
17
+ * │ ├─ Lookup tool in registry
18
+ * │ ├─ Merge step options + run options
19
+ * │ ├─ Run tool with { timeoutMs, signal }; on timeout abort the signal,
20
+ * │ │ give the tool STOP_GRACE_MS to stop, and fail the step
21
+ * │ ├─ On error: if continueOnError → failed step; else propagate error
22
+ * │ ├─ Call onMutations() if mutations produced
23
+ * │ └─ Call onStepEnd()
24
+ * │
25
+ * └─ Return aggregate WorkflowResult
26
+ *
27
+ * resolveIncludes(workflow, allWorkflows)
28
+ * ├─ For each included id, find in allWorkflows
29
+ * ├─ Prepend their steps to current workflow's steps
30
+ * ├─ Track visited ids → detect circular includes → throw
31
+ * └─ Return flattened WorkflowDefinition
32
+ * ```
33
+ *
34
+ * @module
35
+ */
36
+ import * as task from "@eserstack/functions/task";
37
+ import * as results from "@eserstack/primitives/results";
38
+ /** How long a step that sets no `timeout` may run: 60 seconds. */
39
+ const DEFAULT_STEP_TIMEOUT_MS = 60_000;
40
+ /**
41
+ * The longest step timeout, in milliseconds (about 24.8 days): the longest
42
+ * delay a timer holds. A larger delay fires at once.
43
+ */
44
+ const MAX_TIMEOUT_MS = 2_147_483_647;
45
+ /** {@link MAX_TIMEOUT_MS} in whole seconds, the unit of the step option. */
46
+ const MAX_TIMEOUT_SECONDS = Math.floor(MAX_TIMEOUT_MS / 1000);
47
+ /**
48
+ * How long the engine waits, after a step timed out, for its tool to stop the
49
+ * work it started before the run goes on without it. Five seconds, as long as
50
+ * the Go bridge waits for a killed command (processfx `DefaultWaitDelay`).
51
+ */
52
+ const STOP_GRACE_MS = 5_000;
53
+ const TIMED_OUT = Symbol("timed out");
54
+ /**
55
+ * Create a WorkflowError value.
56
+ */
57
+ const workflowError = (message) => ({
58
+ _tag: "WorkflowError",
59
+ message,
60
+ });
61
+ /**
62
+ * Join names for an error message, or "(none)" when there are none.
63
+ */
64
+ const joinOrNone = (names, separator) => names.length > 0 ? names.join(separator) : "(none)";
65
+ /**
66
+ * Convert a step's `timeout` option, in seconds, to milliseconds.
67
+ *
68
+ * @throws {Error} When the value is not a number of seconds above 0 and at
69
+ * most {@link MAX_TIMEOUT_SECONDS}
70
+ */
71
+ const parseStepTimeout = (stepName, value) => {
72
+ if (typeof value !== "number" ||
73
+ !Number.isFinite(value) ||
74
+ value <= 0 ||
75
+ value > MAX_TIMEOUT_SECONDS) {
76
+ throw new Error(`Invalid step config for '${stepName}': timeout must be a number of ` +
77
+ `seconds above 0 and at most ${MAX_TIMEOUT_SECONDS} (about 24.8 ` +
78
+ `days), such as 120; got ${JSON.stringify(value)}`);
79
+ }
80
+ return value * 1000;
81
+ };
82
+ /**
83
+ * Name a step in a message. Every shell step runs the `shell` tool, so a step
84
+ * with a `name` option is named by it too: `'unit-tests' (shell)`.
85
+ */
86
+ const describeStep = (step) => {
87
+ const displayName = step.options["name"];
88
+ return typeof displayName === "string" && displayName !== step.name
89
+ ? `'${displayName}' (${step.name})`
90
+ : `'${step.name}'`;
91
+ };
92
+ /**
93
+ * The name a step answers to besides its tool name: the `name` option, the
94
+ * display name of a shell step.
95
+ */
96
+ const stepDisplayName = (step) => {
97
+ const displayName = step.options["name"];
98
+ return typeof displayName === "string" && displayName !== ""
99
+ ? displayName
100
+ : undefined;
101
+ };
102
+ /**
103
+ * Report whether `--only <name>` selects a step: `name` is its tool name or
104
+ * its `name` option, so it picks a validator or a single shell step.
105
+ */
106
+ const stepMatches = (step, name) => step.name === name || stepDisplayName(step) === name;
107
+ /**
108
+ * Fail when `options.only` is set and no step of `workflows` matches it, so a
109
+ * filter that selects nothing never reads as a passing run. Only the declared
110
+ * steps count; the check runs across every workflow of the run, as one
111
+ * workflow of an event may hold the step and another not.
112
+ */
113
+ const checkOnly = (workflows, options) => {
114
+ if (options.only === undefined) {
115
+ return null;
116
+ }
117
+ const names = [];
118
+ for (const workflow of workflows) {
119
+ for (const stepConfig of workflow.steps) {
120
+ const resolved = resolveStep(stepConfig);
121
+ if (stepMatches(resolved, options.only)) {
122
+ return null;
123
+ }
124
+ names.push(stepDisplayName(resolved) ?? resolved.name);
125
+ }
126
+ }
127
+ return workflowError(`No step matches --only '${options.only}': pass a tool name or a shell ` +
128
+ `step's name. Steps: ${joinOrNone(names, ", ")}`);
129
+ };
130
+ /**
131
+ * Settle with `promise`, or with {@link TIMED_OUT} once `ms` have passed,
132
+ * whichever comes first. The timer is cleared either way.
133
+ */
134
+ const settleWithin = async (promise, ms) => {
135
+ let timer;
136
+ const deadline = new Promise((resolve) => {
137
+ timer = setTimeout(() => resolve(TIMED_OUT), ms);
138
+ });
139
+ try {
140
+ return await Promise.race([promise, deadline]);
141
+ }
142
+ finally {
143
+ clearTimeout(timer);
144
+ }
145
+ };
146
+ /**
147
+ * Run one step's tool within the step's time limit.
148
+ *
149
+ * The tool gets the limit and a signal. When the limit passes, the signal
150
+ * aborts and the step fails with a timeout, but first the tool gets
151
+ * {@link STOP_GRACE_MS} to stop what it started. The shell tool stops its
152
+ * command at the same limit, so the command is gone before the next step
153
+ * starts or the process exits. The signal also aborts when the tool returns.
154
+ *
155
+ * @param step - The step, named in the timeout message
156
+ * @param startedAt - `performance.now()` when the step started
157
+ */
158
+ const runStepTool = async (tool, toolOptions, step, timeoutMs, startedAt) => {
159
+ const controller = new AbortController();
160
+ const timeoutError = workflowError(`Step ${describeStep(step)} ran past its ${timeoutMs / 1000}s timeout; ` +
161
+ `raise the step's timeout option (in seconds) to give it more time`);
162
+ // fromPromise turns a throw into a failed result, so toolRun never rejects.
163
+ const toolRun = task.runTask(task.fromPromise(() => tool.run(toolOptions, { timeoutMs, signal: controller.signal }), (error) => workflowError(error instanceof Error ? error.message : String(error))));
164
+ try {
165
+ // The time left until the step's deadline; none when the tool blocked the
166
+ // event loop past it before returning its promise.
167
+ const outcome = await settleWithin(toolRun, Math.max(0, startedAt + timeoutMs - performance.now()));
168
+ if (outcome === TIMED_OUT) {
169
+ controller.abort();
170
+ await settleWithin(toolRun, STOP_GRACE_MS);
171
+ return results.fail(timeoutError);
172
+ }
173
+ // A tool that applies the limit itself, as the shell tool does, fails at
174
+ // the deadline, and can do so before the timer above fires (or, for a
175
+ // tool that blocks the event loop meanwhile, instead of it), so a failure
176
+ // at or past the limit is reported as the step's timeout too.
177
+ if (results.isFail(outcome) && performance.now() - startedAt >= timeoutMs) {
178
+ return results.fail(timeoutError);
179
+ }
180
+ return outcome;
181
+ }
182
+ finally {
183
+ // The step is over: work the tool started and left running stops now.
184
+ controller.abort();
185
+ }
186
+ };
187
+ /**
188
+ * Parse a step config into a resolved step with name, options, and engine directives.
189
+ *
190
+ * Engine directives (`continueOnError`, `timeout`) are extracted from the options
191
+ * and placed on the ResolvedStep. They are NOT passed to the tool.
192
+ *
193
+ * - `"fix-eof"` → `{ name: "fix-eof", options: {}, continueOnError: false }`
194
+ * - `{ "check-json": { exclude: ["x"], timeout: 120 } }` → timeout extracted, options clean
195
+ *
196
+ * @throws {Error} When the record has other than one key, or its `timeout` is
197
+ * not a number of seconds above 0
198
+ */
199
+ export const resolveStep = (step) => {
200
+ if (typeof step === "string") {
201
+ return { name: step, options: {}, continueOnError: false };
202
+ }
203
+ const entries = Object.entries(step);
204
+ if (entries.length !== 1) {
205
+ throw new Error(`Invalid step config: expected exactly one key, got ${entries.length}`);
206
+ }
207
+ const [name, rawOptions] = entries[0];
208
+ const options = {};
209
+ let continueOnError = false;
210
+ let timeout;
211
+ for (const [key, value] of Object.entries(rawOptions)) {
212
+ if (key === "continueOnError") {
213
+ continueOnError = value === true;
214
+ }
215
+ else if (key === "timeout") {
216
+ // The config gives seconds; the engine works in milliseconds.
217
+ timeout = parseStepTimeout(name, value);
218
+ }
219
+ else {
220
+ options[key] = value;
221
+ }
222
+ }
223
+ return { name, options, continueOnError, timeout };
224
+ };
225
+ /**
226
+ * Run a single workflow definition against a registry of tools.
227
+ *
228
+ * Returns a `Task<WorkflowResult, WorkflowError>` — the computation is
229
+ * lazy and does not execute until `task.runTask()` is called.
230
+ *
231
+ * @param workflow - Workflow to run
232
+ * @param registry - Tool registry
233
+ * @param options - Run options
234
+ * @returns Task wrapping the workflow execution
235
+ */
236
+ export const runWorkflow = (workflow, registry, options = {}) => task.task(async () => {
237
+ const startTime = performance.now();
238
+ const stepResults = [];
239
+ const defaultTimeout = options.defaultTimeout ?? DEFAULT_STEP_TIMEOUT_MS;
240
+ if (!Number.isFinite(defaultTimeout) ||
241
+ defaultTimeout <= 0 ||
242
+ defaultTimeout > MAX_TIMEOUT_MS) {
243
+ return results.fail(workflowError(`defaultTimeout ${defaultTimeout} is out of range: pass ` +
244
+ `milliseconds above 0 and at most ${MAX_TIMEOUT_MS}, such as ` +
245
+ `60_000, or leave it unset for 60 seconds`));
246
+ }
247
+ for (const stepConfig of workflow.steps) {
248
+ const resolved = resolveStep(stepConfig);
249
+ // Filter by --only flag
250
+ if (options.only !== undefined && !stepMatches(resolved, options.only)) {
251
+ continue;
252
+ }
253
+ // Resolve tool from registry
254
+ const tool = registry.get(resolved.name);
255
+ if (tool === undefined) {
256
+ return results.fail(workflowError(`Unknown tool '${resolved.name}' in workflow '${workflow.id}'. ` +
257
+ `Registered tools: ${joinOrNone(registry.names(), ", ")}`));
258
+ }
259
+ // Merge step-level options with run-level options (engine directives already stripped)
260
+ const mergedOptions = {
261
+ ...resolved.options,
262
+ root: options.root ?? ".",
263
+ fix: options.fix ?? false,
264
+ dryRun: options.dryRun ?? false,
265
+ _args: options.args ?? [],
266
+ };
267
+ // Pass changed files for incremental mode
268
+ if (options.changedFiles !== undefined) {
269
+ mergedOptions["_changedFiles"] = options.changedFiles;
270
+ }
271
+ // Notify step start
272
+ options.onStepStart?.(resolved.name);
273
+ const stepStart = performance.now();
274
+ // Steps run one at a time on purpose: each step sees the files the
275
+ // previous step fixed, and a failing step stops the workflow.
276
+ // oxlint-disable-next-line no-await-in-loop
277
+ const stepTaskResult = await runStepTool(tool, mergedOptions, resolved, resolved.timeout ?? defaultTimeout, stepStart);
278
+ let toolResult;
279
+ if (results.isOk(stepTaskResult)) {
280
+ toolResult = stepTaskResult.value;
281
+ }
282
+ else if (resolved.continueOnError) {
283
+ // Create a failed step result from the error
284
+ toolResult = {
285
+ name: resolved.name,
286
+ passed: false,
287
+ issues: [{ message: stepTaskResult.error.message }],
288
+ mutations: [],
289
+ stats: {},
290
+ };
291
+ }
292
+ else {
293
+ return stepTaskResult;
294
+ }
295
+ const durationMs = performance.now() - stepStart;
296
+ const stepResult = {
297
+ ...toolResult,
298
+ durationMs,
299
+ };
300
+ stepResults.push(stepResult);
301
+ // Apply mutations between steps so subsequent tools see the fixed state
302
+ if (toolResult.mutations.length > 0 &&
303
+ options.onMutations !== undefined) {
304
+ // The next step must not start before these mutations are applied.
305
+ // oxlint-disable-next-line no-await-in-loop
306
+ await options.onMutations(toolResult.mutations);
307
+ }
308
+ // Notify step end
309
+ options.onStepEnd?.(stepResult);
310
+ }
311
+ const totalDurationMs = performance.now() - startTime;
312
+ return results.ok({
313
+ workflowId: workflow.id,
314
+ passed: stepResults.every((s) => s.passed),
315
+ steps: stepResults,
316
+ totalDurationMs,
317
+ });
318
+ });
319
+ /**
320
+ * Resolve includes by flattening included workflow steps before the current workflow's steps.
321
+ * Detects circular includes.
322
+ *
323
+ * @param workflow - Workflow with potential includes
324
+ * @param allWorkflows - All available workflow definitions
325
+ * @param visited - Set of visited workflow ids (for cycle detection)
326
+ * @returns A new WorkflowDefinition with includes resolved (steps flattened)
327
+ */
328
+ export const resolveIncludes = (workflow, allWorkflows, visited = new Set()) => {
329
+ if (workflow.includes === undefined || workflow.includes.length === 0) {
330
+ return workflow;
331
+ }
332
+ const currentVisited = new Set(visited);
333
+ currentVisited.add(workflow.id);
334
+ const prependedSteps = [];
335
+ for (const includeId of workflow.includes) {
336
+ if (currentVisited.has(includeId)) {
337
+ throw new Error(`Circular include detected: workflow '${workflow.id}' includes '${includeId}' ` +
338
+ `which is already in the include chain: ${[...currentVisited].join(" → ")}`);
339
+ }
340
+ const included = allWorkflows.find((w) => w.id === includeId);
341
+ if (included === undefined) {
342
+ throw new Error(`Workflow '${workflow.id}' includes '${includeId}' but no workflow with that id exists. ` +
343
+ `Available: ${joinOrNone(allWorkflows.map((w) => w.id), ", ")}`);
344
+ }
345
+ // Recursively resolve includes of the included workflow
346
+ const resolved = resolveIncludes(included, allWorkflows, currentVisited);
347
+ prependedSteps.push(...resolved.steps);
348
+ }
349
+ return {
350
+ ...workflow,
351
+ steps: [...prependedSteps, ...workflow.steps],
352
+ includes: undefined, // Resolved — no longer needed
353
+ };
354
+ };
355
+ /**
356
+ * Run a workflow by id from a full config, resolving includes.
357
+ *
358
+ * @param workflowId - Workflow id to find and run
359
+ * @param config - Full workflow configuration
360
+ * @param registry - Tool registry
361
+ * @param options - Run options
362
+ * @returns Task wrapping the workflow execution
363
+ */
364
+ export const runWorkflowWithConfig = (workflowId, config, registry, options = {}) => task.task(async () => {
365
+ const workflow = config.workflows.find((w) => w.id === workflowId);
366
+ if (workflow === undefined) {
367
+ return results.fail(workflowError(`Workflow '${workflowId}' not found. ` +
368
+ `Available: ${joinOrNone(config.workflows.map((w) => w.id), ", ")}`));
369
+ }
370
+ const resolved = resolveIncludes(workflow, config.workflows);
371
+ const onlyError = checkOnly([resolved], options);
372
+ if (onlyError !== null) {
373
+ return results.fail(onlyError);
374
+ }
375
+ return await task.runTask(runWorkflow(resolved, registry, options));
376
+ });
377
+ /**
378
+ * Run all workflows matching a given event, resolving includes.
379
+ *
380
+ * @param event - Event name to match (e.g., "precommit")
381
+ * @param workflows - Available workflow definitions
382
+ * @param registry - Tool registry
383
+ * @param options - Run options
384
+ * @returns Task wrapping an array of workflow results
385
+ */
386
+ export const runByEvent = (event, workflows, registry, options = {}) => task.task(async () => {
387
+ const matching = workflows.filter((w) => w.on.includes(event));
388
+ if (matching.length === 0) {
389
+ return results.fail(workflowError(`No workflows found for event '${event}'. ` +
390
+ `Available: ${joinOrNone(workflows.map((w) => `${w.id} (${w.on.join(", ")})`), "; ")}`));
391
+ }
392
+ const resolvedWorkflows = matching.map((workflow) => resolveIncludes(workflow, workflows));
393
+ const onlyError = checkOnly(resolvedWorkflows, options);
394
+ if (onlyError !== null) {
395
+ return results.fail(onlyError);
396
+ }
397
+ const workflowResults = [];
398
+ for (const resolved of resolvedWorkflows) {
399
+ // Workflows run one at a time on purpose: in fix mode they change the
400
+ // same files, and the first failing workflow stops the run.
401
+ // oxlint-disable-next-line no-await-in-loop
402
+ const result = await task.runTask(runWorkflow(resolved, registry, options));
403
+ if (results.isFail(result))
404
+ return result;
405
+ workflowResults.push(result.value);
406
+ }
407
+ return results.ok(workflowResults);
408
+ });
@@ -0,0 +1,125 @@
1
+ /**
2
+ * Tools that run a function as a workflow step: a TypeScript `Handler`, or a
3
+ * function registered in Go (ADR 0011).
4
+ *
5
+ * The input of the function is the options of the step, the ones the manifest
6
+ * gives and the ones the engine adds (`root`, `fix`, `dryRun`, `_args`,
7
+ * `_changedFiles`), the same input the Go engine gives a function step. The
8
+ * step's signal ends the function: a TypeScript handler reads it from its
9
+ * `Cancellable` context, and a native function stops through its Go context.
10
+ *
11
+ * A function that answers a `ToolOutput` (`passed`, `issues`, `mutations`,
12
+ * `stats`, the output of a Go function that declares the workflow trigger)
13
+ * fills the result of the step. Any other function passes its step, and its
14
+ * output is not kept: the stats of a TypeScript step hold numbers only.
15
+ *
16
+ * A function that fails with a `ValidationError` or an `AdaptError` fails the
17
+ * step with its message and the run goes on. Any other failure is thrown, which
18
+ * stops the run unless the step sets `continueOnError`.
19
+ *
20
+ * @module
21
+ */
22
+ import * as native from "@eserstack/functions/native";
23
+ import type * as handler from "@eserstack/functions/handler";
24
+ import * as task from "@eserstack/functions/task";
25
+ import type { WorkflowFileMutation, WorkflowIssue, WorkflowTool, WorkflowToolResult } from "./types.ts";
26
+ /** The error a function step fails with: the tag and the message. */
27
+ export type FunctionStepError = {
28
+ readonly _tag: string;
29
+ readonly message: string;
30
+ };
31
+ /**
32
+ * A function the workflow engine runs as a step. The input is the options of
33
+ * the step. A handler that needs the step's signal takes a `Cancellable`
34
+ * context; one that does not takes none. `fromNative` returns the first kind.
35
+ */
36
+ export type StepHandler = handler.Handler<Readonly<Record<string, unknown>>, unknown, FunctionStepError, task.Cancellable> | handler.Handler<Readonly<Record<string, unknown>>, unknown, FunctionStepError, void>;
37
+ /** What a function answers to fill the result of its step. */
38
+ export type ToolOutput = {
39
+ readonly passed: boolean;
40
+ readonly issues?: readonly WorkflowIssue[];
41
+ readonly mutations?: readonly WorkflowFileMutation[];
42
+ readonly stats?: Readonly<Record<string, unknown>>;
43
+ };
44
+ /**
45
+ * Read the output of a function as the result of a step. An output that is a
46
+ * `ToolOutput` is the result; any other output passes the step.
47
+ *
48
+ * ```ts
49
+ * import * as workflows from "@eserstack/workflows/mod";
50
+ *
51
+ * const result = workflows.toolResultOfOutput("check", {
52
+ * passed: false,
53
+ * issues: [{ message: "a.txt: file does not end with a newline" }],
54
+ * });
55
+ * // { name: "check", passed: false, issues: [...], mutations: [], stats: {} }
56
+ * ```
57
+ */
58
+ export declare const toolResultOfOutput: (name: string, output: unknown) => WorkflowToolResult;
59
+ /**
60
+ * Run a TypeScript `Handler` as a workflow tool.
61
+ *
62
+ * ```ts
63
+ * import * as functions from "@eserstack/functions";
64
+ * import * as workflows from "@eserstack/workflows/mod";
65
+ *
66
+ * const countFiles = workflows.createHandlerTool(
67
+ * "count-files",
68
+ * "Count the files a step names",
69
+ * (options) =>
70
+ * functions.task.succeed({
71
+ * passed: true,
72
+ * stats: { files: String(options["root"]).length },
73
+ * }),
74
+ * );
75
+ * ```
76
+ *
77
+ * @param name - The name a step uses for the tool
78
+ * @param description - What the tool does
79
+ * @param stepHandler - The function; its input is the options of the step
80
+ */
81
+ export declare const createHandlerTool: (name: string, description: string, stepHandler: StepHandler) => WorkflowTool;
82
+ /** The name of the tool `createNativeFunctionTool` makes. */
83
+ export declare const NATIVE_FUNCTION_TOOL = "native-function";
84
+ /**
85
+ * A tool that runs a function registered in Go, chosen by the `function`
86
+ * option of the step. The other options are its input.
87
+ *
88
+ * ```yaml
89
+ * - native-function:
90
+ * function: validate-eof
91
+ * exclude: [node_modules]
92
+ * ```
93
+ *
94
+ * The caller is the port to the native library, the way `fromNative` takes it:
95
+ * `callFunction` of `@eserstack/ajan/ffi/functions` on a loaded library. A step
96
+ * without `function` fails with a message that says so.
97
+ *
98
+ * @param caller - Reaches the native library
99
+ */
100
+ export declare const createNativeFunctionTool: (caller: native.NativeCaller) => WorkflowTool;
101
+ /** What a native function says about itself; a descriptor from the bridge has it. */
102
+ export type NativeFunctionInfo = {
103
+ readonly name: string;
104
+ readonly description?: string;
105
+ };
106
+ /**
107
+ * One tool per native function, each under the function's own name, so a step
108
+ * names it directly like it names any other tool.
109
+ *
110
+ * ```ts
111
+ * import * as workflows from "@eserstack/workflows/mod";
112
+ *
113
+ * declare const caller: workflows.NativeCaller;
114
+ *
115
+ * const registry = workflows.createRegistry();
116
+ * registry.registerAll(
117
+ * workflows.createNativeFunctionTools(caller, [{ name: "validate-eof" }]),
118
+ * );
119
+ * ```
120
+ *
121
+ * @param caller - Reaches the native library
122
+ * @param functions - The functions to expose, such as the list the bridge gives
123
+ */
124
+ export declare const createNativeFunctionTools: (caller: native.NativeCaller, functions: readonly NativeFunctionInfo[]) => readonly WorkflowTool[];
125
+ export type { NativeCaller } from "@eserstack/functions/native";
@@ -0,0 +1,159 @@
1
+ // Copyright 2023-present Eser Ozvataf and other contributors. All rights reserved. Apache-2.0 license.
2
+ /**
3
+ * Tools that run a function as a workflow step: a TypeScript `Handler`, or a
4
+ * function registered in Go (ADR 0011).
5
+ *
6
+ * The input of the function is the options of the step, the ones the manifest
7
+ * gives and the ones the engine adds (`root`, `fix`, `dryRun`, `_args`,
8
+ * `_changedFiles`), the same input the Go engine gives a function step. The
9
+ * step's signal ends the function: a TypeScript handler reads it from its
10
+ * `Cancellable` context, and a native function stops through its Go context.
11
+ *
12
+ * A function that answers a `ToolOutput` (`passed`, `issues`, `mutations`,
13
+ * `stats`, the output of a Go function that declares the workflow trigger)
14
+ * fills the result of the step. Any other function passes its step, and its
15
+ * output is not kept: the stats of a TypeScript step hold numbers only.
16
+ *
17
+ * A function that fails with a `ValidationError` or an `AdaptError` fails the
18
+ * step with its message and the run goes on. Any other failure is thrown, which
19
+ * stops the run unless the step sets `continueOnError`.
20
+ *
21
+ * @module
22
+ */
23
+ import * as native from "@eserstack/functions/native";
24
+ import * as task from "@eserstack/functions/task";
25
+ import * as results from "@eserstack/primitives/results";
26
+ const TOOL_OUTPUT_KEYS = new Set([
27
+ "passed",
28
+ "issues",
29
+ "mutations",
30
+ "stats",
31
+ ]);
32
+ const isToolOutput = (value) => {
33
+ if (typeof value !== "object" || value === null || Array.isArray(value)) {
34
+ return false;
35
+ }
36
+ const fields = value;
37
+ return (typeof fields["passed"] === "boolean" &&
38
+ Object.keys(fields).every((key) => TOOL_OUTPUT_KEYS.has(key)));
39
+ };
40
+ const numbersOf = (stats) => Object.fromEntries(Object.entries(stats ?? {}).filter((entry) => typeof entry[1] === "number"));
41
+ /**
42
+ * Read the output of a function as the result of a step. An output that is a
43
+ * `ToolOutput` is the result; any other output passes the step.
44
+ *
45
+ * ```ts
46
+ * import * as workflows from "@eserstack/workflows/mod";
47
+ *
48
+ * const result = workflows.toolResultOfOutput("check", {
49
+ * passed: false,
50
+ * issues: [{ message: "a.txt: file does not end with a newline" }],
51
+ * });
52
+ * // { name: "check", passed: false, issues: [...], mutations: [], stats: {} }
53
+ * ```
54
+ */
55
+ export const toolResultOfOutput = (name, output) => isToolOutput(output)
56
+ ? {
57
+ name,
58
+ passed: output.passed,
59
+ issues: output.issues ?? [],
60
+ mutations: output.mutations ?? [],
61
+ stats: numbersOf(output.stats),
62
+ }
63
+ : { name, passed: true, issues: [], mutations: [], stats: {} };
64
+ const failedStep = (name, message) => ({
65
+ name,
66
+ passed: false,
67
+ issues: [{ message }],
68
+ mutations: [],
69
+ stats: {},
70
+ });
71
+ const runStepHandler = async (name, stepHandler, options, signal) => {
72
+ // A task that needs no context ignores the one it is given, so both kinds of
73
+ // handler run with the step's signal as their context.
74
+ const started = stepHandler(options);
75
+ const result = await started.execute({ signal });
76
+ if (results.isOk(result)) {
77
+ return toolResultOfOutput(name, result.value);
78
+ }
79
+ const { error } = result;
80
+ if (error._tag === "ValidationError" || error._tag === "AdaptError") {
81
+ return failedStep(name, error.message);
82
+ }
83
+ throw new Error(`${name}: ${error.message}`, { cause: error });
84
+ };
85
+ /**
86
+ * Run a TypeScript `Handler` as a workflow tool.
87
+ *
88
+ * ```ts
89
+ * import * as functions from "@eserstack/functions";
90
+ * import * as workflows from "@eserstack/workflows/mod";
91
+ *
92
+ * const countFiles = workflows.createHandlerTool(
93
+ * "count-files",
94
+ * "Count the files a step names",
95
+ * (options) =>
96
+ * functions.task.succeed({
97
+ * passed: true,
98
+ * stats: { files: String(options["root"]).length },
99
+ * }),
100
+ * );
101
+ * ```
102
+ *
103
+ * @param name - The name a step uses for the tool
104
+ * @param description - What the tool does
105
+ * @param stepHandler - The function; its input is the options of the step
106
+ */
107
+ export const createHandlerTool = (name, description, stepHandler) => ({
108
+ name,
109
+ description,
110
+ run: (options, context) => runStepHandler(name, stepHandler, options, context.signal),
111
+ });
112
+ /** The name of the tool `createNativeFunctionTool` makes. */
113
+ export const NATIVE_FUNCTION_TOOL = "native-function";
114
+ /**
115
+ * A tool that runs a function registered in Go, chosen by the `function`
116
+ * option of the step. The other options are its input.
117
+ *
118
+ * ```yaml
119
+ * - native-function:
120
+ * function: validate-eof
121
+ * exclude: [node_modules]
122
+ * ```
123
+ *
124
+ * The caller is the port to the native library, the way `fromNative` takes it:
125
+ * `callFunction` of `@eserstack/ajan/ffi/functions` on a loaded library. A step
126
+ * without `function` fails with a message that says so.
127
+ *
128
+ * @param caller - Reaches the native library
129
+ */
130
+ export const createNativeFunctionTool = (caller) => ({
131
+ name: NATIVE_FUNCTION_TOOL,
132
+ description: "Run a function registered in the native library (Go)",
133
+ run: (options, context) => {
134
+ const { function: functionName, ...input } = options;
135
+ if (typeof functionName !== "string" || functionName === "") {
136
+ return Promise.resolve(failedStep(NATIVE_FUNCTION_TOOL, 'option "function" (string) is required: the name of the native function'));
137
+ }
138
+ return runStepHandler(functionName, native.fromNative(caller, functionName), input, context.signal);
139
+ },
140
+ });
141
+ /**
142
+ * One tool per native function, each under the function's own name, so a step
143
+ * names it directly like it names any other tool.
144
+ *
145
+ * ```ts
146
+ * import * as workflows from "@eserstack/workflows/mod";
147
+ *
148
+ * declare const caller: workflows.NativeCaller;
149
+ *
150
+ * const registry = workflows.createRegistry();
151
+ * registry.registerAll(
152
+ * workflows.createNativeFunctionTools(caller, [{ name: "validate-eof" }]),
153
+ * );
154
+ * ```
155
+ *
156
+ * @param caller - Reaches the native library
157
+ * @param functions - The functions to expose, such as the list the bridge gives
158
+ */
159
+ export const createNativeFunctionTools = (caller, functions) => functions.map((info) => createHandlerTool(info.name, info.description ?? `Native function ${info.name}`, native.fromNative(caller, info.name)));