@yolo-labs/yolo-cli 0.23.0

package/dist/plan-list.js

@@ -0,0 +1,153 @@
+/**
+ * `yolo plan list` — list Plans in the current workspace.
+ *
+ * The third read-path verb after `plan get` and `plan validate`.
+ * Closes the "what's even in this workspace?" gap that operators
+ * hit immediately after `yolo context` (no in-CLI way to discover
+ * planIds without a curl detour). Maps directly to the substrate's
+ * `work.list_plans` route, which is already in
+ * `SUBSTRATE_CLI_PLAN_SCOPES`.
+ *
+ * Two output modes:
+ *   - default (`--summary`): one-line table per plan with planId,
+ *     state, version, latestRunId (or `—`), updatedAt (relative ISO
+ *     date for at-a-glance recency).
+ *   - `--json`: pretty-printed raw `plans[]` array. For jq /
+ *     scripted operator pipelines.
+ *
+ * Filter: `--state <draft|active|archived>` server-side filter
+ * (passed as `?state=` query param; renamed from `authoringState`
+ * 2026-05-09, item 17). Avoids client-side filtering on workspaces
+ * with many plans.
+ *
+ * Exit codes:
+ *   - 0  = success (zero plans is also success — empty list, not an error)
+ *   - 1  = http (e.g., 401 from a token that's been revoked mid-session)
+ *   - 64 = usage (bad --state, missing env, --workspace mismatch)
+ */
+import { SUBSTRATE_CLI_PLAN_SCOPES, WorkClientError, authenticatedRequest, mintSubstrateToken, } from './work-client.js';
+import { resolveSubstrateContext } from './auth-context.js';
+const ALLOWED_STATES = ['draft', 'active', 'archived'];
+// ─── Public entry ─────────────────────────────────────────────────────────
+export async function runPlanList(options) {
+    const env = options.env ?? process.env;
+    const format = options.outputFormat ?? 'summary';
+    // 1) --state value (validated even though the server also validates,
+    //    so we can fail fast without a network round-trip).
+    if (options.stateFilter !== undefined && !ALLOWED_STATES.includes(options.stateFilter)) {
+        return fail('usage', `invalid --state '${options.stateFilter}': must be one of ${ALLOWED_STATES.join(', ')}`);
+    }
+    // 2) Substrate context
+    const auth = resolveSubstrateContext(env);
+    if (!auth.ok)
+        return fail('auth', auth.message);
+    const { sessionId, commonApiUrl, userToken } = auth.context;
+    // 3) Mint token
+    let mint;
+    try {
+        mint = await mintSubstrateToken({
+            commonApiUrl,
+            userToken,
+            sessionId,
+            scopes: SUBSTRATE_CLI_PLAN_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)}`);
+    }
+    // 4) --workspace assertion
+    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}).`);
+    }
+    // 5) GET /workspaces/<wsId>/plans (with optional ?state=)
+    const ctx = {
+        commonApiUrl,
+        delegatedToken: mint.token,
+        fetchImpl: options.fetchImpl,
+    };
+    const path = options.stateFilter
+        ? `/workspaces/${mint.workspaceId}/plans?state=${options.stateFilter}`
+        : `/workspaces/${mint.workspaceId}/plans`;
+    const response = await authenticatedRequest(ctx, path, { method: 'GET' });
+    if (!response.ok) {
+        const text = await safeReadText(response);
+        return fail('http', `work.list_plans failed: HTTP ${response.status} — ${text}`, {
+            status: response.status,
+        });
+    }
+    const json = (await response.json());
+    if (!Array.isArray(json.plans)) {
+        return fail('http', 'work.list_plans response missing `plans` array');
+    }
+    return {
+        ok: true,
+        output: format === 'json'
+            ? formatJson(json.plans)
+            : formatSummary(json.plans, mint.workspaceId, options.stateFilter),
+        plans: json.plans,
+        workspaceId: mint.workspaceId,
+    };
+}
+// ─── Output formatting ────────────────────────────────────────────────────
+/**
+ * One-line header + one row per plan, columns:
+ * `planId  state    v#   latestRun  updatedAt`. Right-padded so
+ * planIds align even when they vary in length. When the list is
+ * empty, prints a clear "(no plans)" hint instead of just a header.
+ */
+export function formatSummary(plans, workspaceId, stateFilter) {
+    const lines = [];
+    const filterTag = stateFilter ? ` (filter: ${stateFilter})` : '';
+    lines.push(`Plans in workspace ${workspaceId}${filterTag}: ${plans.length}`);
+    if (plans.length === 0) {
+        lines.push('  (no plans)');
+        return lines.join('\n');
+    }
+    // Column widths from data — keeps short workspaces compact, won't
+    // visually break at scale.
+    const planIdCol = Math.max(8, ...plans.map((p) => p.planId.length));
+    const nameCol = Math.max(4, ...plans.map((p) => p.name.length));
+    const header = `  ${'planId'.padEnd(planIdCol)}  ${'name'.padEnd(nameCol)}  state     version  latestRun  updatedAt`;
+    lines.push(header);
+    for (const p of plans) {
+        const planId = p.planId.padEnd(planIdCol);
+        const name = p.name.padEnd(nameCol);
+        const state = p.state.padEnd(8);
+        const version = `v${p.version}`.padEnd(7);
+        const latestRun = (p.latestRunId ?? '—').padEnd(9);
+        lines.push(`  ${planId}  ${name}  ${state}  ${version}  ${latestRun}  ${p.updatedAt}`);
+    }
+    return lines.join('\n');
+}
+function formatJson(plans) {
+    return JSON.stringify(plans, 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/plan-open.js

@@ -0,0 +1,100 @@
+/**
+ * `yolo plan open <planId>` — print the webapp Plan-DAG URL for the
+ * given Plan in the calling session's workspace.
+ *
+ * Mints a substrate token to get the workspaceId, calls work.get_plan
+ * just to confirm the Plan exists (so a typo'd planId surfaces an
+ * `http` error instead of printing a URL that 404s in the browser),
+ * then prints the URL. No file I/O, no canonicalization, no Run.
+ *
+ * Output modes:
+ *   - default: prints the URL on a single line — handy for piping
+ *     into clipboard tools or `open`.
+ *   - `--json`: emits `{ ok, planId, workspaceId, url }`.
+ *
+ * Exit codes (via the CLI wrapper):
+ *   - 0  = success
+ *   - 1  = http (plan not found, etc.)
+ *   - 64 = usage error (bad planId, missing env trio, --workspace
+ *          mismatch, derivation failed)
+ */
+import { SUBSTRATE_CLI_PLAN_SCOPES, WorkClientError, authenticatedRequest, mintSubstrateToken, } from './work-client.js';
+import { resolveSubstrateContext } from './auth-context.js';
+import { planDagUrl } from './webapp-url.js';
+const PLAN_ID_REGEX = /^[a-zA-Z0-9][a-zA-Z0-9_-]{0,127}$/;
+export async function runPlanOpen(options) {
+    const env = options.env ?? process.env;
+    if (!PLAN_ID_REGEX.test(options.planId)) {
+        return fail('usage', `invalid planId '${options.planId}': must match /^[a-zA-Z0-9][a-zA-Z0-9_-]{0,127}$/`);
+    }
+    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_PLAN_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}).`);
+    }
+    // Existence check — keeps the CLI honest about typo'd planIds.
+    // Cheaper than fetching the full plan: just rely on the HTTP status.
+    const ctx = {
+        commonApiUrl,
+        delegatedToken: mint.token,
+        fetchImpl: options.fetchImpl,
+    };
+    const response = await authenticatedRequest(ctx, `/workspaces/${mint.workspaceId}/plans/${options.planId}`, { method: 'GET' });
+    if (!response.ok) {
+        const text = await safeReadText(response);
+        return fail('http', `work.get_plan failed: HTTP ${response.status} — ${text}`, { status: response.status });
+    }
+    const url = planDagUrl(env, mint.workspaceId, options.planId);
+    if (!url) {
+        return fail('usage', 'could not derive webapp URL from YOLO_COMMON_API_URL — set YOLO_WEBAPP_URL to override.');
+    }
+    return {
+        ok: true,
+        planId: options.planId,
+        workspaceId: mint.workspaceId,
+        url,
+        output: url,
+    };
+}
+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/plan-state.js

@@ -0,0 +1,228 @@
+/**
+ * `yolo plan activate <planId>` / `yolo plan archive <planId>`.
+ *
+ * Out-of-band Plan-state transitions for plans already in the DB.
+ * The file-driven flow can author a plan as `active` from the start
+ * (Phase 8d.2 — substrate now accepts `state` on `work.create_plan`),
+ * but operators still need a way to:
+ *   - flip an existing draft to active without rewriting the file
+ *   - archive a plan that's done its job
+ * neither of which has a clean file-level expression.
+ *
+ * Flow:
+ *   1. Validate planId regex.
+ *   2. Resolve env trio.
+ *   3. Mint a session-bound delegated token
+ *      (`work.get_plan` + `work.update_plan`, both already in
+ *      `SUBSTRATE_CLI_PLAN_SCOPES`).
+ *   4. Optional `--workspace` sanity-check against the minted
+ *      workspaceId.
+ *   5. GET the current plan to fetch (a) its current state — for the
+ *      "already in target state" no-op — and (b) its current
+ *      `version` for the `update_plan(baseVersion, …)` CAS.
+ *   6. PATCH with `{ baseVersion, mutations: [{ op: 'set-state',
+ *      state: <target> }] }`. The substrate's `applyMutations`
+ *      enforces the transition matrix (draft→active|archived,
+ *      active→archived; archived is terminal; same-state is allowed
+ *      and bumps version).
+ *   7. Refresh the lockfile entry's `lastImportedVersion` to the
+ *      new DB version so a subsequent `yolo plan import` is a
+ *      NO_CHANGE rather than a false-positive DIVERGED. Revision
+ *      is unchanged because the file didn't change — same
+ *      revision pointer, new version.
+ *
+ * Field rename note: the Plan-level state field was `authoringState`
+ * before 2026-05-09 and `state` after (item 17 of
+ * `docs/SUBSTRATE_IMPROVEMENTS.md`). The substrate accepts only `state`.
+ *
+ * Exit codes (used by the CLI wrapper):
+ *   - 0  = success (transition applied OR no-op when already in target)
+ *   - 1  = http (plan not found, version conflict, transition rejected)
+ *   - 64 = usage (bad planId, missing env, --workspace mismatch)
+ */
+import path from 'node:path';
+import { LockfileError, getEntry, readLockfile, resolveLockfilePath, setEntry, writeLockfile, } from './lockfile.js';
+import { SUBSTRATE_CLI_PLAN_SCOPES, WorkClientError, authenticatedRequest, mintSubstrateToken, } from './work-client.js';
+import { resolveSubstrateContext } from './auth-context.js';
+const PLAN_ID_REGEX = /^[a-zA-Z0-9][a-zA-Z0-9_-]{0,127}$/;
+// ─── Public entry ─────────────────────────────────────────────────────────
+export async function runPlanStateTransition(options) {
+    const env = options.env ?? process.env;
+    const now = options.now ?? (() => new Date().toISOString());
+    // 1) planId regex
+    if (!PLAN_ID_REGEX.test(options.planId)) {
+        return fail('usage', `invalid planId '${options.planId}': must match /^[a-zA-Z0-9][a-zA-Z0-9_-]{0,127}$/`);
+    }
+    // 2) env trio
+    const auth = resolveSubstrateContext(env);
+    if (!auth.ok)
+        return fail('auth', auth.message);
+    const { sessionId, commonApiUrl, userToken } = auth.context;
+    // 3) Mint token
+    let mint;
+    try {
+        mint = await mintSubstrateToken({
+            commonApiUrl,
+            userToken,
+            sessionId,
+            scopes: SUBSTRATE_CLI_PLAN_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)}`);
+    }
+    // 4) --workspace assertion
+    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,
+    };
+    // 5) GET current plan (need version for CAS, state for no-op detection)
+    const getResponse = await authenticatedRequest(ctx, `/workspaces/${mint.workspaceId}/plans/${options.planId}`, { method: 'GET' });
+    if (!getResponse.ok) {
+        const text = await safeReadText(getResponse);
+        return fail('http', `work.get_plan failed: HTTP ${getResponse.status} — ${text}`, { status: getResponse.status });
+    }
+    const getJson = (await getResponse.json());
+    if (!getJson.plan) {
+        return fail('http', 'work.get_plan response missing `plan` field');
+    }
+    const currentState = getJson.plan.state;
+    const baseVersion = getJson.plan.version;
+    // 6) No-op short-circuit OR PATCH. Either way, we end up with
+    //    a definitive (state, version) pair that the lockfile must
+    //    reflect — the substrate's view of the plan is the source
+    //    of truth for `lastImportedVersion`. Skipping the lockfile
+    //    refresh on the no-op path was the Codex R1 finding:
+    //    if the lockfile pointed at a stale version (e.g., the
+    //    plan was activated outside this CLI between two
+    //    `yolo plan activate` invocations), retry would return
+    //    success but leave the divergence to fire on the next
+    //    `yolo plan import`.
+    let finalVersion;
+    if (currentState === options.targetState) {
+        // No-op: substrate would accept same-state and bump version,
+        // but we'd rather not churn the DB on idempotent calls. The
+        // GET-response version is what the lockfile must align to.
+        finalVersion = baseVersion;
+    }
+    else {
+        const patchResponse = await authenticatedRequest(ctx, `/workspaces/${mint.workspaceId}/plans/${options.planId}`, {
+            method: 'PATCH',
+            jsonBody: {
+                baseVersion,
+                mutations: [{ op: 'set-state', state: options.targetState }],
+            },
+        });
+        if (!patchResponse.ok) {
+            const text = await safeReadText(patchResponse);
+            return fail('http', `work.update_plan failed: HTTP ${patchResponse.status} — ${text}`, { status: patchResponse.status });
+        }
+        const patchJson = (await patchResponse.json());
+        if (typeof patchJson.version !== 'number') {
+            return fail('http', 'work.update_plan response missing version field');
+        }
+        finalVersion = patchJson.version;
+    }
+    // 7) Refresh the lockfile entry (if one exists for this
+    //    workspace/plan). Same on both paths: revision pointer
+    //    stays put (the file didn't change), version + timestamp
+    //    realign to the substrate's current view. Best-effort skip
+    //    when no entry exists (e.g., plan was created via curl,
+    //    not import).
+    const plansDir = options.plansDir ?? path.resolve('.yolo', 'plans');
+    const lockfileResult = refreshLockfileEntry({
+        plansDir,
+        lockfileFlag: options.lockfileFlag,
+        workspaceId: mint.workspaceId,
+        planId: options.planId,
+        newVersion: finalVersion,
+        now,
+    });
+    if (!lockfileResult.ok)
+        return lockfileResult.error;
+    return {
+        ok: true,
+        planId: options.planId,
+        workspaceId: mint.workspaceId,
+        fromState: currentState,
+        toState: options.targetState,
+        version: finalVersion,
+        noop: currentState === options.targetState,
+    };
+}
+function refreshLockfileEntry(opts) {
+    let lockfilePath;
+    let lockfile;
+    try {
+        lockfilePath = resolveLockfilePath(opts.plansDir, opts.lockfileFlag);
+        lockfile = readLockfile(lockfilePath);
+    }
+    catch (err) {
+        if (err instanceof LockfileError) {
+            return { ok: false, error: fail('lockfile', err.message, { code: err.code }) };
+        }
+        return { ok: false, error: fail('lockfile', describeError(err)) };
+    }
+    const existing = getEntry(lockfile, opts.workspaceId, opts.planId);
+    if (!existing) {
+        // Best-effort: no entry, no write. The plan was likely
+        // created via curl or a different operator's machine.
+        return { ok: true };
+    }
+    const refreshed = {
+        lastImportedRevision: existing.lastImportedRevision,
+        lastImportedVersion: opts.newVersion,
+        lastImportedAt: opts.now(),
+    };
+    setEntry(lockfile, opts.workspaceId, opts.planId, refreshed);
+    try {
+        writeLockfile(lockfilePath, lockfile);
+    }
+    catch (err) {
+        if (err instanceof LockfileError) {
+            return { ok: false, error: fail('lockfile', err.message, { code: err.code }) };
+        }
+        return { ok: false, error: fail('lockfile', describeError(err)) };
+    }
+    return { ok: true };
+}
+// ─── 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':
+        case 'lockfile':
+            return 1;
+    }
+}
+export function formatSuccess(result) {
+    if (result.noop) {
+        return `OK: plan '${result.planId}' is already ${result.toState} (workspace ${result.workspaceId}, version ${result.version})`;
+    }
+    return `OK: plan '${result.planId}' transitioned ${result.fromState} → ${result.toState} (workspace ${result.workspaceId}, version ${result.version})`;
+}