@bastani/atomic 0.5.34 → 0.6.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/README.md +329 -50
- package/dist/commands/cli/session.d.ts +67 -0
- package/dist/commands/cli/session.d.ts.map +1 -0
- package/dist/commands/cli/workflow-status.d.ts +63 -0
- package/dist/commands/cli/workflow-status.d.ts.map +1 -0
- package/dist/sdk/commander.d.ts +74 -0
- package/dist/sdk/commander.d.ts.map +1 -0
- package/dist/sdk/components/workflow-picker-panel.d.ts +14 -17
- package/dist/sdk/components/workflow-picker-panel.d.ts.map +1 -1
- package/dist/sdk/define-workflow.d.ts +18 -9
- package/dist/sdk/define-workflow.d.ts.map +1 -1
- package/dist/sdk/index.d.ts +4 -3
- package/dist/sdk/index.d.ts.map +1 -1
- package/dist/sdk/management-commands.d.ts +42 -0
- package/dist/sdk/management-commands.d.ts.map +1 -0
- package/dist/sdk/registry.d.ts +27 -0
- package/dist/sdk/registry.d.ts.map +1 -0
- package/dist/sdk/runtime/attached-footer.d.ts +1 -1
- package/dist/sdk/runtime/executor-env.d.ts +20 -0
- package/dist/sdk/runtime/executor-env.d.ts.map +1 -0
- package/dist/sdk/runtime/executor.d.ts +61 -10
- package/dist/sdk/runtime/executor.d.ts.map +1 -1
- package/dist/sdk/types.d.ts +147 -4
- package/dist/sdk/types.d.ts.map +1 -1
- package/dist/sdk/worker-shared.d.ts +42 -0
- package/dist/sdk/worker-shared.d.ts.map +1 -0
- package/dist/sdk/workflow-cli.d.ts +103 -0
- package/dist/sdk/workflow-cli.d.ts.map +1 -0
- package/dist/sdk/workflows/builtin-registry.d.ts +113 -0
- package/dist/sdk/workflows/builtin-registry.d.ts.map +1 -0
- package/dist/sdk/workflows/index.d.ts +5 -5
- package/dist/sdk/workflows/index.d.ts.map +1 -1
- package/package.json +12 -8
- package/src/cli.ts +85 -144
- package/src/commands/cli/chat/index.ts +10 -0
- package/src/commands/cli/workflow-command.test.ts +279 -938
- package/src/commands/cli/workflow-inputs.test.ts +41 -11
- package/src/commands/cli/workflow-inputs.ts +47 -12
- package/src/commands/cli/workflow-list.test.ts +234 -0
- package/src/commands/cli/workflow-list.ts +0 -0
- package/src/commands/cli/workflow.ts +11 -798
- package/src/scripts/constants.ts +2 -1
- package/src/sdk/commander.ts +161 -0
- package/src/sdk/components/workflow-picker-panel.tsx +78 -258
- package/src/sdk/define-workflow.test.ts +104 -11
- package/src/sdk/define-workflow.ts +47 -11
- package/src/sdk/errors.test.ts +16 -0
- package/src/sdk/index.ts +8 -8
- package/src/sdk/management-commands.ts +151 -0
- package/src/sdk/registry.ts +132 -0
- package/src/sdk/runtime/attached-footer.ts +1 -1
- package/src/sdk/runtime/executor-env.ts +45 -0
- package/src/sdk/runtime/executor.test.ts +37 -0
- package/src/sdk/runtime/executor.ts +147 -68
- package/src/sdk/types.ts +169 -4
- package/src/sdk/worker-shared.test.ts +163 -0
- package/src/sdk/worker-shared.ts +155 -0
- package/src/sdk/workflow-cli.ts +409 -0
- package/src/sdk/workflows/builtin/deep-research-codebase/claude/index.ts +1 -1
- package/src/sdk/workflows/builtin/deep-research-codebase/copilot/index.ts +1 -1
- package/src/sdk/workflows/builtin/deep-research-codebase/opencode/index.ts +1 -1
- package/src/sdk/workflows/builtin/open-claude-design/claude/index.ts +1 -1
- package/src/sdk/workflows/builtin/open-claude-design/copilot/index.ts +1 -1
- package/src/sdk/workflows/builtin/open-claude-design/opencode/index.ts +1 -1
- package/src/sdk/workflows/builtin/ralph/claude/index.ts +1 -1
- package/src/sdk/workflows/builtin/ralph/copilot/index.ts +1 -1
- package/src/sdk/workflows/builtin/ralph/opencode/index.ts +1 -1
- package/src/sdk/workflows/builtin-registry.ts +23 -0
- package/src/sdk/workflows/index.ts +10 -20
- package/src/services/system/auth.test.ts +63 -1
- package/.agents/skills/workflow-creator/SKILL.md +0 -334
- package/.agents/skills/workflow-creator/references/agent-sessions.md +0 -888
- package/.agents/skills/workflow-creator/references/computation-and-validation.md +0 -201
- package/.agents/skills/workflow-creator/references/control-flow.md +0 -470
- package/.agents/skills/workflow-creator/references/discovery-and-verification.md +0 -232
- package/.agents/skills/workflow-creator/references/failure-modes.md +0 -903
- package/.agents/skills/workflow-creator/references/getting-started.md +0 -275
- package/.agents/skills/workflow-creator/references/running-workflows.md +0 -235
- package/.agents/skills/workflow-creator/references/session-config.md +0 -384
- package/.agents/skills/workflow-creator/references/state-and-data-flow.md +0 -357
- package/.agents/skills/workflow-creator/references/user-input.md +0 -234
- package/.agents/skills/workflow-creator/references/workflow-inputs.md +0 -272
- package/dist/sdk/runtime/discovery.d.ts +0 -132
- package/dist/sdk/runtime/discovery.d.ts.map +0 -1
- package/dist/sdk/runtime/executor-entry.d.ts +0 -11
- package/dist/sdk/runtime/executor-entry.d.ts.map +0 -1
- package/dist/sdk/runtime/loader.d.ts +0 -70
- package/dist/sdk/runtime/loader.d.ts.map +0 -1
- package/dist/version.d.ts +0 -2
- package/dist/version.d.ts.map +0 -1
- package/src/commands/cli/workflow.test.ts +0 -317
- package/src/sdk/runtime/discovery.ts +0 -368
- package/src/sdk/runtime/executor-entry.ts +0 -18
- package/src/sdk/runtime/loader.ts +0 -267
|
@@ -1,272 +0,0 @@
|
|
|
1
|
-
# Workflow Inputs
|
|
2
|
-
|
|
3
|
-
Workflows collect structured data from the user at invocation time through
|
|
4
|
-
a single uniform API: `ctx.inputs` (and `s.inputs` inside stage
|
|
5
|
-
callbacks). This reference covers how the inputs pipe works, how to
|
|
6
|
-
declare input schemas, and how values reach the workflow from the CLI
|
|
7
|
-
and the interactive picker.
|
|
8
|
-
|
|
9
|
-
## The inputs pipe
|
|
10
|
-
|
|
11
|
-
Every workflow run receives a typed inputs object. When the workflow
|
|
12
|
-
declares an `inputs` schema, only the declared field names are valid
|
|
13
|
-
keys — accessing undeclared fields is a compile-time error. The
|
|
14
|
-
runtime populates it from whichever invocation surface the user chose:
|
|
15
|
-
|
|
16
|
-
| Surface | How values are supplied | How they land in `ctx.inputs` |
|
|
17
|
-
|---|---|---|
|
|
18
|
-
| **Named run, positional** — `atomic workflow -n hello -a claude "fix the bug"` | A single positional prompt string (the workflow must declare a `prompt` input) | `{ prompt: "fix the bug" }` |
|
|
19
|
-
| **Named run, structured** — `atomic workflow -n gen-spec -a claude --research_doc=notes.md --focus=standard` | One `--<field>=<value>` flag per declared input | `{ research_doc: "notes.md", focus: "standard" }` |
|
|
20
|
-
| **Interactive picker** — `atomic workflow -a claude` | The user fills in a form rendered from the declared schema | Whatever the user typed, keyed by field name |
|
|
21
|
-
|
|
22
|
-
Workflow code is the same either way — it always reads
|
|
23
|
-
`ctx.inputs.<name>`. The invocation surface is a CLI concern, not a
|
|
24
|
-
workflow concern.
|
|
25
|
-
|
|
26
|
-
## Reading inputs
|
|
27
|
-
|
|
28
|
-
Workflows that accept a user prompt should declare it explicitly as an
|
|
29
|
-
input. Destructure it once at the top of `.run()` so every stage can
|
|
30
|
-
close over a bare string:
|
|
31
|
-
|
|
32
|
-
```ts
|
|
33
|
-
defineWorkflow({
|
|
34
|
-
name: "answer",
|
|
35
|
-
description: "Single-turn answer",
|
|
36
|
-
inputs: [
|
|
37
|
-
{ name: "prompt", type: "text", required: true, description: "question to answer" },
|
|
38
|
-
],
|
|
39
|
-
})
|
|
40
|
-
.for<"claude">()
|
|
41
|
-
.run(async (ctx) => {
|
|
42
|
-
const prompt = ctx.inputs.prompt ?? "";
|
|
43
|
-
|
|
44
|
-
await ctx.stage({ name: "answer" }, {}, {}, async (s) => {
|
|
45
|
-
await s.session.query(prompt);
|
|
46
|
-
s.save(s.sessionId);
|
|
47
|
-
});
|
|
48
|
-
})
|
|
49
|
-
.compile();
|
|
50
|
-
```
|
|
51
|
-
|
|
52
|
-
For structured workflows, read each declared field by name. Pull them
|
|
53
|
-
out of `ctx.inputs` once for readability and so downstream stages can
|
|
54
|
-
close over locals:
|
|
55
|
-
|
|
56
|
-
```ts
|
|
57
|
-
defineWorkflow({
|
|
58
|
-
name: "gen-spec",
|
|
59
|
-
description: "Convert a research doc into a detailed execution spec",
|
|
60
|
-
inputs: [
|
|
61
|
-
{ name: "research_doc", type: "string", required: true },
|
|
62
|
-
{
|
|
63
|
-
name: "focus",
|
|
64
|
-
type: "enum",
|
|
65
|
-
required: true,
|
|
66
|
-
values: ["minimal", "standard", "exhaustive"],
|
|
67
|
-
default: "standard",
|
|
68
|
-
},
|
|
69
|
-
{ name: "notes", type: "text" },
|
|
70
|
-
],
|
|
71
|
-
})
|
|
72
|
-
.for<"claude">()
|
|
73
|
-
.run(async (ctx) => {
|
|
74
|
-
const { research_doc, focus } = ctx.inputs;
|
|
75
|
-
const notes = ctx.inputs.notes ?? "";
|
|
76
|
-
|
|
77
|
-
await ctx.stage({ name: "write-spec" }, {}, {}, async (s) => {
|
|
78
|
-
await s.session.query(
|
|
79
|
-
`Read ${research_doc} and produce a ${focus} spec.` +
|
|
80
|
-
(notes ? `\n\nExtra guidance:\n${notes}` : ""),
|
|
81
|
-
);
|
|
82
|
-
s.save(s.sessionId);
|
|
83
|
-
});
|
|
84
|
-
})
|
|
85
|
-
.compile();
|
|
86
|
-
```
|
|
87
|
-
|
|
88
|
-
The nullish coalescing on `notes` handles the optional field case —
|
|
89
|
-
declared-but-unset inputs resolve to `undefined` unless they have a
|
|
90
|
-
`default`.
|
|
91
|
-
|
|
92
|
-
**Style convention.** Inside a stage callback, both `s.inputs.<name>` and
|
|
93
|
-
`ctx.inputs.<name>` resolve to the same value. Either of these patterns
|
|
94
|
-
works:
|
|
95
|
-
|
|
96
|
-
- **Destructure once at the top of `.run()`** so each stage closes over a
|
|
97
|
-
bare local. Best when many stages reference the same input.
|
|
98
|
-
- **Inline access** with `(s.inputs.<name> ?? "")` at each call site. Best
|
|
99
|
-
for short workflows or when each stage uses a different field.
|
|
100
|
-
|
|
101
|
-
Pick whichever reads cleaner for your workflow. Examples in other reference
|
|
102
|
-
files use the inline form for brevity in focused snippets.
|
|
103
|
-
|
|
104
|
-
## Declaring an input schema
|
|
105
|
-
|
|
106
|
-
Pass an `inputs` array to `defineWorkflow({ ... })`. Each entry is a
|
|
107
|
-
`WorkflowInput`:
|
|
108
|
-
|
|
109
|
-
```ts
|
|
110
|
-
interface WorkflowInput {
|
|
111
|
-
/** Field name — becomes the CLI flag (`--<name>`) and form label. */
|
|
112
|
-
name: string;
|
|
113
|
-
/** Input kind: string | text | enum */
|
|
114
|
-
type: "string" | "text" | "enum";
|
|
115
|
-
/** Whether the field must be non-empty before the workflow can run. */
|
|
116
|
-
required?: boolean;
|
|
117
|
-
/** Short description shown as the field caption. */
|
|
118
|
-
description?: string;
|
|
119
|
-
/** Placeholder shown when the field is empty. */
|
|
120
|
-
placeholder?: string;
|
|
121
|
-
/** Default value — enums use this to pick their initial value. */
|
|
122
|
-
default?: string;
|
|
123
|
-
/** Allowed values — required when `type` is `"enum"`. */
|
|
124
|
-
values?: readonly string[];
|
|
125
|
-
}
|
|
126
|
-
```
|
|
127
|
-
|
|
128
|
-
### Picking a field type
|
|
129
|
-
|
|
130
|
-
| Type | Use when | Picker renders as | Example |
|
|
131
|
-
|---|---|---|---|
|
|
132
|
-
| `string` | Short single-line values — identifiers, file paths, branch names | Single-row text input | `research_doc: "notes.md"` |
|
|
133
|
-
| `text` | Longer free-form prose — specs, prompts, extra context | Multi-row text area | `spec: "Build a..."` |
|
|
134
|
-
| `enum` | A fixed set of allowed values | Radio-button row | `focus: "standard" \| "minimal" \| "exhaustive"` |
|
|
135
|
-
|
|
136
|
-
Rule of thumb: use `enum` whenever there's a closed set of options — it
|
|
137
|
-
gives users discoverable choices instead of making them remember magic
|
|
138
|
-
strings, and the CLI will reject invalid values at parse time.
|
|
139
|
-
|
|
140
|
-
### Validation enforced by the runtime
|
|
141
|
-
|
|
142
|
-
The `defineWorkflow` builder validates the schema at compile time and
|
|
143
|
-
rejects authoring mistakes immediately — you won't discover them in
|
|
144
|
-
production:
|
|
145
|
-
|
|
146
|
-
- **Input names must be valid CLI flag tails** — start with a letter,
|
|
147
|
-
then letters/digits/underscores/dashes. `1bad` is rejected because
|
|
148
|
-
`--1bad` isn't a parseable flag.
|
|
149
|
-
- **Enum inputs must declare `values`** — an enum with no choices is
|
|
150
|
-
always invalid.
|
|
151
|
-
- **Enum `default` must be in `values`** — prevents drift between the
|
|
152
|
-
default and the allowed set.
|
|
153
|
-
- **No duplicate names** — two inputs with the same `name` shadow each
|
|
154
|
-
other and are rejected.
|
|
155
|
-
|
|
156
|
-
At invocation time, the CLI does a second pass to catch runtime errors
|
|
157
|
-
before spinning up any tmux session:
|
|
158
|
-
|
|
159
|
-
- **Required fields must be non-empty** (whitespace-only strings are
|
|
160
|
-
treated as empty). Missing required fields produce a clear
|
|
161
|
-
`Missing required input --<name>` error and exit non-zero.
|
|
162
|
-
- **Enum values must be in the allowed list.** `--focus=bogus` produces
|
|
163
|
-
`Invalid value for --focus: "bogus". Expected one of: minimal, standard, exhaustive.`
|
|
164
|
-
- **Unknown flags are rejected.** A `--random_flag=value` that isn't in
|
|
165
|
-
the schema produces `Unknown input --random_flag` with the valid
|
|
166
|
-
flag list appended.
|
|
167
|
-
|
|
168
|
-
This validation runs before any workflow code, so a malformed
|
|
169
|
-
invocation can never reach your `.run()` callback in a half-filled
|
|
170
|
-
state.
|
|
171
|
-
|
|
172
|
-
## Declaring a prompt input
|
|
173
|
-
|
|
174
|
-
Workflows that accept a user prompt should declare it explicitly in their
|
|
175
|
-
`inputs` array rather than relying on an implicit key:
|
|
176
|
-
|
|
177
|
-
```ts
|
|
178
|
-
inputs: [
|
|
179
|
-
{ name: "prompt", type: "text", required: true, description: "task to perform" },
|
|
180
|
-
]
|
|
181
|
-
```
|
|
182
|
-
|
|
183
|
-
This gives the same CLI ergonomics — `atomic workflow -n hello -a claude "fix the bug"` still works — while providing compile-time safety. Accessing `ctx.inputs.prompt` without declaring it is a type error.
|
|
184
|
-
|
|
185
|
-
For workflows that need both a free-form prompt AND structured parameters,
|
|
186
|
-
declare all fields in the schema:
|
|
187
|
-
|
|
188
|
-
```ts
|
|
189
|
-
inputs: [
|
|
190
|
-
{ name: "prompt", type: "text", required: true, description: "what to build" },
|
|
191
|
-
{ name: "focus", type: "enum", required: true, values: ["minimal", "standard", "exhaustive"], default: "standard" },
|
|
192
|
-
{ name: "notes", type: "text", description: "extra context" },
|
|
193
|
-
]
|
|
194
|
-
```
|
|
195
|
-
|
|
196
|
-
## The interactive picker
|
|
197
|
-
|
|
198
|
-
`atomic workflow -a <agent>` (no `-n`) launches the interactive
|
|
199
|
-
picker. The picker:
|
|
200
|
-
|
|
201
|
-
1. Discovers all workflows compatible with `<agent>` across local,
|
|
202
|
-
global, and builtin sources.
|
|
203
|
-
2. Loads each workflow's metadata (description + declared inputs).
|
|
204
|
-
3. Shows a Telescope-style fuzzy list. The user types to filter,
|
|
205
|
-
arrows to navigate, ↵ to lock in a selection.
|
|
206
|
-
4. Renders the selected workflow's form. The picker renders one field
|
|
207
|
-
per declared input with type-specific rendering.
|
|
208
|
-
5. Validates required fields on ⌃s. If any are empty, focus jumps to
|
|
209
|
-
the first invalid field and the run button stays disabled.
|
|
210
|
-
6. Confirms with a y/n modal, then tears down the picker and hands
|
|
211
|
-
off to the workflow executor — same live-run surface users see
|
|
212
|
-
when they invoke the workflow with `-n` directly.
|
|
213
|
-
|
|
214
|
-
The picker is the preferred discovery path for users who don't
|
|
215
|
-
remember flag names. Structured workflows benefit the most from it
|
|
216
|
-
because the form teaches the schema as the user fills it in.
|
|
217
|
-
|
|
218
|
-
## Builtin protection
|
|
219
|
-
|
|
220
|
-
Builtin names (`ralph`, `deep-research-codebase`) are reserved — pick
|
|
221
|
-
distinct names for your workflows. Full precedence + shadowing rules
|
|
222
|
-
live in `discovery-and-verification.md`.
|
|
223
|
-
|
|
224
|
-
## Invocation details
|
|
225
|
-
|
|
226
|
-
See SKILL.md §"Invocation surfaces" for the table of every top-level
|
|
227
|
-
command. This section only covers the flag-parsing nuances specific to
|
|
228
|
-
structured inputs.
|
|
229
|
-
|
|
230
|
-
Both `--flag=value` and `--flag value` forms are accepted. Short flags
|
|
231
|
-
(`-x value`) are NOT parsed as structured inputs — only long-form
|
|
232
|
-
`--<name>` flags resolve against the schema.
|
|
233
|
-
|
|
234
|
-
The `-d` / `--detach` flag composes with any named shape (positional
|
|
235
|
-
prompt, structured flags) and is independent of the inputs schema.
|
|
236
|
-
|
|
237
|
-
```bash
|
|
238
|
-
# Structured, both flag forms work identically
|
|
239
|
-
atomic workflow -n gen-spec -a claude --focus=standard --research_doc=notes.md
|
|
240
|
-
atomic workflow -n gen-spec -a claude --focus standard --research_doc notes.md
|
|
241
|
-
```
|
|
242
|
-
|
|
243
|
-
## Pitfalls
|
|
244
|
-
|
|
245
|
-
### Declare every field you access
|
|
246
|
-
|
|
247
|
-
With typed inputs, accessing `ctx.inputs.foo` when `foo` is not declared
|
|
248
|
-
in the workflow's `inputs` array is a compile-time error. If your workflow
|
|
249
|
-
needs a prompt field, declare it:
|
|
250
|
-
|
|
251
|
-
```ts
|
|
252
|
-
inputs: [
|
|
253
|
-
{ name: "prompt", type: "text", required: true, description: "task prompt" },
|
|
254
|
-
]
|
|
255
|
-
```
|
|
256
|
-
|
|
257
|
-
The CLI rejects positional prompt strings for workflows that don't declare
|
|
258
|
-
a `prompt` input.
|
|
259
|
-
|
|
260
|
-
### Don't rename inputs across workflow versions
|
|
261
|
-
|
|
262
|
-
Declared input names are part of the workflow's public API — they map
|
|
263
|
-
directly to `--<name>` flags and field identifiers in the picker.
|
|
264
|
-
Renaming a field is a breaking change for any script that invokes the
|
|
265
|
-
workflow. If you need to rename, add the new name alongside the old,
|
|
266
|
-
migrate callers, then remove the old name in a later change.
|
|
267
|
-
|
|
268
|
-
### Don't put secrets in `default`
|
|
269
|
-
|
|
270
|
-
Defaults are visible in the picker and printed in CLI errors. They're
|
|
271
|
-
fine for values like `"standard"` but not for API keys or auth tokens.
|
|
272
|
-
Read those from environment variables inside the workflow instead.
|
|
@@ -1,132 +0,0 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* Workflow discovery — finds workflow definitions from disk.
|
|
3
|
-
*
|
|
4
|
-
* Workflows are discovered from:
|
|
5
|
-
* 1. src/sdk/workflows/builtin/<name>/<agent>/index.ts (SDK-shipped builtins)
|
|
6
|
-
* 2. .atomic/workflows/<name>/<agent>/index.ts (project-local)
|
|
7
|
-
* 3. ~/.atomic/workflows/<name>/<agent>/index.ts (global)
|
|
8
|
-
*
|
|
9
|
-
* All three sources use the same scanning function (`discoverFromBaseDir`)
|
|
10
|
-
* so registration is uniform. Builtin names are reserved — project-local
|
|
11
|
-
* and global workflows with the same name are dropped during merge.
|
|
12
|
-
*/
|
|
13
|
-
import type { AgentType, WorkflowInput } from "../types.ts";
|
|
14
|
-
export interface DiscoveredWorkflow {
|
|
15
|
-
name: string;
|
|
16
|
-
agent: AgentType;
|
|
17
|
-
path: string;
|
|
18
|
-
source: "local" | "global" | "builtin";
|
|
19
|
-
}
|
|
20
|
-
export declare const AGENTS: AgentType[];
|
|
21
|
-
/**
|
|
22
|
-
* Default `.gitignore` content for a workflows directory.
|
|
23
|
-
* Auto-generated during install; regenerated by discovery if missing.
|
|
24
|
-
*/
|
|
25
|
-
export declare const WORKFLOWS_GITIGNORE: string;
|
|
26
|
-
/**
|
|
27
|
-
* Discover all available workflows from built-in, global, and local sources.
|
|
28
|
-
* Optionally filter by agent.
|
|
29
|
-
*
|
|
30
|
-
* **Merge precedence:** `builtin > local > global`.
|
|
31
|
-
*
|
|
32
|
-
* Builtin names are **strictly reserved** — a user-defined local or
|
|
33
|
-
* global workflow whose name matches any built-in workflow is dropped
|
|
34
|
-
* entirely from discovery. It will not be registered, returned from
|
|
35
|
-
* `findWorkflow`, appear in the interactive picker, or show up in
|
|
36
|
-
* `atomic workflow -l`. This protects SDK-shipped workflows (e.g.
|
|
37
|
-
* `ralph`) from being silently overridden or even visibly "competing
|
|
38
|
-
* with" a user's own definition, which would otherwise be confusing
|
|
39
|
-
* when someone tries to run the canonical version.
|
|
40
|
-
*
|
|
41
|
-
* Reservation is by **name only**, across all agents: if a builtin
|
|
42
|
-
* defines `ralph` for any agent, a local `ralph` for any other agent is
|
|
43
|
-
* also dropped. Local still overrides global for every non-builtin
|
|
44
|
-
* name, so project-scoped customisation of user-scoped workflows
|
|
45
|
-
* continues to work.
|
|
46
|
-
*
|
|
47
|
-
* By default, the result is **merged by precedence** — if a workflow is
|
|
48
|
-
* defined in both local and global sources, only the higher-precedence
|
|
49
|
-
* entry is returned. This is the right shape for `findWorkflow`, which
|
|
50
|
-
* needs the single resolved entry per (name, agent) pair.
|
|
51
|
-
*
|
|
52
|
-
* Pass `{ merge: false }` to get the **unmerged** result — local and
|
|
53
|
-
* global contribute their entries independently, so `--list` can show
|
|
54
|
-
* both a local and a global copy of the same workflow when they coexist
|
|
55
|
-
* on disk. (Builtin reservation still applies in both modes.)
|
|
56
|
-
*/
|
|
57
|
-
export declare function discoverWorkflows(projectRoot?: string, agentFilter?: AgentType, options?: {
|
|
58
|
-
merge?: boolean;
|
|
59
|
-
}): Promise<DiscoveredWorkflow[]>;
|
|
60
|
-
/**
|
|
61
|
-
* Find a specific workflow by name and agent.
|
|
62
|
-
*/
|
|
63
|
-
export declare function findWorkflow(name: string, agent: AgentType, projectRoot?: string): Promise<DiscoveredWorkflow | null>;
|
|
64
|
-
/**
|
|
65
|
-
* Load status for a {@link WorkflowWithMetadata} entry.
|
|
66
|
-
*
|
|
67
|
-
* - `ok` — the workflow compiled cleanly and is ready to run.
|
|
68
|
-
* - `incompatible` — the workflow declared a `minSDKVersion` newer
|
|
69
|
-
* than the bundled CLI. The CLI renders it with an
|
|
70
|
-
* "update required" badge so users see the mismatch
|
|
71
|
-
* rather than a silent disappearance.
|
|
72
|
-
* - `error` — any other load failure (syntax error, missing
|
|
73
|
-
* `.compile()`, invalid default export, etc.).
|
|
74
|
-
* Rendered with a "failed to load" badge plus the
|
|
75
|
-
* underlying message.
|
|
76
|
-
*/
|
|
77
|
-
export type WorkflowMetadataStatus = {
|
|
78
|
-
kind: "ok";
|
|
79
|
-
} | {
|
|
80
|
-
kind: "incompatible";
|
|
81
|
-
requiredVersion: string;
|
|
82
|
-
currentVersion: string;
|
|
83
|
-
message: string;
|
|
84
|
-
} | {
|
|
85
|
-
kind: "error";
|
|
86
|
-
stage: "resolve" | "validate" | "load";
|
|
87
|
-
message: string;
|
|
88
|
-
};
|
|
89
|
-
/**
|
|
90
|
-
* A discovered workflow enriched with the metadata the picker needs to
|
|
91
|
-
* render it: the human description, the declared input schema, and the
|
|
92
|
-
* load status.
|
|
93
|
-
*
|
|
94
|
-
* Populated by {@link loadWorkflowsMetadata}, which runs each discovered
|
|
95
|
-
* workflow through {@link WorkflowLoader.loadWorkflow} and extracts the
|
|
96
|
-
* display-relevant fields — the full compiled definition is discarded
|
|
97
|
-
* after extraction so re-imports during execution are cheap.
|
|
98
|
-
*
|
|
99
|
-
* Broken entries still materialise with empty `description` / `inputs`
|
|
100
|
-
* and a non-`ok` {@link status}, so the picker can render them as
|
|
101
|
-
* visible "update required" / "failed to load" rows instead of
|
|
102
|
-
* silently omitting them (the previous behaviour, which made user and
|
|
103
|
-
* global workflows vanish whenever the base SDK shape drifted between
|
|
104
|
-
* releases).
|
|
105
|
-
*/
|
|
106
|
-
export interface WorkflowWithMetadata extends DiscoveredWorkflow {
|
|
107
|
-
/** Workflow description, empty string when none was declared or the workflow failed to load. */
|
|
108
|
-
description: string;
|
|
109
|
-
/** Picker-ready input schema; empty for free-form or failed-to-load workflows. */
|
|
110
|
-
inputs: readonly WorkflowInput[];
|
|
111
|
-
/** Load outcome — non-`ok` entries are rendered as visible diagnostics in the picker/list. */
|
|
112
|
-
status: WorkflowMetadataStatus;
|
|
113
|
-
}
|
|
114
|
-
/**
|
|
115
|
-
* Load metadata (description + picker-ready inputs + status) for a batch
|
|
116
|
-
* of discovered workflows.
|
|
117
|
-
*
|
|
118
|
-
* **Failed workflows are kept in the returned list**, not dropped. Each
|
|
119
|
-
* broken entry carries a {@link WorkflowMetadataStatus} explaining the
|
|
120
|
-
* failure so the picker and `atomic workflow -l` can surface it as an
|
|
121
|
-
* actionable diagnostic. This is the only way end users discover that a
|
|
122
|
-
* workflow from an older SDK release has gone incompatible after an
|
|
123
|
-
* `atomic` upgrade — silent filtering would leave them with a missing
|
|
124
|
-
* entry and no breadcrumb.
|
|
125
|
-
*
|
|
126
|
-
* Callers that want to execute a workflow should still route through
|
|
127
|
-
* {@link WorkflowLoader.loadWorkflow} — this function throws away the
|
|
128
|
-
* compiled definition so re-running the loader on a confirmed pick is
|
|
129
|
-
* unavoidable.
|
|
130
|
-
*/
|
|
131
|
-
export declare function loadWorkflowsMetadata(discovered: DiscoveredWorkflow[]): Promise<WorkflowWithMetadata[]>;
|
|
132
|
-
//# sourceMappingURL=discovery.d.ts.map
|
|
@@ -1 +0,0 @@
|
|
|
1
|
-
{"version":3,"file":"discovery.d.ts","sourceRoot":"","sources":["../../../src/sdk/runtime/discovery.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAMH,OAAO,KAAK,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAI5D,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,SAAS,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,OAAO,GAAG,QAAQ,GAAG,SAAS,CAAC;CACxC;AAUD,eAAO,MAAM,MAAM,EAAE,SAAS,EAAsC,CAAC;AAGrE;;;GAGG;AACH,eAAO,MAAM,mBAAmB,QASpB,CAAC;AAkGb;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAsB,iBAAiB,CACrC,WAAW,GAAE,MAAsB,EACnC,WAAW,CAAC,EAAE,SAAS,EACvB,OAAO,GAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAA;CAAO,GAChC,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAoD/B;AAED;;GAEG;AACH,wBAAsB,YAAY,CAChC,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,SAAS,EAChB,WAAW,GAAE,MAAsB,GAClC,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC,CAGpC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,sBAAsB,GAC9B;IAAE,IAAI,EAAE,IAAI,CAAA;CAAE,GACd;IACE,IAAI,EAAE,cAAc,CAAC;IACrB,eAAe,EAAE,MAAM,CAAC;IACxB,cAAc,EAAE,MAAM,CAAC;IACvB,OAAO,EAAE,MAAM,CAAC;CACjB,GACD;IACE,IAAI,EAAE,OAAO,CAAC;IACd,KAAK,EAAE,SAAS,GAAG,UAAU,GAAG,MAAM,CAAC;IACvC,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAEN;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,oBAAqB,SAAQ,kBAAkB;IAC9D,gGAAgG;IAChG,WAAW,EAAE,MAAM,CAAC;IACpB,kFAAkF;IAClF,MAAM,EAAE,SAAS,aAAa,EAAE,CAAC;IACjC,8FAA8F;IAC9F,MAAM,EAAE,sBAAsB,CAAC;CAChC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,qBAAqB,CACzC,UAAU,EAAE,kBAAkB,EAAE,GAC/B,OAAO,CAAC,oBAAoB,EAAE,CAAC,CA2CjC"}
|
|
@@ -1,11 +0,0 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* Orchestrator entry point — invoked inside a tmux pane by the launcher script.
|
|
3
|
-
*
|
|
4
|
-
* Separated from executor.ts to avoid the dual-module-identity problem:
|
|
5
|
-
* Bun evaluates a file twice when it is both the entry point (`bun run`)
|
|
6
|
-
* and reached through package.json `exports` self-referencing. Keeping
|
|
7
|
-
* the side-effectful `--run` guard here ensures executor.ts stays a pure
|
|
8
|
-
* library module that can be safely re-exported from the SDK barrel.
|
|
9
|
-
*/
|
|
10
|
-
export {};
|
|
11
|
-
//# sourceMappingURL=executor-entry.d.ts.map
|
|
@@ -1 +0,0 @@
|
|
|
1
|
-
{"version":3,"file":"executor-entry.d.ts","sourceRoot":"","sources":["../../../src/sdk/runtime/executor-entry.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}
|
|
@@ -1,70 +0,0 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* Workflow Loader — multi-stage pipeline for resolving and loading workflows.
|
|
3
|
-
*
|
|
4
|
-
* Pipeline: Discover → Resolve → Validate → Load
|
|
5
|
-
*
|
|
6
|
-
* Each stage returns a typed discriminated result so callers get structured
|
|
7
|
-
* error information without try/catch guesswork.
|
|
8
|
-
*
|
|
9
|
-
* Discovery (finding workflow files on disk) remains in `discovery.ts`.
|
|
10
|
-
* This module handles everything after a workflow is discovered.
|
|
11
|
-
*/
|
|
12
|
-
import type { WorkflowDefinition } from "../types.ts";
|
|
13
|
-
import type { DiscoveredWorkflow } from "./discovery.ts";
|
|
14
|
-
export declare namespace WorkflowLoader {
|
|
15
|
-
/** Successful pipeline result. */
|
|
16
|
-
type Ok<T> = {
|
|
17
|
-
ok: true;
|
|
18
|
-
value: T;
|
|
19
|
-
};
|
|
20
|
-
/** Failed pipeline result with stage and error context. */
|
|
21
|
-
type StageError<S extends string> = {
|
|
22
|
-
ok: false;
|
|
23
|
-
stage: S;
|
|
24
|
-
error: unknown;
|
|
25
|
-
message: string;
|
|
26
|
-
};
|
|
27
|
-
type StageResult<T, S extends string> = Ok<T> | StageError<S>;
|
|
28
|
-
/** Input to the pipeline — a discovered workflow from disk. */
|
|
29
|
-
type Plan = DiscoveredWorkflow;
|
|
30
|
-
/** Output of the resolve stage. */
|
|
31
|
-
type Resolved = Plan;
|
|
32
|
-
/** Source validation warning — alias of the canonical type from types.ts. */
|
|
33
|
-
type ValidationWarning = import("../types.ts").ValidationWarning;
|
|
34
|
-
/** Output of the validate stage. */
|
|
35
|
-
type Validated = Resolved & {
|
|
36
|
-
warnings: ValidationWarning[];
|
|
37
|
-
};
|
|
38
|
-
/** Output of the load stage — the final result. */
|
|
39
|
-
type Loaded = Validated & {
|
|
40
|
-
definition: WorkflowDefinition;
|
|
41
|
-
};
|
|
42
|
-
interface Report {
|
|
43
|
-
/** Called when a stage begins. */
|
|
44
|
-
start?: (stage: "resolve" | "validate" | "load") => void;
|
|
45
|
-
/** Called when source validation produces warnings. */
|
|
46
|
-
warn?: (warnings: ValidationWarning[]) => void;
|
|
47
|
-
/** Called when a stage fails. */
|
|
48
|
-
error?: (stage: "resolve" | "validate" | "load", error: unknown, message: string) => void;
|
|
49
|
-
}
|
|
50
|
-
/** Verify the workflow file exists. */
|
|
51
|
-
function resolve(plan: Plan): Promise<StageResult<Resolved, "resolve">>;
|
|
52
|
-
/**
|
|
53
|
-
* Read the workflow source and run agent-specific validation checks.
|
|
54
|
-
* Validation warnings are non-fatal — the pipeline continues.
|
|
55
|
-
*/
|
|
56
|
-
function validate(resolved: Resolved): Promise<StageResult<Validated, "validate">>;
|
|
57
|
-
/**
|
|
58
|
-
* Import the workflow module and extract the WorkflowDefinition.
|
|
59
|
-
* Checks for common authoring mistakes (missing `.compile()`, wrong export).
|
|
60
|
-
*/
|
|
61
|
-
function load(validated: Validated): Promise<StageResult<Loaded, "load">>;
|
|
62
|
-
/**
|
|
63
|
-
* Run the full pipeline: resolve → validate → load.
|
|
64
|
-
*
|
|
65
|
-
* Returns a structured result with the loaded WorkflowDefinition on success,
|
|
66
|
-
* or a stage-specific error on failure.
|
|
67
|
-
*/
|
|
68
|
-
function loadWorkflow(plan: Plan, report?: Report): Promise<StageResult<Loaded, "resolve" | "validate" | "load">>;
|
|
69
|
-
}
|
|
70
|
-
//# sourceMappingURL=loader.d.ts.map
|
|
@@ -1 +0,0 @@
|
|
|
1
|
-
{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../../../src/sdk/runtime/loader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAa,MAAM,aAAa,CAAC;AACjE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAazD,yBAAiB,cAAc,CAAC;IAK9B,kCAAkC;IAClC,KAAY,EAAE,CAAC,CAAC,IAAI;QAAE,EAAE,EAAE,IAAI,CAAC;QAAC,KAAK,EAAE,CAAC,CAAA;KAAE,CAAC;IAE3C,2DAA2D;IAC3D,KAAY,UAAU,CAAC,CAAC,SAAS,MAAM,IAAI;QACzC,EAAE,EAAE,KAAK,CAAC;QACV,KAAK,EAAE,CAAC,CAAC;QACT,KAAK,EAAE,OAAO,CAAC;QACf,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC;IAEF,KAAY,WAAW,CAAC,CAAC,EAAE,CAAC,SAAS,MAAM,IAAI,EAAE,CAAC,CAAC,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,CAAC;IAMrE,+DAA+D;IAC/D,KAAY,IAAI,GAAG,kBAAkB,CAAC;IAEtC,mCAAmC;IACnC,KAAY,QAAQ,GAAG,IAAI,CAAC;IAE5B,6EAA6E;IAC7E,KAAY,iBAAiB,GAAG,OAAO,aAAa,EAAE,iBAAiB,CAAC;IAExE,oCAAoC;IACpC,KAAY,SAAS,GAAG,QAAQ,GAAG;QACjC,QAAQ,EAAE,iBAAiB,EAAE,CAAC;KAC/B,CAAC;IAEF,mDAAmD;IACnD,KAAY,MAAM,GAAG,SAAS,GAAG;QAC/B,UAAU,EAAE,kBAAkB,CAAC;KAChC,CAAC;IAMF,UAAiB,MAAM;QACrB,kCAAkC;QAClC,KAAK,CAAC,EAAE,CAAC,KAAK,EAAE,SAAS,GAAG,UAAU,GAAG,MAAM,KAAK,IAAI,CAAC;QACzD,uDAAuD;QACvD,IAAI,CAAC,EAAE,CAAC,QAAQ,EAAE,iBAAiB,EAAE,KAAK,IAAI,CAAC;QAC/C,iCAAiC;QACjC,KAAK,CAAC,EAAE,CAAC,KAAK,EAAE,SAAS,GAAG,UAAU,GAAG,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;KAC3F;IAMD,uCAAuC;IACvC,SAAsB,OAAO,CAC3B,IAAI,EAAE,IAAI,GACT,OAAO,CAAC,WAAW,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC,CAoB3C;IAsBD;;;OAGG;IACH,SAAsB,QAAQ,CAC5B,QAAQ,EAAE,QAAQ,GACjB,OAAO,CAAC,WAAW,CAAC,SAAS,EAAE,UAAU,CAAC,CAAC,CAiB7C;IAMD;;;OAGG;IACH,SAAsB,IAAI,CACxB,SAAS,EAAE,SAAS,GACnB,OAAO,CAAC,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAyDtC;IAMD;;;;;OAKG;IACH,SAAsB,YAAY,CAChC,IAAI,EAAE,IAAI,EACV,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAAC,WAAW,CAAC,MAAM,EAAE,SAAS,GAAG,UAAU,GAAG,MAAM,CAAC,CAAC,CA6B/D;CACF"}
|
package/dist/version.d.ts
DELETED
package/dist/version.d.ts.map
DELETED
|
@@ -1 +0,0 @@
|
|
|
1
|
-
{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAKA,eAAO,MAAM,OAAO,QAAsB,CAAC"}
|