@skillstate/cli 2.0.1 → 2.0.2
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 +112 -0
- package/package.json +1 -1
package/README.md
ADDED
|
@@ -0,0 +1,112 @@
|
|
|
1
|
+
<div align="center">
|
|
2
|
+
|
|
3
|
+
# @skillstate/cli
|
|
4
|
+
|
|
5
|
+
**skillstate CLI — `init | run | report` over the paper-exact runtime, plus a terminal dashboard.**
|
|
6
|
+
|
|
7
|
+
[](https://www.npmjs.com/package/@skillstate/cli)
|
|
8
|
+
[](https://www.npmjs.com/package/@skillstate/cli)
|
|
9
|
+
[](https://github.com/vitalykuzyaev/skillstate)
|
|
10
|
+
[](https://github.com/vitalykuzyaev/skillstate/blob/main/LICENSE)
|
|
11
|
+
|
|
12
|
+
</div>
|
|
13
|
+
|
|
14
|
+
---
|
|
15
|
+
|
|
16
|
+
`@skillstate/cli` is a thin file-orchestration layer over the paper-exact
|
|
17
|
+
runtime ([`@skillstate/core`](../core)): `init` writes a `skillstate.json`
|
|
18
|
+
config plus a spec file, `run` drives a deterministic offline stub LLM (empty
|
|
19
|
+
patch + `noop` action) so the whole `init → run → report` flow works from a
|
|
20
|
+
clean directory with no network, and `report` renders the session metrics as
|
|
21
|
+
JSON or a markdown dashboard.
|
|
22
|
+
|
|
23
|
+
> **@non-paper** — the CLI is an additive Wave-4 DX tool, not part of the
|
|
24
|
+
> paper. Bring your own `LLMFn`/`LLMProvider` (via the library API) for real
|
|
25
|
+
> runs. Units are raw string chars throughout (§4.3).
|
|
26
|
+
|
|
27
|
+
## Installation
|
|
28
|
+
|
|
29
|
+
```bash
|
|
30
|
+
npm i @skillstate/core @skillstate/cli
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
Requires Node.js >= 20. TypeScript types are bundled. Ships the `skillstate`
|
|
34
|
+
bin.
|
|
35
|
+
|
|
36
|
+
## Quick start
|
|
37
|
+
|
|
38
|
+
```bash
|
|
39
|
+
npx skillstate init # creates ./skillstate.json + ./skill-spec.json
|
|
40
|
+
npx skillstate run # runs the offline stub-LLM against the spec
|
|
41
|
+
npx skillstate run --resume # continue from the persisted .skillstate.json
|
|
42
|
+
npx skillstate run --config ./my-config.json
|
|
43
|
+
npx skillstate report # pretty JSON report
|
|
44
|
+
npx skillstate report --format md # markdown dashboard
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
Programmatically:
|
|
48
|
+
|
|
49
|
+
```ts
|
|
50
|
+
import { main, parseRunArgs, parseReportArgs, stubLlmResponse } from '@skillstate/cli';
|
|
51
|
+
|
|
52
|
+
// Exit-code API (0 ok, 1 runtime error, 2 usage error). Never throws for usage.
|
|
53
|
+
const code = await main(['run', '--resume'], process.cwd());
|
|
54
|
+
|
|
55
|
+
const runFlags = parseRunArgs(['--config', './c.json', '--resume']);
|
|
56
|
+
const reportFlags = parseReportArgs(['--format', 'md']);
|
|
57
|
+
|
|
58
|
+
console.log(stubLlmResponse()); // deterministic empty patch + 'noop' action
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
## API / Exports
|
|
62
|
+
|
|
63
|
+
Root path `@skillstate/cli` exports the command layer and the dashboard.
|
|
64
|
+
|
|
65
|
+
**Commands (`commands.ts`):**
|
|
66
|
+
|
|
67
|
+
- `main(argv, cwd?): Promise<number>` — CLI entry; returns a process exit code.
|
|
68
|
+
- `CLI_USAGE` — the usage string.
|
|
69
|
+
- `parseRunArgs(args): RunFlags` — `--config <path>`, `--config=<path>`, `--resume`.
|
|
70
|
+
- `parseReportArgs(args): ReportFlags` — `--format json|md` (default `json`).
|
|
71
|
+
- `wantsHelp(args): boolean` and `HelpRequestedError`.
|
|
72
|
+
- `resolveInCwd(cwd, p): string`.
|
|
73
|
+
- `loadCliConfig(cwd, configPath?): SkillStateConfig`.
|
|
74
|
+
- `loadCliSpec(cwd, specPath): ProceduralSpec` — JSON file or `@intercode-ctf`.
|
|
75
|
+
- `loadResumeState(cwd, statePath): SkillState | null`.
|
|
76
|
+
- `stubLlmResponse(): string`.
|
|
77
|
+
|
|
78
|
+
**Dashboard (`dashboard.ts`):**
|
|
79
|
+
|
|
80
|
+
- `generateReport(input: ReportInput): string` — full markdown report.
|
|
81
|
+
- `printDashboard(input: DashboardInput): string` — terminal dashboard.
|
|
82
|
+
- `formatMetricsTable(metrics): string`, `formatComparisonTable(comparison): string`,
|
|
83
|
+
`formatStepHistory(steps): string`, `formatProgressBar(progress, width?): string`.
|
|
84
|
+
- Types: `DashboardMetrics`, `BaselineComparison`, `SessionInfo`,
|
|
85
|
+
`BudgetProgress`, `ReportInput`, `DashboardInput`.
|
|
86
|
+
|
|
87
|
+
**Bin:** `skillstate` — `init | run | report`.
|
|
88
|
+
|
|
89
|
+
## Notes
|
|
90
|
+
|
|
91
|
+
- `run` uses a **stub LLM** by default (no network, deterministic): each step
|
|
92
|
+
yields an empty `state_patch` and a `noop` action. For a real agent, drive
|
|
93
|
+
`SkillStateRuntime` from [`@skillstate/core`](../core) with your own
|
|
94
|
+
`LLMFn`/`LLMProvider`.
|
|
95
|
+
- Depends on [`@skillstate/core`](../core) for `SkillStateRuntime`,
|
|
96
|
+
`TokenTracker`, `atomicWriteFile`, `migrate`, config loading
|
|
97
|
+
(`defaultConfig`/`loadConfig`/`mergeConfig`), and the builtin
|
|
98
|
+
`INTERCODE_CTF_SPEC`.
|
|
99
|
+
- `report --format md` computes the conversation-baseline comparison from the
|
|
100
|
+
report's per-step `promptChars` (the `TokenTracker.compareWithBaseline`
|
|
101
|
+
model). All units are raw string chars.
|
|
102
|
+
|
|
103
|
+
## Related
|
|
104
|
+
|
|
105
|
+
- Paper: [arXiv:2608.26263](https://arxiv.org/abs/2608.26263).
|
|
106
|
+
- Core runtime: [`@skillstate/core`](../core).
|
|
107
|
+
- [`state.md`](../../state.md) — design notes.
|
|
108
|
+
- Benchmark harness: `@skillstate/bench`.
|
|
109
|
+
|
|
110
|
+
## License
|
|
111
|
+
|
|
112
|
+
[MIT](LICENSE) © 2026 Vitaly Kuzyaev
|