@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 +13 -0
- package/README.md +310 -2
- 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 +57 -3
|
@@ -0,0 +1,88 @@
|
|
|
1
|
+
import type { WorkflowFileMutation, WorkflowIssue, WorkflowTool, WorkflowToolResult } from "./types.ts";
|
|
2
|
+
/** The request of the Go engine's `workflowRun`. */
|
|
3
|
+
export type GoWorkflowRequest = {
|
|
4
|
+
/** The text of a `.eser/manifest.yml`. */
|
|
5
|
+
readonly manifest: string;
|
|
6
|
+
/** The id of the workflow to run. */
|
|
7
|
+
readonly workflowId: string;
|
|
8
|
+
readonly root: string;
|
|
9
|
+
readonly fix: boolean;
|
|
10
|
+
readonly dryRun: boolean;
|
|
11
|
+
readonly args: readonly string[];
|
|
12
|
+
/** Absent runs every file; present runs the validators on these only. */
|
|
13
|
+
readonly changedFiles?: readonly string[];
|
|
14
|
+
/** Runs only the steps this names. */
|
|
15
|
+
readonly only?: string;
|
|
16
|
+
/** The Go engine's timeout for a step that sets none, in milliseconds. */
|
|
17
|
+
readonly timeoutMs: number;
|
|
18
|
+
};
|
|
19
|
+
/** One step a Go workflow ran. */
|
|
20
|
+
export type GoWorkflowStep = {
|
|
21
|
+
readonly name: string;
|
|
22
|
+
readonly passed: boolean;
|
|
23
|
+
readonly issues?: readonly WorkflowIssue[];
|
|
24
|
+
readonly mutations?: readonly WorkflowFileMutation[];
|
|
25
|
+
readonly stats?: Readonly<Record<string, unknown>>;
|
|
26
|
+
readonly durationMs?: number;
|
|
27
|
+
};
|
|
28
|
+
/** The answer of `workflowRun`: the workflows that ran, or an error. */
|
|
29
|
+
export type GoWorkflowAnswer = {
|
|
30
|
+
readonly error?: string;
|
|
31
|
+
readonly results?: ReadonlyArray<{
|
|
32
|
+
readonly id: string;
|
|
33
|
+
readonly passed: boolean;
|
|
34
|
+
readonly steps: readonly GoWorkflowStep[];
|
|
35
|
+
readonly totalDurationMs?: number;
|
|
36
|
+
}>;
|
|
37
|
+
};
|
|
38
|
+
/**
|
|
39
|
+
* Runs a workflow on the Go engine: the port to the native library. On a
|
|
40
|
+
* loaded `@eserstack/ajan` library it is
|
|
41
|
+
* `(request, signal) => lib.call("workflowRun", request, { signal })`.
|
|
42
|
+
*/
|
|
43
|
+
export type GoWorkflowRunner = (request: GoWorkflowRequest, signal: AbortSignal) => Promise<GoWorkflowAnswer>;
|
|
44
|
+
/** The name of the tool `createGoWorkflowTool` makes. */
|
|
45
|
+
export declare const GO_WORKFLOW_TOOL = "go-workflow";
|
|
46
|
+
/**
|
|
47
|
+
* Turn the answer of the Go engine into the result of one step: it passes when
|
|
48
|
+
* every workflow that ran passed, the issues and mutations of every step are
|
|
49
|
+
* joined (an issue's message names its step), and the stats count the steps.
|
|
50
|
+
*
|
|
51
|
+
* ```ts
|
|
52
|
+
* import * as workflows from "@eserstack/workflows/mod";
|
|
53
|
+
*
|
|
54
|
+
* const result = workflows.toolResultOfGoWorkflow({
|
|
55
|
+
* results: [
|
|
56
|
+
* {
|
|
57
|
+
* id: "check",
|
|
58
|
+
* passed: false,
|
|
59
|
+
* steps: [
|
|
60
|
+
* { name: "validate-eof", passed: false, issues: [{ message: "a.txt" }] },
|
|
61
|
+
* ],
|
|
62
|
+
* },
|
|
63
|
+
* ],
|
|
64
|
+
* });
|
|
65
|
+
* // result.issues[0].message === "[validate-eof] a.txt"
|
|
66
|
+
* ```
|
|
67
|
+
*/
|
|
68
|
+
export declare const toolResultOfGoWorkflow: (answer: GoWorkflowAnswer) => WorkflowToolResult;
|
|
69
|
+
/**
|
|
70
|
+
* A tool that runs a workflow on the Go engine.
|
|
71
|
+
*
|
|
72
|
+
* Options:
|
|
73
|
+
* - `workflow` (string, required): the id of the workflow
|
|
74
|
+
* - `manifest` (string): the text of the manifest; wins over `manifestFile`
|
|
75
|
+
* - `manifestFile` (string): the manifest to read, relative to `root`
|
|
76
|
+
* (default `.eser/manifest.yml`)
|
|
77
|
+
* - `only` (string): run only the steps this names
|
|
78
|
+
* - `root`, `fix`, `dryRun`, `_args` and `_changedFiles`: from the run, and
|
|
79
|
+
* passed on to the Go engine
|
|
80
|
+
*
|
|
81
|
+
* The step's timeout is the Go engine's default step timeout, and the step's
|
|
82
|
+
* signal stops the call. An error the Go engine answers (an unknown workflow,
|
|
83
|
+
* a manifest it cannot parse) is thrown, which stops the run unless the step
|
|
84
|
+
* sets `continueOnError`.
|
|
85
|
+
*
|
|
86
|
+
* @param run - Runs a workflow on the Go engine
|
|
87
|
+
*/
|
|
88
|
+
export declare const createGoWorkflowTool: (run: GoWorkflowRunner) => WorkflowTool;
|
|
@@ -0,0 +1,142 @@
|
|
|
1
|
+
// Copyright 2023-present Eser Ozvataf and other contributors. All rights reserved. Apache-2.0 license.
|
|
2
|
+
/**
|
|
3
|
+
* A tool that runs a workflow on the Go engine (`pkg/ajan/workflowfx`) and
|
|
4
|
+
* brings its step results back (ADR 0011).
|
|
5
|
+
*
|
|
6
|
+
* The TypeScript engine stays the default of `workflows run`. This tool is for
|
|
7
|
+
* a workflow that wants one of its steps to be a whole Go workflow: the Go
|
|
8
|
+
* engine runs the steps, with its `if`, `loop`, `includes` and the Go tools
|
|
9
|
+
* and functions, and the TypeScript engine sees one step with the issues,
|
|
10
|
+
* mutations and counts of all of them. Go calls Go only: a Go workflow cannot
|
|
11
|
+
* call a TypeScript tool.
|
|
12
|
+
*
|
|
13
|
+
* ```yaml
|
|
14
|
+
* - go-workflow:
|
|
15
|
+
* workflow: precommit
|
|
16
|
+
* manifestFile: .eser/manifest.yml
|
|
17
|
+
* ```
|
|
18
|
+
*
|
|
19
|
+
* @module
|
|
20
|
+
*/
|
|
21
|
+
import { runtime } from "@eserstack/standards/cross-runtime";
|
|
22
|
+
/** The name of the tool `createGoWorkflowTool` makes. */
|
|
23
|
+
export const GO_WORKFLOW_TOOL = "go-workflow";
|
|
24
|
+
const DEFAULT_MANIFEST_FILE = ".eser/manifest.yml";
|
|
25
|
+
const stringOption = (options, key) => {
|
|
26
|
+
const value = options[key];
|
|
27
|
+
return typeof value === "string" && value !== "" ? value : undefined;
|
|
28
|
+
};
|
|
29
|
+
const stringListOption = (options, key) => {
|
|
30
|
+
const value = options[key];
|
|
31
|
+
return Array.isArray(value) &&
|
|
32
|
+
value.every((item) => typeof item === "string")
|
|
33
|
+
? value
|
|
34
|
+
: undefined;
|
|
35
|
+
};
|
|
36
|
+
const failed = (message) => ({
|
|
37
|
+
name: GO_WORKFLOW_TOOL,
|
|
38
|
+
passed: false,
|
|
39
|
+
issues: [{ message }],
|
|
40
|
+
mutations: [],
|
|
41
|
+
stats: {},
|
|
42
|
+
});
|
|
43
|
+
/**
|
|
44
|
+
* Turn the answer of the Go engine into the result of one step: it passes when
|
|
45
|
+
* every workflow that ran passed, the issues and mutations of every step are
|
|
46
|
+
* joined (an issue's message names its step), and the stats count the steps.
|
|
47
|
+
*
|
|
48
|
+
* ```ts
|
|
49
|
+
* import * as workflows from "@eserstack/workflows/mod";
|
|
50
|
+
*
|
|
51
|
+
* const result = workflows.toolResultOfGoWorkflow({
|
|
52
|
+
* results: [
|
|
53
|
+
* {
|
|
54
|
+
* id: "check",
|
|
55
|
+
* passed: false,
|
|
56
|
+
* steps: [
|
|
57
|
+
* { name: "validate-eof", passed: false, issues: [{ message: "a.txt" }] },
|
|
58
|
+
* ],
|
|
59
|
+
* },
|
|
60
|
+
* ],
|
|
61
|
+
* });
|
|
62
|
+
* // result.issues[0].message === "[validate-eof] a.txt"
|
|
63
|
+
* ```
|
|
64
|
+
*/
|
|
65
|
+
export const toolResultOfGoWorkflow = (answer) => {
|
|
66
|
+
const workflows = answer.results ?? [];
|
|
67
|
+
const steps = workflows.flatMap((workflow) => workflow.steps);
|
|
68
|
+
return {
|
|
69
|
+
name: GO_WORKFLOW_TOOL,
|
|
70
|
+
passed: workflows.every((workflow) => workflow.passed),
|
|
71
|
+
issues: steps.flatMap((step) => (step.issues ?? []).map((issue) => ({
|
|
72
|
+
...issue,
|
|
73
|
+
message: `[${step.name}] ${issue.message}`,
|
|
74
|
+
}))),
|
|
75
|
+
mutations: steps.flatMap((step) => step.mutations ?? []),
|
|
76
|
+
stats: {
|
|
77
|
+
steps: steps.length,
|
|
78
|
+
failedSteps: steps.filter((step) => !step.passed).length,
|
|
79
|
+
durationMs: workflows.reduce((total, workflow) => total + (workflow.totalDurationMs ?? 0), 0),
|
|
80
|
+
},
|
|
81
|
+
};
|
|
82
|
+
};
|
|
83
|
+
/**
|
|
84
|
+
* A tool that runs a workflow on the Go engine.
|
|
85
|
+
*
|
|
86
|
+
* Options:
|
|
87
|
+
* - `workflow` (string, required): the id of the workflow
|
|
88
|
+
* - `manifest` (string): the text of the manifest; wins over `manifestFile`
|
|
89
|
+
* - `manifestFile` (string): the manifest to read, relative to `root`
|
|
90
|
+
* (default `.eser/manifest.yml`)
|
|
91
|
+
* - `only` (string): run only the steps this names
|
|
92
|
+
* - `root`, `fix`, `dryRun`, `_args` and `_changedFiles`: from the run, and
|
|
93
|
+
* passed on to the Go engine
|
|
94
|
+
*
|
|
95
|
+
* The step's timeout is the Go engine's default step timeout, and the step's
|
|
96
|
+
* signal stops the call. An error the Go engine answers (an unknown workflow,
|
|
97
|
+
* a manifest it cannot parse) is thrown, which stops the run unless the step
|
|
98
|
+
* sets `continueOnError`.
|
|
99
|
+
*
|
|
100
|
+
* @param run - Runs a workflow on the Go engine
|
|
101
|
+
*/
|
|
102
|
+
export const createGoWorkflowTool = (run) => ({
|
|
103
|
+
name: GO_WORKFLOW_TOOL,
|
|
104
|
+
description: "Run a workflow on the Go engine and bring back its step results",
|
|
105
|
+
run: async (options, context) => {
|
|
106
|
+
const workflowId = stringOption(options, "workflow");
|
|
107
|
+
if (workflowId === undefined) {
|
|
108
|
+
return failed('option "workflow" (string) is required: the workflow id');
|
|
109
|
+
}
|
|
110
|
+
const root = stringOption(options, "root") ?? ".";
|
|
111
|
+
let manifest = stringOption(options, "manifest");
|
|
112
|
+
if (manifest === undefined) {
|
|
113
|
+
const file = stringOption(options, "manifestFile") ?? DEFAULT_MANIFEST_FILE;
|
|
114
|
+
const path = runtime.path.isAbsolute(file)
|
|
115
|
+
? file
|
|
116
|
+
: runtime.path.join(root, file);
|
|
117
|
+
try {
|
|
118
|
+
manifest = await runtime.fs.readTextFile(path);
|
|
119
|
+
}
|
|
120
|
+
catch (cause) {
|
|
121
|
+
return failed(`cannot read the manifest ${path}: ${cause instanceof Error ? cause.message : String(cause)}`);
|
|
122
|
+
}
|
|
123
|
+
}
|
|
124
|
+
const changedFiles = stringListOption(options, "_changedFiles");
|
|
125
|
+
const only = stringOption(options, "only");
|
|
126
|
+
const answer = await run({
|
|
127
|
+
manifest,
|
|
128
|
+
workflowId,
|
|
129
|
+
root,
|
|
130
|
+
fix: options["fix"] === true,
|
|
131
|
+
dryRun: options["dryRun"] === true,
|
|
132
|
+
args: stringListOption(options, "_args") ?? [],
|
|
133
|
+
...(changedFiles === undefined ? {} : { changedFiles }),
|
|
134
|
+
...(only === undefined ? {} : { only }),
|
|
135
|
+
timeoutMs: context.timeoutMs,
|
|
136
|
+
}, context.signal);
|
|
137
|
+
if (answer.error !== undefined && answer.error !== "") {
|
|
138
|
+
throw new Error(`go-workflow ${workflowId}: ${answer.error}`);
|
|
139
|
+
}
|
|
140
|
+
return toolResultOfGoWorkflow(answer);
|
|
141
|
+
},
|
|
142
|
+
});
|
package/dist/list.d.ts
ADDED
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
import type * as shellArgs from "@eserstack/shell/args";
|
|
2
|
+
import type { WorkflowTool } from "./types.ts";
|
|
3
|
+
/**
|
|
4
|
+
* Options injected by the CLI dispatcher.
|
|
5
|
+
*/
|
|
6
|
+
export type ListCliOptions = {
|
|
7
|
+
readonly tools?: readonly WorkflowTool[];
|
|
8
|
+
};
|
|
9
|
+
/** Parse the `eser workflows list` arguments: `--config`, `--help` (`-h`). */
|
|
10
|
+
export declare const parseCliArgs: (cliArgs?: readonly string[]) => {
|
|
11
|
+
readonly help: boolean;
|
|
12
|
+
readonly config: string | undefined;
|
|
13
|
+
};
|
|
14
|
+
/**
|
|
15
|
+
* CLI main function.
|
|
16
|
+
*
|
|
17
|
+
* @param cliArgs - CLI arguments
|
|
18
|
+
* @param cliOptions - Injected options (tools)
|
|
19
|
+
*/
|
|
20
|
+
export declare const main: (cliArgs?: readonly string[], cliOptions?: ListCliOptions) => Promise<shellArgs.CliResult<void>>;
|
package/dist/list.js
ADDED
|
@@ -0,0 +1,94 @@
|
|
|
1
|
+
// Copyright 2023-present Eser Ozvataf and other contributors. All rights reserved. Apache-2.0 license.
|
|
2
|
+
/**
|
|
3
|
+
* CLI command handler for `eser workflows list`.
|
|
4
|
+
*
|
|
5
|
+
* Lists available workflows and registered tools from the configuration.
|
|
6
|
+
*
|
|
7
|
+
* @module
|
|
8
|
+
*/
|
|
9
|
+
import * as shellFlags from "@eserstack/shell/args/flags";
|
|
10
|
+
import * as span from "@eserstack/streams/span";
|
|
11
|
+
import * as streams from "@eserstack/streams";
|
|
12
|
+
import * as results from "@eserstack/primitives/results";
|
|
13
|
+
import * as registry from "./registry.js";
|
|
14
|
+
import * as loader from "./loader.js";
|
|
15
|
+
import * as shellTool from "./shell-tool.js";
|
|
16
|
+
const writeHelp = (out) => {
|
|
17
|
+
out.writeln("eser workflows list — List available workflows and tools\n");
|
|
18
|
+
out.writeln("Options:");
|
|
19
|
+
out.writeln(" --config <path> Config directory (default: .)");
|
|
20
|
+
out.writeln(" -h, --help Show this help");
|
|
21
|
+
};
|
|
22
|
+
const writeListing = async (out, configArg, cliOptions) => {
|
|
23
|
+
const configDir = configArg ?? ".";
|
|
24
|
+
const config = await loader.loadFromFile(configDir);
|
|
25
|
+
// Registry (shell tool built-in, then injected tools)
|
|
26
|
+
const toolRegistry = registry.createRegistry();
|
|
27
|
+
toolRegistry.register(shellTool.shellTool);
|
|
28
|
+
if (cliOptions?.tools !== undefined) {
|
|
29
|
+
toolRegistry.registerAll(cliOptions.tools);
|
|
30
|
+
}
|
|
31
|
+
// Print workflows
|
|
32
|
+
if (config !== null && config.workflows.length > 0) {
|
|
33
|
+
out.writeln(span.bold("Workflows:"));
|
|
34
|
+
for (const wf of config.workflows) {
|
|
35
|
+
const events = wf.on.length > 0 ? wf.on.join(", ") : "(no events)";
|
|
36
|
+
const stepCount = wf.steps.length;
|
|
37
|
+
const stepWord = stepCount === 1 ? "step" : "steps";
|
|
38
|
+
out.writeln(span.text(` ${wf.id.padEnd(20)} `), span.dim(events.padEnd(25)), span.text(` ${stepCount} ${stepWord}`));
|
|
39
|
+
}
|
|
40
|
+
}
|
|
41
|
+
else {
|
|
42
|
+
out.writeln(span.dim("No workflows defined."));
|
|
43
|
+
}
|
|
44
|
+
out.writeln();
|
|
45
|
+
// Print registered tools
|
|
46
|
+
const tools = toolRegistry.getAll();
|
|
47
|
+
if (tools.length > 0) {
|
|
48
|
+
out.writeln(span.bold(`Registered tools (${tools.length}):`));
|
|
49
|
+
for (const tool of tools) {
|
|
50
|
+
out.writeln(span.text(` ${tool.name.padEnd(28)} `), span.dim(tool.description));
|
|
51
|
+
}
|
|
52
|
+
}
|
|
53
|
+
else {
|
|
54
|
+
out.writeln(span.dim("No tools registered."));
|
|
55
|
+
}
|
|
56
|
+
};
|
|
57
|
+
/** Parse the `eser workflows list` arguments: `--config`, `--help` (`-h`). */
|
|
58
|
+
export const parseCliArgs = (cliArgs) => {
|
|
59
|
+
const { values } = shellFlags.parseArgs(cliArgs ?? [], {
|
|
60
|
+
options: {
|
|
61
|
+
config: { type: "string" },
|
|
62
|
+
help: { type: "boolean", short: "h" },
|
|
63
|
+
},
|
|
64
|
+
});
|
|
65
|
+
const config = values["config"];
|
|
66
|
+
return {
|
|
67
|
+
help: values["help"] === true,
|
|
68
|
+
config: typeof config === "string" ? config : undefined,
|
|
69
|
+
};
|
|
70
|
+
};
|
|
71
|
+
/**
|
|
72
|
+
* CLI main function.
|
|
73
|
+
*
|
|
74
|
+
* @param cliArgs - CLI arguments
|
|
75
|
+
* @param cliOptions - Injected options (tools)
|
|
76
|
+
*/
|
|
77
|
+
export const main = async (cliArgs, cliOptions) => {
|
|
78
|
+
const parsed = parseCliArgs(cliArgs);
|
|
79
|
+
const out = streams.output({
|
|
80
|
+
renderer: streams.renderers.ansi(),
|
|
81
|
+
sink: streams.sinks.stdout(),
|
|
82
|
+
});
|
|
83
|
+
try {
|
|
84
|
+
if (parsed.help) {
|
|
85
|
+
writeHelp(out);
|
|
86
|
+
return results.ok(undefined);
|
|
87
|
+
}
|
|
88
|
+
await writeListing(out, parsed.config, cliOptions);
|
|
89
|
+
return results.ok(undefined);
|
|
90
|
+
}
|
|
91
|
+
finally {
|
|
92
|
+
await out.close();
|
|
93
|
+
}
|
|
94
|
+
};
|
package/dist/loader.d.ts
ADDED
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
import type { WorkflowsConfig } from "./types.ts";
|
|
2
|
+
/**
|
|
3
|
+
* Validate a parsed configuration object.
|
|
4
|
+
*
|
|
5
|
+
* Checks structural invariants: `workflows` must be an array where every
|
|
6
|
+
* entry has a non-empty `id`, at least one `on` event, and at least one
|
|
7
|
+
* valid step.
|
|
8
|
+
*
|
|
9
|
+
* @param config - The configuration to validate
|
|
10
|
+
* @throws {Error} Descriptive error naming the invalid workflow/step
|
|
11
|
+
*/
|
|
12
|
+
export declare const validateConfig: (config: WorkflowsConfig) => void;
|
|
13
|
+
/**
|
|
14
|
+
* Parse a YAML string into a WorkflowsConfig.
|
|
15
|
+
*
|
|
16
|
+
* @param content - YAML content
|
|
17
|
+
* @returns Parsed configuration
|
|
18
|
+
*/
|
|
19
|
+
export declare const parseConfig: (content: string) => WorkflowsConfig;
|
|
20
|
+
/**
|
|
21
|
+
* Load workflow configuration from a directory.
|
|
22
|
+
*
|
|
23
|
+
* Looks for `.eser/manifest.yml` or `.eser/manifest.yaml` in the specified directory.
|
|
24
|
+
*
|
|
25
|
+
* @param dir - Directory to load config from
|
|
26
|
+
* @returns Parsed configuration or null if no config file exists
|
|
27
|
+
*/
|
|
28
|
+
export declare const loadFromFile: (dir: string) => Promise<WorkflowsConfig | null>;
|
|
29
|
+
/**
|
|
30
|
+
* Get the config filenames that the loader searches for.
|
|
31
|
+
*/
|
|
32
|
+
export declare const getConfigFilenames: () => readonly string[];
|
package/dist/loader.js
ADDED
|
@@ -0,0 +1,109 @@
|
|
|
1
|
+
// Copyright 2023-present Eser Ozvataf and other contributors. All rights reserved. Apache-2.0 license.
|
|
2
|
+
/**
|
|
3
|
+
* Optional config file loader for `.eser/manifest.yml` files.
|
|
4
|
+
*
|
|
5
|
+
* The workflow engine does not require file-based configuration —
|
|
6
|
+
* workflows can be constructed programmatically via the builder.
|
|
7
|
+
* This loader provides convenience for file-based usage.
|
|
8
|
+
*
|
|
9
|
+
* @example
|
|
10
|
+
* ```typescript
|
|
11
|
+
* import * as workflowLoader from "@eserstack/workflows/loader";
|
|
12
|
+
*
|
|
13
|
+
* // Load from directory
|
|
14
|
+
* const config = await workflowLoader.loadFromFile(".");
|
|
15
|
+
*
|
|
16
|
+
* // Parse YAML directly
|
|
17
|
+
* const config2 = workflowLoader.parseConfig(
|
|
18
|
+
* "workflows:\n - id: ci\n on: [precommit]\n steps: [fix-eof]\n",
|
|
19
|
+
* );
|
|
20
|
+
* ```
|
|
21
|
+
*
|
|
22
|
+
* @module
|
|
23
|
+
*/
|
|
24
|
+
import * as yaml from "yaml";
|
|
25
|
+
import * as configManifest from "@eserstack/config/manifest";
|
|
26
|
+
/**
|
|
27
|
+
* Validate a parsed configuration object.
|
|
28
|
+
*
|
|
29
|
+
* Checks structural invariants: `workflows` must be an array where every
|
|
30
|
+
* entry has a non-empty `id`, at least one `on` event, and at least one
|
|
31
|
+
* valid step.
|
|
32
|
+
*
|
|
33
|
+
* @param config - The configuration to validate
|
|
34
|
+
* @throws {Error} Descriptive error naming the invalid workflow/step
|
|
35
|
+
*/
|
|
36
|
+
export const validateConfig = (config) => {
|
|
37
|
+
const workflows = config.workflows;
|
|
38
|
+
if (!Array.isArray(workflows)) {
|
|
39
|
+
throw new Error("Invalid config: 'workflows' must be an array");
|
|
40
|
+
}
|
|
41
|
+
for (let i = 0; i < workflows.length; i++) {
|
|
42
|
+
const wf = workflows[i];
|
|
43
|
+
const label = wf?.id !== undefined && wf.id !== ""
|
|
44
|
+
? `workflow '${wf.id}'`
|
|
45
|
+
: `workflow at index ${i}`;
|
|
46
|
+
if (typeof wf?.id !== "string" || wf.id === "") {
|
|
47
|
+
throw new Error(`Invalid config: ${label} must have a non-empty 'id' string`);
|
|
48
|
+
}
|
|
49
|
+
if (!Array.isArray(wf.on) || wf.on.length === 0) {
|
|
50
|
+
throw new Error(`Invalid config: ${label} must have a non-empty 'on' array`);
|
|
51
|
+
}
|
|
52
|
+
if (!Array.isArray(wf.steps) || wf.steps.length === 0) {
|
|
53
|
+
throw new Error(`Invalid config: ${label} must have a non-empty 'steps' array`);
|
|
54
|
+
}
|
|
55
|
+
for (let j = 0; j < wf.steps.length; j++) {
|
|
56
|
+
const step = wf.steps[j];
|
|
57
|
+
if (typeof step === "string") {
|
|
58
|
+
continue;
|
|
59
|
+
}
|
|
60
|
+
if (typeof step !== "object" || step === null || Array.isArray(step)) {
|
|
61
|
+
throw new Error(`Invalid config: ${label}, step ${j} must be a string or an object with exactly one key`);
|
|
62
|
+
}
|
|
63
|
+
const keys = Object.keys(step);
|
|
64
|
+
if (keys.length !== 1) {
|
|
65
|
+
throw new Error(`Invalid config: ${label}, step ${j} must be an object with exactly one key (got ${keys.length})`);
|
|
66
|
+
}
|
|
67
|
+
}
|
|
68
|
+
}
|
|
69
|
+
};
|
|
70
|
+
/**
|
|
71
|
+
* Parse a YAML string into a WorkflowsConfig.
|
|
72
|
+
*
|
|
73
|
+
* @param content - YAML content
|
|
74
|
+
* @returns Parsed configuration
|
|
75
|
+
*/
|
|
76
|
+
export const parseConfig = (content) => {
|
|
77
|
+
const raw = yaml.parse(content);
|
|
78
|
+
const config = {
|
|
79
|
+
stack: raw["stack"],
|
|
80
|
+
workflows: raw["workflows"] ?? [],
|
|
81
|
+
scripts: raw["scripts"],
|
|
82
|
+
};
|
|
83
|
+
validateConfig(config);
|
|
84
|
+
return config;
|
|
85
|
+
};
|
|
86
|
+
/**
|
|
87
|
+
* Load workflow configuration from a directory.
|
|
88
|
+
*
|
|
89
|
+
* Looks for `.eser/manifest.yml` or `.eser/manifest.yaml` in the specified directory.
|
|
90
|
+
*
|
|
91
|
+
* @param dir - Directory to load config from
|
|
92
|
+
* @returns Parsed configuration or null if no config file exists
|
|
93
|
+
*/
|
|
94
|
+
export const loadFromFile = async (dir) => {
|
|
95
|
+
const raw = await configManifest.loadManifest(dir);
|
|
96
|
+
if (raw === null)
|
|
97
|
+
return null;
|
|
98
|
+
const config = {
|
|
99
|
+
stack: raw["stack"],
|
|
100
|
+
workflows: raw["workflows"] ?? [],
|
|
101
|
+
scripts: raw["scripts"],
|
|
102
|
+
};
|
|
103
|
+
validateConfig(config);
|
|
104
|
+
return config;
|
|
105
|
+
};
|
|
106
|
+
/**
|
|
107
|
+
* Get the config filenames that the loader searches for.
|
|
108
|
+
*/
|
|
109
|
+
export const getConfigFilenames = () => configManifest.MANIFEST_FILENAMES;
|
package/dist/main.d.ts
ADDED
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The standalone CLI of @eserstack/workflows. The package's `.` export runs
|
|
3
|
+
* this CLI, and the library is published at `/mod`:
|
|
4
|
+
*
|
|
5
|
+
* ```typescript
|
|
6
|
+
* import * as workflows from "@eserstack/workflows/mod";
|
|
7
|
+
*
|
|
8
|
+
* const registry = workflows.createRegistry();
|
|
9
|
+
* ```
|
|
10
|
+
*
|
|
11
|
+
* Usage:
|
|
12
|
+
* npx eser workflows run -e precommit
|
|
13
|
+
* node ./main.ts list
|
|
14
|
+
*
|
|
15
|
+
* @module
|
|
16
|
+
*/
|
|
17
|
+
import * as results from "@eserstack/primitives/results";
|
|
18
|
+
/** Parse the process arguments and run the matching workflows command. */
|
|
19
|
+
export declare const main: () => Promise<results.Result<void, {
|
|
20
|
+
message?: string;
|
|
21
|
+
exitCode: number;
|
|
22
|
+
}>>;
|
package/dist/main.js
ADDED
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
// Copyright 2023-present Eser Ozvataf and other contributors. All rights reserved. Apache-2.0 license.
|
|
2
|
+
/**
|
|
3
|
+
* The standalone CLI of @eserstack/workflows. The package's `.` export runs
|
|
4
|
+
* this CLI, and the library is published at `/mod`:
|
|
5
|
+
*
|
|
6
|
+
* ```typescript
|
|
7
|
+
* import * as workflows from "@eserstack/workflows/mod";
|
|
8
|
+
*
|
|
9
|
+
* const registry = workflows.createRegistry();
|
|
10
|
+
* ```
|
|
11
|
+
*
|
|
12
|
+
* Usage:
|
|
13
|
+
* npx eser workflows run -e precommit
|
|
14
|
+
* node ./main.ts list
|
|
15
|
+
*
|
|
16
|
+
* @module
|
|
17
|
+
*/
|
|
18
|
+
import * as results from "@eserstack/primitives/results";
|
|
19
|
+
import { runtime } from "@eserstack/standards/cross-runtime";
|
|
20
|
+
import * as module from "./module.js";
|
|
21
|
+
import config from "./package.json" with { type: "json" };
|
|
22
|
+
const app = module.moduleDef.toCommand("workflows", config.version);
|
|
23
|
+
/** Parse the process arguments and run the matching workflows command. */
|
|
24
|
+
export const main = async () => {
|
|
25
|
+
return await app.parse();
|
|
26
|
+
};
|
|
27
|
+
if (import.meta.main) {
|
|
28
|
+
// CLI entry point: the await runs only when this file is the program, never
|
|
29
|
+
// on import.
|
|
30
|
+
// oxlint-disable-next-line node/no-top-level-await
|
|
31
|
+
const exitCode = results.match(await main(), {
|
|
32
|
+
ok: () => 0,
|
|
33
|
+
fail: (error) => {
|
|
34
|
+
if (error.message !== undefined) {
|
|
35
|
+
// oxlint-disable-next-line no-console
|
|
36
|
+
console.error(error.message);
|
|
37
|
+
}
|
|
38
|
+
return error.exitCode;
|
|
39
|
+
},
|
|
40
|
+
});
|
|
41
|
+
// A natural exit: the Go library no longer crashes the host on teardown
|
|
42
|
+
// under Node (TASK-175, measurement (c)), the shell tool's commands run in
|
|
43
|
+
// worker threads that end with the process, and nothing here reads stdin.
|
|
44
|
+
// main-exit.ffi.test.ts checks that the exit code survives the exit.
|
|
45
|
+
runtime.process.setExitCode(exitCode);
|
|
46
|
+
}
|
package/dist/mod.d.ts
ADDED
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Event-driven workflow engine for running tool pipelines.
|
|
3
|
+
*
|
|
4
|
+
* Core library — no I/O, no file loading. Compose workflows
|
|
5
|
+
* programmatically with the builder, register tools into a registry,
|
|
6
|
+
* and run them through the engine.
|
|
7
|
+
*
|
|
8
|
+
* For file-based config loading, use `@eserstack/workflows/loader`.
|
|
9
|
+
* For CLI execution, use `@eserstack/workflows/run`.
|
|
10
|
+
*
|
|
11
|
+
* @example
|
|
12
|
+
* ```typescript
|
|
13
|
+
* import * as workflows from "@eserstack/workflows/mod";
|
|
14
|
+
* import * as functions from "@eserstack/functions";
|
|
15
|
+
*
|
|
16
|
+
* // Create a registry and register tools
|
|
17
|
+
* const registry = workflows.createRegistry();
|
|
18
|
+
* registry.register({
|
|
19
|
+
* name: "my-tool",
|
|
20
|
+
* description: "Custom checker",
|
|
21
|
+
* run: () =>
|
|
22
|
+
* Promise.resolve({
|
|
23
|
+
* name: "my-tool",
|
|
24
|
+
* passed: true,
|
|
25
|
+
* issues: [],
|
|
26
|
+
* mutations: [],
|
|
27
|
+
* stats: {},
|
|
28
|
+
* }),
|
|
29
|
+
* });
|
|
30
|
+
*
|
|
31
|
+
* // Build a workflow
|
|
32
|
+
* const workflow = workflows.createWorkflow("ci")
|
|
33
|
+
* .on("precommit")
|
|
34
|
+
* .step("my-tool", { strict: true })
|
|
35
|
+
* .build();
|
|
36
|
+
*
|
|
37
|
+
* // Run it: runWorkflow() returns a Task, functions.task.runTask() executes it
|
|
38
|
+
* const result = await functions.task.runTask(
|
|
39
|
+
* workflows.runWorkflow(workflow, registry, { fix: true }),
|
|
40
|
+
* );
|
|
41
|
+
* ```
|
|
42
|
+
*
|
|
43
|
+
* @module
|
|
44
|
+
*/
|
|
45
|
+
export type { ResolvedStep, RunOptions, ScriptConfig, StepResult, WorkflowDefinition, WorkflowError, WorkflowFileMutation, WorkflowIssue, WorkflowResult, WorkflowsConfig, WorkflowStepConfig, WorkflowTool, WorkflowToolContext, WorkflowToolResult, } from "./types.ts";
|
|
46
|
+
export type { Registry } from "./registry.ts";
|
|
47
|
+
export { createRegistry } from "./registry.ts";
|
|
48
|
+
export type { WorkflowBuilder } from "./builder.ts";
|
|
49
|
+
export { createWorkflow, defineWorkflow } from "./builder.ts";
|
|
50
|
+
export { resolveIncludes, resolveStep, runByEvent, runWorkflow, runWorkflowWithConfig, } from "./engine.ts";
|
|
51
|
+
export { shellTool } from "./shell-tool.ts";
|
|
52
|
+
export { createHandlerTool, createNativeFunctionTool, createNativeFunctionTools, NATIVE_FUNCTION_TOOL, toolResultOfOutput, } from "./function-tools.ts";
|
|
53
|
+
export type { FunctionStepError, NativeCaller, NativeFunctionInfo, StepHandler, ToolOutput, } from "./function-tools.ts";
|
|
54
|
+
export { createGoWorkflowTool, GO_WORKFLOW_TOOL, toolResultOfGoWorkflow, } from "./go-workflow-tool.ts";
|
|
55
|
+
export type { GoWorkflowAnswer, GoWorkflowRequest, GoWorkflowRunner, GoWorkflowStep, } from "./go-workflow-tool.ts";
|
package/dist/mod.js
ADDED
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
// Copyright 2023-present Eser Ozvataf and other contributors. All rights reserved. Apache-2.0 license.
|
|
2
|
+
export { createRegistry } from "./registry.js";
|
|
3
|
+
export { createWorkflow, defineWorkflow } from "./builder.js";
|
|
4
|
+
// Engine
|
|
5
|
+
export { resolveIncludes, resolveStep, runByEvent, runWorkflow, runWorkflowWithConfig, } from "./engine.js";
|
|
6
|
+
// Built-in tools
|
|
7
|
+
export { shellTool } from "./shell-tool.js";
|
|
8
|
+
// Tools that run a function as a step: a TypeScript handler or a native one
|
|
9
|
+
export { createHandlerTool, createNativeFunctionTool, createNativeFunctionTools, NATIVE_FUNCTION_TOOL, toolResultOfOutput, } from "./function-tools.js";
|
|
10
|
+
// A tool that runs a workflow on the Go engine as one step
|
|
11
|
+
export { createGoWorkflowTool, GO_WORKFLOW_TOOL, toolResultOfGoWorkflow, } from "./go-workflow-tool.js";
|
package/dist/module.d.ts
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Workflows module definition for @eserstack/shell integration.
|
|
3
|
+
*
|
|
4
|
+
* Tool injection is the caller's responsibility — pass tools via
|
|
5
|
+
* createModuleDef() or let the CLI layer compose them.
|
|
6
|
+
*
|
|
7
|
+
* @module
|
|
8
|
+
*/
|
|
9
|
+
import * as module from "@eserstack/shell/module";
|
|
10
|
+
import type * as types from "./types.ts";
|
|
11
|
+
/** The command module type, `Module` from `@eserstack/shell/module`. */
|
|
12
|
+
export type Module = module.Module;
|
|
13
|
+
/**
|
|
14
|
+
* Build the `workflows` command module with its `run` and `list` subcommands.
|
|
15
|
+
*
|
|
16
|
+
* @param tools - Tools to register next to the built-in shell tool
|
|
17
|
+
* @returns The module, ready to mount with `toCommand()`
|
|
18
|
+
*/
|
|
19
|
+
export declare const createModuleDef: (tools?: readonly types.WorkflowTool[]) => Module;
|
|
20
|
+
/** Module with only the built-in shell tool, for standalone use. */
|
|
21
|
+
export declare const moduleDef: Module;
|