@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.
@@ -0,0 +1,143 @@
1
+ /**
2
+ * Core types for the workflow engine.
3
+ *
4
+ * @module
5
+ */
6
+ /** A step in a workflow — either a tool name string or a name→options record. */
7
+ export type WorkflowStepConfig = string | Record<string, Record<string, unknown>>;
8
+ /**
9
+ * A parsed step with resolved name, tool options, and engine directives.
10
+ *
11
+ * Engine directives (`continueOnError`, `timeout`, `bypass`, `inputSchema`) are
12
+ * extracted from the step config and consumed by the engine, not passed to the tool.
13
+ */
14
+ export type ResolvedStep = {
15
+ readonly name: string;
16
+ readonly options: Record<string, unknown>;
17
+ /** If true, tool errors are caught and reported as a failed step instead of crashing the workflow. Default: false. */
18
+ readonly continueOnError: boolean;
19
+ /** Per-step timeout in milliseconds. Overrides RunOptions.defaultTimeout. */
20
+ readonly timeout?: number;
21
+ /** If true, skip tool execution; step output = previous step's stats. Default: false. */
22
+ readonly bypass?: boolean;
23
+ /** JSON Schema (draft-2020-12) to validate merged options before tool.run(). Nil = no validation. */
24
+ readonly inputSchema?: Record<string, unknown>;
25
+ };
26
+ /** A workflow definition with an id, triggering events, and ordered steps. */
27
+ export type WorkflowDefinition = {
28
+ readonly id: string;
29
+ readonly on: readonly string[];
30
+ readonly steps: readonly WorkflowStepConfig[];
31
+ /** Workflow ids to include (their steps are prepended before this workflow's steps). */
32
+ readonly includes?: readonly string[];
33
+ };
34
+ /** A script definition — either a command string or a config object. */
35
+ export type ScriptConfig = string | {
36
+ readonly command: string;
37
+ readonly description?: string;
38
+ readonly workingDirectory?: string;
39
+ readonly depends?: readonly string[];
40
+ };
41
+ /** Top-level configuration (can be loaded from .eser/manifest.yml or built programmatically). */
42
+ export type WorkflowsConfig = {
43
+ readonly stack?: readonly string[];
44
+ readonly workflows: readonly WorkflowDefinition[];
45
+ readonly scripts?: Readonly<Record<string, ScriptConfig>>;
46
+ };
47
+ /** A single issue found by a workflow tool. */
48
+ export type WorkflowIssue = {
49
+ readonly path?: string;
50
+ readonly line?: number;
51
+ readonly message: string;
52
+ readonly fixed?: boolean;
53
+ };
54
+ /** A file mutation produced by a fixer tool. */
55
+ export type WorkflowFileMutation = {
56
+ readonly path: string;
57
+ readonly oldContent: string;
58
+ readonly newContent: string;
59
+ };
60
+ /**
61
+ * What the engine passes to a tool, next to its options, for one step.
62
+ */
63
+ export type WorkflowToolContext = {
64
+ /**
65
+ * How long the step may run, in milliseconds: the step's `timeout`, or
66
+ * `RunOptions.defaultTimeout`. A tool that starts a subprocess or a request
67
+ * gives it this limit, so the work stops when the step times out.
68
+ */
69
+ readonly timeoutMs: number;
70
+ /**
71
+ * Aborted when the step ends: when it runs past `timeoutMs`, or when the
72
+ * tool has returned. Work the tool started and still runs should stop then.
73
+ */
74
+ readonly signal: AbortSignal;
75
+ };
76
+ /** A tool that can be registered and run within a workflow. */
77
+ export type WorkflowTool = {
78
+ readonly name: string;
79
+ readonly description: string;
80
+ /**
81
+ * Run the tool for one step.
82
+ *
83
+ * @param options - The step's options, plus `root`, `fix`, `dryRun`, `_args`
84
+ * and, in incremental mode, `_changedFiles` from the run
85
+ * @param context - The step's time limit and the signal that ends it
86
+ */
87
+ readonly run: (options: Record<string, unknown>, context: WorkflowToolContext) => Promise<WorkflowToolResult>;
88
+ };
89
+ /** Result from running a single workflow tool. */
90
+ export type WorkflowToolResult = {
91
+ readonly name: string;
92
+ readonly passed: boolean;
93
+ readonly issues: readonly WorkflowIssue[];
94
+ readonly mutations: readonly WorkflowFileMutation[];
95
+ readonly stats: Record<string, number>;
96
+ };
97
+ /** Result from a single step execution (includes timing). */
98
+ export type StepResult = WorkflowToolResult & {
99
+ readonly durationMs: number;
100
+ };
101
+ /** Aggregate result from running a full workflow. */
102
+ export type WorkflowResult = {
103
+ readonly workflowId: string;
104
+ readonly passed: boolean;
105
+ readonly steps: readonly StepResult[];
106
+ readonly totalDurationMs: number;
107
+ };
108
+ /** Error type for workflow engine failures. */
109
+ export type WorkflowError = {
110
+ readonly _tag: "WorkflowError";
111
+ readonly message: string;
112
+ };
113
+ /** Options for running a workflow. */
114
+ export type RunOptions = {
115
+ readonly root?: string;
116
+ readonly fix?: boolean;
117
+ /**
118
+ * Preview fixes without writing files. Tools receive it as the `dryRun`
119
+ * option; the shell tool runs `command` instead of `fixCommand`.
120
+ */
121
+ readonly dryRun?: boolean;
122
+ /**
123
+ * Run only the steps this names: a step matches by its tool name or by its
124
+ * `name` option, the name of a shell step. When no declared step matches,
125
+ * `runByEvent` and `runWorkflowWithConfig` fail and name the filter.
126
+ */
127
+ readonly only?: string;
128
+ /**
129
+ * Timeout for steps that set none, in milliseconds: above 0 and at most
130
+ * 2147483647. Default: 60000 (60s).
131
+ */
132
+ readonly defaultTimeout?: number;
133
+ /** Positional args passed through to tools (e.g., commit message file path). */
134
+ readonly args?: readonly string[];
135
+ /** Changed file paths for incremental mode (only run tools on these files). */
136
+ readonly changedFiles?: readonly string[];
137
+ /** Called when a step starts. */
138
+ readonly onStepStart?: (name: string) => void;
139
+ /** Called when a step finishes. */
140
+ readonly onStepEnd?: (result: StepResult) => void;
141
+ /** Called when a step produces mutations — allows the caller to write them to disk between steps. */
142
+ readonly onMutations?: (mutations: readonly WorkflowFileMutation[]) => Promise<void>;
143
+ };
package/dist/types.js ADDED
@@ -0,0 +1,2 @@
1
+ // Copyright 2023-present Eser Ozvataf and other contributors. All rights reserved. Apache-2.0 license.
2
+ export {};
package/package.json CHANGED
@@ -1,6 +1,60 @@
1
1
  {
2
2
  "name": "@eserstack/workflows",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
3
+ "version": "5.0.0",
4
+ "type": "module",
5
+ "repository": {
6
+ "type": "git",
7
+ "url": "https://github.com/eser/stack",
8
+ "directory": "pkg/@eserstack/workflows"
9
+ },
10
+ "files": [
11
+ "dist/**/*.js",
12
+ "dist/**/*.d.ts",
13
+ "dist/**/*.json"
14
+ ],
15
+ "exports": {
16
+ ".": {
17
+ "types": "./dist/main.d.ts",
18
+ "import": "./dist/main.js"
19
+ },
20
+ "./mod": {
21
+ "types": "./dist/mod.d.ts",
22
+ "import": "./dist/mod.js"
23
+ },
24
+ "./module": {
25
+ "types": "./dist/module.d.ts",
26
+ "import": "./dist/module.js"
27
+ },
28
+ "./loader": {
29
+ "types": "./dist/loader.d.ts",
30
+ "import": "./dist/loader.js"
31
+ },
32
+ "./run": {
33
+ "types": "./dist/run.d.ts",
34
+ "import": "./dist/run.js"
35
+ },
36
+ "./list": {
37
+ "types": "./dist/list.d.ts",
38
+ "import": "./dist/list.js"
39
+ },
40
+ "./native-functions": {
41
+ "types": "./dist/native-functions.d.ts",
42
+ "import": "./dist/native-functions.js"
43
+ }
44
+ },
45
+ "dependencies": {
46
+ "yaml": "^2.9.1",
47
+ "@eserstack/config": "5.0.0",
48
+ "@eserstack/primitives": "5.0.0",
49
+ "@eserstack/functions": "5.0.0",
50
+ "@eserstack/shell": "5.0.0",
51
+ "@eserstack/standards": "5.0.0",
52
+ "@eserstack/streams": "5.0.0"
53
+ },
54
+ "devDependencies": {
55
+ "@eserstack/test-kit": "5.0.0"
56
+ },
57
+ "scripts": {
58
+ "build": "node ../../../etc/scripts/build-library.ts"
59
+ }
6
60
  }