@yolo-labs/yolo-cli 0.23.0

package/dist/plan-get.js

@@ -0,0 +1,244 @@
+/**
+ * `yolo plan get <planId>` — read a Plan from the substrate.
+ *
+ * The thinnest of the three workflow commands. No file I/O, no
+ * lockfile mutation, no canonicalization. Mints a session-bound
+ * delegated token (work.get_plan scope) and prints the plan.
+ *
+ * Three output modes:
+ *   - default (`--summary`): one-line plan header + per-step rows
+ *     in declared order, with stepId, mode, and dependency
+ *     stepIds. Good for an operator's "is the import what I
+ *     expected" sanity check.
+ *   - `--waves`: same header, but steps grouped by topological
+ *     wave (computed from dependency gates). A wave is the set of
+ *     steps whose dependencies are all satisfied by earlier waves;
+ *     a step's wave is `1 + max(wave of any dependency)`. Good for
+ *     "what runs in parallel at each stage" reading.
+ *   - `--json`: pretty-printed `work.get_plan` response. Useful in
+ *     pipelines / for `jq` consumers.
+ *
+ * Errors map to exit codes via the CLI wrapper:
+ *   - 0  = success
+ *   - 1  = http (plan not found, etc.)
+ *   - 64 = usage error (bad planId, missing env trio,
+ *          --workspace mismatch)
+ */
+import { SUBSTRATE_CLI_PLAN_SCOPES, WorkClientError, authenticatedRequest, mintSubstrateToken, } from './work-client.js';
+import { resolveSubstrateContext } from './auth-context.js';
+import { planDagUrl } from './webapp-url.js';
+// ─── Public entry ─────────────────────────────────────────────────────────
+const PLAN_ID_REGEX = /^[a-zA-Z0-9][a-zA-Z0-9_-]{0,127}$/;
+export async function runPlanGet(options) {
+    const env = options.env ?? process.env;
+    const format = options.outputFormat ?? 'summary';
+    // 1) planId shape (matches substrate's PLAN_ID_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) 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) work.get_plan
+    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 json = (await response.json());
+    if (!json.plan) {
+        return fail('http', 'work.get_plan response missing `plan` field');
+    }
+    let output;
+    if (format === 'json')
+        output = formatJson(json.plan);
+    else if (format === 'waves')
+        output = formatWaves(json.plan, mint.workspaceId, env);
+    else
+        output = formatSummary(json.plan, mint.workspaceId, env);
+    return {
+        ok: true,
+        output,
+        plan: json.plan,
+        workspaceId: mint.workspaceId,
+    };
+}
+// ─── Output formatting ────────────────────────────────────────────────────
+/**
+ * One-line header + per-step rows. Each row: `<stepId> (<mode>)`
+ * with `← deps: <predId1>, <predId2>` if the step has dependency
+ * gates. Matches the substrate's actual gate shape (single
+ * `config.stepId` per dependency gate, per gate-readiness.ts:180);
+ * one row per step lists ALL its dependency-gate stepIds.
+ */
+export function formatSummary(plan, workspaceId, env = process.env) {
+    const lines = [];
+    lines.push(`Plan '${plan.planId}' (workspace ${workspaceId}, version ${plan.version}, ${plan.state})`);
+    const dagUrl = planDagUrl(env, workspaceId, plan.planId);
+    if (dagUrl)
+        lines.push(`  view: ${dagUrl}`);
+    if (plan.failurePolicy)
+        lines.push(`  failurePolicy: ${plan.failurePolicy}`);
+    if (typeof plan.autoRetryCap === 'number')
+        lines.push(`  autoRetryCap: ${plan.autoRetryCap}`);
+    const inputCount = Array.isArray(plan.inputs) ? plan.inputs.length : 0;
+    lines.push(`  inputs: ${inputCount}`);
+    lines.push(`  steps: ${plan.steps.length}`);
+    for (const step of plan.steps) {
+        const deps = depStepIds(step);
+        const depTag = deps.length > 0 ? `  ← deps: ${deps.join(', ')}` : '';
+        lines.push(`    - ${step.stepId} (${step.mode ?? '?'})${depTag}`);
+    }
+    return lines.join('\n');
+}
+/**
+ * Wave-grouped renderer. Same header as formatSummary, then steps
+ * grouped by their topological wave. Within a wave, step order
+ * matches the declared order in `plan.steps` so output is stable
+ * across runs.
+ *
+ * Defensive on bad shapes the substrate would normally reject:
+ * unknown predecessor stepIds collapse to wave 1, cycles short-circuit
+ * to wave 1 for the visiting node (so we never recurse forever).
+ */
+export function formatWaves(plan, workspaceId, env = process.env) {
+    const lines = [];
+    lines.push(`Plan '${plan.planId}' (workspace ${workspaceId}, version ${plan.version}, ${plan.state})`);
+    const dagUrl = planDagUrl(env, workspaceId, plan.planId);
+    if (dagUrl)
+        lines.push(`  view: ${dagUrl}`);
+    if (plan.failurePolicy)
+        lines.push(`  failurePolicy: ${plan.failurePolicy}`);
+    if (typeof plan.autoRetryCap === 'number')
+        lines.push(`  autoRetryCap: ${plan.autoRetryCap}`);
+    const inputCount = Array.isArray(plan.inputs) ? plan.inputs.length : 0;
+    lines.push(`  inputs: ${inputCount}`);
+    const waves = computeWaves(plan.steps);
+    const waveCount = waves.length;
+    const stepWord = plan.steps.length === 1 ? 'step' : 'steps';
+    lines.push(`  steps: ${plan.steps.length} ${stepWord} in ${waveCount} ${waveCount === 1 ? 'wave' : 'waves'}`);
+    lines.push('');
+    for (let i = 0; i < waves.length; i++) {
+        const stepsInWave = waves[i];
+        const count = stepsInWave.length;
+        const parallelTag = count > 1 ? ', parallel' : '';
+        lines.push(`  Wave ${i + 1} (${count} ${count === 1 ? 'step' : 'steps'}${parallelTag}):`);
+        for (const step of stepsInWave) {
+            const deps = depStepIds(step);
+            const depTag = deps.length > 0 ? `  ← deps: ${deps.join(', ')}` : '';
+            lines.push(`    - ${step.stepId} (${step.mode ?? '?'})${depTag}`);
+        }
+    }
+    return lines.join('\n');
+}
+/**
+ * Topological wave grouping. Returns an array of arrays — index 0 is
+ * wave 1, index 1 is wave 2, etc. Within each wave, steps appear in
+ * the order they were declared in `plan.steps`.
+ */
+function computeWaves(steps) {
+    const stepById = new Map();
+    for (const s of steps)
+        stepById.set(s.stepId, s);
+    const waveOfStep = new Map();
+    const waveOf = (stepId, visiting) => {
+        const cached = waveOfStep.get(stepId);
+        if (cached !== undefined)
+            return cached;
+        const step = stepById.get(stepId);
+        if (!step)
+            return 1; // unknown predecessor — substrate rejects on import
+        visiting.add(stepId);
+        let max = 0;
+        for (const dep of depStepIds(step)) {
+            if (!stepById.has(dep))
+                continue; // unknown predecessor → ignore
+            if (visiting.has(dep))
+                continue; // cycle: ignore the back-edge
+            const w = waveOf(dep, visiting);
+            if (w > max)
+                max = w;
+        }
+        visiting.delete(stepId);
+        const wave = max + 1;
+        waveOfStep.set(stepId, wave);
+        return wave;
+    };
+    for (const s of steps)
+        waveOf(s.stepId, new Set());
+    const grouped = [];
+    for (const s of steps) {
+        const w = waveOfStep.get(s.stepId) ?? 1;
+        while (grouped.length < w)
+            grouped.push([]);
+        grouped[w - 1].push(s);
+    }
+    return grouped;
+}
+function depStepIds(step) {
+    const out = [];
+    for (const gate of step.gates ?? []) {
+        if (gate.type === 'dependency') {
+            const predId = gate.config?.stepId;
+            if (typeof predId === 'string')
+                out.push(predId);
+        }
+    }
+    return out;
+}
+function formatJson(plan) {
+    return JSON.stringify(plan, 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-import.js

@@ -0,0 +1,420 @@
+/**
+ * `yolo plan import <file>` orchestration (Phase 8c.3).
+ *
+ * Composes everything from earlier slices:
+ *   - `plan-validate` (8c.1)  — parse + schema + canonical + no-coercion
+ *   - `revision`     (8c.2)  — sha256 over canonical bytes
+ *   - `lockfile`     (8c.2)  — `(workspaceId, planId) → entry` storage
+ *   - `work-client`  (8c.2)  — `mintSubstrateToken` + `authenticatedRequest`
+ *   - `plan-diff`    (8c.3)  — DB plan vs file plan → mutation list
+ *
+ * High-level flow:
+ *
+ *   1. Validate file (offline: parse + schema + canonical + no-coercion).
+ *   2. Enforce planId equals the file stem (semantic check, design F8.1).
+ *   3. Resolve substrate context (env trio); error otherwise.
+ *   4. Mint a session-bound delegated token; the response carries the
+ *      authoritative `workspaceId` (Phase 8 design: workspace binding
+ *      is derived from session, not env/args).
+ *   5. If `--workspace` was passed, assert it matches the minted
+ *      workspaceId — otherwise the user's mental model and the
+ *      session's binding diverge silently.
+ *   6. Read the lockfile (gitignored default unless `--env` is set).
+ *   7. Decide the action:
+ *        - **NO_CHANGE**   — file revision == lockfile.lastImportedRevision.
+ *                            Refresh the timestamp on the lockfile entry,
+ *                            do not touch the DB.
+ *        - **CREATE**      — no lockfile entry. Call `work.create_plan`.
+ *                            On 409 (plan already exists in DB), refuse
+ *                            unless `--force`.
+ *        - **UPDATE**      — lockfile entry exists, file revision differs.
+ *                            GET the DB plan, check `version` against
+ *                            `lastImportedVersion` to detect drift, then
+ *                            `work.update_plan` with computed mutations.
+ *        - **DIVERGED**    — lockfile entry exists but DB version >
+ *                            lastImportedVersion. Refuse unless `--force`.
+ *   8. On success, write the new lockfile entry
+ *      (`{ revision, version, importedAt }`).
+ *
+ * Errors map to exit codes via the CLI wrapper:
+ *   - 0  = success (CREATE / UPDATE / NO_CHANGE all success)
+ *   - 1  = validation failure / refused divergence / DB error
+ *   - 64 = usage error (missing file, planId/stem mismatch, --workspace
+ *          mismatch, missing env trio)
+ *
+ * Out of scope (deferred to a later slice if real demand emerges):
+ *   - Step REORDER detection. Substrate executor reads
+ *     `gate.config.requires`, not array order; reordering is a
+ *     semantic no-op. New steps land at the end via `add-step`.
+ *   - Outside-container login flow. v1 errors out without `SESSION_ID`
+ *     (substrate CLI is container-only — design Round 5).
+ *   - Concurrent import safety. The lockfile read-modify-write is not
+ *     atomic across processes; multi-developer concurrent imports to
+ *     the same workspace are rare enough to defer.
+ */
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { canonicalizePlanFile } from './canonicalizer.js';
+import { computeMutations } from './plan-diff.js';
+import { validatePlanText, formatErrors } from './plan-validate.js';
+import { computeRevisionHash } from './revision.js';
+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';
+import yaml from 'js-yaml';
+import { planDagUrl } from './webapp-url.js';
+// ─── Public entry ─────────────────────────────────────────────────────────
+export async function runPlanImport(options) {
+    const env = options.env ?? process.env;
+    const now = options.now ?? (() => new Date().toISOString());
+    // 1) Validate file
+    let fileText;
+    try {
+        fileText = readFileSync(options.filePath, 'utf8');
+    }
+    catch (err) {
+        return fail('usage', `cannot read plan file '${options.filePath}': ${describeError(err)}`);
+    }
+    const validation = validatePlanText(fileText);
+    if (!validation.ok) {
+        return fail('validation', `plan-file validation failed:\n${formatErrors(validation.errors)}`);
+    }
+    // Parse the file once we know it's valid+canonical so we can hand
+    // both the frontmatter and body to the diff.
+    let frontmatter;
+    let body;
+    try {
+        const parsed = parsePlanFile(fileText);
+        frontmatter = parsed.frontmatter;
+        body = parsed.body;
+    }
+    catch (err) {
+        // validatePlanText already ruled this path out; defense-in-depth.
+        return fail('validation', `plan-file parse failed: ${describeError(err)}`);
+    }
+    const filePlan = makeFilePlan(frontmatter, body);
+    // 2) planId vs file stem (design F8.1)
+    const stem = path.basename(options.filePath, path.extname(options.filePath));
+    if (filePlan.planId !== stem) {
+        return fail('planid_stem_mismatch', `frontmatter planId '${filePlan.planId}' must equal the file stem '${stem}' (file '${options.filePath}')`);
+    }
+    // 3) Substrate context
+    const auth = resolveSubstrateContext(env);
+    if (!auth.ok)
+        return fail('auth', auth.message);
+    const { sessionId, commonApiUrl, userToken } = auth.context;
+    // 4) 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)}`);
+    }
+    // 5) --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}). ` +
+            `Either omit the flag (it's optional in containers) or open a session for the right workspace.`);
+    }
+    // 6) Lockfile
+    const plansDir = options.plansDir ?? path.dirname(options.filePath);
+    let lockfilePath;
+    let lockfile;
+    try {
+        lockfilePath = resolveLockfilePath(plansDir, options.lockfileFlag);
+        lockfile = readLockfile(lockfilePath);
+    }
+    catch (err) {
+        if (err instanceof LockfileError) {
+            return fail('lockfile', err.message, { code: err.code });
+        }
+        return fail('lockfile', describeError(err));
+    }
+    // 7) Decide action
+    const canonicalBytes = canonicalizePlanFile(frontmatter, body);
+    const fileRevision = computeRevisionHash(canonicalBytes);
+    const existingEntry = getEntry(lockfile, mint.workspaceId, filePlan.planId);
+    const requestCtx = {
+        commonApiUrl,
+        delegatedToken: mint.token,
+        fetchImpl: options.fetchImpl,
+    };
+    let resultAction;
+    let resultVersion;
+    if (!existingEntry) {
+        // CREATE path
+        const created = await tryCreate(requestCtx, mint.workspaceId, filePlan);
+        if (created.ok) {
+            resultAction = 'created';
+            resultVersion = created.version;
+        }
+        else if (created.conflict409) {
+            if (!options.force) {
+                return fail('conflict_no_force', `plan '${filePlan.planId}' already exists in workspace ${mint.workspaceId} but the lockfile has no entry. ` +
+                    `Run with --force to fast-forward import (will rewrite the DB plan with the file's contents), or ` +
+                    `run \`yolo plan export ${filePlan.planId}\` first to capture the DB shape.`);
+            }
+            // --force on 409: pull the DB plan, run the UPDATE path with whatever's there as the base.
+            const fetched = await tryGet(requestCtx, mint.workspaceId, filePlan.planId);
+            if (!fetched.ok)
+                return fetched.error;
+            const updated = await tryUpdate(requestCtx, mint.workspaceId, filePlan, fetched.plan);
+            if (!updated.ok)
+                return updated.error;
+            resultAction = 'updated';
+            resultVersion = updated.version;
+        }
+        else {
+            return created.error;
+        }
+    }
+    else if (existingEntry.lastImportedRevision === fileRevision) {
+        // NO_CHANGE path: refresh timestamp, write lockfile, exit.
+        resultAction = 'no-change';
+        resultVersion = existingEntry.lastImportedVersion;
+    }
+    else {
+        // UPDATE path: GET DB, check drift, compute mutations, PATCH.
+        const fetched = await tryGet(requestCtx, mint.workspaceId, filePlan.planId);
+        if (!fetched.ok)
+            return fetched.error;
+        if (fetched.plan.version !== existingEntry.lastImportedVersion) {
+            if (!options.force) {
+                return fail('diverged', `DB has plan '${filePlan.planId}' at version ${fetched.plan.version}, but lockfile expected version ${existingEntry.lastImportedVersion}. ` +
+                    `Run with --force to fast-forward (overwrites DB changes), or \`yolo plan export\` first to capture the DB shape.`, { dbVersion: fetched.plan.version, expectedVersion: existingEntry.lastImportedVersion });
+            }
+        }
+        const updated = await tryUpdate(requestCtx, mint.workspaceId, filePlan, fetched.plan);
+        if (!updated.ok)
+            return updated.error;
+        resultAction = updated.action;
+        resultVersion = updated.version;
+    }
+    // 8) Update lockfile (idempotent — same input → same bytes).
+    const importedAt = now();
+    const newEntry = {
+        lastImportedRevision: fileRevision,
+        lastImportedVersion: resultVersion,
+        lastImportedAt: importedAt,
+    };
+    setEntry(lockfile, mint.workspaceId, filePlan.planId, newEntry);
+    try {
+        writeLockfile(lockfilePath, lockfile);
+    }
+    catch (err) {
+        if (err instanceof LockfileError) {
+            return fail('lockfile', err.message, { code: err.code });
+        }
+        return fail('lockfile', describeError(err));
+    }
+    return {
+        ok: true,
+        action: resultAction,
+        planId: filePlan.planId,
+        workspaceId: mint.workspaceId,
+        version: resultVersion,
+        revision: fileRevision,
+        importedAt,
+        lockfilePath,
+    };
+}
+async function tryCreate(ctx, workspaceId, filePlan) {
+    // `filePlan.description` is the SEPARATOR-NORMALIZED body
+    // (`makeFilePlan` strips the leading `\n` that the regex captures
+    // along with the body). Sending it raw was the Codex 8c.3 R1 bug —
+    // canonical files emit `---\n\n<body>` so the captured `body`
+    // starts with `\n`, which would make imported descriptions begin
+    // with a phantom blank line and break round-trips.
+    const body = {
+        planId: filePlan.planId,
+        name: filePlan.name,
+        description: filePlan.description,
+        inputs: filePlan.inputs ?? [],
+        failurePolicy: filePlan.failurePolicy ?? 'pause-and-wait',
+        autoRetryCap: filePlan.autoRetryCap,
+        autoRetryFallback: filePlan.autoRetryFallback,
+        integrationPolicy: filePlan.integrationPolicy,
+        steps: filePlan.steps,
+        // Send the file's state so a Plan authored as 'active' lands at
+        // 'active' instead of silently downgrading to 'draft'. Surfaced
+        // in Phase 8d.2 verification: the substrate's create_plan didn't
+        // accept the field until this slice (validatePlanCreateFields now
+        // normalizes it via PLAN_STATES). Omitting the field keeps the
+        // substrate's draft-first default for hand-authored callers that
+        // don't supply one.
+        //
+        // Renamed from `authoringState` 2026-05-09 (item 17 of
+        // `docs/SUBSTRATE_IMPROVEMENTS.md`).
+        state: filePlan.state,
+    };
+    const response = await authenticatedRequest(ctx, `/workspaces/${workspaceId}/plans`, {
+        method: 'POST',
+        jsonBody: body,
+    });
+    if (response.ok) {
+        const json = (await response.json());
+        if (typeof json.version !== 'number') {
+            return { ok: false, error: fail('http', 'create_plan response missing version field') };
+        }
+        return { ok: true, version: json.version };
+    }
+    if (response.status === 409) {
+        return { ok: false, conflict409: true };
+    }
+    const text = await safeReadText(response);
+    return {
+        ok: false,
+        error: fail('http', `work.create_plan failed: HTTP ${response.status} — ${text}`, {
+            status: response.status,
+        }),
+    };
+}
+async function tryGet(ctx, workspaceId, planId) {
+    const response = await authenticatedRequest(ctx, `/workspaces/${workspaceId}/plans/${planId}`, {
+        method: 'GET',
+    });
+    if (!response.ok) {
+        const text = await safeReadText(response);
+        return {
+            ok: false,
+            error: fail('http', `work.get_plan failed: HTTP ${response.status} — ${text}`, { status: response.status }),
+        };
+    }
+    const json = (await response.json());
+    if (!json.plan) {
+        return { ok: false, error: fail('http', 'work.get_plan response missing `plan` field') };
+    }
+    return { ok: true, plan: json.plan };
+}
+async function tryUpdate(ctx, workspaceId, filePlan, dbPlan) {
+    const mutations = computeMutations(dbPlan, filePlan);
+    if (mutations.length === 0) {
+        // Lockfile knew the file was different (otherwise we'd be on the
+        // NO_CHANGE path), but the diff says nothing to change. Likely:
+        // the file's revision changed cosmetically (e.g., the
+        // canonicalizer's output changed across versions). Treat as
+        // no-change, and the caller will refresh the lockfile entry.
+        return { ok: true, action: 'no-change', version: dbPlan.version };
+    }
+    const response = await authenticatedRequest(ctx, `/workspaces/${workspaceId}/plans/${filePlan.planId}`, {
+        method: 'PATCH',
+        jsonBody: { baseVersion: dbPlan.version, mutations: mutations },
+    });
+    if (!response.ok) {
+        const text = await safeReadText(response);
+        return {
+            ok: false,
+            error: fail('http', `work.update_plan failed: HTTP ${response.status} — ${text}`, { status: response.status }),
+        };
+    }
+    const json = (await response.json());
+    if (typeof json.version !== 'number') {
+        return { ok: false, error: fail('http', 'work.update_plan response missing version field') };
+    }
+    return { ok: true, action: 'updated', version: json.version };
+}
+// ─── Helpers ──────────────────────────────────────────────────────────────
+const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---\r?\n([\s\S]*)$/;
+/**
+ * Re-split the file into frontmatter object + body string. Mirrors
+ * the regex used by validatePlanText so that a successful validate
+ * implies a successful parse here. Throws on failure (defense-in-depth
+ * against future drift between the two parsers).
+ */
+function parsePlanFile(text) {
+    const match = text.match(FRONTMATTER_RE);
+    if (!match)
+        throw new Error('frontmatter delimiters missing');
+    const fm = yaml.load(match[1]);
+    return { frontmatter: fm, body: match[2] };
+}
+function makeFilePlan(frontmatter, body) {
+    // Body is Plan.description (Phase 8b design). The frontmatter→body
+    // separator (the blank line after the closing `---`) is OWNED by
+    // the canonicalizer (`canonicalizePlanFile` builds `---\n\n<body>`
+    // and strips leading `\n+` from the captured body before re-emit).
+    // Mirror that normalization here so `description` we send to
+    // `work.create_plan` / `work.update_plan` is exactly what
+    // round-tripping back through the canonicalizer would produce —
+    // otherwise an imported description gets a phantom leading blank
+    // line, and 8c.4 export round-trips churn (Codex 8c.3 R1 Medium).
+    const description = body
+        .replace(/\r\n/g, '\n') // CRLF → LF (validate already rejects CRLF; defense in depth)
+        .replace(/^\n+/, '') // strip separator-owned leading newline(s)
+        .replace(/\s+$/, '') + // collapse trailing whitespace…
+        '\n'; // …and ensure exactly one trailing newline.
+    return {
+        planId: String(frontmatter.planId ?? ''),
+        name: String(frontmatter.name ?? ''),
+        description,
+        state: frontmatter.state ?? 'draft',
+        failurePolicy: frontmatter.failurePolicy,
+        autoRetryCap: frontmatter.autoRetryCap,
+        autoRetryFallback: frontmatter.autoRetryFallback,
+        inputs: frontmatter.inputs ?? [],
+        integrationPolicy: frontmatter.integrationPolicy,
+        steps: (frontmatter.steps ?? []),
+    };
+}
+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>';
+    }
+}
+/**
+ * Map an `ImportFailure.kind` to a CLI exit code. Used by cli.ts and
+ * exported for tests.
+ */
+export function exitCodeForFailure(kind) {
+    switch (kind) {
+        case 'usage':
+        case 'auth':
+        case 'planid_stem_mismatch':
+        case 'workspace_mismatch':
+            return 64; // EX_USAGE
+        case 'validation':
+        case 'lockfile':
+        case 'diverged':
+        case 'conflict_no_force':
+        case 'http':
+            return 1;
+    }
+}
+/**
+ * Render an `ImportSuccess` as a CLI summary. The first line is the
+ * existing one-liner; if a webapp URL can be derived from the env, a
+ * second line prints the Plan-DAG link so operators can click straight
+ * through to the visual topology view. Caller appends `\n` if needed.
+ */
+export function formatSuccess(result, env = process.env) {
+    const headline = (() => {
+        switch (result.action) {
+            case 'created':
+                return `OK: created plan '${result.planId}' in workspace ${result.workspaceId} at version ${result.version} (revision ${result.revision.slice(0, 14)}…)`;
+            case 'updated':
+                return `OK: updated plan '${result.planId}' in workspace ${result.workspaceId} to version ${result.version} (revision ${result.revision.slice(0, 14)}…)`;
+            case 'no-change':
+                return `OK: plan '${result.planId}' already at file revision (workspace ${result.workspaceId}, version ${result.version})`;
+        }
+    })();
+    const dagUrl = planDagUrl(env, result.workspaceId, result.planId);
+    return dagUrl ? `${headline}\n  view: ${dagUrl}` : headline;
+}