@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/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 CHANGED
@@ -1,3 +1,311 @@
1
- # Temporary Holding Version
1
+ # ⚡ [@eserstack/workflows](./)
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
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;
@@ -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
+ };
@@ -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>;