@eserstack/workflows 0.0.0-bootstrap.0 → 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/LICENSE +13 -0
- package/README.md +311 -0
- package/dist/builder.d.ts +45 -0
- package/dist/builder.js +61 -0
- package/dist/engine.d.ts +92 -0
- package/dist/engine.js +408 -0
- package/dist/function-tools.d.ts +125 -0
- package/dist/function-tools.js +159 -0
- package/dist/go-workflow-tool.d.ts +88 -0
- package/dist/go-workflow-tool.js +142 -0
- package/dist/list.d.ts +20 -0
- package/dist/list.js +94 -0
- package/dist/loader.d.ts +32 -0
- package/dist/loader.js +109 -0
- package/dist/main.d.ts +22 -0
- package/dist/main.js +46 -0
- package/dist/mod.d.ts +55 -0
- package/dist/mod.js +11 -0
- package/dist/module.d.ts +21 -0
- package/dist/module.js +41 -0
- package/dist/native-functions.d.ts +49 -0
- package/dist/native-functions.js +2 -0
- package/dist/package.json +71 -0
- package/dist/registry.d.ts +47 -0
- package/dist/registry.js +23 -0
- package/dist/run.d.ts +41 -0
- package/dist/run.js +283 -0
- package/dist/shell-tool.d.ts +18 -0
- package/dist/shell-tool.js +96 -0
- package/dist/types.d.ts +143 -0
- package/dist/types.js +2 -0
- package/package.json +60 -1
package/LICENSE
ADDED
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
Copyright 2023-present Eser Ozvataf and other contributors.
|
|
2
|
+
|
|
3
|
+
Licensed under the Apache License, Version 2.0 (the "License");
|
|
4
|
+
you may not use this file except in compliance with the License.
|
|
5
|
+
You may obtain a copy of the License at
|
|
6
|
+
|
|
7
|
+
http://www.apache.org/licenses/LICENSE-2.0
|
|
8
|
+
|
|
9
|
+
Unless required by applicable law or agreed to in writing, software
|
|
10
|
+
distributed under the License is distributed on an "AS IS" BASIS,
|
|
11
|
+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
12
|
+
See the License for the specific language governing permissions and
|
|
13
|
+
limitations under the License.
|
package/README.md
ADDED
|
@@ -0,0 +1,311 @@
|
|
|
1
|
+
# ⚡ [@eserstack/workflows](./)
|
|
2
|
+
|
|
3
|
+
> **Note:** JSR is frozen at 4.5.x. From 5.0.0, `@eserstack/workflows` is
|
|
4
|
+
> published on npm under the same name (`pnpm add @eserstack/workflows`); the
|
|
5
|
+
> JSR versions stay available but get no updates.
|
|
6
|
+
|
|
7
|
+
> **eserstack Tool** — [eser/stack on GitHub](https://github.com/eser/stack)
|
|
8
|
+
> **Install:** `pnpm add @eserstack/workflows`
|
|
9
|
+
|
|
10
|
+
`@eserstack/workflows` is an event-driven workflow engine for running tool
|
|
11
|
+
pipelines. Define workflows declaratively in YAML or build them programmatically
|
|
12
|
+
with the builder API.
|
|
13
|
+
|
|
14
|
+
## 🚀 Quick Start
|
|
15
|
+
|
|
16
|
+
```bash
|
|
17
|
+
# Run all workflows matching an event
|
|
18
|
+
npx eser workflows run -e precommit
|
|
19
|
+
|
|
20
|
+
# Run a specific workflow by id
|
|
21
|
+
npx eser workflows run -w default --fix
|
|
22
|
+
|
|
23
|
+
# List available workflows and tools
|
|
24
|
+
npx eser workflows list
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
## 📋 .eser/manifest.yml
|
|
28
|
+
|
|
29
|
+
Create a `.eser/manifest.yml` at your project root:
|
|
30
|
+
|
|
31
|
+
```yaml
|
|
32
|
+
stack:
|
|
33
|
+
- javascript
|
|
34
|
+
|
|
35
|
+
workflows:
|
|
36
|
+
- id: default
|
|
37
|
+
on: [precommit, prepush]
|
|
38
|
+
steps:
|
|
39
|
+
# Built-in validation tools (from @eserstack/codebase)
|
|
40
|
+
- validate-eof
|
|
41
|
+
- validate-json:
|
|
42
|
+
exclude: ["tsconfig.json"]
|
|
43
|
+
|
|
44
|
+
# Shell commands for external tools
|
|
45
|
+
- shell:
|
|
46
|
+
name: format
|
|
47
|
+
command: npx oxfmt --check
|
|
48
|
+
fixCommand: npx oxfmt
|
|
49
|
+
- shell:
|
|
50
|
+
name: tests
|
|
51
|
+
command: node --run test
|
|
52
|
+
timeout: 300
|
|
53
|
+
|
|
54
|
+
- id: commit-validation
|
|
55
|
+
on: [commitmsg]
|
|
56
|
+
steps:
|
|
57
|
+
- validate-commit-msg:
|
|
58
|
+
forceScope: true
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
## 🏗 Builder API
|
|
62
|
+
|
|
63
|
+
Build workflows programmatically without YAML. The package root
|
|
64
|
+
(`@eserstack/workflows`) is the standalone CLI, so the library API is imported
|
|
65
|
+
from `@eserstack/workflows/mod`:
|
|
66
|
+
|
|
67
|
+
```ts
|
|
68
|
+
import * as workflows from "@eserstack/workflows/mod";
|
|
69
|
+
import * as functions from "@eserstack/functions";
|
|
70
|
+
import * as primitives from "@eserstack/primitives";
|
|
71
|
+
|
|
72
|
+
// Create a registry and register tools
|
|
73
|
+
const registry = workflows.createRegistry();
|
|
74
|
+
registry.register({
|
|
75
|
+
name: "my-check",
|
|
76
|
+
description: "Custom checker",
|
|
77
|
+
run: () =>
|
|
78
|
+
Promise.resolve({
|
|
79
|
+
name: "my-check",
|
|
80
|
+
passed: true,
|
|
81
|
+
issues: [],
|
|
82
|
+
mutations: [],
|
|
83
|
+
stats: { filesChecked: 1 },
|
|
84
|
+
}),
|
|
85
|
+
});
|
|
86
|
+
|
|
87
|
+
// Build a workflow
|
|
88
|
+
const workflow = workflows
|
|
89
|
+
.createWorkflow("ci")
|
|
90
|
+
.on("precommit")
|
|
91
|
+
.step("my-check", { strict: true })
|
|
92
|
+
.build();
|
|
93
|
+
|
|
94
|
+
// Run it: runWorkflow() returns a Task, functions.task.runTask() executes it
|
|
95
|
+
const result = await functions.task.runTask(
|
|
96
|
+
workflows.runWorkflow(workflow, registry, { fix: true }),
|
|
97
|
+
);
|
|
98
|
+
|
|
99
|
+
// result is Result<WorkflowResult, WorkflowError>
|
|
100
|
+
if (primitives.results.isFail(result)) {
|
|
101
|
+
throw new Error(`workflow "ci" did not run: ${result.error.message}`);
|
|
102
|
+
}
|
|
103
|
+
|
|
104
|
+
// passed is false when any step failed; steps holds each step's issues
|
|
105
|
+
const { passed, steps } = result.value;
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
The engine calls a tool's `run(options, context)` once per step. `options` holds
|
|
109
|
+
the step's options plus `root`, `fix`, `dryRun` and `_args` from the run.
|
|
110
|
+
`context.timeoutMs` is the step's time limit, and `context.signal` aborts when
|
|
111
|
+
the step ends, so pass them to the work the tool starts:
|
|
112
|
+
|
|
113
|
+
```ts
|
|
114
|
+
import * as workflows from "@eserstack/workflows/mod";
|
|
115
|
+
|
|
116
|
+
const registry = workflows.createRegistry();
|
|
117
|
+
registry.register({
|
|
118
|
+
name: "status-check",
|
|
119
|
+
description: "Checks that a URL answers 200",
|
|
120
|
+
run: async (options, context) => {
|
|
121
|
+
const url = options["url"] as string;
|
|
122
|
+
// Aborts when the step runs past its timeout, so the request stops too
|
|
123
|
+
const response = await fetch(url, { signal: context.signal });
|
|
124
|
+
await response.body?.cancel();
|
|
125
|
+
|
|
126
|
+
return {
|
|
127
|
+
name: "status-check",
|
|
128
|
+
passed: response.status === 200,
|
|
129
|
+
issues:
|
|
130
|
+
response.status === 200
|
|
131
|
+
? []
|
|
132
|
+
: [{ message: `${url} answered ${response.status}` }],
|
|
133
|
+
mutations: [],
|
|
134
|
+
stats: { status: response.status },
|
|
135
|
+
};
|
|
136
|
+
},
|
|
137
|
+
});
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
Or define from a plain object:
|
|
141
|
+
|
|
142
|
+
```ts
|
|
143
|
+
import * as workflows from "@eserstack/workflows/mod";
|
|
144
|
+
|
|
145
|
+
const workflow = workflows.defineWorkflow({
|
|
146
|
+
id: "ci",
|
|
147
|
+
on: ["precommit"],
|
|
148
|
+
steps: ["my-check", { "other-check": { strict: true } }],
|
|
149
|
+
});
|
|
150
|
+
```
|
|
151
|
+
|
|
152
|
+
## 🐚 Shell Tool
|
|
153
|
+
|
|
154
|
+
The built-in `shell` tool executes commands via subprocess:
|
|
155
|
+
|
|
156
|
+
```yaml
|
|
157
|
+
- shell:
|
|
158
|
+
name: format
|
|
159
|
+
command: npx oxfmt --check # runs in check mode
|
|
160
|
+
fixCommand: npx oxfmt # runs when --fix is passed without --dry-run
|
|
161
|
+
workingDirectory: ./src/ # optional, relative to the project root
|
|
162
|
+
timeout: 120 # timeout in seconds
|
|
163
|
+
continueOnError: true # don't fail the whole workflow
|
|
164
|
+
```
|
|
165
|
+
|
|
166
|
+
A command that runs past the step's `timeout` is stopped, and the step fails
|
|
167
|
+
with "Step 'format' (shell) ran past its 120s timeout". With `--dry-run` the
|
|
168
|
+
tool never runs `fixCommand`, which would write files; it runs `command` and
|
|
169
|
+
reports what that finds.
|
|
170
|
+
|
|
171
|
+
## 🔗 Functions and Go Workflows as Steps
|
|
172
|
+
|
|
173
|
+
A step can run a function that lives in Go, a TypeScript function, or a whole
|
|
174
|
+
workflow on the Go engine. The tools take the port to the native library as an
|
|
175
|
+
argument, so this package loads no native library until you pass one:
|
|
176
|
+
|
|
177
|
+
```typescript
|
|
178
|
+
import * as workflows from "@eserstack/workflows/mod";
|
|
179
|
+
|
|
180
|
+
// A caller reaches the native library; `@eserstack/ajan/ffi/functions` has one.
|
|
181
|
+
const caller: workflows.NativeCaller = () =>
|
|
182
|
+
Promise.resolve({ ok: true, output: { passed: true } });
|
|
183
|
+
|
|
184
|
+
const registry = workflows.createRegistry();
|
|
185
|
+
registry.register(workflows.createNativeFunctionTool(caller));
|
|
186
|
+
|
|
187
|
+
const workflow = workflows
|
|
188
|
+
.createWorkflow("mixed")
|
|
189
|
+
.on("check")
|
|
190
|
+
.step("native-function", { function: "validate-eof" })
|
|
191
|
+
.build();
|
|
192
|
+
```
|
|
193
|
+
|
|
194
|
+
`createGoWorkflowTool` runs a manifest workflow on the Go engine, and
|
|
195
|
+
`createHandlerTool` runs a `@eserstack/functions` handler. The eser CLI
|
|
196
|
+
registers `native-function` and `go-workflow` on `eser workflows run`, so the
|
|
197
|
+
steps of a manifest can name them. Go cannot call TypeScript. [WIRING.md](./WIRING.md#tools-that-reach-go-adr-0011) has the
|
|
198
|
+
options, the results and the two ports.
|
|
199
|
+
|
|
200
|
+
## 📋 CLI Flags
|
|
201
|
+
|
|
202
|
+
```text
|
|
203
|
+
-e, --event <name> Run workflows matching an event
|
|
204
|
+
-w, --workflow <id> Run a specific workflow by id
|
|
205
|
+
--fix Auto-fix issues (uses fixCommand for shell steps)
|
|
206
|
+
--dry-run Preview mutations without writing files (shell steps run command)
|
|
207
|
+
--json Output results as JSON (suppresses progress)
|
|
208
|
+
-v, --verbose Show stats and issues for all steps
|
|
209
|
+
--changed Only check files changed in git
|
|
210
|
+
--only <step> Run only the steps with this tool or step name; fails when none matches
|
|
211
|
+
--config <path> Config directory (default: .)
|
|
212
|
+
-h, --help Show help
|
|
213
|
+
```
|
|
214
|
+
|
|
215
|
+
## ⚙️ Step Options
|
|
216
|
+
|
|
217
|
+
Engine directives that can be added to any step:
|
|
218
|
+
|
|
219
|
+
```yaml
|
|
220
|
+
- validate-json:
|
|
221
|
+
exclude: [...] # tool-specific option
|
|
222
|
+
continueOnError: true # don't stop workflow on failure
|
|
223
|
+
timeout: 120 # per-step timeout in seconds (default: 60)
|
|
224
|
+
```
|
|
225
|
+
|
|
226
|
+
A step that runs past its `timeout` fails with "Step 'validate-json' ran past
|
|
227
|
+
its 120s timeout". The engine then aborts the signal it gave the tool and waits
|
|
228
|
+
up to five seconds for the tool to stop before the workflow goes on.
|
|
229
|
+
|
|
230
|
+
## 🔗 Workflow Composition
|
|
231
|
+
|
|
232
|
+
Reuse steps across workflows with `includes`:
|
|
233
|
+
|
|
234
|
+
```yaml
|
|
235
|
+
workflows:
|
|
236
|
+
- id: common-fixers
|
|
237
|
+
on: []
|
|
238
|
+
steps:
|
|
239
|
+
- validate-eof
|
|
240
|
+
- validate-trailing-whitespace
|
|
241
|
+
|
|
242
|
+
- id: default
|
|
243
|
+
on: [precommit]
|
|
244
|
+
includes: [common-fixers]
|
|
245
|
+
steps:
|
|
246
|
+
- validate-json
|
|
247
|
+
```
|
|
248
|
+
|
|
249
|
+
## 📦 Package Structure
|
|
250
|
+
|
|
251
|
+
```text
|
|
252
|
+
@eserstack/workflows
|
|
253
|
+
├── main.ts Standalone CLI (package root)
|
|
254
|
+
├── mod.ts Core library (types, registry, engine, builder)
|
|
255
|
+
├── module.ts Command module that the eser CLI mounts
|
|
256
|
+
├── loader.ts .eser/manifest.yml file loader
|
|
257
|
+
├── run.ts CLI: workflows run
|
|
258
|
+
├── list.ts CLI: workflows list
|
|
259
|
+
└── shell-tool.ts Built-in shell command tool
|
|
260
|
+
```
|
|
261
|
+
|
|
262
|
+
The core library (`mod.ts`) has zero I/O dependencies — it's pure functions for
|
|
263
|
+
composing and running workflows. File loading and CLI are separate entry points.
|
|
264
|
+
|
|
265
|
+
`runWorkflow()`, `runWorkflowWithConfig()` and `runByEvent()` return lazy `Task`
|
|
266
|
+
values (from `@eserstack/functions`). Use `functions.task.runTask()` to execute
|
|
267
|
+
one and get a `Result`, then check it with `primitives.results.isOk()` or
|
|
268
|
+
`primitives.results.isFail()`.
|
|
269
|
+
|
|
270
|
+
## Upgrading from 4.x
|
|
271
|
+
|
|
272
|
+
These changes since 4.5.2 need a change in code, commands or files that use this
|
|
273
|
+
package. The [changelog](https://github.com/eser/stack/blob/main/CHANGELOG.md)
|
|
274
|
+
lists the changes in every package.
|
|
275
|
+
|
|
276
|
+
- `WorkflowTool.run` takes a second argument, `context: WorkflowToolContext`
|
|
277
|
+
(`{ timeoutMs, signal }`), and the engine always passes it. Code that calls a
|
|
278
|
+
tool itself passes a context:
|
|
279
|
+
|
|
280
|
+
```typescript
|
|
281
|
+
// Before
|
|
282
|
+
await tool.run(options);
|
|
283
|
+
// After
|
|
284
|
+
await tool.run(options, {
|
|
285
|
+
timeoutMs: 60_000,
|
|
286
|
+
signal: AbortSignal.timeout(60_000),
|
|
287
|
+
});
|
|
288
|
+
```
|
|
289
|
+
|
|
290
|
+
- Shell step commands are stopped at the step timeout, 60 s by default; with the
|
|
291
|
+
native library loaded the timeout never fired before. Set `timeout` (seconds)
|
|
292
|
+
on steps that need longer: `timeout: 600`.
|
|
293
|
+
- A step `timeout` must be a number of seconds above 0 and at most 2147483. A
|
|
294
|
+
string, zero, a negative number, `.nan` or `.inf` throws
|
|
295
|
+
`Invalid step config for '<step>': timeout must be a number of seconds ...`,
|
|
296
|
+
and `RunOptions.defaultTimeout` outside (0, 2147483647] makes `runWorkflow`
|
|
297
|
+
return a `WorkflowError`. Before: `timeout: "30"`. After: `timeout: 30`.
|
|
298
|
+
- A step timeout reads
|
|
299
|
+
`Step 'x' ran past its Ns timeout; raise the step's timeout option (in seconds) to give it more time`
|
|
300
|
+
instead of `Step 'x' timed out after Ns`, and the run waits up to 5 s for the
|
|
301
|
+
tool to stop. Update code that matches the old message.
|
|
302
|
+
- With `--fix --dry-run`, a shell step runs `command`, not `fixCommand`, which
|
|
303
|
+
used to write files during a dry run. Drop `--dry-run` to apply shell fixes.
|
|
304
|
+
- The shell tool's `workingDirectory` is resolved against the run root (the
|
|
305
|
+
`--config` directory) instead of the process working directory. Write it
|
|
306
|
+
relative to the project root, or as an absolute path.
|
|
307
|
+
|
|
308
|
+
---
|
|
309
|
+
|
|
310
|
+
🔗 For further details, visit the
|
|
311
|
+
[eserstack repository](https://github.com/eser/stack).
|
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Builder pattern for constructing workflow definitions programmatically.
|
|
3
|
+
*
|
|
4
|
+
* @example
|
|
5
|
+
* ```typescript
|
|
6
|
+
* import * as workflows from "@eserstack/workflows/mod";
|
|
7
|
+
*
|
|
8
|
+
* const workflow = workflows.createWorkflow("default")
|
|
9
|
+
* .on("precommit", "prepush")
|
|
10
|
+
* .step("fix-eof")
|
|
11
|
+
* .step("check-json", { exclude: ["tsconfig.json"] })
|
|
12
|
+
* .build();
|
|
13
|
+
* ```
|
|
14
|
+
*
|
|
15
|
+
* @module
|
|
16
|
+
*/
|
|
17
|
+
import type { WorkflowDefinition } from "./types.ts";
|
|
18
|
+
/** Fluent builder for workflow definitions. */
|
|
19
|
+
export type WorkflowBuilder = {
|
|
20
|
+
/** Add events that trigger this workflow. */
|
|
21
|
+
readonly on: (...events: string[]) => WorkflowBuilder;
|
|
22
|
+
/** Add a step (tool name, optionally with config). */
|
|
23
|
+
readonly step: (name: string, options?: Record<string, unknown>) => WorkflowBuilder;
|
|
24
|
+
/** Mark the last step as bypass — skip tool execution; output = previous step's stats. */
|
|
25
|
+
readonly bypass: () => WorkflowBuilder;
|
|
26
|
+
/** Set a JSON Schema (draft-2020-12) that validates the last step's merged options before tool.run(). */
|
|
27
|
+
readonly inputSchema: (schema: Record<string, unknown>) => WorkflowBuilder;
|
|
28
|
+
/** Build the immutable WorkflowDefinition. */
|
|
29
|
+
readonly build: () => WorkflowDefinition;
|
|
30
|
+
};
|
|
31
|
+
/**
|
|
32
|
+
* Create a workflow builder.
|
|
33
|
+
*
|
|
34
|
+
* @param id - Workflow identifier
|
|
35
|
+
* @returns A fluent WorkflowBuilder
|
|
36
|
+
*/
|
|
37
|
+
export declare const createWorkflow: (id: string) => WorkflowBuilder;
|
|
38
|
+
/**
|
|
39
|
+
* Define a workflow from a plain object.
|
|
40
|
+
* Validates the definition structure.
|
|
41
|
+
*
|
|
42
|
+
* @param definition - Workflow definition object
|
|
43
|
+
* @returns Validated WorkflowDefinition
|
|
44
|
+
*/
|
|
45
|
+
export declare const defineWorkflow: (definition: WorkflowDefinition) => WorkflowDefinition;
|
package/dist/builder.js
ADDED
|
@@ -0,0 +1,61 @@
|
|
|
1
|
+
// Copyright 2023-present Eser Ozvataf and other contributors. All rights reserved. Apache-2.0 license.
|
|
2
|
+
/**
|
|
3
|
+
* Create a workflow builder.
|
|
4
|
+
*
|
|
5
|
+
* @param id - Workflow identifier
|
|
6
|
+
* @returns A fluent WorkflowBuilder
|
|
7
|
+
*/
|
|
8
|
+
export const createWorkflow = (id) => {
|
|
9
|
+
const events = [];
|
|
10
|
+
const steps = [];
|
|
11
|
+
const toStepConfig = (s) => Object.keys(s.options).length > 0 ? { [s.name]: s.options } : s.name;
|
|
12
|
+
const builder = {
|
|
13
|
+
on: (...newEvents) => {
|
|
14
|
+
events.push(...newEvents);
|
|
15
|
+
return builder;
|
|
16
|
+
},
|
|
17
|
+
step: (name, options) => {
|
|
18
|
+
steps.push({ name, options: { ...(options ?? {}) } });
|
|
19
|
+
return builder;
|
|
20
|
+
},
|
|
21
|
+
bypass: () => {
|
|
22
|
+
const last = steps[steps.length - 1];
|
|
23
|
+
if (last !== undefined) {
|
|
24
|
+
last.options["bypass"] = true;
|
|
25
|
+
}
|
|
26
|
+
return builder;
|
|
27
|
+
},
|
|
28
|
+
inputSchema: (schema) => {
|
|
29
|
+
const last = steps[steps.length - 1];
|
|
30
|
+
if (last !== undefined) {
|
|
31
|
+
last.options["inputSchema"] = schema;
|
|
32
|
+
}
|
|
33
|
+
return builder;
|
|
34
|
+
},
|
|
35
|
+
build: () => ({
|
|
36
|
+
id,
|
|
37
|
+
on: [...events],
|
|
38
|
+
steps: steps.map(toStepConfig),
|
|
39
|
+
}),
|
|
40
|
+
};
|
|
41
|
+
return builder;
|
|
42
|
+
};
|
|
43
|
+
/**
|
|
44
|
+
* Define a workflow from a plain object.
|
|
45
|
+
* Validates the definition structure.
|
|
46
|
+
*
|
|
47
|
+
* @param definition - Workflow definition object
|
|
48
|
+
* @returns Validated WorkflowDefinition
|
|
49
|
+
*/
|
|
50
|
+
export const defineWorkflow = (definition) => {
|
|
51
|
+
if (definition.id === undefined || definition.id.length === 0) {
|
|
52
|
+
throw new Error("Workflow id is required");
|
|
53
|
+
}
|
|
54
|
+
if (definition.on.length === 0) {
|
|
55
|
+
throw new Error(`Workflow '${definition.id}' must have at least one event`);
|
|
56
|
+
}
|
|
57
|
+
if (definition.steps.length === 0) {
|
|
58
|
+
throw new Error(`Workflow '${definition.id}' must have at least one step`);
|
|
59
|
+
}
|
|
60
|
+
return definition;
|
|
61
|
+
};
|
package/dist/engine.d.ts
ADDED
|
@@ -0,0 +1,92 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Workflow execution engine.
|
|
3
|
+
*
|
|
4
|
+
* Pure functions that run workflow pipelines. The engine itself performs
|
|
5
|
+
* no I/O — mutations are returned in results and the caller decides
|
|
6
|
+
* whether to apply them (via the `onMutations` callback).
|
|
7
|
+
*
|
|
8
|
+
* Uses `@eserstack/functions/task` for lazy composition and result-based
|
|
9
|
+
* error recovery.
|
|
10
|
+
*
|
|
11
|
+
* ```
|
|
12
|
+
* runWorkflow(workflow, registry, options)
|
|
13
|
+
* │
|
|
14
|
+
* ├─ For each step:
|
|
15
|
+
* │ ├─ resolveStep() → { name, options, continueOnError, timeout }
|
|
16
|
+
* │ ├─ Lookup tool in registry
|
|
17
|
+
* │ ├─ Merge step options + run options
|
|
18
|
+
* │ ├─ Run tool with { timeoutMs, signal }; on timeout abort the signal,
|
|
19
|
+
* │ │ give the tool STOP_GRACE_MS to stop, and fail the step
|
|
20
|
+
* │ ├─ On error: if continueOnError → failed step; else propagate error
|
|
21
|
+
* │ ├─ Call onMutations() if mutations produced
|
|
22
|
+
* │ └─ Call onStepEnd()
|
|
23
|
+
* │
|
|
24
|
+
* └─ Return aggregate WorkflowResult
|
|
25
|
+
*
|
|
26
|
+
* resolveIncludes(workflow, allWorkflows)
|
|
27
|
+
* ├─ For each included id, find in allWorkflows
|
|
28
|
+
* ├─ Prepend their steps to current workflow's steps
|
|
29
|
+
* ├─ Track visited ids → detect circular includes → throw
|
|
30
|
+
* └─ Return flattened WorkflowDefinition
|
|
31
|
+
* ```
|
|
32
|
+
*
|
|
33
|
+
* @module
|
|
34
|
+
*/
|
|
35
|
+
import * as task from "@eserstack/functions/task";
|
|
36
|
+
import type { Registry } from "./registry.ts";
|
|
37
|
+
import type { ResolvedStep, RunOptions, WorkflowDefinition, WorkflowError, WorkflowResult, WorkflowsConfig, WorkflowStepConfig } from "./types.ts";
|
|
38
|
+
/**
|
|
39
|
+
* Parse a step config into a resolved step with name, options, and engine directives.
|
|
40
|
+
*
|
|
41
|
+
* Engine directives (`continueOnError`, `timeout`) are extracted from the options
|
|
42
|
+
* and placed on the ResolvedStep. They are NOT passed to the tool.
|
|
43
|
+
*
|
|
44
|
+
* - `"fix-eof"` → `{ name: "fix-eof", options: {}, continueOnError: false }`
|
|
45
|
+
* - `{ "check-json": { exclude: ["x"], timeout: 120 } }` → timeout extracted, options clean
|
|
46
|
+
*
|
|
47
|
+
* @throws {Error} When the record has other than one key, or its `timeout` is
|
|
48
|
+
* not a number of seconds above 0
|
|
49
|
+
*/
|
|
50
|
+
export declare const resolveStep: (step: WorkflowStepConfig) => ResolvedStep;
|
|
51
|
+
/**
|
|
52
|
+
* Run a single workflow definition against a registry of tools.
|
|
53
|
+
*
|
|
54
|
+
* Returns a `Task<WorkflowResult, WorkflowError>` — the computation is
|
|
55
|
+
* lazy and does not execute until `task.runTask()` is called.
|
|
56
|
+
*
|
|
57
|
+
* @param workflow - Workflow to run
|
|
58
|
+
* @param registry - Tool registry
|
|
59
|
+
* @param options - Run options
|
|
60
|
+
* @returns Task wrapping the workflow execution
|
|
61
|
+
*/
|
|
62
|
+
export declare const runWorkflow: (workflow: WorkflowDefinition, registry: Registry, options?: RunOptions) => task.Task<WorkflowResult, WorkflowError>;
|
|
63
|
+
/**
|
|
64
|
+
* Resolve includes by flattening included workflow steps before the current workflow's steps.
|
|
65
|
+
* Detects circular includes.
|
|
66
|
+
*
|
|
67
|
+
* @param workflow - Workflow with potential includes
|
|
68
|
+
* @param allWorkflows - All available workflow definitions
|
|
69
|
+
* @param visited - Set of visited workflow ids (for cycle detection)
|
|
70
|
+
* @returns A new WorkflowDefinition with includes resolved (steps flattened)
|
|
71
|
+
*/
|
|
72
|
+
export declare const resolveIncludes: (workflow: WorkflowDefinition, allWorkflows: readonly WorkflowDefinition[], visited?: ReadonlySet<string>) => WorkflowDefinition;
|
|
73
|
+
/**
|
|
74
|
+
* Run a workflow by id from a full config, resolving includes.
|
|
75
|
+
*
|
|
76
|
+
* @param workflowId - Workflow id to find and run
|
|
77
|
+
* @param config - Full workflow configuration
|
|
78
|
+
* @param registry - Tool registry
|
|
79
|
+
* @param options - Run options
|
|
80
|
+
* @returns Task wrapping the workflow execution
|
|
81
|
+
*/
|
|
82
|
+
export declare const runWorkflowWithConfig: (workflowId: string, config: WorkflowsConfig, registry: Registry, options?: RunOptions) => task.Task<WorkflowResult, WorkflowError>;
|
|
83
|
+
/**
|
|
84
|
+
* Run all workflows matching a given event, resolving includes.
|
|
85
|
+
*
|
|
86
|
+
* @param event - Event name to match (e.g., "precommit")
|
|
87
|
+
* @param workflows - Available workflow definitions
|
|
88
|
+
* @param registry - Tool registry
|
|
89
|
+
* @param options - Run options
|
|
90
|
+
* @returns Task wrapping an array of workflow results
|
|
91
|
+
*/
|
|
92
|
+
export declare const runByEvent: (event: string, workflows: readonly WorkflowDefinition[], registry: Registry, options?: RunOptions) => task.Task<readonly WorkflowResult[], WorkflowError>;
|