@yolo-labs/yolo-cli 0.23.0

package/README.md

@@ -0,0 +1,57 @@
+# @yololabs/yolo-cli — YOLO Studio substrate CLI
+
+The `yolo` binary owns substrate-tooling subcommands (Plan import/export,
+future workspace and artifact primitives). Distinct from:
+
+- **`yolo-code`** — YOLO Studio's built-in coding agent CLI (separate package).
+- **`yolo-router`** — the LLM gateway client (separate package).
+
+## Status
+
+Phase 8a Group 9 scaffold. v1 ships only `yolo --version` and
+`yolo context` (resolves and prints the container ambient session
+context). Plan import/export lands in Phase 8c.
+
+## Usage (in-container)
+
+```sh
+yolo --version
+yolo context
+```
+
+Outside a Studio container the CLI exits with `session-required`. A future
+external-login flow is planned but out of scope for Phase 8.
+
+## Auth contract
+
+Requires:
+
+- `SESSION_ID` (load-bearing — workspace derives from the session record)
+- `YOLO_COMMON_API_URL` (or `YOLO_API_URL`)
+- A credential — resolved by precedence (AUTH_AND_ONBOARDING Slice 0):
+  1. `~/.config/yolo/token` — the rotated **user access JWT**, rewritten
+     every ~10 min by container-api's token-refresh service. Preferred;
+     reading the file (not the env var) avoids the stale-shell problem.
+  2. `YOLO_API_TOKEN` env — the pod-injected user JWT (≤24h).
+  3. `INTERNAL_API_KEY` env — service master-key fallback, kept for
+     lane-runner / service callers. **No longer required in user shells**
+     and intentionally excluded from the sandbox env.
+
+The CLI mints a short-lived delegated MCP token via the session-bound
+endpoint (`POST /internal/mcp/tokens`) with `agentId: 'substrate-cli'`
+and a capped scope set, authenticating with the user JWT
+(`Authorization: Bearer`) when available, falling back to
+`X-Internal-Auth` otherwise. It then calls `/internal/work/*` REST
+routes with the delegated bearer (which is the capability — the
+service header is no longer required by `requireMcpAuth`).
+
+## Local build
+
+```sh
+npm install
+npm run build
+node dist/cli.js --version
+```
+
+Standalone package — not a workspace member. Container install is an
+explicit `COPY` + `npm install -g` block in `containers/sandboxes/yolo-main/Dockerfile`.

package/dist/artifact-get.js

@@ -0,0 +1,131 @@
+/**
+ * `yolo artifact get <key>` — fetch a single artifact version.
+ *
+ * Returns the latest version by default; `--version <n>` pins to a
+ * specific version. Default summary renders metadata only (key,
+ * version, type, producer, fingerprint, contentLength, createdAt).
+ * `--content` flag emits ONLY the artifact content body to stdout
+ * (suitable for piping). `--json` emits the full record including
+ * content.
+ *
+ * Errors map to exit codes via the CLI wrapper:
+ *   - 0  = success
+ *   - 1  = http (artifact not found, etc.)
+ *   - 64 = usage (bad key, bad --version, missing env trio,
+ *          --workspace mismatch, --content + --json conflict)
+ */
+import { SUBSTRATE_CLI_ARTIFACT_SCOPES, WorkClientError, authenticatedRequest, mintSubstrateToken, } from './work-client.js';
+import { resolveSubstrateContext } from './auth-context.js';
+// ─── Public entry ─────────────────────────────────────────────────────────
+const ARTIFACT_KEY_REGEX = /^[a-z0-9][a-z0-9/_.\-]{0,127}$/;
+export async function runArtifactGet(options) {
+    const env = options.env ?? process.env;
+    const format = options.outputFormat ?? 'summary';
+    if (!ARTIFACT_KEY_REGEX.test(options.key)) {
+        return fail('usage', `invalid artifact key '${options.key}': must match /^[a-z0-9][a-z0-9/_.\\-]{0,127}$/`);
+    }
+    if (options.version !== undefined) {
+        if (!Number.isInteger(options.version) || options.version < 1) {
+            return fail('usage', `invalid --version '${options.version}': must be a positive integer`);
+        }
+    }
+    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_ARTIFACT_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 path = options.version !== undefined
+        ? `/workspaces/${mint.workspaceId}/artifacts/${encodeURIComponent(options.key)}?version=${options.version}`
+        : `/workspaces/${mint.workspaceId}/artifacts/${encodeURIComponent(options.key)}`;
+    const response = await authenticatedRequest(ctx, path, { method: 'GET' });
+    if (!response.ok) {
+        const text = await safeReadText(response);
+        return fail('http', `work.get_artifact failed: HTTP ${response.status} — ${text}`, { status: response.status });
+    }
+    const artifact = (await response.json());
+    if (typeof artifact.key !== 'string' || typeof artifact.version !== 'number') {
+        return fail('http', 'work.get_artifact response missing required fields');
+    }
+    let output;
+    if (format === 'json')
+        output = formatJson(artifact);
+    else if (format === 'content')
+        output = artifact.content;
+    else
+        output = formatSummary(artifact, mint.workspaceId);
+    return { ok: true, output, artifact, workspaceId: mint.workspaceId };
+}
+// ─── Output formatting ────────────────────────────────────────────────────
+/**
+ * Header with metadata — no content body. The producer block tells
+ * the operator who emitted the artifact (agent + tile) and provenance
+ * fingerprint for cross-run identity.
+ */
+export function formatSummary(artifact, workspaceId) {
+    const lines = [];
+    lines.push(`Artifact ${artifact.key} v${artifact.version} (workspace ${workspaceId})`);
+    lines.push(`  type:           ${artifact.artifactType}`);
+    lines.push(`  contentLength:  ${artifact.contentLength}`);
+    lines.push(`  producedBy:     ${artifact.producedByAgentId}${artifact.producedByTileId ? ` (tile ${artifact.producedByTileId})` : ''}`);
+    if (artifact.producerType)
+        lines.push(`  producerType:   ${artifact.producerType}`);
+    if (artifact.producerId)
+        lines.push(`  producerId:     ${artifact.producerId}`);
+    if (artifact.fingerprint)
+        lines.push(`  fingerprint:    ${artifact.fingerprint}`);
+    if (artifact.refPath)
+        lines.push(`  refPath:        ${artifact.refPath}`);
+    lines.push(`  createdAt:      ${artifact.createdAt}`);
+    return lines.join('\n');
+}
+function formatJson(artifact) {
+    return JSON.stringify(artifact, 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/artifact-list.js

@@ -0,0 +1,133 @@
+/**
+ * `yolo artifact list` — enumerate workspace artifacts (newest-first).
+ *
+ * Default summary is a table per artifact: key, latest version,
+ * artifactType, latestTimestamp. `--prefix <prefix>` server-side
+ * filters by key prefix; `--limit <n>` caps result count (1-500,
+ * default 100). `--json` emits the raw `artifacts[]` array.
+ *
+ * Exit codes:
+ *   - 0  = success (zero artifacts is also success — empty list,
+ *          not an error)
+ *   - 1  = http (server error, etc.)
+ *   - 64 = usage (bad --limit, missing env, --workspace mismatch)
+ */
+import { SUBSTRATE_CLI_ARTIFACT_SCOPES, WorkClientError, authenticatedRequest, mintSubstrateToken, } from './work-client.js';
+import { resolveSubstrateContext } from './auth-context.js';
+// ─── Public entry ─────────────────────────────────────────────────────────
+export async function runArtifactList(options) {
+    const env = options.env ?? process.env;
+    const format = options.outputFormat ?? 'summary';
+    if (options.limit !== undefined) {
+        if (!Number.isInteger(options.limit) || options.limit < 1 || options.limit > 500) {
+            return fail('usage', `invalid --limit '${options.limit}': must be an integer between 1 and 500`);
+        }
+    }
+    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_ARTIFACT_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 params = [];
+    if (options.prefix)
+        params.push(`prefix=${encodeURIComponent(options.prefix)}`);
+    if (options.limit !== undefined)
+        params.push(`limit=${options.limit}`);
+    const query = params.length > 0 ? `?${params.join('&')}` : '';
+    const path = `/workspaces/${mint.workspaceId}/artifacts${query}`;
+    const response = await authenticatedRequest(ctx, path, { method: 'GET' });
+    if (!response.ok) {
+        const text = await safeReadText(response);
+        return fail('http', `work.list_artifacts failed: HTTP ${response.status} — ${text}`, {
+            status: response.status,
+        });
+    }
+    const json = (await response.json());
+    if (!Array.isArray(json.artifacts)) {
+        return fail('http', 'work.list_artifacts response missing `artifacts` array');
+    }
+    return {
+        ok: true,
+        output: format === 'json'
+            ? formatJson(json.artifacts)
+            : formatSummary(json.artifacts, mint.workspaceId, options.prefix),
+        artifacts: json.artifacts,
+        workspaceId: mint.workspaceId,
+    };
+}
+// ─── Output formatting ────────────────────────────────────────────────────
+/**
+ * Header + table row per artifact. Columns auto-pad to longest key
+ * and artifactType. Empty workspace renders "(no artifacts)" rather
+ * than just a header.
+ */
+export function formatSummary(artifacts, workspaceId, prefix) {
+    const lines = [];
+    const filterTag = prefix ? ` (prefix: ${prefix})` : '';
+    lines.push(`Artifacts in workspace ${workspaceId}${filterTag}: ${artifacts.length}`);
+    if (artifacts.length === 0) {
+        lines.push('  (no artifacts)');
+        return lines.join('\n');
+    }
+    const keyCol = Math.max(3, ...artifacts.map((a) => a.key.length));
+    const typeCol = Math.max(4, ...artifacts.map((a) => a.artifactType.length));
+    lines.push(`  ${'key'.padEnd(keyCol)}  v#     ${'type'.padEnd(typeCol)}  latestTimestamp`);
+    for (const a of artifacts) {
+        const key = a.key.padEnd(keyCol);
+        const v = `v${a.latestVersion}`.padEnd(5);
+        const type = a.artifactType.padEnd(typeCol);
+        lines.push(`  ${key}  ${v}  ${type}  ${a.latestTimestamp}`);
+    }
+    return lines.join('\n');
+}
+function formatJson(artifacts) {
+    return JSON.stringify(artifacts, 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/auth-context.js

@@ -0,0 +1,60 @@
+/**
+ * Substrate CLI auth-context resolution (AUTH_AND_ONBOARDING Slice 0).
+ *
+ * The CLI used to accept `INTERNAL_API_KEY` — the service-to-service master
+ * key — from the shell env as a fallback. That master key should never be the
+ * credential a user-controlled shell wields, and the JWT path has fully
+ * replaced it (the mint + work routes accept the user JWT, ownership-checked).
+ * The fallback is now REMOVED: the CLI is user-JWT-only.
+ *
+ * Token precedence:
+ *   1. `~/.config/yolo/token` — the rotated user JWT, rewritten every
+ *      ~10 min by container-api's yolo-token-refresh. Reading the FILE
+ *      (not the `YOLO_API_TOKEN` env var) sidesteps the stale-shell
+ *      problem: a long-lived shell holds whatever token was in scope at
+ *      its own launch, but the file is always fresh.
+ *   2. `YOLO_API_TOKEN` env — the pod-injected user JWT (≤24h TTL).
+ *
+ * Auth requires SESSION_ID + a common-api URL + a user access JWT.
+ */
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+export function resolveSubstrateContext(env, readFileImpl = defaultReadFile) {
+    const sessionId = env.SESSION_ID;
+    const commonApiUrl = env.YOLO_COMMON_API_URL || env.YOLO_API_URL;
+    if (!sessionId) {
+        return { ok: false, message: 'SESSION_ID env var is required (substrate CLI is container-only in v1)' };
+    }
+    if (!commonApiUrl) {
+        return { ok: false, message: 'YOLO_COMMON_API_URL (or YOLO_API_URL) env var is required' };
+    }
+    const userToken = resolveUserToken(env, readFileImpl);
+    if (!userToken) {
+        return {
+            ok: false,
+            message: 'no user token available: expected a user access JWT in ~/.config/yolo/token or the YOLO_API_TOKEN env var. ' +
+                'The substrate CLI is user-JWT-only — the INTERNAL_API_KEY fallback was removed.',
+        };
+    }
+    return { ok: true, context: { sessionId, commonApiUrl, userToken } };
+}
+export function resolveUserToken(env, readFileImpl = defaultReadFile) {
+    const home = env.HOME || os.homedir();
+    const tokenFile = path.join(home, '.config', 'yolo', 'token');
+    const fromFile = readFileImpl(tokenFile);
+    if (fromFile && fromFile.trim())
+        return fromFile.trim();
+    const fromEnv = env.YOLO_API_TOKEN;
+    if (fromEnv && fromEnv.trim())
+        return fromEnv.trim();
+    return undefined;
+}
+export function defaultReadFile(filePath) {
+    try {
+        return fs.readFileSync(filePath, 'utf-8');
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/canonicalizer.js

@@ -0,0 +1,208 @@
+/**
+ * Plan-file canonicalizer (Phase 8b).
+ *
+ * Pure function: a parsed plan-frontmatter object → canonical YAML
+ * string. The canonical form is what `import` writes to the file
+ * after parsing/normalizing user input AND what `export` emits when
+ * snapshotting the live DB plan back to disk. Both paths share this
+ * one engine so a round-trip through import → export produces a
+ * byte-identical file.
+ *
+ * Round 5 stance #7 + Round 2 stance answers locked these rules:
+ *   - Stable key order at the schema-defined level (planId, name,
+ *     state, …, steps[]). Top-level field order is fixed.
+ *   - Step-level + gate-level + input-level + declared-output-level +
+ *     template-level orders are also schema-defined.
+ *   - Nested arbitrary-keyed objects (gate.config,
+ *     integrationPolicy, template.metadata) sort recursively
+ *     lexicographically. The schema says nothing about their key
+ *     order, so alphabetical is the only stable rule.
+ *   - Unknown top-level keys (forward-compat) trail the known schema
+ *     fields in lexicographic order.
+ *   - Output uses `\n` line endings, single trailing newline, 2-space
+ *     indent, plain scalars where unambiguous (double-quoted when a
+ *     string would otherwise parse as a non-string YAML value), and
+ *     no boolean/numeric coercion at parse time (caller's
+ *     responsibility — js-yaml's default load is happy to coerce, so
+ *     callers should run their own validator that doesn't).
+ *
+ * NOT enforced here (caller's job):
+ *   - Schema validation (frontmatter shape).
+ *   - Stripping DB-only fields (`_id`, `workspaceId`, `version`,
+ *     `latestRunId`, `nextRunNumber`, `createdAt`, `updatedAt`).
+ *   - Verifying `planId` matches the file stem.
+ *   - Asserting stepId uniqueness, gate `requires` resolves to
+ *     siblings, etc.
+ */
+import yaml from 'js-yaml';
+// ─── Schema-defined field orders ──────────────────────────────────────────
+// NB: no `description` at the plan level. Per the Phase 8 design
+// (`docs/_ORCHESTRATION_PHASE8_PLAN_FILES_DESIGN.md` §"body is
+// Plan.description"), the markdown body IS `Plan.description` —
+// frontmatter has no description field, by design, to avoid dual
+// sources. Step- and input-level `description` fields are unrelated
+// and remain in their respective `*_FIELD_ORDER`s below.
+const PLAN_FIELD_ORDER = [
+    'planId',
+    'name',
+    'state',
+    'failurePolicy',
+    'autoRetryCap',
+    'autoRetryFallback',
+    'inputs',
+    'integrationPolicy',
+    'steps',
+];
+const STEP_FIELD_ORDER = [
+    'stepId',
+    'name',
+    'description',
+    'mode',
+    'runner',
+    'gates',
+    'declaredOutputs',
+    'failurePolicy',
+    'autoRetryCap',
+    'autoRetryFallback',
+    'template',
+];
+const GATE_FIELD_ORDER = ['gateId', 'type', 'config'];
+const INPUT_FIELD_ORDER = ['name', 'required', 'default', 'description'];
+const DECLARED_OUTPUT_FIELD_ORDER = ['name', 'artifactType', 'required'];
+const TEMPLATE_FIELD_ORDER = ['todoContent', 'todoFile', 'branch', 'metadata'];
+// ─── Helpers ──────────────────────────────────────────────────────────────
+/**
+ * Reorder an object's keys: known schema keys first (in the given
+ * order), then any unknown keys lexicographically. Missing schema
+ * keys are skipped (we never emit `null` for unset optional fields).
+ */
+function reorderObject(obj, order) {
+    const out = {};
+    for (const key of order) {
+        if (key in obj && obj[key] !== undefined) {
+            out[key] = obj[key];
+        }
+    }
+    const known = new Set(order);
+    const extras = Object.keys(obj)
+        .filter((k) => !known.has(k) && obj[k] !== undefined)
+        .sort();
+    for (const k of extras) {
+        out[k] = obj[k];
+    }
+    return out;
+}
+/**
+ * Recursively sort the keys of arbitrary-keyed nested objects
+ * lexicographically. Arrays preserve their declared order; primitives
+ * pass through unchanged.
+ *
+ * Used for `gate.config`, `integrationPolicy`, `template.metadata`,
+ * and any future free-form nested map. The schema doesn't dictate
+ * key order for these, so alphabetical is the only deterministic
+ * choice.
+ */
+function sortNestedKeys(value) {
+    if (Array.isArray(value)) {
+        return value.map(sortNestedKeys);
+    }
+    if (value !== null && typeof value === 'object') {
+        const obj = value;
+        const out = {};
+        for (const key of Object.keys(obj).sort()) {
+            out[key] = sortNestedKeys(obj[key]);
+        }
+        return out;
+    }
+    return value;
+}
+/**
+ * Reorder a parsed plan frontmatter to canonical shape. Pure — does
+ * not mutate the input.
+ */
+export function canonicalizeFrontmatterObject(plan) {
+    const ordered = reorderObject(plan, PLAN_FIELD_ORDER);
+    if (Array.isArray(ordered.inputs)) {
+        ordered.inputs = ordered.inputs.map((input) => reorderObject(input, INPUT_FIELD_ORDER));
+    }
+    if (ordered.integrationPolicy && typeof ordered.integrationPolicy === 'object') {
+        ordered.integrationPolicy = sortNestedKeys(ordered.integrationPolicy);
+    }
+    if (Array.isArray(ordered.steps)) {
+        ordered.steps = ordered.steps.map((step) => {
+            const orderedStep = reorderObject(step, STEP_FIELD_ORDER);
+            if (Array.isArray(orderedStep.gates)) {
+                orderedStep.gates = orderedStep.gates.map((gate) => {
+                    const og = reorderObject(gate, GATE_FIELD_ORDER);
+                    if (og.config && typeof og.config === 'object') {
+                        og.config = sortNestedKeys(og.config);
+                    }
+                    return og;
+                });
+            }
+            if (Array.isArray(orderedStep.declaredOutputs)) {
+                orderedStep.declaredOutputs = orderedStep.declaredOutputs.map((d) => reorderObject(d, DECLARED_OUTPUT_FIELD_ORDER));
+            }
+            if (orderedStep.template && typeof orderedStep.template === 'object') {
+                const ot = reorderObject(orderedStep.template, TEMPLATE_FIELD_ORDER);
+                if (ot.metadata && typeof ot.metadata === 'object') {
+                    ot.metadata = sortNestedKeys(ot.metadata);
+                }
+                orderedStep.template = ot;
+            }
+            return orderedStep;
+        });
+    }
+    return ordered;
+}
+// ─── YAML emission ────────────────────────────────────────────────────────
+/**
+ * Emit a canonical YAML string for the given (already-reordered)
+ * frontmatter object. Always ends with a single `\n`.
+ */
+export function emitCanonicalYaml(ordered) {
+    return yaml.dump(ordered, {
+        noRefs: true, // no anchors/aliases
+        sortKeys: false, // we control order ourselves; js-yaml leaves it alone
+        lineWidth: -1, // never wrap long scalars
+        quotingType: '"', // double-quotes when quoting is needed
+        forceQuotes: false, // only quote when ambiguous
+        indent: 2,
+        flowLevel: -1, // always block style for objects/arrays (except where the YAML grammar requires flow)
+    });
+}
+// ─── Public entry points ──────────────────────────────────────────────────
+/**
+ * Canonicalize a parsed plan frontmatter object to its YAML string.
+ * Pure: same input → same byte-identical output.
+ */
+export function canonicalizeFrontmatter(plan) {
+    const ordered = canonicalizeFrontmatterObject(plan);
+    return emitCanonicalYaml(ordered);
+}
+/**
+ * Canonicalize a full plan file (frontmatter + body). Output shape:
+ *
+ *     ---
+ *     <frontmatter>
+ *     ---
+ *
+ *     <body>
+ *
+ * Body is normalized to LF-only, exactly one trailing newline, no
+ * trailing whitespace beyond that. Frontmatter and body are
+ * separated by `---` plus one blank line (markdown-friendly).
+ */
+export function canonicalizePlanFile(plan, body) {
+    const fm = canonicalizeFrontmatter(plan);
+    // js-yaml's dump always ends with a single \n; collapse any
+    // accidental trailing blanks just in case.
+    const fmTrimmed = fm.replace(/\n+$/, '\n');
+    // Body: LF-only, strip CR; strip any leading newlines (the
+    // frontmatter-body separator is owned by this function, not the
+    // caller's body string — a parsed file's body capture often starts
+    // with the blank line after the closing `---`); trim trailing
+    // whitespace; ensure exactly one trailing newline.
+    const bodyTrimmed = body.replace(/\r\n/g, '\n').replace(/^\n+/, '').replace(/\s+$/, '');
+    return `---\n${fmTrimmed}---\n\n${bodyTrimmed}\n`;
+}