skill-rails 0.2.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.
Files changed (57) hide show
  1. package/.claude-plugin/marketplace.json +16 -0
  2. package/.claude-plugin/plugin.json +16 -0
  3. package/.mcp.json +8 -0
  4. package/LICENSE +21 -0
  5. package/README.md +255 -0
  6. package/bin/skill-rails.js +4 -0
  7. package/dist/api.d.ts +38 -0
  8. package/dist/api.js +73 -0
  9. package/dist/api.js.map +1 -0
  10. package/dist/cli.d.ts +2 -0
  11. package/dist/cli.js +112 -0
  12. package/dist/cli.js.map +1 -0
  13. package/dist/engine.d.ts +18 -0
  14. package/dist/engine.js +312 -0
  15. package/dist/engine.js.map +1 -0
  16. package/dist/expressions.d.ts +12 -0
  17. package/dist/expressions.js +44 -0
  18. package/dist/expressions.js.map +1 -0
  19. package/dist/flow.d.ts +11 -0
  20. package/dist/flow.js +137 -0
  21. package/dist/flow.js.map +1 -0
  22. package/dist/mcp.d.ts +5 -0
  23. package/dist/mcp.js +37 -0
  24. package/dist/mcp.js.map +1 -0
  25. package/dist/run.d.ts +6 -0
  26. package/dist/run.js +67 -0
  27. package/dist/run.js.map +1 -0
  28. package/dist/schema.d.ts +10 -0
  29. package/dist/schema.js +15 -0
  30. package/dist/schema.js.map +1 -0
  31. package/dist/state.d.ts +6 -0
  32. package/dist/state.js +24 -0
  33. package/dist/state.js.map +1 -0
  34. package/dist/testing.d.ts +50 -0
  35. package/dist/testing.js +233 -0
  36. package/dist/testing.js.map +1 -0
  37. package/dist/types.d.ts +200 -0
  38. package/dist/types.js +2 -0
  39. package/dist/types.js.map +1 -0
  40. package/docs/format.md +256 -0
  41. package/docs/testing.md +100 -0
  42. package/examples/hello/flow.yaml +32 -0
  43. package/examples/hello/tests/hello.test.yaml +22 -0
  44. package/examples/open-pr/flow.yaml +87 -0
  45. package/examples/open-pr/prompts/text.md +26 -0
  46. package/examples/open-pr/scripts/body-file.sh +10 -0
  47. package/examples/open-pr/scripts/context.sh +21 -0
  48. package/examples/open-pr/scripts/create.sh +6 -0
  49. package/examples/open-pr/scripts/push.sh +8 -0
  50. package/examples/open-pr/tests/open-pr.test.yaml +42 -0
  51. package/examples/open-pr/tests/stubs/gh +9 -0
  52. package/package.json +72 -0
  53. package/schema/flow.schema.json +440 -0
  54. package/skills/create-skill-rails/SKILL.md +72 -0
  55. package/skills/create-skill-rails/template/SKILL.md +24 -0
  56. package/skills/migrate-to-skill-rails/SKILL.md +78 -0
  57. package/skills/run-skill-rails/SKILL.md +63 -0
@@ -0,0 +1,16 @@
1
+ {
2
+ "name": "skill-rails",
3
+ "description": "skill-rails: deterministic YAML flows for agent skills",
4
+ "owner": {
5
+ "name": "Juani Galán",
6
+ "url": "https://github.com/juanigalan91"
7
+ },
8
+ "plugins": [
9
+ {
10
+ "name": "skill-rails",
11
+ "source": "./",
12
+ "description": "Deterministic YAML flows for agent skills: run, create and migrate skills to skill-rails",
13
+ "version": "0.2.0"
14
+ }
15
+ ]
16
+ }
@@ -0,0 +1,16 @@
1
+ {
2
+ "name": "skill-rails",
3
+ "description": "Deterministic YAML flows for agent skills: run, create and migrate skills to skill-rails",
4
+ "version": "0.2.0",
5
+ "license": "MIT",
6
+ "keywords": [
7
+ "skills",
8
+ "workflow",
9
+ "flow",
10
+ "deterministic"
11
+ ],
12
+ "author": {
13
+ "name": "Juani Galán",
14
+ "url": "https://github.com/juanigalan91"
15
+ }
16
+ }
package/.mcp.json ADDED
@@ -0,0 +1,8 @@
1
+ {
2
+ "mcpServers": {
3
+ "skill-rails": {
4
+ "command": "npx",
5
+ "args": ["-y", "skill-rails@0.2", "mcp"]
6
+ }
7
+ }
8
+ }
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Juani Galán
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,255 @@
1
+ <div align="center">
2
+
3
+ # skill-rails
4
+
5
+ ### Stop hoping your agent follows the steps. Make it follow them.
6
+
7
+ [![npm](https://img.shields.io/npm/v/skill-rails.svg)](https://www.npmjs.com/package/skill-rails)
8
+ [![license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
9
+ [![node](https://img.shields.io/badge/node-%3E%3D20-brightgreen.svg)](package.json)
10
+
11
+ **2× faster · up to 40% cheaper · the same result, every run**
12
+
13
+ </div>
14
+
15
+ ---
16
+
17
+ You wrote a great skill.
18
+ It has twelve steps, four conditions, and one rule that must never break.
19
+ Then the model skips step 7, runs `git log` five times, and invents a flag for `gh`.
20
+
21
+ **skill-rails turns a skill into a flow.**
22
+ Code does the steps that are always the same.
23
+ The agent does only the steps that need judgment, one at a time.
24
+ Every answer is checked against a schema before the flow goes on.
25
+
26
+ | | Markdown skill | skill-rails |
27
+ |---|---|---|
28
+ | Order of the steps | The model remembers it | The runner enforces it |
29
+ | `if` conditions and gates | The model reads them | `${{ }}` expressions, evaluated in code |
30
+ | `git`, `gh`, checks, file operations | Model turns, tokens, mistakes | Scripts, with no model turn |
31
+ | Values between steps | Free text in the context | JSON outputs, validated against a schema |
32
+ | Questions to the user | Mixed into the prompt | Typed `ask` steps, with validated answers |
33
+ | Loops, waits and reuse | "Do this for each comment", "wait for CI" | `foreach`, `run` with `until`, and `uses` to call another flow |
34
+ | The skill file | One long prompt | `flow.yaml` + `scripts/` + `prompts/` that you can test and review |
35
+
36
+ The flow format is the GitHub Actions syntax that you already know: `steps`, `if: ${{ }}`, `run`, `env`, `$FLOW_OUTPUT`.
37
+ It runs inside the session of your agent, with its context, its tools and its permissions: you add no new service and no API key.
38
+
39
+ ## Before and after
40
+
41
+ The same skill, "open a pull request", as Markdown and as a flow.
42
+
43
+ **Before:** `SKILL.md`, one long prompt.
44
+ The model must run every command, remember every value, and respect every condition.
45
+
46
+ ````markdown
47
+ ## Step 1: Gather the context
48
+ Run `git branch --show-current`, `gh pr view` and `git merge-base origin/<base> HEAD`.
49
+ Store the branch, the base, the open PR and the commits.
50
+ If the branch has no commits ahead of the base, stop: there is nothing to merge.
51
+ If the branch is the base branch, stop.
52
+
53
+ ## Step 2: Push
54
+ Push the branch with `git push -u origin HEAD`. Never force-push.
55
+
56
+ ## Step 3: Write the PR
57
+ Copy the PR template to a temp file, then fill it. Keep every HTML comment.
58
+ Write a title under 72 characters, in the format of the recent commits.
59
+
60
+ ## Step 4: Create the PR
61
+ If the user wants a draft, add `--draft`.
62
+ Run `gh pr create --title "<title>" --body-file <file>` and show the URL.
63
+ ````
64
+
65
+ **After:** `flow.yaml` holds the order and the conditions, `scripts/` the commands, and `prompts/` the only part that needs the model.
66
+
67
+ ```yaml
68
+ # flow.yaml
69
+ name: open-pr
70
+ steps:
71
+ - id: context
72
+ run: context.sh # scripts/context.sh: branch, base, PR, commits, template
73
+ - if: ${{ !steps.context.outputs.commits }}
74
+ stop: Nothing to merge.
75
+ outcome: failure
76
+ - id: push
77
+ run: push.sh # never force-pushes
78
+ - id: body-file
79
+ run: body-file.sh # copies the template
80
+ - id: text
81
+ prompt-file: prompts/text.md # the agent fills the body and writes the title
82
+ output:
83
+ type: object
84
+ required: [title]
85
+ properties:
86
+ title: { type: string, maxLength: 72 }
87
+ - id: create
88
+ run: create.sh
89
+ env:
90
+ TITLE: ${{ steps.text.outputs.title }}
91
+ - stop: 'PR created: ${{ steps.create.outputs.url }}'
92
+ ```
93
+
94
+ ```bash
95
+ # scripts/context.sh (excerpt)
96
+ branch="$(git branch --show-current)"
97
+ echo "branch=$branch" >> "$FLOW_OUTPUT"
98
+ echo 'commits<<EOF' >> "$FLOW_OUTPUT"; git log "$merge_base..HEAD" --oneline >> "$FLOW_OUTPUT"; echo EOF >> "$FLOW_OUTPUT"
99
+ ```
100
+
101
+ ```markdown
102
+ <!-- prompts/text.md (excerpt) -->
103
+ Fill `${{ steps.body-file.outputs.file }}` in place: one sentence on the goal, then 2–4 bullet points.
104
+ Write the title in the format of the recent commits:
105
+ ${{ steps.context.outputs.recent }}
106
+ ```
107
+
108
+ What changes:
109
+
110
+ - The model gets **one step**: the text. The other steps run as code, with no model turn.
111
+ - The gate "nothing to merge" is an `if:` that always runs, and the title is checked against `maxLength: 72`.
112
+ - The flow can be tested with no model: see [Testing](#testing).
113
+
114
+ The agent drives the loop from inside its own session, so the flow keeps the session context, the tools and the permissions of the agent:
115
+
116
+ ```text
117
+ agent ── start flow.yaml ──▶ runner (runs the shell steps, then stops at the first agent step)
118
+ agent ◀── { status: step, instructions, output schema } ──
119
+ agent ── done <step> <json> ──▶ runner (validates the output, runs the next shell steps)
120
+ agent ◀── { status: done, message } ──
121
+ ```
122
+
123
+ ## Benchmarks
124
+
125
+ Two skills, each run headless 3 times as a Markdown skill and as a skill-rails flow, on the same input.
126
+ Both versions gave the same result in every run.
127
+
128
+ | Skill | Version | Duration | Model turns | Cost |
129
+ |-------|---------|----------|-------------|------|
130
+ | A | Markdown | 37 s | 21 | $0.43 |
131
+ | A | skill-rails | 17–20 s | 7–8 | $0.25–0.28 |
132
+ | B | Markdown | 38 s | 9 | $0.29 |
133
+ | B | skill-rails | 30 s | 8 | $0.21–0.25 |
134
+
135
+ These are small samples on simple inputs.
136
+ The gain is largest when a skill has many mechanical steps.
137
+ It is small when most of the work is research that only the model can do.
138
+
139
+ ## Install
140
+
141
+ As a Claude Code plugin, with the skills and the MCP server:
142
+
143
+ ```text
144
+ /plugin marketplace add juanigalan91/skill-rails
145
+ /plugin install skill-rails@skill-rails
146
+ ```
147
+
148
+ As a CLI or a library (Node 20 or later):
149
+
150
+ ```bash
151
+ yarn add skill-rails # or: npx skill-rails check flow.yaml
152
+ yarn skill-rails check flow.yaml
153
+ ```
154
+
155
+ ```ts
156
+ import { start, done } from 'skill-rails';
157
+ ```
158
+
159
+ The MCP server works with any MCP client:
160
+
161
+ ```json
162
+ { "mcpServers": { "skill-rails": { "command": "npx", "args": ["-y", "skill-rails@0.2", "mcp"] } } }
163
+ ```
164
+
165
+ ## Use
166
+
167
+ - **Run a flow:** the `run-skill-rails` skill, the MCP tools `flow_start` and `flow_done`, or the CLI.
168
+ - **Create a skill:** the `create-skill-rails` skill designs the steps and writes `flow.yaml`, `scripts/` and `prompts/`.
169
+ - **Migrate a skill:** the `migrate-to-skill-rails` skill converts a Markdown skill, keeps every rule, and compares the two versions.
170
+
171
+ A flow skill is a folder:
172
+
173
+ ```text
174
+ my-skill/
175
+ SKILL.md # the short loop: start the flow, do each step, report it
176
+ flow.yaml # the order, the conditions and the inputs
177
+ scripts/ # the code of the run steps (in PATH)
178
+ prompts/ # the instructions of the agent steps
179
+ ```
180
+
181
+ ## Testing
182
+
183
+ A flow is deterministic everywhere except in the agent steps, so you can test it with no model.
184
+ A test gives the answers that the agent would give, and the runner does the rest for real: scripts, conditions, outputs and files.
185
+
186
+ ```yaml
187
+ # tests/open-pr.test.yaml
188
+ flow: ../flow.yaml
189
+ path: [stubs] # a stub gh, so the test never calls GitHub
190
+ setup: | # a local remote and a branch with one commit
191
+ git init -q --bare "$(mktemp -d)/origin.git" ...
192
+ tests:
193
+ - name: unattended, new draft PR
194
+ inputs: { auto: true }
195
+ answers:
196
+ text: { title: 'feat: add a' }
197
+ expect:
198
+ status: done
199
+ message: 'PR created: https://github.com/acme/app/pull/7'
200
+ steps: { draft: skipped, create: success }
201
+ ```
202
+
203
+ ```text
204
+ $ skill-rails test
205
+ ✓ interactive, new draft PR (examples/open-pr/tests/open-pr.test.yaml, 2 agent steps, 1308 ms)
206
+ ✓ unattended, no questions (examples/open-pr/tests/open-pr.test.yaml, 1 agent steps, 640 ms)
207
+ ✓ stops on the base branch (examples/open-pr/tests/open-pr.test.yaml, 0 agent steps, 494 ms)
208
+ ```
209
+
210
+ A test fails when the flow asks for a step that has no answer, when an answer is never used, when an answer does not match its schema, or when the result is not the expected one.
211
+ See [Testing flows](docs/testing.md).
212
+
213
+ ## CLI
214
+
215
+ ```text
216
+ skill-rails start <flow.yaml> [--input <key>=<value> ...] check the flow, reset its state, print the first agent step
217
+ skill-rails done <flow> <step-id> [--output <json> | -] record the output of a step, print the next step
218
+ skill-rails done <flow> <step-id> --fail <reason> end the flow with an error
219
+ skill-rails status <flow> print the current step and the step results
220
+ skill-rails reset <flow> delete the state of a flow
221
+ skill-rails check <flow.yaml> check a flow file without running it
222
+ skill-rails mcp run the MCP server on stdio
223
+ ```
224
+
225
+ ## Documentation
226
+
227
+ - [The flow format](docs/format.md): steps, expressions, outputs, and the protocol.
228
+ - [Testing flows](docs/testing.md): answers, fixtures, stubs and expectations.
229
+ - [Examples](examples/): `hello` and `open-pr`.
230
+
231
+ ## Security
232
+
233
+ - A `run` command cannot hold `${{ }}`: values go through `env`, so a commit message or a title cannot run as shell code.
234
+ - The runner runs the scripts of the flow with the permissions of the user who starts it.
235
+ Read a flow and its scripts before you run them, as you read any script.
236
+
237
+ ## Related projects
238
+
239
+ - [claude-workflow](https://github.com/AxGord/claude-workflow): YAML state machines that a Claude Code agent moves through with an MCP server.
240
+ skill-rails adds schema-validated outputs, user questions, and the GitHub Actions syntax.
241
+ - [Archon](https://github.com/coleam00/Archon) and [GitHub Agentic Workflows](https://github.com/github/gh-aw): the runner starts the agent.
242
+ In skill-rails, the agent drives the runner from inside its own session.
243
+ - [Goose recipes](https://github.com/aaif-goose/goose): YAML recipes with structured output.
244
+
245
+ ## Contributing
246
+
247
+ ```bash
248
+ yarn install
249
+ yarn typecheck
250
+ yarn test
251
+ ```
252
+
253
+ ## License
254
+
255
+ MIT
@@ -0,0 +1,4 @@
1
+ #!/usr/bin/env node
2
+ import { main } from '../dist/cli.js';
3
+
4
+ process.exitCode = await main(process.argv.slice(2));
package/dist/api.d.ts ADDED
@@ -0,0 +1,38 @@
1
+ import type { Exec, Report, StepResult } from './types.js';
2
+ export { loadFlow, validateFlow, FlowError } from './flow.js';
3
+ export { advance, newState, submit, report } from './engine.js';
4
+ export type * from './types.js';
5
+ export { runTests, runTest, loadTests, findTests } from './testing.js';
6
+ export type { TestCase, TestResult } from './testing.js';
7
+ interface CommonOptions {
8
+ cwd?: string;
9
+ exec?: Exec;
10
+ }
11
+ /** Checks the flow, resets its state, runs until the first agent step. */
12
+ export declare function start({ file, inputs, cwd, exec }: {
13
+ file: string;
14
+ inputs?: Record<string, unknown>;
15
+ } & CommonOptions): Report;
16
+ /** Records the output of a step (or fails the flow), then runs until the next agent step. */
17
+ export declare function done({ flow, id, output, fail, cwd, exec, }: {
18
+ flow: string;
19
+ id: string;
20
+ output?: unknown;
21
+ fail?: string;
22
+ } & CommonOptions): Report;
23
+ /** The current step again, or the end of the flow, with the step results. */
24
+ export declare function status({ flow, cwd }: {
25
+ flow: string;
26
+ cwd?: string;
27
+ }): Report | (Report & {
28
+ results: Record<string, StepResult>;
29
+ });
30
+ /** Deletes the state of a flow. */
31
+ export declare function reset({ flow, cwd }: {
32
+ flow: string;
33
+ cwd?: string;
34
+ }): Report;
35
+ /** Checks a flow file without running it. */
36
+ export declare function check({ file }: {
37
+ file: string;
38
+ }): Report;
package/dist/api.js ADDED
@@ -0,0 +1,73 @@
1
+ // The commands that the CLI and the MCP server share. Each one returns the JSON report for the agent.
2
+ import { advance, finish, newState, report, rootResults, submit } from './engine.js';
3
+ import { loadFlow } from './flow.js';
4
+ import { readState, removeState, writeState } from './state.js';
5
+ export { loadFlow, validateFlow, FlowError } from './flow.js';
6
+ export { advance, newState, submit, report } from './engine.js';
7
+ export { runTests, runTest, loadTests, findTests } from './testing.js';
8
+ const errorReport = (error) => ({
9
+ status: 'error',
10
+ errors: error.errors ?? [error.message],
11
+ });
12
+ function save(state) {
13
+ const result = report(state);
14
+ writeState(state);
15
+ return result;
16
+ }
17
+ /** Checks the flow, resets its state, runs until the first agent step. */
18
+ export function start({ file, inputs = {}, cwd = process.cwd(), exec }) {
19
+ try {
20
+ const state = newState(loadFlow(file), inputs, cwd);
21
+ advance(state, { exec });
22
+ return save(state);
23
+ }
24
+ catch (error) {
25
+ return errorReport(error);
26
+ }
27
+ }
28
+ /** Records the output of a step (or fails the flow), then runs until the next agent step. */
29
+ export function done({ flow, id, output, fail, cwd = process.cwd(), exec, }) {
30
+ try {
31
+ const state = readState(flow, cwd);
32
+ if (fail !== undefined) {
33
+ if (state.pending?.id !== id)
34
+ return { status: 'invalid', id, errors: [`the current step is "${state.pending?.id ?? 'none'}", not "${id}"`] };
35
+ finish(state, 'failed', fail);
36
+ return save(state);
37
+ }
38
+ const errors = submit(state, id, output);
39
+ if (errors.length)
40
+ return { status: 'invalid', id, errors, output: state.pending?.output };
41
+ advance(state, { exec });
42
+ return save(state);
43
+ }
44
+ catch (error) {
45
+ return errorReport(error);
46
+ }
47
+ }
48
+ /** The current step again, or the end of the flow, with the step results. */
49
+ export function status({ flow, cwd = process.cwd() }) {
50
+ try {
51
+ const state = readState(flow, cwd);
52
+ return { ...report(state), results: rootResults(state) };
53
+ }
54
+ catch (error) {
55
+ return errorReport(error);
56
+ }
57
+ }
58
+ /** Deletes the state of a flow. */
59
+ export function reset({ flow, cwd = process.cwd() }) {
60
+ removeState(flow, cwd);
61
+ return { status: 'reset', flow };
62
+ }
63
+ /** Checks a flow file without running it. */
64
+ export function check({ file }) {
65
+ try {
66
+ const flow = loadFlow(file);
67
+ return { status: 'ok', flow: flow.name, steps: flow.steps.length };
68
+ }
69
+ catch (error) {
70
+ return errorReport(error);
71
+ }
72
+ }
73
+ //# sourceMappingURL=api.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"api.js","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"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"}
package/dist/cli.d.ts ADDED
@@ -0,0 +1,2 @@
1
+ import type { Report } from './types.js';
2
+ export declare function main(argv: string[], print?: (value: Report) => boolean): Promise<number>;
package/dist/cli.js ADDED
@@ -0,0 +1,112 @@
1
+ import fs from 'node:fs';
2
+ import { check, done, reset, start, status } from './api.js';
3
+ const USAGE = `Usage:
4
+ skill-rails start <flow.yaml> [--input <key>=<value> ...] check the flow, reset its state, print the first agent step
5
+ skill-rails done <flow> <step-id> [--output <json> | -] record the output of a step, print the next step
6
+ skill-rails done <flow> <step-id> --fail <reason> end the flow with an error
7
+ skill-rails status <flow> print the current step and the step results
8
+ skill-rails reset <flow> delete the state of a flow
9
+ skill-rails check <flow.yaml> check a flow file without running it
10
+ skill-rails test [<file or folder> ...] [--json] run the *.test.yaml flow tests (default: the current folder)
11
+ skill-rails mcp run the MCP server on stdio`;
12
+ function option(args, name) {
13
+ const i = args.indexOf(`--${name}`);
14
+ if (i === -1)
15
+ return undefined;
16
+ const value = args[i + 1];
17
+ if (value === undefined)
18
+ throw new Error(`--${name} needs a value`);
19
+ return value;
20
+ }
21
+ function inputsOf(args) {
22
+ const inputs = {};
23
+ args.forEach((arg, i) => {
24
+ if (arg !== '--input')
25
+ return;
26
+ const pair = args[i + 1] ?? '';
27
+ const eq = pair.indexOf('=');
28
+ if (eq < 1)
29
+ throw new Error(`--input must be <key>=<value>, not "${pair}"`);
30
+ inputs[pair.slice(0, eq)] = pair.slice(eq + 1);
31
+ });
32
+ return inputs;
33
+ }
34
+ function outputOf(args) {
35
+ const raw = option(args, 'output');
36
+ if (raw === undefined)
37
+ return undefined;
38
+ return JSON.parse(raw === '-' ? fs.readFileSync(0, 'utf8') : raw);
39
+ }
40
+ export async function main(argv, print = (value) => process.stdout.write(`${JSON.stringify(value)}\n`)) {
41
+ const [command, ...args] = argv;
42
+ const [first, second] = args;
43
+ let result;
44
+ try {
45
+ switch (command) {
46
+ case 'start':
47
+ if (!first || first.startsWith('--'))
48
+ throw new Error(USAGE);
49
+ result = start({ file: first, inputs: inputsOf(args) });
50
+ break;
51
+ case 'done': {
52
+ if (!first || !second)
53
+ throw new Error(USAGE);
54
+ let output;
55
+ try {
56
+ output = outputOf(args);
57
+ }
58
+ catch (error) {
59
+ result = { status: 'invalid', id: second, errors: [`--output is not valid JSON: ${error.message}`] };
60
+ break;
61
+ }
62
+ result = done({ flow: first, id: second, output, fail: option(args, 'fail') });
63
+ break;
64
+ }
65
+ case 'status':
66
+ if (!first)
67
+ throw new Error(USAGE);
68
+ result = status({ flow: first });
69
+ break;
70
+ case 'reset':
71
+ if (!first)
72
+ throw new Error(USAGE);
73
+ result = reset({ flow: first });
74
+ break;
75
+ case 'check':
76
+ if (!first)
77
+ throw new Error(USAGE);
78
+ result = check({ file: first });
79
+ break;
80
+ case 'test': {
81
+ const { runTests } = await import('./testing.js');
82
+ const targets = args.filter((arg) => !arg.startsWith('--'));
83
+ const results = runTests(targets.length ? targets : ['.']);
84
+ if (args.includes('--json'))
85
+ process.stdout.write(`${JSON.stringify(results)}\n`);
86
+ else {
87
+ for (const r of results) {
88
+ process.stdout.write(`${r.passed ? '✓' : '✗'} ${r.name} (${r.file}, ${r.trace.length} agent steps, ${r.ms} ms)\n`);
89
+ for (const failure of r.failures)
90
+ process.stdout.write(` ${failure}\n`);
91
+ }
92
+ const failed = results.filter((r) => !r.passed).length;
93
+ process.stdout.write(`\n${results.length - failed} passed, ${failed} failed\n`);
94
+ }
95
+ return results.length && results.every((r) => r.passed) ? 0 : 1;
96
+ }
97
+ case 'mcp': {
98
+ const { serve } = await import('./mcp.js');
99
+ await serve();
100
+ return 0;
101
+ }
102
+ default:
103
+ throw new Error(USAGE);
104
+ }
105
+ }
106
+ catch (error) {
107
+ result = { status: 'error', errors: [error.message] };
108
+ }
109
+ print(result);
110
+ return result.status === 'error' ? 2 : 0;
111
+ }
112
+ //# sourceMappingURL=cli.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,18 @@
1
+ import type { Exec, Flow, InputSpec, InputValue, Report, State } from './types.js';
2
+ export declare class InputError extends Error {
3
+ readonly errors: string[];
4
+ constructor(errors: string[]);
5
+ }
6
+ export declare function resolveInputs(spec: Record<string, InputSpec>, given: Record<string, unknown>): Record<string, InputValue>;
7
+ export declare function newState(flow: Flow, given?: Record<string, unknown>, cwd?: string): State;
8
+ export declare function finish(state: State, status: 'done' | 'failed', message: string | null): void;
9
+ /** Runs steps until the flow ends or a step waits for the agent. */
10
+ export declare function advance(state: State, { exec }?: {
11
+ exec?: Exec;
12
+ }): void;
13
+ /** Records the output of the waiting step. Returns the errors; none when the flow can go on. */
14
+ export declare function submit(state: State, id: string, output?: unknown): string[];
15
+ /** The step results of the root flow. */
16
+ export declare const rootResults: (state: State) => Record<string, import("./types.js").StepResult>;
17
+ /** What the agent reads after each command. The notes are shown once. */
18
+ export declare function report(state: State): Report;