@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.
@@ -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
+ };
@@ -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";
@@ -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;