@yolo-labs/yolo-cli 0.23.0

package/dist/plan-validate.js

@@ -0,0 +1,270 @@
+/**
+ * `yolo plan validate` core (Phase 8c.1).
+ *
+ * Pure offline validation of a `.yolo/plans/<slug>.md` plan file. No
+ * network I/O. Three checks, in order:
+ *
+ *   1. **Parse** — file must split cleanly into YAML frontmatter +
+ *      markdown body via the standard `---` delimiters.
+ *   2. **Schema** — frontmatter must satisfy the Draft-07 JSON Schema
+ *      shipped at `src/plan-frontmatter.schema.json` (a copy of the
+ *      repo's `.yolo/plans/.schema.json`; a drift-check test enforces
+ *      they stay byte-equal).
+ *   3. **Canonical** — running the file through `canonicalizePlanFile`
+ *      must return the same bytes. This is the parity that
+ *      `yolo plan import` will rely on, and that 8c.5's CI check
+ *      enforces across all `.yolo/plans/*.md` files in the repo.
+ *
+ * The first failing check short-circuits subsequent ones (a parse
+ * failure makes "schema" / "canonical" meaningless). Successful checks
+ * still run all three and report all errors when the `collectAll`
+ * flag is true (used by tests; the CLI prints the first one).
+ *
+ * Exit codes (used by cli.ts):
+ *   - 0 = valid
+ *   - 1 = validation failure (parse / schema / canonical)
+ *   - 64 = usage error (missing file argument, file not found at path)
+ *
+ * Out of scope (lands in 8c.3 import):
+ *   - planId-vs-filename equality (semantic check; the import command
+ *     enforces it because the file path is the source of truth there).
+ *   - Stricter `name` regex (semantic, Unicode-aware — was deliberately
+ *     dropped from the schema in Phase 8b Round 1 because Draft-07
+ *     pattern doesn't support `\\p{L}`/`\\p{N}` consistently across
+ *     validators).
+ *   - Cross-step / cross-gate semantic checks (gate.requires resolves
+ *     to a sibling step, declaredOutput names unique within a step,
+ *     etc.) — these belong in plan-validators.ts on the server side
+ *     and run at import-time anyway.
+ *
+ * No-coercion rule (Phase 8 contract; Codex 8c.1 Round 1 Medium):
+ *   The Phase 8 design and the canonicalizer's docstring both pin a
+ *   "no boolean/numeric coercion" rule on validate/import. js-yaml's
+ *   default `load` happily coerces unquoted scalars
+ *   (`minPassRate: 0.95` → JS number 0.95). For schema-typed
+ *   positions (PlanInputDecl.required: boolean, autoRetryCap: integer,
+ *   StepDeclaredOutput.required: boolean, etc.) coercion is fine
+ *   because Ajv enforces the declared type. For the free-form maps
+ *   (`gate.config`, `integrationPolicy`) the JSON Schema is
+ *   intentionally `additionalProperties: true` and can't catch silent
+ *   type drift. The `assertStringValuedFreeFormMap` walk below is
+ *   the enforcement point: every leaf in those maps must be a string
+ *   or array of strings, and the user is told to quote the value if
+ *   not.
+ *   (`template.metadata` is already string-locked at the schema level
+ *   via `additionalProperties: { type: string }`, so a coerced int
+ *   there fails Ajv directly — no extra walk needed.)
+ */
+import { readFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+import yaml from 'js-yaml';
+import Ajv from 'ajv';
+import { canonicalizePlanFile } from './canonicalizer.js';
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const SCHEMA_PATH = path.join(__dirname, 'plan-frontmatter.schema.json');
+// Lazy-load + cache: keeps test parallelism cheap. The schema is
+// small (<10 KB), so synchronous read + JSON.parse on first use is
+// fine.
+let cachedSchema;
+function getSchema() {
+    if (!cachedSchema) {
+        cachedSchema = JSON.parse(readFileSync(SCHEMA_PATH, 'utf8'));
+    }
+    return cachedSchema;
+}
+let cachedValidator = null;
+function getValidator() {
+    if (!cachedValidator) {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const ajv = new Ajv({ allErrors: true });
+        cachedValidator = ajv.compile(getSchema());
+    }
+    return cachedValidator;
+}
+const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---\r?\n([\s\S]*)$/;
+/**
+ * Validate the contents of a plan file (already read into memory).
+ * Pure — no fs access; the caller owns reading the file. Used by both
+ * the CLI (`validatePlanFile` wraps a `readFileSync`) and tests
+ * (which feed in synthesized strings).
+ */
+export function validatePlanText(text) {
+    const errors = [];
+    // 1) Parse
+    const match = text.match(FRONTMATTER_RE);
+    if (!match) {
+        return {
+            ok: false,
+            errors: [
+                {
+                    kind: 'parse',
+                    message: 'plan file must start with `---` frontmatter delimiter, contain a closing `---`, and have a body — no match',
+                },
+            ],
+        };
+    }
+    const [, fmText, body] = match;
+    let frontmatter;
+    try {
+        const loaded = yaml.load(fmText);
+        if (loaded === null || typeof loaded !== 'object' || Array.isArray(loaded)) {
+            return {
+                ok: false,
+                errors: [
+                    {
+                        kind: 'parse',
+                        message: 'frontmatter must be a YAML mapping (object), not a list or scalar',
+                    },
+                ],
+            };
+        }
+        frontmatter = loaded;
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return {
+            ok: false,
+            errors: [{ kind: 'parse', message: `YAML parse failed: ${msg}` }],
+        };
+    }
+    // 2) Schema
+    const validate = getValidator();
+    const ok = validate(frontmatter);
+    if (!ok) {
+        const ajvErrors = validate.errors ?? [];
+        for (const err of ajvErrors) {
+            errors.push({
+                kind: 'schema',
+                message: err.message ?? 'schema validation failed',
+                path: err.dataPath || '',
+            });
+        }
+    }
+    // 2b) No-coercion rule on free-form maps. See header comment.
+    if ('integrationPolicy' in frontmatter) {
+        assertStringValuedFreeFormMap(frontmatter.integrationPolicy, '.integrationPolicy', errors);
+    }
+    if (Array.isArray(frontmatter.steps)) {
+        for (let i = 0; i < frontmatter.steps.length; i++) {
+            const step = frontmatter.steps[i];
+            if (!step || !Array.isArray(step.gates))
+                continue;
+            for (let j = 0; j < step.gates.length; j++) {
+                const gate = step.gates[j];
+                if (gate && 'config' in gate) {
+                    assertStringValuedFreeFormMap(gate.config, `.steps[${i}].gates[${j}].config`, errors);
+                }
+            }
+        }
+    }
+    // 3) Canonical
+    // Only meaningful when the parse step succeeded — schema fails
+    // don't preclude canonicalization, so we always run this check too
+    // and the caller gets a complete report.
+    const canonical = canonicalizePlanFile(frontmatter, body);
+    if (canonical !== text) {
+        errors.push({
+            kind: 'canonical',
+            message: 'file is not in canonical form (frontmatter field order / lex-sort / body normalization). Run `yolo plan import` to rewrite, or canonicalize manually.',
+        });
+    }
+    if (errors.length > 0) {
+        return { ok: false, errors };
+    }
+    const planId = typeof frontmatter.planId === 'string' ? frontmatter.planId : '';
+    return { ok: true, planId, bytes: text.length };
+}
+/**
+ * Read a plan file from disk and validate it.
+ *
+ * Throws `ENOENT`-style errors through the caller (cli.ts maps them
+ * to exit code 64 + a friendly message).
+ */
+export function validatePlanFile(filePath) {
+    const text = readFileSync(filePath, 'utf8');
+    return validatePlanText(text);
+}
+/**
+ * Walk a free-form map (gate.config / integrationPolicy) recursively
+ * and reject any non-string LEAF. Phase 8 + the 8b canonicalizer
+ * explicitly support nested mappings/arrays in these positions
+ * (`sortNestedKeys` recurses through them); the no-coercion contract
+ * applies only at the leaves — every terminal value must be a string,
+ * because js-yaml's default load coerces unquoted scalars to JS
+ * booleans/numbers and the JSON Schema's `additionalProperties: true`
+ * can't catch it (Codex 8c.1 Round 1 Medium).
+ *
+ * Recursion rules:
+ *   - object → recurse into each property (path: `.key`).
+ *   - array → recurse into each item (path: `[i]`).
+ *   - string → OK (leaf).
+ *   - anything else (number / boolean / null / undefined) → REJECT.
+ *
+ * The top-level value (gate.config or integrationPolicy itself) MUST
+ * be a mapping; a list or scalar there is also a structural error.
+ *
+ * Error paths use dot/bracket notation matching Ajv's `dataPath` style
+ * so the rendered output stays consistent.
+ */
+function assertStringValuedFreeFormMap(value, pathPrefix, errors) {
+    if (value === undefined)
+        return;
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+        errors.push({
+            kind: 'schema',
+            path: pathPrefix,
+            message: 'free-form map must be a YAML mapping (object), not a list, scalar, or null',
+        });
+        return;
+    }
+    walkLeaves(value, pathPrefix, errors);
+}
+/**
+ * Recursive helper: walk a value of any shape and report non-string
+ * leaves. Used by `assertStringValuedFreeFormMap` once we've confirmed
+ * the outer value is a mapping.
+ */
+function walkLeaves(value, pathPrefix, errors) {
+    if (typeof value === 'string')
+        return;
+    if (Array.isArray(value)) {
+        for (let i = 0; i < value.length; i++) {
+            walkLeaves(value[i], `${pathPrefix}[${i}]`, errors);
+        }
+        return;
+    }
+    if (value !== null && typeof value === 'object') {
+        for (const [key, leaf] of Object.entries(value)) {
+            walkLeaves(leaf, `${pathPrefix}.${key}`, errors);
+        }
+        return;
+    }
+    errors.push({
+        kind: 'schema',
+        path: pathPrefix,
+        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`,
+    });
+}
+function describeJsType(value) {
+    if (value === null)
+        return 'null';
+    if (Array.isArray(value))
+        return 'array';
+    return typeof value;
+}
+/**
+ * Render a `ValidationFail` result as human-readable text for the
+ * CLI. One line per error, with kind tag + optional path. Caller
+ * appends a trailing newline if needed.
+ */
+export function formatErrors(errors) {
+    return errors
+        .map((e) => {
+        const tag = `[${e.kind}]`;
+        const loc = e.path ? ` (at ${e.path})` : '';
+        return `${tag}${loc} ${e.message}`;
+    })
+        .join('\n');
+}

package/dist/revision.js

@@ -0,0 +1,43 @@
+/**
+ * Plan-file revision hash (Phase 8c.2).
+ *
+ * The lockfile records a `lastImportedRevision` for each
+ * `(workspaceId, planId)` so re-import can detect divergence: if the
+ * file's current canonical bytes hash to the same revision as the
+ * lockfile entry's `lastImportedRevision`, the file hasn't changed
+ * since the last import (no-op or version bump only). If the hash
+ * differs, the user actually edited the file — and `import` then
+ * compares the lockfile's `lastImportedVersion` against the DB's
+ * current `version` to decide whether to fast-forward
+ * (`work.update_plan`) or refuse (without `--force`).
+ *
+ * Hash domain: the **canonical** bytes of the plan file
+ * (frontmatter + body, post-`canonicalizePlanFile`). Hashing the raw
+ * input bytes would mean cosmetic re-formatting (whitespace, key
+ * order) shows up as drift; using the canonical form means only
+ * semantic edits register.
+ *
+ * Format: `sha256:<hex>` per the design doc strawman
+ * (`docs/_ORCHESTRATION_PHASE8_PLAN_FILES_DESIGN.md` §"Plan ID
+ * identity"). The `sha256:` prefix is intentional: it leaves room for
+ * a future algorithm bump (e.g., `blake3:…`) without re-keying old
+ * entries.
+ */
+import { createHash } from 'node:crypto';
+export const REVISION_PREFIX = 'sha256:';
+/**
+ * Compute the lockfile revision hash for a canonical plan-file string.
+ * Pure: same input → same output.
+ */
+export function computeRevisionHash(canonicalText) {
+    const digest = createHash('sha256').update(canonicalText, 'utf8').digest('hex');
+    return `${REVISION_PREFIX}${digest}`;
+}
+/**
+ * True if `revision` is well-formed (matches the `sha256:<64-hex>`
+ * shape this version emits). Used by lockfile-read code to flag
+ * malformed entries up front rather than letting them propagate.
+ */
+export function isWellFormedRevision(revision) {
+    return /^sha256:[0-9a-f]{64}$/.test(revision);
+}

package/dist/run-get.js

@@ -0,0 +1,130 @@
+/**
+ * `yolo run get <runId>` — read a Plan Run from the substrate.
+ *
+ * Mints a session-bound delegated token (work.get_run scope) and
+ * GETs `/internal/work/workspaces/<wsId>/runs/<planRunId>`. Prints
+ * a human-readable summary by default; `--json` for the raw response
+ * (useful for jq pipelines).
+ *
+ * No file I/O, no lockfile mutation. Pure read.
+ *
+ * Errors map to exit codes via the CLI wrapper:
+ *   - 0  = success
+ *   - 1  = http (run not found, etc.)
+ *   - 64 = usage (bad runId, missing env trio, --workspace mismatch)
+ */
+import { SUBSTRATE_CLI_RUN_SCOPES, WorkClientError, authenticatedRequest, mintSubstrateToken, } from './work-client.js';
+import { resolveSubstrateContext } from './auth-context.js';
+// ─── Public entry ─────────────────────────────────────────────────────────
+const PLAN_RUN_ID_REGEX = /^[a-zA-Z0-9][a-zA-Z0-9_-]{0,191}$/;
+export async function runRunGet(options) {
+    const env = options.env ?? process.env;
+    const format = options.outputFormat ?? 'summary';
+    if (!PLAN_RUN_ID_REGEX.test(options.planRunId)) {
+        return fail('usage', `invalid planRunId '${options.planRunId}': must match /^[a-zA-Z0-9][a-zA-Z0-9_-]{0,191}$/`);
+    }
+    const auth = resolveSubstrateContext(env);
+    if (!auth.ok)
+        return fail('auth', auth.message);
+    const { sessionId, commonApiUrl, userToken } = auth.context;
+    let mint;
+    try {
+        mint = await mintSubstrateToken({
+            commonApiUrl,
+            userToken,
+            sessionId,
+            scopes: SUBSTRATE_CLI_RUN_SCOPES,
+            fetchImpl: options.fetchImpl,
+        });
+    }
+    catch (err) {
+        if (err instanceof WorkClientError) {
+            return fail('auth', `failed to mint substrate token: ${err.message}`, { status: err.status, code: err.code });
+        }
+        return fail('auth', `failed to mint substrate token: ${describeError(err)}`);
+    }
+    if (options.workspaceFlag && options.workspaceFlag !== mint.workspaceId) {
+        return fail('workspace_mismatch', `--workspace ${options.workspaceFlag} does not match the workspace bound to this session (${mint.workspaceId}).`);
+    }
+    const ctx = {
+        commonApiUrl,
+        delegatedToken: mint.token,
+        fetchImpl: options.fetchImpl,
+    };
+    const response = await authenticatedRequest(ctx, `/workspaces/${mint.workspaceId}/runs/${options.planRunId}`, { method: 'GET' });
+    if (!response.ok) {
+        const text = await safeReadText(response);
+        return fail('http', `work.get_run failed: HTTP ${response.status} — ${text}`, { status: response.status });
+    }
+    const json = (await response.json());
+    if (!json.run) {
+        return fail('http', 'work.get_run response missing `run` field');
+    }
+    return {
+        ok: true,
+        output: format === 'json' ? formatJson(json.run) : formatSummary(json.run, mint.workspaceId),
+        run: json.run,
+        workspaceId: mint.workspaceId,
+    };
+}
+// ─── Output formatting ────────────────────────────────────────────────────
+/**
+ * Header + per-step table. Table columns auto-size to the longest
+ * stepId / state / stepRunId / tileId so output stays aligned even
+ * for plans with mixed-width identifiers.
+ */
+export function formatSummary(run, workspaceId) {
+    const lines = [];
+    lines.push(`Plan Run ${run.planRunId} (workspace ${workspaceId}, run #${run.runNumber}, plan ${run.planId} v${run.planVersion}, executionState=${run.executionState})`);
+    const operatorTag = run.operatorAgentId
+        ? `${run.operatorAgentId}${run.operatorResponsive === false ? ' (unresponsive)' : run.operatorResponsive === true ? ' (responsive)' : ''}`
+        : '(unbound)';
+    lines.push(`  operator: ${operatorTag}`);
+    if (run.startedAt)
+        lines.push(`  startedAt: ${run.startedAt}`);
+    if (run.endedAt)
+        lines.push(`  endedAt:   ${run.endedAt}`);
+    const inputCount = run.inputs ? Object.keys(run.inputs).length : 0;
+    if (inputCount > 0)
+        lines.push(`  inputs: ${inputCount}`);
+    lines.push(`  steps: ${run.steps.length}`);
+    if (run.steps.length === 0)
+        return lines.join('\n');
+    const stepIdW = Math.max(6, ...run.steps.map((s) => s.stepId.length));
+    const stateW = Math.max(5, ...run.steps.map((s) => s.state.length));
+    const stepRunW = Math.max(8, ...run.steps.map((s) => (s.latestStepRunId ?? '—').length));
+    for (const step of run.steps) {
+        const stepRun = step.latestStepRunId ?? '—';
+        const tile = step.tileId ?? '—';
+        lines.push(`    - ${step.stepId.padEnd(stepIdW)}  ${step.state.padEnd(stateW)}  ${stepRun.padEnd(stepRunW)}  ${tile}`);
+    }
+    return lines.join('\n');
+}
+function formatJson(run) {
+    return JSON.stringify(run, null, 2);
+}
+// ─── Helpers ──────────────────────────────────────────────────────────────
+function fail(kind, message, detail) {
+    return { ok: false, kind, message, detail };
+}
+function describeError(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+async function safeReadText(response) {
+    try {
+        return await response.text();
+    }
+    catch {
+        return '<no body>';
+    }
+}
+export function exitCodeForFailure(kind) {
+    switch (kind) {
+        case 'usage':
+        case 'auth':
+        case 'workspace_mismatch':
+            return 64;
+        case 'http':
+            return 1;
+    }
+}

package/dist/run-lifecycle.js

@@ -0,0 +1,133 @@
+/**
+ * `yolo run pause / resume / cancel <runId>` — lifecycle transitions.
+ *
+ * The three verbs share a single runner because the routes share a
+ * single transition handler on the server (common-api/src/routes/
+ * workspaces.ts:transitionPlanRunForUser). They differ only in
+ * target state, valid source states, and whether they accept a
+ * `--reason`.
+ *
+ * Auth model: hits the user-facing route at
+ * `/v1/workspaces/:id/runs/:planRunId/{verb}` via X-Internal-Auth +
+ * X-User-Id (the substrate CLI is by definition invoked by the
+ * workspace owner — operating as them is the right default). The
+ * user route checks workspace ownership only and skips R4 operator
+ * binding, so this works regardless of which agent (if any) is
+ * bound to the run.
+ *
+ * Why not the MCP path: that path's R4 binding makes sense for
+ * agent-to-agent calls (claude pausing its own run) but produces
+ * 403 NOT_AUTHORIZED whenever the user wants to cancel a run owned
+ * by a different agent or by the webapp launcher. Forcing the user
+ * to know which side of that fence they're on is bad UX. The CLI
+ * decides automatically.
+ *
+ * Errors map to exit codes via the CLI wrapper:
+ *   - 0  = success
+ *   - 1  = http (404, 409 INVALID_STATE, 5xx)
+ *   - 64 = usage (bad runId, missing env trio, --workspace mismatch,
+ *          reason too long pre-network, bad target verb)
+ */
+import { SUBSTRATE_CLI_RUN_SCOPES, WorkClientError, mintSubstrateToken, userRouteRequest, } from './work-client.js';
+import { resolveSubstrateContext } from './auth-context.js';
+// ─── Public entry ─────────────────────────────────────────────────────────
+const PLAN_RUN_ID_REGEX = /^[a-zA-Z0-9][a-zA-Z0-9_-]{0,191}$/;
+const REASON_MAX_LEN = 1024;
+export async function runRunLifecycle(options) {
+    const env = options.env ?? process.env;
+    const format = options.outputFormat ?? 'summary';
+    if (options.verb !== 'pause' && options.verb !== 'resume' && options.verb !== 'cancel') {
+        return fail('usage', `unknown verb '${options.verb}': must be pause, resume, or cancel`);
+    }
+    if (!PLAN_RUN_ID_REGEX.test(options.planRunId)) {
+        return fail('usage', `invalid planRunId '${options.planRunId}': must match /^[a-zA-Z0-9][a-zA-Z0-9_-]{0,191}$/`);
+    }
+    if (options.reason !== undefined) {
+        if (typeof options.reason !== 'string' || options.reason.length > REASON_MAX_LEN) {
+            return fail('usage', `--reason must be a string of at most ${REASON_MAX_LEN} chars`);
+        }
+        if (options.verb === 'resume') {
+            return fail('usage', '--reason is not accepted by `run resume`');
+        }
+    }
+    const auth = resolveSubstrateContext(env);
+    if (!auth.ok)
+        return fail('auth', auth.message);
+    const { sessionId, commonApiUrl, userToken } = auth.context;
+    let mint;
+    try {
+        mint = await mintSubstrateToken({
+            commonApiUrl,
+            userToken,
+            sessionId,
+            scopes: SUBSTRATE_CLI_RUN_SCOPES,
+            fetchImpl: options.fetchImpl,
+        });
+    }
+    catch (err) {
+        if (err instanceof WorkClientError) {
+            return fail('auth', `failed to mint substrate token: ${err.message}`, { status: err.status, code: err.code });
+        }
+        return fail('auth', `failed to mint substrate token: ${describeError(err)}`);
+    }
+    if (options.workspaceFlag && options.workspaceFlag !== mint.workspaceId) {
+        return fail('workspace_mismatch', `--workspace ${options.workspaceFlag} does not match the workspace bound to this session (${mint.workspaceId}).`);
+    }
+    const body = {};
+    if (options.reason !== undefined && options.verb !== 'resume') {
+        body.reason = options.reason;
+    }
+    const path = `/workspaces/${mint.workspaceId}/runs/${options.planRunId}/${options.verb}`;
+    const response = await userRouteRequest({
+        commonApiUrl,
+        userToken,
+        fetchImpl: options.fetchImpl,
+    }, path, { method: 'POST', jsonBody: body });
+    if (!response.ok) {
+        const text = await safeReadText(response);
+        return fail('http', `work.${options.verb}_run failed: HTTP ${response.status} — ${text}`, { status: response.status });
+    }
+    const json = (await response.json());
+    if (typeof json.planRunId !== 'string' || typeof json.executionState !== 'string') {
+        return fail('http', `work.${options.verb}_run response missing planRunId or executionState`);
+    }
+    return {
+        ok: true,
+        output: format === 'json' ? formatJson(json) : formatSummary(options.verb, json),
+        response: json,
+        workspaceId: mint.workspaceId,
+    };
+}
+// ─── Output formatting ────────────────────────────────────────────────────
+export function formatSummary(verb, response) {
+    const past = verb === 'pause' ? 'paused' : verb === 'resume' ? 'resumed' : 'cancelled';
+    return `OK: ${past} run ${response.planRunId} (executionState=${response.executionState})`;
+}
+function formatJson(response) {
+    return JSON.stringify(response, null, 2);
+}
+// ─── Helpers ──────────────────────────────────────────────────────────────
+function fail(kind, message, detail) {
+    return { ok: false, kind, message, detail };
+}
+function describeError(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+async function safeReadText(response) {
+    try {
+        return await response.text();
+    }
+    catch {
+        return '<no body>';
+    }
+}
+export function exitCodeForFailure(kind) {
+    switch (kind) {
+        case 'usage':
+        case 'auth':
+        case 'workspace_mismatch':
+            return 64;
+        case 'http':
+            return 1;
+    }
+}