@yolo-labs/yolo-cli 0.43.0 → 0.44.1

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.
@@ -1,270 +0,0 @@
1
- /**
2
- * `yolo plan validate` core (Phase 8c.1).
3
- *
4
- * Pure offline validation of a `.yolo/plans/<slug>.md` plan file. No
5
- * network I/O. Three checks, in order:
6
- *
7
- * 1. **Parse** — file must split cleanly into YAML frontmatter +
8
- * markdown body via the standard `---` delimiters.
9
- * 2. **Schema** — frontmatter must satisfy the Draft-07 JSON Schema
10
- * shipped at `src/plan-frontmatter.schema.json` (a copy of the
11
- * repo's `.yolo/plans/.schema.json`; a drift-check test enforces
12
- * they stay byte-equal).
13
- * 3. **Canonical** — running the file through `canonicalizePlanFile`
14
- * must return the same bytes. This is the parity that
15
- * `yolo plan import` will rely on, and that 8c.5's CI check
16
- * enforces across all `.yolo/plans/*.md` files in the repo.
17
- *
18
- * The first failing check short-circuits subsequent ones (a parse
19
- * failure makes "schema" / "canonical" meaningless). Successful checks
20
- * still run all three and report all errors when the `collectAll`
21
- * flag is true (used by tests; the CLI prints the first one).
22
- *
23
- * Exit codes (used by cli.ts):
24
- * - 0 = valid
25
- * - 1 = validation failure (parse / schema / canonical)
26
- * - 64 = usage error (missing file argument, file not found at path)
27
- *
28
- * Out of scope (lands in 8c.3 import):
29
- * - planId-vs-filename equality (semantic check; the import command
30
- * enforces it because the file path is the source of truth there).
31
- * - Stricter `name` regex (semantic, Unicode-aware — was deliberately
32
- * dropped from the schema in Phase 8b Round 1 because Draft-07
33
- * pattern doesn't support `\\p{L}`/`\\p{N}` consistently across
34
- * validators).
35
- * - Cross-step / cross-gate semantic checks (gate.requires resolves
36
- * to a sibling step, declaredOutput names unique within a step,
37
- * etc.) — these belong in plan-validators.ts on the server side
38
- * and run at import-time anyway.
39
- *
40
- * No-coercion rule (Phase 8 contract; Codex 8c.1 Round 1 Medium):
41
- * The Phase 8 design and the canonicalizer's docstring both pin a
42
- * "no boolean/numeric coercion" rule on validate/import. js-yaml's
43
- * default `load` happily coerces unquoted scalars
44
- * (`minPassRate: 0.95` → JS number 0.95). For schema-typed
45
- * positions (PlanInputDecl.required: boolean, autoRetryCap: integer,
46
- * StepDeclaredOutput.required: boolean, etc.) coercion is fine
47
- * because Ajv enforces the declared type. For the free-form maps
48
- * (`gate.config`, `integrationPolicy`) the JSON Schema is
49
- * intentionally `additionalProperties: true` and can't catch silent
50
- * type drift. The `assertStringValuedFreeFormMap` walk below is
51
- * the enforcement point: every leaf in those maps must be a string
52
- * or array of strings, and the user is told to quote the value if
53
- * not.
54
- * (`template.metadata` is already string-locked at the schema level
55
- * via `additionalProperties: { type: string }`, so a coerced int
56
- * there fails Ajv directly — no extra walk needed.)
57
- */
58
- import { readFileSync } from 'node:fs';
59
- import { dirname } from 'node:path';
60
- import { fileURLToPath } from 'node:url';
61
- import path from 'node:path';
62
- import yaml from 'js-yaml';
63
- import Ajv from 'ajv';
64
- import { canonicalizePlanFile } from './canonicalizer.js';
65
- const __dirname = dirname(fileURLToPath(import.meta.url));
66
- const SCHEMA_PATH = path.join(__dirname, 'plan-frontmatter.schema.json');
67
- // Lazy-load + cache: keeps test parallelism cheap. The schema is
68
- // small (<10 KB), so synchronous read + JSON.parse on first use is
69
- // fine.
70
- let cachedSchema;
71
- function getSchema() {
72
- if (!cachedSchema) {
73
- cachedSchema = JSON.parse(readFileSync(SCHEMA_PATH, 'utf8'));
74
- }
75
- return cachedSchema;
76
- }
77
- let cachedValidator = null;
78
- function getValidator() {
79
- if (!cachedValidator) {
80
- // eslint-disable-next-line @typescript-eslint/no-explicit-any
81
- const ajv = new Ajv({ allErrors: true });
82
- cachedValidator = ajv.compile(getSchema());
83
- }
84
- return cachedValidator;
85
- }
86
- const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---\r?\n([\s\S]*)$/;
87
- /**
88
- * Validate the contents of a plan file (already read into memory).
89
- * Pure — no fs access; the caller owns reading the file. Used by both
90
- * the CLI (`validatePlanFile` wraps a `readFileSync`) and tests
91
- * (which feed in synthesized strings).
92
- */
93
- export function validatePlanText(text) {
94
- const errors = [];
95
- // 1) Parse
96
- const match = text.match(FRONTMATTER_RE);
97
- if (!match) {
98
- return {
99
- ok: false,
100
- errors: [
101
- {
102
- kind: 'parse',
103
- message: 'plan file must start with `---` frontmatter delimiter, contain a closing `---`, and have a body — no match',
104
- },
105
- ],
106
- };
107
- }
108
- const [, fmText, body] = match;
109
- let frontmatter;
110
- try {
111
- const loaded = yaml.load(fmText);
112
- if (loaded === null || typeof loaded !== 'object' || Array.isArray(loaded)) {
113
- return {
114
- ok: false,
115
- errors: [
116
- {
117
- kind: 'parse',
118
- message: 'frontmatter must be a YAML mapping (object), not a list or scalar',
119
- },
120
- ],
121
- };
122
- }
123
- frontmatter = loaded;
124
- }
125
- catch (err) {
126
- const msg = err instanceof Error ? err.message : String(err);
127
- return {
128
- ok: false,
129
- errors: [{ kind: 'parse', message: `YAML parse failed: ${msg}` }],
130
- };
131
- }
132
- // 2) Schema
133
- const validate = getValidator();
134
- const ok = validate(frontmatter);
135
- if (!ok) {
136
- const ajvErrors = validate.errors ?? [];
137
- for (const err of ajvErrors) {
138
- errors.push({
139
- kind: 'schema',
140
- message: err.message ?? 'schema validation failed',
141
- path: err.dataPath || '',
142
- });
143
- }
144
- }
145
- // 2b) No-coercion rule on free-form maps. See header comment.
146
- if ('integrationPolicy' in frontmatter) {
147
- assertStringValuedFreeFormMap(frontmatter.integrationPolicy, '.integrationPolicy', errors);
148
- }
149
- if (Array.isArray(frontmatter.steps)) {
150
- for (let i = 0; i < frontmatter.steps.length; i++) {
151
- const step = frontmatter.steps[i];
152
- if (!step || !Array.isArray(step.gates))
153
- continue;
154
- for (let j = 0; j < step.gates.length; j++) {
155
- const gate = step.gates[j];
156
- if (gate && 'config' in gate) {
157
- assertStringValuedFreeFormMap(gate.config, `.steps[${i}].gates[${j}].config`, errors);
158
- }
159
- }
160
- }
161
- }
162
- // 3) Canonical
163
- // Only meaningful when the parse step succeeded — schema fails
164
- // don't preclude canonicalization, so we always run this check too
165
- // and the caller gets a complete report.
166
- const canonical = canonicalizePlanFile(frontmatter, body);
167
- if (canonical !== text) {
168
- errors.push({
169
- kind: 'canonical',
170
- message: 'file is not in canonical form (frontmatter field order / lex-sort / body normalization). Run `yolo plan import` to rewrite, or canonicalize manually.',
171
- });
172
- }
173
- if (errors.length > 0) {
174
- return { ok: false, errors };
175
- }
176
- const planId = typeof frontmatter.planId === 'string' ? frontmatter.planId : '';
177
- return { ok: true, planId, bytes: text.length };
178
- }
179
- /**
180
- * Read a plan file from disk and validate it.
181
- *
182
- * Throws `ENOENT`-style errors through the caller (cli.ts maps them
183
- * to exit code 64 + a friendly message).
184
- */
185
- export function validatePlanFile(filePath) {
186
- const text = readFileSync(filePath, 'utf8');
187
- return validatePlanText(text);
188
- }
189
- /**
190
- * Walk a free-form map (gate.config / integrationPolicy) recursively
191
- * and reject any non-string LEAF. Phase 8 + the 8b canonicalizer
192
- * explicitly support nested mappings/arrays in these positions
193
- * (`sortNestedKeys` recurses through them); the no-coercion contract
194
- * applies only at the leaves — every terminal value must be a string,
195
- * because js-yaml's default load coerces unquoted scalars to JS
196
- * booleans/numbers and the JSON Schema's `additionalProperties: true`
197
- * can't catch it (Codex 8c.1 Round 1 Medium).
198
- *
199
- * Recursion rules:
200
- * - object → recurse into each property (path: `.key`).
201
- * - array → recurse into each item (path: `[i]`).
202
- * - string → OK (leaf).
203
- * - anything else (number / boolean / null / undefined) → REJECT.
204
- *
205
- * The top-level value (gate.config or integrationPolicy itself) MUST
206
- * be a mapping; a list or scalar there is also a structural error.
207
- *
208
- * Error paths use dot/bracket notation matching Ajv's `dataPath` style
209
- * so the rendered output stays consistent.
210
- */
211
- function assertStringValuedFreeFormMap(value, pathPrefix, errors) {
212
- if (value === undefined)
213
- return;
214
- if (value === null || typeof value !== 'object' || Array.isArray(value)) {
215
- errors.push({
216
- kind: 'schema',
217
- path: pathPrefix,
218
- message: 'free-form map must be a YAML mapping (object), not a list, scalar, or null',
219
- });
220
- return;
221
- }
222
- walkLeaves(value, pathPrefix, errors);
223
- }
224
- /**
225
- * Recursive helper: walk a value of any shape and report non-string
226
- * leaves. Used by `assertStringValuedFreeFormMap` once we've confirmed
227
- * the outer value is a mapping.
228
- */
229
- function walkLeaves(value, pathPrefix, errors) {
230
- if (typeof value === 'string')
231
- return;
232
- if (Array.isArray(value)) {
233
- for (let i = 0; i < value.length; i++) {
234
- walkLeaves(value[i], `${pathPrefix}[${i}]`, errors);
235
- }
236
- return;
237
- }
238
- if (value !== null && typeof value === 'object') {
239
- for (const [key, leaf] of Object.entries(value)) {
240
- walkLeaves(leaf, `${pathPrefix}.${key}`, errors);
241
- }
242
- return;
243
- }
244
- errors.push({
245
- kind: 'schema',
246
- path: pathPrefix,
247
- message: `value must be a string (got ${describeJsType(value)}). YAML scalar coercion is disallowed in free-form config maps; quote the value explicitly to keep it as a string`,
248
- });
249
- }
250
- function describeJsType(value) {
251
- if (value === null)
252
- return 'null';
253
- if (Array.isArray(value))
254
- return 'array';
255
- return typeof value;
256
- }
257
- /**
258
- * Render a `ValidationFail` result as human-readable text for the
259
- * CLI. One line per error, with kind tag + optional path. Caller
260
- * appends a trailing newline if needed.
261
- */
262
- export function formatErrors(errors) {
263
- return errors
264
- .map((e) => {
265
- const tag = `[${e.kind}]`;
266
- const loc = e.path ? ` (at ${e.path})` : '';
267
- return `${tag}${loc} ${e.message}`;
268
- })
269
- .join('\n');
270
- }
package/dist/revision.js DELETED
@@ -1,43 +0,0 @@
1
- /**
2
- * Plan-file revision hash (Phase 8c.2).
3
- *
4
- * The lockfile records a `lastImportedRevision` for each
5
- * `(workspaceId, planId)` so re-import can detect divergence: if the
6
- * file's current canonical bytes hash to the same revision as the
7
- * lockfile entry's `lastImportedRevision`, the file hasn't changed
8
- * since the last import (no-op or version bump only). If the hash
9
- * differs, the user actually edited the file — and `import` then
10
- * compares the lockfile's `lastImportedVersion` against the DB's
11
- * current `version` to decide whether to fast-forward
12
- * (`work.update_plan`) or refuse (without `--force`).
13
- *
14
- * Hash domain: the **canonical** bytes of the plan file
15
- * (frontmatter + body, post-`canonicalizePlanFile`). Hashing the raw
16
- * input bytes would mean cosmetic re-formatting (whitespace, key
17
- * order) shows up as drift; using the canonical form means only
18
- * semantic edits register.
19
- *
20
- * Format: `sha256:<hex>` per the design doc strawman
21
- * (`docs/_ORCHESTRATION_PHASE8_PLAN_FILES_DESIGN.md` §"Plan ID
22
- * identity"). The `sha256:` prefix is intentional: it leaves room for
23
- * a future algorithm bump (e.g., `blake3:…`) without re-keying old
24
- * entries.
25
- */
26
- import { createHash } from 'node:crypto';
27
- export const REVISION_PREFIX = 'sha256:';
28
- /**
29
- * Compute the lockfile revision hash for a canonical plan-file string.
30
- * Pure: same input → same output.
31
- */
32
- export function computeRevisionHash(canonicalText) {
33
- const digest = createHash('sha256').update(canonicalText, 'utf8').digest('hex');
34
- return `${REVISION_PREFIX}${digest}`;
35
- }
36
- /**
37
- * True if `revision` is well-formed (matches the `sha256:<64-hex>`
38
- * shape this version emits). Used by lockfile-read code to flag
39
- * malformed entries up front rather than letting them propagate.
40
- */
41
- export function isWellFormedRevision(revision) {
42
- return /^sha256:[0-9a-f]{64}$/.test(revision);
43
- }
package/dist/run-list.js DELETED
@@ -1,148 +0,0 @@
1
- /**
2
- * `yolo run list` — list Plan Runs in the current workspace.
3
- *
4
- * Read companion to the run lifecycle slice. After starting/transitioning
5
- * runs, an operator wants a "what runs are in this workspace?" view
6
- * without remembering planRunIds. Maps to `work.list_runs` (added on
7
- * the server side as part of this slice).
8
- *
9
- * Two output modes:
10
- * - default (`--summary`): one row per run with planRunId, planId,
11
- * run #, executionState, operator, startedAt.
12
- * - `--json`: pretty-printed raw `runs[]` for jq pipelines.
13
- *
14
- * Filter: `--state <pending|running|paused|succeeded|failed|cancelled|superseded>`
15
- * passed as `?executionState=` query string for server-side filtering.
16
- *
17
- * Exit codes:
18
- * - 0 = success (zero runs is also success — empty list, not an error)
19
- * - 1 = http (e.g., 401 from a revoked token)
20
- * - 64 = usage (bad --state, missing env, --workspace mismatch)
21
- */
22
- import { SUBSTRATE_CLI_RUN_SCOPES, WorkClientError, authenticatedRequest, mintSubstrateToken, } from './work-client.js';
23
- import { resolveSubstrateContext } from './auth-context.js';
24
- const ALLOWED_STATES = [
25
- 'pending',
26
- 'running',
27
- 'paused',
28
- 'succeeded',
29
- 'failed',
30
- 'cancelled',
31
- 'superseded',
32
- ];
33
- // ─── Public entry ─────────────────────────────────────────────────────────
34
- export async function runRunList(options) {
35
- const env = options.env ?? process.env;
36
- const format = options.outputFormat ?? 'summary';
37
- if (options.stateFilter !== undefined && !ALLOWED_STATES.includes(options.stateFilter)) {
38
- return fail('usage', `invalid --state '${options.stateFilter}': must be one of ${ALLOWED_STATES.join(', ')}`);
39
- }
40
- const auth = resolveSubstrateContext(env);
41
- if (!auth.ok)
42
- return fail('auth', auth.message);
43
- const { sessionId, commonApiUrl, userToken } = auth.context;
44
- let mint;
45
- try {
46
- mint = await mintSubstrateToken({
47
- commonApiUrl,
48
- userToken,
49
- sessionId,
50
- scopes: SUBSTRATE_CLI_RUN_SCOPES,
51
- fetchImpl: options.fetchImpl,
52
- });
53
- }
54
- catch (err) {
55
- if (err instanceof WorkClientError) {
56
- return fail('auth', `failed to mint substrate token: ${err.message}`, { status: err.status, code: err.code });
57
- }
58
- return fail('auth', `failed to mint substrate token: ${describeError(err)}`);
59
- }
60
- if (options.workspaceFlag && options.workspaceFlag !== mint.workspaceId) {
61
- return fail('workspace_mismatch', `--workspace ${options.workspaceFlag} does not match the workspace bound to this session (${mint.workspaceId}).`);
62
- }
63
- const ctx = {
64
- commonApiUrl,
65
- delegatedToken: mint.token,
66
- fetchImpl: options.fetchImpl,
67
- };
68
- const path = options.stateFilter
69
- ? `/workspaces/${mint.workspaceId}/runs?executionState=${options.stateFilter}`
70
- : `/workspaces/${mint.workspaceId}/runs`;
71
- const response = await authenticatedRequest(ctx, path, { method: 'GET' });
72
- if (!response.ok) {
73
- const text = await safeReadText(response);
74
- return fail('http', `work.list_runs failed: HTTP ${response.status} — ${text}`, {
75
- status: response.status,
76
- });
77
- }
78
- const json = (await response.json());
79
- if (!Array.isArray(json.runs)) {
80
- return fail('http', 'work.list_runs response missing `runs` array');
81
- }
82
- return {
83
- ok: true,
84
- output: format === 'json'
85
- ? formatJson(json.runs)
86
- : formatSummary(json.runs, mint.workspaceId, options.stateFilter),
87
- runs: json.runs,
88
- workspaceId: mint.workspaceId,
89
- };
90
- }
91
- // ─── Output formatting ────────────────────────────────────────────────────
92
- /**
93
- * Header + one row per run. Columns (auto-padded):
94
- * planRunId planId #N state operator startedAt
95
- * Empty list renders "(no runs)" instead of just a header.
96
- */
97
- export function formatSummary(runs, workspaceId, stateFilter) {
98
- const lines = [];
99
- const filterTag = stateFilter ? ` (filter: ${stateFilter})` : '';
100
- lines.push(`Plan Runs in workspace ${workspaceId}${filterTag}: ${runs.length}`);
101
- if (runs.length === 0) {
102
- lines.push(' (no runs)');
103
- return lines.join('\n');
104
- }
105
- const idCol = Math.max(9, ...runs.map((r) => r.planRunId.length));
106
- const planCol = Math.max(6, ...runs.map((r) => r.planId.length));
107
- const stateCol = Math.max(5, ...runs.map((r) => r.executionState.length));
108
- const operatorCol = Math.max(8, ...runs.map((r) => (r.operatorAgentId ?? '(unbound)').length));
109
- const header = ` ${'planRunId'.padEnd(idCol)} ${'planId'.padEnd(planCol)} run# ${'state'.padEnd(stateCol)} ${'operator'.padEnd(operatorCol)} startedAt`;
110
- lines.push(header);
111
- for (const r of runs) {
112
- const id = r.planRunId.padEnd(idCol);
113
- const plan = r.planId.padEnd(planCol);
114
- const runNum = `#${r.runNumber}`.padEnd(5);
115
- const state = r.executionState.padEnd(stateCol);
116
- const operator = (r.operatorAgentId ?? '(unbound)').padEnd(operatorCol);
117
- lines.push(` ${id} ${plan} ${runNum} ${state} ${operator} ${r.startedAt}`);
118
- }
119
- return lines.join('\n');
120
- }
121
- function formatJson(runs) {
122
- return JSON.stringify(runs, null, 2);
123
- }
124
- // ─── Helpers ──────────────────────────────────────────────────────────────
125
- function fail(kind, message, detail) {
126
- return { ok: false, kind, message, detail };
127
- }
128
- function describeError(err) {
129
- return err instanceof Error ? err.message : String(err);
130
- }
131
- async function safeReadText(response) {
132
- try {
133
- return await response.text();
134
- }
135
- catch {
136
- return '<no body>';
137
- }
138
- }
139
- export function exitCodeForFailure(kind) {
140
- switch (kind) {
141
- case 'usage':
142
- case 'auth':
143
- case 'workspace_mismatch':
144
- return 64;
145
- case 'http':
146
- return 1;
147
- }
148
- }
@@ -1,61 +0,0 @@
1
- /**
2
- * Webapp URL derivation for CLI link-print.
3
- *
4
- * The substrate CLI runs in a container that has `YOLO_COMMON_API_URL`
5
- * but no first-class webapp URL var. To keep `yolo plan import` / `yolo
6
- * plan get` able to print a clickable Plan-DAG link without requiring
7
- * operators to set a new env var, derive the webapp host from the
8
- * common-api host: prod is `api.yolo.studio` → `yolo.studio`, staging
9
- * is `api-staging.yolo.studio` → `staging.yolo.studio`. Operators can
10
- * override via `YOLO_WEBAPP_URL` for local dev / custom deployments.
11
- *
12
- * When derivation fails (an unrecognized API URL shape, e.g. a raw
13
- * localhost port), `deriveWebappUrl` returns null and the caller is
14
- * expected to skip the URL line — printing a bogus URL would be worse
15
- * than printing nothing.
16
- */
17
- export function deriveWebappUrl(input) {
18
- if (input.webappUrlOverride && input.webappUrlOverride.length > 0) {
19
- return stripTrailingSlash(input.webappUrlOverride);
20
- }
21
- let parsed;
22
- try {
23
- parsed = new URL(input.commonApiUrl);
24
- }
25
- catch {
26
- return null;
27
- }
28
- const host = parsed.hostname;
29
- // Recognized prod shape: api.<rest> → <rest>
30
- if (host.startsWith('api.')) {
31
- return `${parsed.protocol}//${host.slice('api.'.length)}`;
32
- }
33
- // Recognized env-suffixed shape: api-<env>.<rest> → <env>.<rest>
34
- const envMatch = /^api-([^.]+)\.(.+)$/.exec(host);
35
- if (envMatch) {
36
- return `${parsed.protocol}//${envMatch[1]}.${envMatch[2]}`;
37
- }
38
- // Unknown shape (raw localhost, IPs, custom hosts). Don't guess.
39
- return null;
40
- }
41
- /**
42
- * Convenience for the CLI flows: derive the webapp URL from
43
- * `process.env`-style inputs and format the Plan-DAG path. Returns
44
- * null when derivation fails so the caller can omit the URL line
45
- * entirely.
46
- */
47
- export function planDagUrl(env, workspaceId, planId) {
48
- const commonApiUrl = env.YOLO_COMMON_API_URL || env.YOLO_API_URL;
49
- if (!commonApiUrl)
50
- return null;
51
- const base = deriveWebappUrl({
52
- commonApiUrl,
53
- webappUrlOverride: env.YOLO_WEBAPP_URL,
54
- });
55
- if (!base)
56
- return null;
57
- return `${base}/workspaces/${workspaceId}/plans/${planId}`;
58
- }
59
- function stripTrailingSlash(s) {
60
- return s.endsWith('/') ? s.slice(0, -1) : s;
61
- }