@yolo-labs/yolo-cli 0.23.0

package/dist/webapp-url.js

@@ -0,0 +1,61 @@
+/**
+ * Webapp URL derivation for CLI link-print.
+ *
+ * The substrate CLI runs in a container that has `YOLO_COMMON_API_URL`
+ * but no first-class webapp URL var. To keep `yolo plan import` / `yolo
+ * plan get` able to print a clickable Plan-DAG link without requiring
+ * operators to set a new env var, derive the webapp host from the
+ * common-api host: prod is `api.yolo.studio` → `yolo.studio`, staging
+ * is `api-staging.yolo.studio` → `staging.yolo.studio`. Operators can
+ * override via `YOLO_WEBAPP_URL` for local dev / custom deployments.
+ *
+ * When derivation fails (an unrecognized API URL shape, e.g. a raw
+ * localhost port), `deriveWebappUrl` returns null and the caller is
+ * expected to skip the URL line — printing a bogus URL would be worse
+ * than printing nothing.
+ */
+export function deriveWebappUrl(input) {
+    if (input.webappUrlOverride && input.webappUrlOverride.length > 0) {
+        return stripTrailingSlash(input.webappUrlOverride);
+    }
+    let parsed;
+    try {
+        parsed = new URL(input.commonApiUrl);
+    }
+    catch {
+        return null;
+    }
+    const host = parsed.hostname;
+    // Recognized prod shape: api.<rest> → <rest>
+    if (host.startsWith('api.')) {
+        return `${parsed.protocol}//${host.slice('api.'.length)}`;
+    }
+    // Recognized env-suffixed shape: api-<env>.<rest> → <env>.<rest>
+    const envMatch = /^api-([^.]+)\.(.+)$/.exec(host);
+    if (envMatch) {
+        return `${parsed.protocol}//${envMatch[1]}.${envMatch[2]}`;
+    }
+    // Unknown shape (raw localhost, IPs, custom hosts). Don't guess.
+    return null;
+}
+/**
+ * Convenience for the CLI flows: derive the webapp URL from
+ * `process.env`-style inputs and format the Plan-DAG path. Returns
+ * null when derivation fails so the caller can omit the URL line
+ * entirely.
+ */
+export function planDagUrl(env, workspaceId, planId) {
+    const commonApiUrl = env.YOLO_COMMON_API_URL || env.YOLO_API_URL;
+    if (!commonApiUrl)
+        return null;
+    const base = deriveWebappUrl({
+        commonApiUrl,
+        webappUrlOverride: env.YOLO_WEBAPP_URL,
+    });
+    if (!base)
+        return null;
+    return `${base}/workspaces/${workspaceId}/plans/${planId}`;
+}
+function stripTrailingSlash(s) {
+    return s.endsWith('/') ? s.slice(0, -1) : s;
+}

package/dist/work-client.js

@@ -0,0 +1,195 @@
+/**
+ * Substrate-CLI work client (Phase 8c.2).
+ *
+ * Replaces the 8a Group 9 scaffold stub with the real auth flow:
+ *
+ *   1. `mintSubstrateToken` POSTs to `/internal/mcp/tokens` with
+ *      `Authorization: Bearer <user JWT>` and the session-bound payload
+ *      `{ sessionId, agentId: 'substrate-cli', scopes: [...] }`. The endpoint
+ *      (`internalOrUserAuth`) verifies the JWT's userId owns the session,
+ *      derives `workspaceId`, and returns a delegated JWT in `result.token`
+ *      plus `result.claims.workspaceId`. The substrate CLI's lockfile is
+ *      keyed by that workspaceId — `--workspace` is optional in containers
+ *      because the session record IS the source of truth.
+ *
+ *   2. `authenticatedRequest` is the helper used by `yolo plan
+ *      import/export` (8c.3+) to call `/internal/work/*`. It sends
+ *      `Authorization: Bearer <delegated>` — the delegated MCP token is the
+ *      capability (the per-agent allowedScopes check at the work routes is
+ *      satisfied by the token's claims). The CLI is user-JWT-only; the
+ *      INTERNAL_API_KEY / X-Internal-Auth path was removed.
+ *
+ * Both calls take an injectable `fetchImpl` so unit tests can stub
+ * the transport without touching real `globalThis.fetch`. In v1 the
+ * substrate CLI requires Node 20+, which guarantees `fetch` exists
+ * globally — `engines: ">=20"` is pinned in package.json.
+ *
+ * Substrate-CLI v1 scopes (capped per agents.json `substrate-cli`):
+ *   - Plan authoring: work.create_plan, work.update_plan,
+ *     work.get_plan, work.list_plans
+ *   - Run lifecycle:  work.start_run, work.get_run,
+ *     work.list_runs, work.pause_run, work.resume_run,
+ *     work.cancel_run, work.transfer_run_operator
+ *   - Artifact reads: work.get_artifact, work.list_artifacts, work.transfer_run_operator
+ *
+ * Run-lifecycle implication: `work.start_run` binds the calling agent
+ * as the Run's Operator (route handler, Phase 4/6 R4). So a Run started
+ * via `yolo run start` has `operatorAgentId === 'substrate-cli'`, and
+ * only the substrate CLI can pause/resume/cancel it via MCP. The
+ * natural handoff loop is `yolo run transfer <runId> --to claude` —
+ * substrate-cli is the current Operator, claude/codex is an
+ * Operator-tier target, route's R4 self-transfer path applies.
+ * Substrate-cli is NOT itself Operator-tier (per
+ * `OPERATOR_TIER_AGENT_IDS` in operator-binding.ts), so `--to
+ * substrate-cli` is rejected by the route's `isValidOperatorTarget`
+ * check.
+ */
+export const SUBSTRATE_CLI_AGENT_ID = 'substrate-cli';
+export const SUBSTRATE_CLI_PLAN_SCOPES = [
+    'work.create_plan',
+    'work.update_plan',
+    'work.get_plan',
+    'work.list_plans',
+];
+export const SUBSTRATE_CLI_RUN_SCOPES = [
+    'work.start_run',
+    'work.get_run',
+    'work.list_runs',
+    'work.pause_run',
+    'work.resume_run',
+    'work.cancel_run',
+    'work.transfer_run_operator',
+];
+export const SUBSTRATE_CLI_ARTIFACT_SCOPES = [
+    'work.get_artifact',
+    'work.list_artifacts',
+];
+export class WorkClientError extends Error {
+    status;
+    code;
+    constructor(message, status, code) {
+        super(message);
+        this.name = 'WorkClientError';
+        this.status = status;
+        this.code = code;
+    }
+}
+/**
+ * Mint a session-bound delegated token for the substrate CLI.
+ * Server-derived workspaceId comes back in `claims.workspaceId`.
+ *
+ * Throws `WorkClientError` with `status` and `code` from the
+ * common-api error envelope (`{ error, code }`); networks failures
+ * surface as plain `Error` from the underlying fetch.
+ */
+export async function mintSubstrateToken(options) {
+    const fetchImpl = options.fetchImpl ?? globalThis.fetch;
+    if (!fetchImpl) {
+        throw new WorkClientError('fetch is not available; substrate CLI requires Node 20+', 0, 'INTERNAL');
+    }
+    if (!options.userToken) {
+        throw new WorkClientError('no user token available to mint a substrate token', 0, 'INTERNAL');
+    }
+    const url = `${stripTrailingSlash(options.commonApiUrl)}/internal/mcp/tokens`;
+    const response = await fetchImpl(url, {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json',
+            Authorization: `Bearer ${options.userToken}`,
+        },
+        body: JSON.stringify({
+            sessionId: options.sessionId,
+            agentId: SUBSTRATE_CLI_AGENT_ID,
+            scopes: options.scopes,
+        }),
+    });
+    if (!response.ok) {
+        let parsed = {};
+        try {
+            parsed = (await response.json());
+        }
+        catch {
+            // body wasn't JSON — fall through to a generic message
+        }
+        throw new WorkClientError(parsed.error ?? `mint failed: HTTP ${response.status}`, response.status, parsed.code ?? 'INTERNAL');
+    }
+    const json = (await response.json());
+    if (typeof json.token !== 'string' || json.token.length === 0) {
+        throw new WorkClientError('mint response missing string `token`', 502, 'INTERNAL');
+    }
+    if (typeof json.expiresAt !== 'string' || json.expiresAt.length === 0) {
+        throw new WorkClientError('mint response missing string `expiresAt`', 502, 'INTERNAL');
+    }
+    if (typeof json.jti !== 'string' || json.jti.length === 0) {
+        throw new WorkClientError('mint response missing string `jti`', 502, 'INTERNAL');
+    }
+    const workspaceId = json.claims?.workspaceId;
+    if (typeof workspaceId !== 'string' || workspaceId.length === 0) {
+        throw new WorkClientError('mint response missing string `claims.workspaceId`', 502, 'INTERNAL');
+    }
+    const userId = json.claims?.userId;
+    if (typeof userId !== 'string' || userId.length === 0) {
+        throw new WorkClientError('mint response missing string `claims.userId`', 502, 'INTERNAL');
+    }
+    return {
+        token: json.token,
+        expiresAt: json.expiresAt,
+        workspaceId,
+        userId,
+        jti: json.jti,
+    };
+}
+/**
+ * Make an authenticated request to `/internal/work/*` with
+ * `Authorization: Bearer <delegated token>` (the delegated MCP token is the
+ * capability; requireMcpAuth accepts it without any service header). `workPath`
+ * is appended verbatim to `${commonApiUrl}/internal/work` — start it with a
+ * slash, e.g., `/workspaces/${workspaceId}/plans/${planId}`.
+ */
+export async function authenticatedRequest(options, workPath, init = {}) {
+    const fetchImpl = options.fetchImpl ?? globalThis.fetch;
+    if (!fetchImpl) {
+        throw new WorkClientError('fetch is not available; substrate CLI requires Node 20+', 0, 'INTERNAL');
+    }
+    const url = `${stripTrailingSlash(options.commonApiUrl)}/internal/work${workPath}`;
+    const headers = {
+        ...(init.headers ?? {}),
+        Authorization: `Bearer ${options.delegatedToken}`,
+    };
+    const fetchInit = {
+        method: init.method ?? 'GET',
+        headers,
+    };
+    if (init.jsonBody !== undefined) {
+        headers['Content-Type'] = 'application/json';
+        fetchInit.body = JSON.stringify(init.jsonBody);
+    }
+    return fetchImpl(url, fetchInit);
+}
+export async function userRouteRequest(options, routePath, init = {}) {
+    const fetchImpl = options.fetchImpl ?? globalThis.fetch;
+    if (!fetchImpl) {
+        throw new WorkClientError('fetch is not available; substrate CLI requires Node 20+', 0, 'INTERNAL');
+    }
+    if (!options.userToken) {
+        throw new WorkClientError('no user token available for user-route request', 0, 'INTERNAL');
+    }
+    const authHeaders = { Authorization: `Bearer ${options.userToken}` };
+    const url = `${stripTrailingSlash(options.commonApiUrl)}/v1${routePath}`;
+    const headers = {
+        ...(init.headers ?? {}),
+        ...authHeaders,
+    };
+    const fetchInit = {
+        method: init.method ?? 'GET',
+        headers,
+    };
+    if (init.jsonBody !== undefined) {
+        headers['Content-Type'] = 'application/json';
+        fetchInit.body = JSON.stringify(init.jsonBody);
+    }
+    return fetchImpl(url, fetchInit);
+}
+function stripTrailingSlash(url) {
+    return url.endsWith('/') ? url.slice(0, -1) : url;
+}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@yolo-labs/yolo-cli",
+  "version": "0.23.0",
+  "description": "YOLO Studio substrate CLI — owns yolo plan/workspace/artifact substrate-tooling commands. Distinct from yolo-code (the agent CLI) and yolo-router (the LLM gateway client).",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "yolo": "dist/cli.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist/**/*.js",
+    "!dist/**/*.test.js",
+    "dist/**/*.mjs",
+    "dist/**/*.json",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json && cp src/plan-frontmatter.schema.json dist/ && node scripts/build-vendored-flexdb.mjs",
+    "test": "npm run build && node --test --test-reporter=spec dist/*.test.js",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "npm test"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "ajv": "^6.12.6",
+    "esbuild": "^0.24.0",
+    "js-yaml": "^4.1.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.4.0",
+    "@types/node": "^20.0.0",
+    "@types/js-yaml": "^4.0.9"
+  }
+}