@db-lyon/flowkit 0.17.2 → 0.18.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/README.md +53 -1
- package/dist/.tsbuildinfo +1 -1
- package/dist/config/index.d.ts +4 -2
- package/dist/config/index.d.ts.map +1 -1
- package/dist/config/index.js +2 -1
- package/dist/config/index.js.map +1 -1
- package/dist/config/loader.d.ts +11 -0
- package/dist/config/loader.d.ts.map +1 -1
- package/dist/config/loader.js +4 -0
- package/dist/config/loader.js.map +1 -1
- package/dist/config/schema.d.ts +1486 -79
- package/dist/config/schema.d.ts.map +1 -1
- package/dist/config/schema.js +125 -8
- package/dist/config/schema.js.map +1 -1
- package/dist/config/strict.d.ts +40 -0
- package/dist/config/strict.d.ts.map +1 -0
- package/dist/config/strict.js +146 -0
- package/dist/config/strict.js.map +1 -0
- package/dist/flow/index.d.ts +2 -2
- package/dist/flow/index.d.ts.map +1 -1
- package/dist/flow/index.js +1 -1
- package/dist/flow/index.js.map +1 -1
- package/dist/flow/runner.d.ts +279 -6
- package/dist/flow/runner.d.ts.map +1 -1
- package/dist/flow/runner.js +845 -40
- package/dist/flow/runner.js.map +1 -1
- package/dist/index.d.ts +13 -5
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +6 -2
- package/dist/index.js.map +1 -1
- package/dist/task/base-task.d.ts +55 -1
- package/dist/task/base-task.d.ts.map +1 -1
- package/dist/task/base-task.js +39 -0
- package/dist/task/base-task.js.map +1 -1
- package/dist/task/composite.d.ts +66 -0
- package/dist/task/composite.d.ts.map +1 -0
- package/dist/task/composite.js +21 -0
- package/dist/task/composite.js.map +1 -0
- package/dist/task/index.d.ts +7 -1
- package/dist/task/index.d.ts.map +1 -1
- package/dist/task/index.js +3 -0
- package/dist/task/index.js.map +1 -1
- package/dist/task/options-schema.d.ts +51 -0
- package/dist/task/options-schema.d.ts.map +1 -0
- package/dist/task/options-schema.js +102 -0
- package/dist/task/options-schema.js.map +1 -0
- package/dist/task/registry.d.ts +39 -1
- package/dist/task/registry.d.ts.map +1 -1
- package/dist/task/registry.js +44 -2
- package/dist/task/registry.js.map +1 -1
- package/dist/task/warnings.d.ts +25 -0
- package/dist/task/warnings.d.ts.map +1 -0
- package/dist/task/warnings.js +30 -0
- package/dist/task/warnings.js.map +1 -0
- package/docs/api-reference.md +273 -0
- package/docs/configuration.md +262 -1
- package/docs/custom-tasks.md +155 -0
- package/docs/releases.md +47 -0
- package/package.json +1 -1
package/dist/flow/runner.d.ts
CHANGED
|
@@ -1,7 +1,9 @@
|
|
|
1
1
|
import type { Logger } from '../logger.js';
|
|
2
|
-
import type { TaskDefinition, FlowDefinition, AgentDefinition } from '../config/schema.js';
|
|
2
|
+
import type { TaskDefinition, FlowDefinition, AgentDefinition, StepCheck } from '../config/schema.js';
|
|
3
3
|
import type { TaskResult, TaskContext, TaskContextInput, ResolvedTaskContext } from '../task/base-task.js';
|
|
4
|
-
import type { TaskRegistry } from '../task/registry.js';
|
|
4
|
+
import type { TaskRegistry, TaskDescription } from '../task/registry.js';
|
|
5
|
+
import { type RunWarning } from '../task/warnings.js';
|
|
6
|
+
import type { ChildPlanEntry } from '../task/composite.js';
|
|
5
7
|
import { type AgentTaskOptions } from '../task/agent-task.js';
|
|
6
8
|
export type HookPhase = 'on_start' | 'on_success' | 'on_failure' | 'finally';
|
|
7
9
|
/**
|
|
@@ -10,12 +12,37 @@ export type HookPhase = 'on_start' | 'on_success' | 'on_failure' | 'finally';
|
|
|
10
12
|
* are interpreted as this map and threaded down into the nested flow.
|
|
11
13
|
*/
|
|
12
14
|
export type ParentOptions = Record<string, Record<string, unknown>>;
|
|
15
|
+
/** How runtime `params` reach steps. See `FlowRunOptions.optionsScope`. */
|
|
16
|
+
export type OptionsScope = 'flat' | 'step';
|
|
13
17
|
export interface FlowRunOptions {
|
|
14
18
|
flowName: string;
|
|
15
19
|
skip?: string[];
|
|
16
20
|
plan?: boolean;
|
|
17
|
-
/**
|
|
21
|
+
/**
|
|
22
|
+
* Runtime parameters, the highest-precedence option layer. Under the default
|
|
23
|
+
* `flat` scope every key is merged into every step's options. Under the
|
|
24
|
+
* `step` scope each key is a step selector and its value an options object
|
|
25
|
+
* for the matching steps only; see `optionsScope`.
|
|
26
|
+
*/
|
|
18
27
|
params?: Record<string, unknown>;
|
|
28
|
+
/**
|
|
29
|
+
* How `params` are addressed. `flat` (default) spreads every key into every
|
|
30
|
+
* step. `step` reads each key as a selector:
|
|
31
|
+
*
|
|
32
|
+
* - a task name (`deploy`, `asset.list`): every step running that task,
|
|
33
|
+
* anywhere in the run, including nested flows and hook steps;
|
|
34
|
+
* - a step path (`2`, or `2/1` for step 1 of the flow run by step 2): that
|
|
35
|
+
* one main step.
|
|
36
|
+
*
|
|
37
|
+
* and each value as the options for the matching steps. A path is more
|
|
38
|
+
* specific than a name and wins on a shared key. A selector matching no step,
|
|
39
|
+
* or a value that is not an object, fails the run before anything starts.
|
|
40
|
+
*
|
|
41
|
+
* Precedence: this option, then the flow's `options_scope`, then
|
|
42
|
+
* `FlowRunnerConfig.optionsScope`, then `flat`. It is fixed by the flow the
|
|
43
|
+
* run starts on; nested flows follow it.
|
|
44
|
+
*/
|
|
45
|
+
optionsScope?: OptionsScope;
|
|
19
46
|
/** If true, invoke rollback records from completed steps in reverse order on failure. */
|
|
20
47
|
rollback_on_failure?: boolean;
|
|
21
48
|
/**
|
|
@@ -24,6 +51,12 @@ export interface FlowRunOptions {
|
|
|
24
51
|
* flat, one-line-per-flow-step plan.
|
|
25
52
|
*/
|
|
26
53
|
expandNestedFlows?: boolean;
|
|
54
|
+
/**
|
|
55
|
+
* Plan mode only: expand composite task steps whose class declares a static
|
|
56
|
+
* `expand` into the children it reports, each with a hierarchical `path`.
|
|
57
|
+
* A composite whose `expand` returns `null` is marked `composite: 'opaque'`.
|
|
58
|
+
*/
|
|
59
|
+
expandComposites?: boolean;
|
|
27
60
|
/**
|
|
28
61
|
* Internal. Set by the runner on a nested run when an ancestor flow has
|
|
29
62
|
* rollback armed and will therefore invoke this child's records itself.
|
|
@@ -37,7 +70,7 @@ export interface FlowRunOptions {
|
|
|
37
70
|
*/
|
|
38
71
|
rollbackOwnedByAncestor?: boolean;
|
|
39
72
|
}
|
|
40
|
-
/** Context handed to a `conditionEvaluator` when resolving a string `when
|
|
73
|
+
/** Context handed to a `conditionEvaluator` when resolving a string `when:` or check. */
|
|
41
74
|
export interface ConditionContext {
|
|
42
75
|
steps: FlowStepResult[];
|
|
43
76
|
params?: Record<string, unknown>;
|
|
@@ -48,6 +81,71 @@ export interface ConditionContext {
|
|
|
48
81
|
stack?: string;
|
|
49
82
|
step?: string;
|
|
50
83
|
};
|
|
84
|
+
/** The host namespaces from `FlowRunnerConfig.references`, when configured. */
|
|
85
|
+
references?: Record<string, unknown>;
|
|
86
|
+
/** The step being gated. Absent for a flow-level check. */
|
|
87
|
+
step?: PlanStep;
|
|
88
|
+
/** Set when the expression is a declared check rather than a `when:`. */
|
|
89
|
+
check?: StepCheck;
|
|
90
|
+
/** The flow whose step (or which itself) is being gated. */
|
|
91
|
+
flowName?: string;
|
|
92
|
+
}
|
|
93
|
+
/**
|
|
94
|
+
* One evaluated check. A run reports the ones that fired; `preflight` reports
|
|
95
|
+
* every one it evaluated.
|
|
96
|
+
*/
|
|
97
|
+
export interface CheckOutcome {
|
|
98
|
+
scope: 'flow' | 'step';
|
|
99
|
+
flowName: string;
|
|
100
|
+
/** For a step check: the step it gates. */
|
|
101
|
+
stepNumber?: number;
|
|
102
|
+
name?: string;
|
|
103
|
+
/** For a step check: the step's path (`2/1`), as in an expanded plan. */
|
|
104
|
+
path?: string;
|
|
105
|
+
when: string | boolean;
|
|
106
|
+
action: 'error' | 'warn' | 'skip';
|
|
107
|
+
/** The declared message, else one naming the condition. */
|
|
108
|
+
message: string;
|
|
109
|
+
/** The condition was truthy, so the action applies. */
|
|
110
|
+
triggered: boolean;
|
|
111
|
+
/** The evaluator threw. `triggered` is false and the outcome is unknown. */
|
|
112
|
+
error?: Error;
|
|
113
|
+
}
|
|
114
|
+
/** Raised (as a step or flow error) when an `action: error` check fires. */
|
|
115
|
+
export declare class CheckFailedError extends Error {
|
|
116
|
+
readonly outcome: CheckOutcome;
|
|
117
|
+
constructor(outcome: CheckOutcome);
|
|
118
|
+
}
|
|
119
|
+
/** One row of `FlowRunner.preflight`. */
|
|
120
|
+
export interface PreflightStep {
|
|
121
|
+
stepNumber: number;
|
|
122
|
+
type: 'task' | 'flow';
|
|
123
|
+
name: string;
|
|
124
|
+
/** Hierarchical id, as in an expanded plan (`2/1`); hooks use their phase (`finally/1`). */
|
|
125
|
+
path: string;
|
|
126
|
+
depth: number;
|
|
127
|
+
phase?: HookPhase;
|
|
128
|
+
/**
|
|
129
|
+
* What the checks say would happen: `run`, `skip` (statically, or a `skip`
|
|
130
|
+
* check fired), `error` (an `error` check fired) or `unknown` (a check could
|
|
131
|
+
* not be evaluated before the run, e.g. it reads a step result).
|
|
132
|
+
*/
|
|
133
|
+
status: 'run' | 'skip' | 'error' | 'unknown';
|
|
134
|
+
skipReason?: 'static' | 'check';
|
|
135
|
+
/** Every check evaluated for this row; for a flow step, the child flow's own checks too. */
|
|
136
|
+
checks: CheckOutcome[]; /** The step's task or flow is deprecated (as in plan mode). */
|
|
137
|
+
deprecated?: boolean | string;
|
|
138
|
+
replaced_by?: string;
|
|
139
|
+
}
|
|
140
|
+
export interface PreflightResult {
|
|
141
|
+
flowName: string;
|
|
142
|
+
/** False when any `error` check fired (flow-level or on any step). */
|
|
143
|
+
ok: boolean;
|
|
144
|
+
/** The flow's own checks. */
|
|
145
|
+
checks: CheckOutcome[];
|
|
146
|
+
steps: PreflightStep[];
|
|
147
|
+
/** Fired `warn` checks and deprecations, as a run would report them. */
|
|
148
|
+
warnings?: RunWarning[];
|
|
51
149
|
}
|
|
52
150
|
/**
|
|
53
151
|
* Evaluates a string `when:` expression to a boolean. Supply one to use a real
|
|
@@ -64,8 +162,16 @@ export interface FlowStepResult {
|
|
|
64
162
|
duration: number;
|
|
65
163
|
/** Number of attempts including the first try (≥1 when executed). */
|
|
66
164
|
attempts?: number;
|
|
67
|
-
/**
|
|
68
|
-
|
|
165
|
+
/**
|
|
166
|
+
* Why the step was skipped: 'static' (skip list / task: None / flow: None),
|
|
167
|
+
* 'when' (condition false) or 'check' (a `skip` check fired).
|
|
168
|
+
*/
|
|
169
|
+
skipReason?: 'static' | 'when' | 'check';
|
|
170
|
+
/**
|
|
171
|
+
* Checks that fired for this step. For a flow step, those that fired inside
|
|
172
|
+
* the child flow too.
|
|
173
|
+
*/
|
|
174
|
+
checks?: CheckOutcome[];
|
|
69
175
|
/** True when the step failed but `ignore_failure` let the flow continue. */
|
|
70
176
|
ignoredFailure?: boolean;
|
|
71
177
|
/**
|
|
@@ -74,6 +180,8 @@ export interface FlowStepResult {
|
|
|
74
180
|
* child's run error message as the only thing that crosses the boundary.
|
|
75
181
|
*/
|
|
76
182
|
nestedSteps?: FlowStepResult[];
|
|
183
|
+
/** For a composite's child step (`TaskResult.children`): its path, e.g. `2/1`. */
|
|
184
|
+
path?: string;
|
|
77
185
|
}
|
|
78
186
|
export interface HookError {
|
|
79
187
|
phase: HookPhase;
|
|
@@ -99,6 +207,14 @@ export interface FlowRunResult {
|
|
|
99
207
|
hookErrors?: HookError[];
|
|
100
208
|
/** Populated when rollback_on_failure ran. */
|
|
101
209
|
rollback?: RollbackResult;
|
|
210
|
+
/**
|
|
211
|
+
* Non-fatal notices from the run or plan, in order and without repeats:
|
|
212
|
+
* deprecated tasks and flows that ran (or would run), and fired `warn` checks.
|
|
213
|
+
* Absent when there are none.
|
|
214
|
+
*/
|
|
215
|
+
warnings?: RunWarning[];
|
|
216
|
+
/** Every check that fired in the run, flow-level and per step, nested flows included. */
|
|
217
|
+
checks?: CheckOutcome[];
|
|
102
218
|
}
|
|
103
219
|
export interface PlanStep {
|
|
104
220
|
stepNumber: number;
|
|
@@ -113,12 +229,57 @@ export interface PlanStep {
|
|
|
113
229
|
when?: string | boolean;
|
|
114
230
|
/** Whether a failure of this step is tolerated. */
|
|
115
231
|
ignore_failure?: boolean;
|
|
232
|
+
/** Declared checks, unevaluated. `FlowRunner.preflight` evaluates them. */
|
|
233
|
+
checks?: StepCheck[];
|
|
116
234
|
/** For hook steps: the phase they belong to. Undefined for main steps. */
|
|
117
235
|
phase?: HookPhase;
|
|
118
236
|
/** Hierarchical id (e.g. "2/1") — only set when a plan expands nested flows. */
|
|
119
237
|
path?: string;
|
|
120
238
|
/** Nesting depth — 0 for top-level, increments per expanded nested flow. */
|
|
121
239
|
depth?: number;
|
|
240
|
+
/**
|
|
241
|
+
* Plan mode with `expandComposites`: `expanded` when the task's `expand`
|
|
242
|
+
* listed its children (the rows that follow, one level deeper), `opaque` when
|
|
243
|
+
* it declared `expand` but could not say.
|
|
244
|
+
*/
|
|
245
|
+
composite?: 'expanded' | 'opaque';
|
|
246
|
+
/** Plan mode only: the step's task or flow is deprecated. */
|
|
247
|
+
deprecated?: boolean | string;
|
|
248
|
+
/** Plan mode only: the deprecated target's declared replacement. */
|
|
249
|
+
replaced_by?: string;
|
|
250
|
+
}
|
|
251
|
+
/**
|
|
252
|
+
* A `${steps.<id>...}` reference in a flow that cannot be bound to exactly one
|
|
253
|
+
* earlier step. See `FlowRunner.checkStepReferences`.
|
|
254
|
+
*/
|
|
255
|
+
export interface StepReferenceIssue {
|
|
256
|
+
flowName: string;
|
|
257
|
+
/** The step whose configuration holds the reference. */
|
|
258
|
+
stepNumber: number;
|
|
259
|
+
/** For a hook step: its phase. */
|
|
260
|
+
phase?: HookPhase;
|
|
261
|
+
/** The reference as written, e.g. `${steps.deploy.url}`. */
|
|
262
|
+
reference: string;
|
|
263
|
+
/**
|
|
264
|
+
* `ambiguous`: a name used by more than one main step. `unknown`: no main
|
|
265
|
+
* step has that number or name. `forward`: the step has not run yet at that
|
|
266
|
+
* point (itself or a later one).
|
|
267
|
+
*/
|
|
268
|
+
kind: 'ambiguous' | 'unknown' | 'forward';
|
|
269
|
+
message: string;
|
|
270
|
+
}
|
|
271
|
+
/** A flow as `FlowRunner.describeFlow` reports it. */
|
|
272
|
+
export interface FlowDescription {
|
|
273
|
+
name: string;
|
|
274
|
+
description?: string;
|
|
275
|
+
deprecated?: boolean | string;
|
|
276
|
+
replaced_by?: string;
|
|
277
|
+
rollback_on_failure?: boolean;
|
|
278
|
+
options_scope?: OptionsScope;
|
|
279
|
+
/** The flow's own declared checks. */
|
|
280
|
+
checks?: StepCheck[];
|
|
281
|
+
/** Main steps, in run order, as the planner resolves them. */
|
|
282
|
+
steps: PlanStep[];
|
|
122
283
|
}
|
|
123
284
|
export interface FlowRunnerHooks {
|
|
124
285
|
beforeRun?(flowName: string, plan: PlanStep[]): Promise<void>;
|
|
@@ -167,6 +328,18 @@ export interface FlowRunnerConfig {
|
|
|
167
328
|
* run as flow steps continue to use the registry path.
|
|
168
329
|
*/
|
|
169
330
|
nestedAgentTaskFactory?: NestedAgentTaskFactory;
|
|
331
|
+
/**
|
|
332
|
+
* Default for how runtime `params` are addressed when neither the run nor
|
|
333
|
+
* the flow says. See `FlowRunOptions.optionsScope`. Default `flat`.
|
|
334
|
+
*/
|
|
335
|
+
optionsScope?: OptionsScope;
|
|
336
|
+
/**
|
|
337
|
+
* Refuse to run (or plan) a flow with a `${steps.<id>}` reference that is
|
|
338
|
+
* ambiguous, unknown or forward, instead of letting it resolve at run time
|
|
339
|
+
* to the most recent step of that name, or fail when reached. Checked for the
|
|
340
|
+
* flow a run starts on and every flow nested under it. Default false.
|
|
341
|
+
*/
|
|
342
|
+
strictStepReferences?: boolean;
|
|
170
343
|
}
|
|
171
344
|
export declare class FlowRunner {
|
|
172
345
|
private logger;
|
|
@@ -179,6 +352,8 @@ export declare class FlowRunner {
|
|
|
179
352
|
private references?;
|
|
180
353
|
private agents;
|
|
181
354
|
private nestedAgentTaskFactory;
|
|
355
|
+
private optionsScope;
|
|
356
|
+
private strictStepReferences;
|
|
182
357
|
private runDepth;
|
|
183
358
|
/**
|
|
184
359
|
* Reference scope outside any step: the host namespaces, no step results.
|
|
@@ -195,6 +370,17 @@ export declare class FlowRunner {
|
|
|
195
370
|
* configured defaults exactly as it would as a top-level step.
|
|
196
371
|
*/
|
|
197
372
|
private contextFor;
|
|
373
|
+
/**
|
|
374
|
+
* Run one composite child through the same machinery as a flow step: hooks,
|
|
375
|
+
* retries, option schema, deprecation and rollback capture. The child is
|
|
376
|
+
* recorded on the parent's sink and becomes `TaskResult.children`.
|
|
377
|
+
*
|
|
378
|
+
* A child's options are the composite's runtime data: they layer over the
|
|
379
|
+
* child task's configured defaults (interpolated in the parent's reference
|
|
380
|
+
* scope) verbatim. Runtime `params` and enclosing-flow overrides do not
|
|
381
|
+
* reach children, and a child flow gets `options` as its `params`.
|
|
382
|
+
*/
|
|
383
|
+
private runChildStep;
|
|
198
384
|
/** Map an agent definition onto AgentTask options (everything but the prompt). */
|
|
199
385
|
private compileAgent;
|
|
200
386
|
/** Run a configured flow as an agent tool, returning a compact step summary. */
|
|
@@ -213,6 +399,39 @@ export declare class FlowRunner {
|
|
|
213
399
|
* on its own or as a step. `options` merge over the task's configured defaults.
|
|
214
400
|
*/
|
|
215
401
|
runTask(taskName: string, options?: Record<string, unknown>): Promise<TaskResult>;
|
|
402
|
+
/**
|
|
403
|
+
* Describe a configured (or registered) task: its class, merged default
|
|
404
|
+
* options, option schema, outputs and deprecation. See `TaskRegistry.describe`.
|
|
405
|
+
*/
|
|
406
|
+
describeTask(taskName: string): Promise<TaskDescription>;
|
|
407
|
+
/** Describe a configured flow: its declared metadata and its resolved main steps. */
|
|
408
|
+
describeFlow(flowName: string): FlowDescription;
|
|
409
|
+
/**
|
|
410
|
+
* The children a composite task would run for `options`, from its class's
|
|
411
|
+
* static `expand`, without running anything. `options` layer over the task's
|
|
412
|
+
* configured defaults as `runTask` would layer them. Returns `null` when the
|
|
413
|
+
* class declares no `expand` or its `expand` cannot say.
|
|
414
|
+
*/
|
|
415
|
+
expandTask(taskName: string, options?: Record<string, unknown>): Promise<ChildPlanEntry[] | null>;
|
|
416
|
+
private expandContext;
|
|
417
|
+
/** A task class's static `expand`, or undefined (including when the class cannot load). */
|
|
418
|
+
private expandFunctionOf;
|
|
419
|
+
/**
|
|
420
|
+
* Plan mode: follow each composite task row with the children its `expand`
|
|
421
|
+
* reports, one level deeper, recursively. Options are resolved as far as
|
|
422
|
+
* they can be before a run: definition defaults, the step's options and its
|
|
423
|
+
* runtime params, with host references interpolated and step references left
|
|
424
|
+
* as written.
|
|
425
|
+
*/
|
|
426
|
+
private expandCompositeRows;
|
|
427
|
+
/**
|
|
428
|
+
* The deprecation notice for a task or flow, or undefined. A task's class is
|
|
429
|
+
* resolved for its static metadata; one that cannot load reports nothing
|
|
430
|
+
* here and fails where it would have anyway, at run time.
|
|
431
|
+
*/
|
|
432
|
+
private deprecationOf;
|
|
433
|
+
/** Plan mode: mark deprecated rows and collect their warnings. */
|
|
434
|
+
private annotatePlan;
|
|
216
435
|
/**
|
|
217
436
|
* Instantiate and run a task with fully-resolved options (the shared leaf).
|
|
218
437
|
*
|
|
@@ -222,9 +441,38 @@ export declare class FlowRunner {
|
|
|
222
441
|
* as a step, directly, as a tool, or during rollback all report failure
|
|
223
442
|
* identically — and a step's `retries` cover construction, not just execution.
|
|
224
443
|
* Task-to-task calls derive their equivalent context in `BaseTask.resolve`.
|
|
444
|
+
*
|
|
445
|
+
* `taskName` is the configured name the call came through. When given, the
|
|
446
|
+
* task's declared options (class `optionsSchema` refined by the definition's
|
|
447
|
+
* `options_schema`) supply defaults and are checked here, so every runner
|
|
448
|
+
* path validates the same way and a bad option fails before the task exists.
|
|
225
449
|
*/
|
|
226
450
|
private executeTask;
|
|
227
451
|
private runWith;
|
|
452
|
+
/** Path of a main step inside a frame: `3` at the root, `2/3` inside step 2's flow. */
|
|
453
|
+
private stepPath;
|
|
454
|
+
/**
|
|
455
|
+
* The runtime option layer one step receives. Flat: all of `params`.
|
|
456
|
+
* Step-scoped: the options under the step's task name, then under its path.
|
|
457
|
+
*/
|
|
458
|
+
private runtimeOptionsFor;
|
|
459
|
+
/**
|
|
460
|
+
* Every selector a step-scoped `params` key may use for a run of `flowName`:
|
|
461
|
+
* task names anywhere in the tree (main and hook steps, nested flows
|
|
462
|
+
* included) and the paths of main task steps.
|
|
463
|
+
*/
|
|
464
|
+
private collectSelectors;
|
|
465
|
+
/**
|
|
466
|
+
* Find `${steps.<id>...}` references that cannot be bound to exactly one
|
|
467
|
+
* earlier main step: ambiguous names, unknown ids and forward references.
|
|
468
|
+
* Scans the flow's main and hook steps (`options` of task steps, `when`, and
|
|
469
|
+
* check `when`s) and, recursively, every flow they nest. It does not scan
|
|
470
|
+
* task definition defaults, which are resolved in whatever step runs them.
|
|
471
|
+
*/
|
|
472
|
+
checkStepReferences(flowName: string): StepReferenceIssue[];
|
|
473
|
+
private collectReferenceIssues;
|
|
474
|
+
/** Reject step-scoped `params` that address nothing or are not option objects. */
|
|
475
|
+
private checkScopedParams;
|
|
228
476
|
resolveExecutionPlan(flow: FlowDefinition, skipSet: Set<string>): PlanStep[];
|
|
229
477
|
private planStepFromDef;
|
|
230
478
|
private planHookSteps;
|
|
@@ -244,9 +492,34 @@ export declare class FlowRunner {
|
|
|
244
492
|
* would otherwise be told `'task'` and run when it meant to skip.
|
|
245
493
|
*/
|
|
246
494
|
private evaluateWhen;
|
|
495
|
+
/**
|
|
496
|
+
* Evaluate declared checks in order. Never throws: an evaluator failure is
|
|
497
|
+
* reported on the outcome.
|
|
498
|
+
*/
|
|
499
|
+
private evaluateChecks;
|
|
500
|
+
/**
|
|
501
|
+
* Fold evaluated checks into a verdict. Fired checks go to `fired`, fired
|
|
502
|
+
* `warn` checks to `warnings`. The first fired `error` check wins; an
|
|
503
|
+
* evaluator failure is returned separately so the caller can treat it like a
|
|
504
|
+
* `when:` that throws.
|
|
505
|
+
*/
|
|
506
|
+
private applyChecks;
|
|
507
|
+
/**
|
|
508
|
+
* Evaluate every declared check of a flow and its steps without running
|
|
509
|
+
* anything. Checks see no step results (nothing has run) and the runtime
|
|
510
|
+
* `params`; one that needs a step result reports an evaluation error and the
|
|
511
|
+
* row's status is `unknown`. Nested flows are expanded, with paths as in an
|
|
512
|
+
* expanded plan; hook steps are listed under their phase.
|
|
513
|
+
*/
|
|
514
|
+
preflight(flowName: string, params?: Record<string, unknown>, options?: {
|
|
515
|
+
skip?: string[];
|
|
516
|
+
}): Promise<PreflightResult>;
|
|
517
|
+
private preflightFlow;
|
|
247
518
|
private executeFlow;
|
|
248
519
|
private runHookStep;
|
|
249
520
|
private executeTaskStepWithRetry;
|
|
521
|
+
/** A step's retry policy (`retries`, `retryDelay`, `retryOn`) around one attempt function. */
|
|
522
|
+
private withRetry;
|
|
250
523
|
private executeTaskStep;
|
|
251
524
|
private performRollback;
|
|
252
525
|
}
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"runner.d.ts","sourceRoot":"","sources":["../../src/flow/runner.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAE3C,OAAO,KAAK,
|
|
1
|
+
{"version":3,"file":"runner.d.ts","sourceRoot":"","sources":["../../src/flow/runner.ts"],"names":[],"mappings":"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"}
|