@yolo-labs/yolo-cli 0.23.0

package/dist/deploy-ship.js

@@ -0,0 +1,389 @@
+/**
+ * deploy-ship — orchestration for bare `yolo deploy` (the one-move ship).
+ *
+ * Pipeline (docs/MANAGED_HOSTING_CLI_SPEC.md §4):
+ *   link (.yolo/deploy.json) → detect → build (if buildCommand) → bundle
+ *   → ship/start (manifest) → upload ONLY the missing-hash buckets
+ *   → finalize → live release (or 409 awaiting-approval on the T3 prod gate).
+ *
+ * `--dry-run` stops after bundle and is fully offline (no auth resolution,
+ * no network) — it prints the manifest summary and returns success.
+ *
+ * Progress is line-oriented and agent-parseable: every line starts with
+ * `deploy: ` and goes through the injected `progress` sink (the CLI layer
+ * routes it to stdout, or stderr under --json). The final OK / PENDING /
+ * FAIL line is the CLI layer's job (formatters exported from here).
+ *
+ * Exit-code mapping (spec §5) lives in `exitCodeForFailure` — backend
+ * refusal reasons pass through verbatim as failure kinds and default to
+ * exit 2 (backend rejected — don't blind-retry).
+ */
+import * as path from 'node:path';
+import * as fs from 'node:fs';
+import { spawn, execFileSync } from 'node:child_process';
+import { readDeployConfig } from './deploy-config.js';
+import { detectProjectShape } from './deploy-detect.js';
+import { bundleProject } from './deploy-bundle.js';
+import { resolveDeployContext, startShip, uploadAssetBucket, finalizeShip, } from './deploy-client.js';
+const NOT_LINKED_HINT = "run 'yolo deploy init' to create or link a hosting project";
+// ─── Orchestration ────────────────────────────────────────────────────────
+export async function runDeployShip(options) {
+    const cwd = options.cwd ?? process.cwd();
+    const envFlag = options.envFlag ?? 'staging';
+    const channel = envFlag === 'prod' ? 'prod' : 'preview';
+    const dryRun = options.dryRun ?? false;
+    const progress = options.progress ?? ((line) => process.stdout.write(`${line}\n`));
+    const deps = options.deps ?? {};
+    const readConfig = deps.readDeployConfigImpl ?? readDeployConfig;
+    const detect = deps.detectProjectShapeImpl ?? detectProjectShape;
+    const bundle = deps.bundleProjectImpl ?? bundleProject;
+    const startShipLeg = deps.startShipImpl ?? startShip;
+    const uploadLeg = deps.uploadAssetBucketImpl ?? uploadAssetBucket;
+    const finalizeLeg = deps.finalizeShipImpl ?? finalizeShip;
+    const runBuild = deps.runBuildImpl ?? defaultRunBuild;
+    const readAssetFile = deps.readAssetFileImpl ?? defaultReadAssetFile;
+    const resolveGitSha = deps.resolveGitShaImpl ?? defaultResolveGitSha;
+    // 1. Link — .yolo/deploy.json with a projectId is the durable bond.
+    const readResult = readConfig(cwd);
+    if (!readResult.ok) {
+        // 'malformed' | 'invalid' — a broken link file is a local failure
+        // (exit 1), distinct from the not-linked first-ship case.
+        return fail(readResult.kind, readResult.message);
+    }
+    const config = readResult.config;
+    if (!config || !config.projectId) {
+        return fail('not-linked', 'this directory is not linked to a hosting project (.yolo/deploy.json missing or has no projectId)', NOT_LINKED_HINT);
+    }
+    const projectId = config.projectId;
+    progress(`deploy: link ok (project ${projectId}${config.slug ? `, slug ${config.slug}` : ''}${config.type ? `, type ${config.type}` : ''})`);
+    // 2. Detect.
+    const detected = detect({ cwd, config });
+    if (!detected.ok)
+        return fail('detect-failed', detected.message);
+    const shape = detected.shape;
+    // 3. Build (if the shape carries a build command).
+    if (shape.buildCommand) {
+        const startedAt = Date.now();
+        const buildResult = await runBuild(shape.buildCommand, cwd, (chunk) => {
+            for (const line of chunk.split(/\r?\n/)) {
+                if (line.trim())
+                    progress(`deploy: build> ${line}`);
+            }
+        });
+        if (buildResult.code !== 0) {
+            return fail('build-failed', `build command \`${shape.buildCommand}\` exited with code ${buildResult.code}`);
+        }
+        progress(`deploy: build \`${shape.buildCommand}\` ... ok (${((Date.now() - startedAt) / 1000).toFixed(1)}s)`);
+    }
+    // 4. Bundle — all size/count ceilings fire locally in here, pre-network.
+    const bundled = await bundle(shape, cwd);
+    if (!bundled.ok) {
+        return { ok: false, kind: bundled.kind, message: bundled.message, hint: bundled.hint, detail: bundled.detail };
+    }
+    const fileCount = bundled.fileCount;
+    for (const warning of bundled.warnings)
+        progress(`deploy: warn ${warning}`);
+    progress(`deploy: bundle ok (${bundleLabel(shape)}, ${fileCount} files, ${formatMiB(bundled.totalAssetBytes)}, digest ${shortDigest(bundled.bundleDigest)})`);
+    const base = {
+        projectId,
+        slug: config.slug,
+        env: envFlag,
+        channel,
+        type: shape.type,
+        fileCount,
+        totalAssetBytes: bundled.totalAssetBytes,
+        bundleDigest: bundled.bundleDigest,
+    };
+    // 5. Dry-run stops here — fully offline by construction (auth + network
+    //    resolution happen below this line).
+    if (dryRun)
+        return { ok: true, dryRun: true, ...base };
+    const auth = resolveDeployContext(options.env ?? process.env, options.readFileImpl, options.fetchImpl);
+    if (!auth.ok)
+        return fail('auth', auth.message);
+    // Bounded auto-retry for transient edge/origin 5xx (incl. CF 522) on the
+    // ship legs — a single transient blip shouldn't hard-fail a prod deploy.
+    const ctx = {
+        ...auth.context,
+        retry: {
+            onRetry: ({ leg, attempt, maxAttempts, delayMs, failure }) => progress(`deploy: ${leg} transient error (${failure.message}); retrying ${attempt}/${maxAttempts - 1} in ${Math.round(delayMs)}ms`),
+        },
+    };
+    // 6. ship/start — manifest up, missing-hash buckets back.
+    const manifest = bundled.manifest;
+    const request = {
+        env: channel,
+        type: shape.type,
+        manifest,
+        bundleDigest: bundled.bundleDigest,
+    };
+    const workerModules = bundled.workerModules;
+    if (workerModules.length > 0) {
+        request.worker = {
+            mainModule: workerModules[0].name,
+            sizeBytes: workerModules.reduce((total, module) => total + module.contents.byteLength, 0),
+        };
+    }
+    if (config.compatibilityFlags && config.compatibilityFlags.length > 0) {
+        request.compatibilityFlags = config.compatibilityFlags;
+    }
+    const gitSha = resolveGitSha(cwd);
+    if (gitSha)
+        request.gitSha = gitSha;
+    const started = await startShipLeg(ctx, projectId, request);
+    if (!started.ok)
+        return clientFail(started);
+    const { shipId, missing } = started.value;
+    const assetsByHash = new Map(bundled.assets.map((asset) => [asset.hash, asset]));
+    const missingHashes = new Set(missing.flat());
+    let missingBytes = 0;
+    for (const hash of missingHashes)
+        missingBytes += assetsByHash.get(hash)?.size ?? 0;
+    progress(`deploy: ship/start ok (shipId ${shipId}, ${missingHashes.size}/${fileCount} assets missing, ${formatMiB(missingBytes)} to upload)`);
+    // 7. Upload ONLY the missing buckets — hash-matched unchanged assets never
+    //    leave the pod (the incremental-redeploy hot loop).
+    const buckets = missing.filter((bucket) => bucket.length > 0);
+    if (buckets.length === 0) {
+        progress('deploy: assets 0/0 buckets ok (0.0 MiB)');
+    }
+    else {
+        let uploadedBytes = 0;
+        for (let i = 0; i < buckets.length; i++) {
+            const files = readBucketFiles(buckets[i], assetsByHash, readAssetFile);
+            if (!files.ok)
+                return files;
+            const uploaded = await uploadLeg(ctx, projectId, shipId, files.files);
+            if (!uploaded.ok)
+                return clientFail(uploaded);
+            uploadedBytes += files.bytes;
+            progress(`deploy: assets ${i + 1}/${buckets.length} buckets ok (${formatMiB(uploadedBytes)})`);
+        }
+    }
+    // 8. Finalize — worker modules multipart / empty JSON for pure-static.
+    const finalized = await finalizeLeg(ctx, projectId, shipId, workerModules);
+    if (!finalized.ok) {
+        if (finalized.kind === 'awaiting-approval' && 'approvalId' in finalized) {
+            progress('deploy: finalize → pending operator approval (T3 prod ship)');
+            return {
+                ok: false,
+                kind: 'awaiting-approval',
+                projectId,
+                slug: config.slug,
+                approvalId: finalized.approvalId,
+                approvalUrl: finalized.approvalUrl,
+                releaseId: finalized.releaseId,
+                statement: finalized.statement,
+                expiresAt: finalized.expiresAt,
+                message: finalized.message,
+            };
+        }
+        return clientFail(finalized);
+    }
+    progress('deploy: finalize ok');
+    const bootCheck = parseBootCheck(finalized.value.bootCheck);
+    if (bootCheck)
+        progress(`deploy: warn — deployed Worker failed to boot (HTTP ${bootCheck.status})`);
+    return {
+        ok: true,
+        dryRun: false,
+        ...base,
+        shipId,
+        releaseId: finalized.value.releaseId,
+        url: finalized.value.url,
+        ...(bootCheck ? { bootCheck } : {}),
+    };
+}
+/** Narrow the backend's optional `bootCheck` envelope; ignore anything malformed. */
+function parseBootCheck(raw) {
+    if (!raw || typeof raw !== 'object')
+        return undefined;
+    const r = raw;
+    if (typeof r.status !== 'number' || typeof r.detail !== 'string')
+        return undefined;
+    return { status: r.status, detail: r.detail };
+}
+// ─── Exit codes (spec §5 — EXACT) ─────────────────────────────────────────
+/**
+ * | Exit | Meaning                                  |
+ * |------|------------------------------------------|
+ * | 0    | success                                  |
+ * | 64   | usage (bad flags/args)                   |
+ * | 78   | environment (session-required, auth)     |
+ * | 1    | local failure (fix project, retry)       |
+ * | 2    | backend rejected (don't blind-retry)     |
+ * | 3    | awaiting-approval (T3 — NOT an error)    |
+ * | 4    | transient transport (retry w/ backoff)   |
+ *
+ * Backend refusal reasons not listed locally (slug-taken, quota-exceeded,
+ * upload-expired, …) fall through to 2 — backend rejected.
+ */
+export function exitCodeForFailure(kind) {
+    switch (kind) {
+        case 'usage':
+            return 64;
+        case 'session-required':
+        case 'auth':
+            return 78;
+        case 'not-linked':
+        case 'detect-failed':
+        case 'build-failed':
+        case 'file-too-large':
+        case 'too-many-files':
+        case 'bundle-too-large':
+        case 'asset-read-failed':
+        case 'config-write-failed':
+        case 'malformed': // .yolo/deploy.json unparseable (deploy-config kind)
+        case 'invalid': // .yolo/deploy.json schema-invalid (deploy-config kind)
+            return 1;
+        case 'awaiting-approval':
+            return 3;
+        case 'network':
+            return 4;
+        default:
+            return 2;
+    }
+}
+// ─── Final-line formatters (rendered by the CLI layer) ────────────────────
+export function formatShipSuccess(result) {
+    const name = result.slug ?? result.projectId;
+    if (result.dryRun) {
+        return (`OK: dry-run — would ship ${name} (${result.type}, ${result.fileCount} files, ` +
+            `${formatMiB(result.totalAssetBytes)}, digest ${shortDigest(result.bundleDigest)}) to ${result.env}; nothing was uploaded`);
+    }
+    return `OK: shipped ${name} release ${result.releaseId ?? '(unknown)'} → ${result.url ?? '(no url reported)'} (${result.env})`;
+}
+/**
+ * Two independent "do not retry" signals: the PENDING prefix (not FAIL) and
+ * exit 3 — so neither prefix-matching nor exit-code-matching agents loop.
+ */
+export function formatPending(result) {
+    const name = result.slug ?? result.projectId;
+    const releaseTag = result.releaseId ? ` (release-candidate ${result.releaseId})` : '';
+    const approveLine = result.approvalUrl
+        ? `  approve: ${result.approvalUrl}  (single-use, states action+project)`
+        : `  approve: approval ${result.approvalId} in the Studio approvals panel (single-use, states action+project)`;
+    return [
+        `PENDING [awaiting-approval]: prod ship of ${name}${releaseTag} needs operator confirmation.`,
+        approveLine,
+        '  then: poll `yolo deploy status` — do NOT rerun `yolo deploy`; the bundle is already staged.',
+    ].join('\n');
+}
+export function formatFail(result) {
+    return `FAIL [${result.kind}]: ${result.message}${result.hint ? ` | hint: ${result.hint}` : ''}`;
+}
+// ─── Helpers ──────────────────────────────────────────────────────────────
+function fail(kind, message, hint) {
+    return { ok: false, kind, message, hint };
+}
+/** Pass a deploy-client failure through verbatim (reason taxonomy is shared). */
+function clientFail(failure) {
+    return {
+        ok: false,
+        kind: failure.kind,
+        message: failure.message,
+        hint: failure.hint,
+        status: failure.status,
+        detail: failure.detail,
+    };
+}
+function readBucketFiles(bucket, assetsByHash, readAssetFile) {
+    const files = [];
+    let bytes = 0;
+    for (const hash of bucket) {
+        const asset = assetsByHash.get(hash);
+        if (!asset) {
+            return fail('bundle-rejected', `server requested an asset hash not in the local manifest: ${hash}`);
+        }
+        let contents;
+        try {
+            contents = readAssetFile(asset.absPath);
+        }
+        catch (err) {
+            return fail('asset-read-failed', `failed to read asset ${asset.path}: ${describeError(err)}`);
+        }
+        bytes += contents.byteLength;
+        files.push({
+            hash,
+            base64: Buffer.from(contents).toString('base64'),
+            contentType: contentTypeFor(asset.path),
+        });
+    }
+    return { ok: true, files, bytes };
+}
+function bundleLabel(shape) {
+    if (shape.type === 'static')
+        return `${shape.assetsDir.replace(/\/+$/, '')}/`;
+    return shape.entry;
+}
+export function formatMiB(bytes) {
+    return `${(bytes / (1024 * 1024)).toFixed(1)} MiB`;
+}
+export function shortDigest(digest) {
+    const hex = digest.startsWith('sha256:') ? digest.slice('sha256:'.length) : digest;
+    return `sha256:${hex.slice(0, 8)}…`;
+}
+function describeError(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+function defaultRunBuild(command, cwd, onOutput) {
+    return new Promise((resolve) => {
+        const child = spawn(command, { cwd, shell: true, stdio: ['ignore', 'pipe', 'pipe'], env: process.env });
+        child.stdout?.on('data', (data) => onOutput(String(data)));
+        child.stderr?.on('data', (data) => onOutput(String(data)));
+        child.on('error', (err) => {
+            onOutput(`spawn failed: ${err.message}`);
+            resolve({ code: 127 });
+        });
+        child.on('close', (code) => resolve({ code: code ?? 1 }));
+    });
+}
+function defaultReadAssetFile(absolutePath) {
+    return fs.readFileSync(absolutePath);
+}
+function defaultResolveGitSha(cwd) {
+    try {
+        const out = execFileSync('git', ['rev-parse', 'HEAD'], {
+            cwd,
+            stdio: ['ignore', 'pipe', 'ignore'],
+            timeout: 5000,
+        })
+            .toString()
+            .trim();
+        return /^[0-9a-f]{40}$/.test(out) ? out : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+const CONTENT_TYPES = {
+    '.html': 'text/html',
+    '.htm': 'text/html',
+    '.css': 'text/css',
+    '.js': 'text/javascript',
+    '.mjs': 'text/javascript',
+    '.json': 'application/json',
+    '.svg': 'image/svg+xml',
+    '.png': 'image/png',
+    '.jpg': 'image/jpeg',
+    '.jpeg': 'image/jpeg',
+    '.gif': 'image/gif',
+    '.webp': 'image/webp',
+    '.avif': 'image/avif',
+    '.ico': 'image/x-icon',
+    '.txt': 'text/plain',
+    '.xml': 'application/xml',
+    '.pdf': 'application/pdf',
+    '.wasm': 'application/wasm',
+    '.woff': 'font/woff',
+    '.woff2': 'font/woff2',
+    '.ttf': 'font/ttf',
+    '.otf': 'font/otf',
+    '.map': 'application/json',
+    '.webmanifest': 'application/manifest+json',
+    '.mp4': 'video/mp4',
+    '.webm': 'video/webm',
+    '.mp3': 'audio/mpeg',
+};
+function contentTypeFor(assetPath) {
+    return CONTENT_TYPES[path.extname(assetPath).toLowerCase()] ?? 'application/octet-stream';
+}

package/dist/lockfile.js

@@ -0,0 +1,203 @@
+/**
+ * Plan-import lockfile (Phase 8c.2).
+ *
+ * Tracks `(workspaceId, planId) → { lastImportedRevision,
+ * lastImportedVersion, lastImportedAt }` so `yolo plan import` (8c.3)
+ * can detect drift between the file and the DB. The lockfile is NOT
+ * an identity remap — `planId` IS the workspace-scoped DB identifier
+ * (substrate enforces `(workspaceId, planId)` uniqueness directly).
+ *
+ * Two locations, per design F8.2:
+ *   - **Default** (`.yolo/plans/.imports.json`) — gitignored. Per-developer
+ *     state. Each engineer's local Plan Run / staging workspace lands here.
+ *   - **Env-named** (`.yolo/plans/.imports.<env>.json`) — opt-in checked-in.
+ *     Use for shared stable workspaces (e.g., the team's prod workspace)
+ *     so reproducible imports work across machines. Selected via
+ *     `--env <name>` on the CLI.
+ *
+ * Canonical write shape:
+ *   - JSON, 2-space indent, single trailing `\n`.
+ *   - Workspace IDs sorted lexicographically; planIds within each
+ *     workspace also sorted; entry keys in fixed order
+ *     (lastImportedAt, lastImportedRevision, lastImportedVersion —
+ *     alphabetical, mirroring how the plan-file canonicalizer treats
+ *     free-form maps).
+ *   - Same input → byte-identical output (idempotent re-write).
+ *
+ * Out of scope here (lands in 8c.3 import):
+ *   - The actual import flow (mint token → call work.create_plan /
+ *     work.update_plan → update lockfile).
+ *   - Divergence-policy decisions (`--force` to override DB version
+ *     drift, etc.) — `lockfile.ts` is just storage.
+ *
+ * Out of scope (8c.5 / future):
+ *   - Lockfile schema evolution. v1 has no version field; if the shape
+ *     ever changes, add a `$version` top-level field then.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { isWellFormedRevision } from './revision.js';
+const LOCKFILE_DEFAULT_BASENAME = '.imports.json';
+export class LockfileError extends Error {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.name = 'LockfileError';
+        this.code = code;
+    }
+}
+/**
+ * Resolve the lockfile path for a given plans directory and optional
+ * env name.
+ *
+ * @param plansDir - the absolute or relative path to `.yolo/plans/`.
+ * @param env - if set, picks `.imports.<env>.json` (the opt-in
+ *   checked-in variant). If unset, picks the gitignored default.
+ */
+export function resolveLockfilePath(plansDir, env) {
+    if (env !== undefined) {
+        if (!/^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$/.test(env)) {
+            throw new LockfileError(`--env name must match /^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$/, got '${env}'`, 'malformed');
+        }
+        return path.join(plansDir, `.imports.${env}.json`);
+    }
+    return path.join(plansDir, LOCKFILE_DEFAULT_BASENAME);
+}
+/**
+ * Read a lockfile from disk. Returns an empty object if the file
+ * doesn't exist (first-import case). Throws `LockfileError` if the
+ * file is unreadable or malformed.
+ */
+export function readLockfile(filePath) {
+    if (!existsSync(filePath))
+        return {};
+    let text;
+    try {
+        text = readFileSync(filePath, 'utf8');
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        throw new LockfileError(`could not read lockfile at ${filePath}: ${msg}`, 'unreadable');
+    }
+    if (text.trim() === '')
+        return {};
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        throw new LockfileError(`malformed JSON in lockfile at ${filePath}: ${msg}`, 'malformed');
+    }
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new LockfileError(`malformed lockfile at ${filePath}: top-level must be a JSON object, got ${describe(parsed)}`, 'malformed');
+    }
+    return validateShape(parsed, filePath);
+}
+/**
+ * Write a lockfile to disk in canonical form. Creates the parent
+ * directory if missing. Idempotent: same lockfile contents always
+ * produce byte-identical output.
+ */
+export function writeLockfile(filePath, lockfile) {
+    const dir = path.dirname(filePath);
+    try {
+        mkdirSync(dir, { recursive: true });
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        throw new LockfileError(`could not create lockfile dir ${dir}: ${msg}`, 'unwritable');
+    }
+    const sorted = canonicalize(lockfile);
+    const text = JSON.stringify(sorted, null, 2) + '\n';
+    try {
+        writeFileSync(filePath, text, 'utf8');
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        throw new LockfileError(`could not write lockfile at ${filePath}: ${msg}`, 'unwritable');
+    }
+}
+/**
+ * Lookup helper. Returns the entry for a `(workspaceId, planId)` pair,
+ * or `null` if either key is missing. Pure read — does not mutate the
+ * lockfile.
+ */
+export function getEntry(lockfile, workspaceId, planId) {
+    return lockfile[workspaceId]?.[planId] ?? null;
+}
+/**
+ * Mutator. Inserts or replaces the entry for a `(workspaceId, planId)`
+ * pair. Mutates `lockfile` in place AND returns it (for chaining /
+ * test ergonomics).
+ */
+export function setEntry(lockfile, workspaceId, planId, entry) {
+    if (!lockfile[workspaceId])
+        lockfile[workspaceId] = {};
+    lockfile[workspaceId][planId] = entry;
+    return lockfile;
+}
+// ─── Internals ────────────────────────────────────────────────────────────
+/**
+ * Reorder the lockfile to canonical shape: workspace IDs sorted,
+ * planIds within each sorted, entry fields in fixed alphabetical
+ * order. Same canonicalization rule as the plan-file canonicalizer's
+ * `sortNestedKeys`: lex sort because the schema doesn't dictate
+ * order. Pure — does not mutate input.
+ */
+function canonicalize(lockfile) {
+    const out = {};
+    for (const ws of Object.keys(lockfile).sort()) {
+        out[ws] = {};
+        for (const planId of Object.keys(lockfile[ws]).sort()) {
+            const e = lockfile[ws][planId];
+            // Fixed alphabetical entry-field order (matches a future
+            // round-trip test: read → write → read produces same object).
+            out[ws][planId] = {
+                lastImportedAt: e.lastImportedAt,
+                lastImportedRevision: e.lastImportedRevision,
+                lastImportedVersion: e.lastImportedVersion,
+            };
+        }
+    }
+    return out;
+}
+/**
+ * Validate the shape of a parsed lockfile. Throws `LockfileError`
+ * with `code: 'malformed_entry'` if any entry is missing required
+ * fields or has wrong types. Returns the validated object cast to
+ * `Lockfile`.
+ */
+function validateShape(parsed, filePath) {
+    for (const [ws, plans] of Object.entries(parsed)) {
+        if (plans === null || typeof plans !== 'object' || Array.isArray(plans)) {
+            throw new LockfileError(`malformed lockfile at ${filePath}: entry for workspace '${ws}' must be an object, got ${describe(plans)}`, 'malformed_entry');
+        }
+        for (const [planId, entry] of Object.entries(plans)) {
+            if (entry === null || typeof entry !== 'object' || Array.isArray(entry)) {
+                throw new LockfileError(`malformed lockfile at ${filePath}: entry for ${ws}/${planId} must be an object, got ${describe(entry)}`, 'malformed_entry');
+            }
+            const e = entry;
+            if (typeof e.lastImportedRevision !== 'string') {
+                throw new LockfileError(`malformed lockfile at ${filePath}: ${ws}/${planId}.lastImportedRevision must be a string, got ${describe(e.lastImportedRevision)}`, 'malformed_entry');
+            }
+            if (!isWellFormedRevision(e.lastImportedRevision)) {
+                throw new LockfileError(`malformed lockfile at ${filePath}: ${ws}/${planId}.lastImportedRevision must match 'sha256:<64-hex>', got '${e.lastImportedRevision}'`, 'malformed_entry');
+            }
+            if (typeof e.lastImportedVersion !== 'number' || !Number.isInteger(e.lastImportedVersion) || e.lastImportedVersion < 1) {
+                throw new LockfileError(`malformed lockfile at ${filePath}: ${ws}/${planId}.lastImportedVersion must be a positive integer, got ${describe(e.lastImportedVersion)}`, 'malformed_entry');
+            }
+            if (typeof e.lastImportedAt !== 'string' || Number.isNaN(Date.parse(e.lastImportedAt))) {
+                throw new LockfileError(`malformed lockfile at ${filePath}: ${ws}/${planId}.lastImportedAt must be an ISO-8601 timestamp, got ${describe(e.lastImportedAt)}`, 'malformed_entry');
+            }
+        }
+    }
+    return parsed;
+}
+function describe(value) {
+    if (value === null)
+        return 'null';
+    if (Array.isArray(value))
+        return 'array';
+    return typeof value;
+}