loadout-ai 0.1.0

package/dist/src/core/catalog-coverage.js

@@ -0,0 +1,85 @@
+import { catalogTrustStage } from "./profiles.js";
+const componentTypes = [
+    "skill",
+    "rule",
+    "command",
+    "agent",
+    "mcp",
+    "plugin",
+    "root",
+];
+const operatingSystems = ["windows", "macos", "linux"];
+const trustStages = [
+    "discovered",
+    "inspected",
+    "human-reviewed",
+    "benchmarked",
+    "recommended",
+];
+function tally(values, keys) {
+    return Object.fromEntries(keys.map((key) => [key, values.filter((value) => value === key).length]));
+}
+function technicallyScreened(pkg) {
+    return Boolean(pkg.license &&
+        pkg.components?.length &&
+        pkg.operatingSystems?.length === operatingSystems.length &&
+        operatingSystems.every((system) => pkg.operatingSystems?.includes(system)) &&
+        pkg.source?.commit.match(/^[a-f0-9]{40}$/) &&
+        pkg.source.evidencePaths.length &&
+        pkg.source.verifiedAt);
+}
+/**
+ * Explain catalog breadth without pretending repository count equals quality.
+ * All metrics are derived from technically screened records; live activity remains explicit
+ * and absent until `catalog --refresh` observes it.
+ */
+export function buildCatalogCoverage(catalog, targetRecords = 50) {
+    const categories = catalog.reduce((result, pkg) => {
+        result[pkg.category] = (result[pkg.category] ?? 0) + 1;
+        return result;
+    }, {});
+    const components = tally(catalog.flatMap((pkg) => pkg.components ?? []), componentTypes);
+    const platforms = tally(catalog.flatMap((pkg) => pkg.operatingSystems ?? []), operatingSystems);
+    return {
+        records: catalog.length,
+        targetRecords,
+        technicallyScreenedRecords: catalog.filter(technicallyScreened).length,
+        recommendedRecords: catalog.filter((pkg) => catalogTrustStage(pkg) === "recommended").length,
+        trustStages: tally(catalog.map(catalogTrustStage), trustStages),
+        immutablePins: catalog.filter((pkg) => pkg.source?.commit.match(/^[a-f0-9]{40}$/)).length,
+        assertedLicenses: catalog.filter((pkg) => pkg.license && pkg.license !== "NOASSERTION").length,
+        noAssertionLicenses: catalog.filter((pkg) => pkg.license === "NOASSERTION")
+            .length,
+        activityObserved: catalog.filter((pkg) => pkg.pushedAt || pkg.lastUpdatedAt)
+            .length,
+        evaluationReady: catalog.filter((pkg) => pkg.source?.evidencePaths.length &&
+            pkg.components?.some((type) => type === "skill" || type === "mcp")).length,
+        categories,
+        components,
+        operatingSystems: platforms,
+        installShapes: {
+            skills: catalog.filter((pkg) => pkg.components?.includes("skill") && !pkg.components.includes("mcp")).length,
+            mcpOnly: catalog.filter((pkg) => pkg.components?.includes("mcp") && !pkg.components.includes("skill")).length,
+            mixed: catalog.filter((pkg) => pkg.components?.includes("skill") && pkg.components.includes("mcp")).length,
+        },
+        duplicateCapabilityGroups: Object.entries(categories)
+            .filter(([, records]) => records > 1)
+            .map(([category, records]) => ({ category, records }))
+            .sort((left, right) => right.records - left.records ||
+            left.category.localeCompare(right.category)),
+    };
+}
+export function formatCatalogCoverage(report) {
+    const categories = Object.entries(report.categories)
+        .sort((left, right) => right[1] - left[1] || left[0].localeCompare(right[0]))
+        .map(([category, count]) => `${category}:${count}`)
+        .join(", ");
+    return [
+        `Screened catalog: ${report.technicallyScreenedRecords}/${report.records} technically complete records (target ${report.targetRecords})`,
+        `Recommendation trust: ${report.recommendedRecords} Stable sources · human license approval still required before release`,
+        `Evidence: ${report.immutablePins} immutable pins · ${report.assertedLicenses} asserted licenses · ${report.noAssertionLicenses} NOASSERTION`,
+        `Coverage: ${Object.values(report.categories).length} categories · ${report.evaluationReady} evaluation-ready · ${report.activityObserved} with refreshed activity`,
+        `Install shape: ${report.installShapes.skills} skill · ${report.installShapes.mcpOnly} MCP-only · ${report.installShapes.mixed} mixed`,
+        `Categories: ${categories}`,
+    ].join("\n");
+}

package/dist/src/core/catalog-install.js

@@ -0,0 +1,186 @@
+import { loadEffectiveCatalog } from "./catalog.js";
+import { detectAgents } from "./paths.js";
+import { isStableSkillSelected, isPowerSkillSelected, resolveCatalogProfile, } from "./profiles.js";
+import { applySkillLibraryBatch, applySkillInstallBatch, buildSkillPlan, installedAgents, } from "./install.js";
+import { fetchRepositorySnapshot, } from "./source.js";
+import { analyzeInstallPlanSafety, } from "./safety.js";
+export const RECOMMENDED_ACTIVE_SKILL_LIMIT = 30;
+async function parallelMap(values, concurrency, worker) {
+    const results = new Array(values.length);
+    let cursor = 0;
+    async function run() {
+        while (cursor < values.length) {
+            const index = cursor++;
+            results[index] = await worker(values[index], index);
+        }
+    }
+    await Promise.all(Array.from({ length: Math.min(Math.max(1, concurrency), values.length) }, () => run()));
+    return results;
+}
+/**
+ * Prepare a broad catalog loadout without mutating agent files. Only packages
+ * with reviewed skill evidence are fetched automatically; MCP servers and
+ * executables need agent-specific configuration or credentials and remain
+ * explicit customization steps.
+ */
+export async function prepareCatalogInstall(selection, options = {}) {
+    const catalog = options.catalog ?? (await loadEffectiveCatalog());
+    const resolution = resolveCatalogProfile(catalog, selection);
+    const agents = installedAgents(options.detectedAgents ?? (await detectAgents()), options.requestedAgents);
+    if (!agents.length)
+        throw new Error("No supported AI coding agent was detected. Install Codex, Claude Code, Cursor, Gemini CLI, OpenCode, or Hermes first.");
+    const skipped = resolution.packages
+        .filter((pkg) => !pkg.components?.includes("skill"))
+        .map((pkg) => ({
+        packageId: pkg.id,
+        kind: "explicit-setup",
+        reason: "Not auto-installed: this catalog record has no reviewed skill component; MCP/executable setup requires explicit configuration.",
+    }));
+    const installable = resolution.packages.filter((pkg) => pkg.components?.includes("skill"));
+    const fetchSnapshot = options.fetchSnapshot ?? fetchRepositorySnapshot;
+    let completed = 0;
+    const prepared = await parallelMap(installable, options.concurrency ?? 4, async (pkg) => {
+        options.onProgress?.({
+            packageId: pkg.id,
+            completed,
+            total: installable.length,
+            status: "fetching",
+            message: `Fetching reviewed ${pkg.displayName} snapshot`,
+        });
+        try {
+            if (!pkg.source?.commit)
+                throw new Error("catalog record has no reviewed commit");
+            const fetched = await fetchSnapshot(pkg.repository, {
+                ref: pkg.source.commit,
+            });
+            if (fetched.commit.toLowerCase() !== pkg.source.commit.toLowerCase())
+                throw new Error(`resolved ${fetched.commit}, expected reviewed commit ${pkg.source.commit}`);
+            const include = selection.mode === "stable"
+                ? (skill) => isStableSkillSelected(pkg.id, skill.name, skill.targetName)
+                : selection.mode === "power"
+                    ? (skill) => isPowerSkillSelected(pkg.id, skill.name, skill.targetName)
+                    : undefined;
+            const plan = await buildSkillPlan(fetched.path, pkg.id, agents, include ? { include } : {});
+            if (selection.mode === "stable")
+                plan.files = plan.files.filter((file) => isStableSkillSelected(pkg.id, file.skillName, file.target.split(/[\\/]/).at(-1) ?? pkg.id));
+            if (selection.mode === "power")
+                plan.files = plan.files.filter((file) => isPowerSkillSelected(pkg.id, file.skillName, file.target.split(/[\\/]/).at(-1) ?? pkg.id));
+            if (!plan.files.length)
+                throw new Error(`no skills from this collection are selected by the ${selection.mode === "stable" ? "Stable" : "Power"} profile`);
+            const safety = await analyzeInstallPlanSafety(plan);
+            completed += 1;
+            options.onProgress?.({
+                packageId: pkg.id,
+                completed,
+                total: installable.length,
+                status: "ready",
+                message: `${pkg.displayName} is ready (${plan.files.length} target directories)`,
+            });
+            return {
+                package: pkg,
+                plan,
+                metadata: {
+                    repository: fetched.repository,
+                    resolvedCommit: fetched.commit,
+                    reviewed: true,
+                },
+                safety,
+            };
+        }
+        catch (error) {
+            completed += 1;
+            const reason = error instanceof Error ? error.message : String(error);
+            options.onProgress?.({
+                packageId: pkg.id,
+                completed,
+                total: installable.length,
+                status: "skipped",
+                message: `${pkg.displayName} could not be prepared: ${reason}`,
+            });
+            return { packageId: pkg.id, reason, kind: "preparation-failed" };
+        }
+    });
+    const entries = prepared.filter((item) => "plan" in item);
+    skipped.push(...prepared.filter((item) => !("plan" in item)));
+    // Broad collections frequently publish the same conventional skill name.
+    // Resolution order is already deterministic and evidence-ranked, so keep
+    // the first source for a target and defer only the lower-ranked duplicate
+    // instead of overwriting it or blocking every other useful skill.
+    const claimedTargets = new Map();
+    const collisions = [];
+    for (const entry of entries) {
+        entry.plan.files = entry.plan.files.filter((file) => {
+            const keptPackageId = claimedTargets.get(file.target);
+            if (!keptPackageId) {
+                claimedTargets.set(file.target, entry.plan.packageId);
+                return true;
+            }
+            collisions.push({
+                target: file.target,
+                keptPackageId,
+                deferredPackageId: entry.plan.packageId,
+            });
+            return false;
+        });
+    }
+    const usableEntries = entries.filter((entry) => {
+        if (entry.plan.files.length)
+            return true;
+        skipped.push({
+            packageId: entry.plan.packageId,
+            kind: "overlap",
+            reason: "Every discovered skill overlaps a higher-ranked reviewed package.",
+        });
+        return false;
+    });
+    return {
+        selection,
+        resolution,
+        agents,
+        entries: usableEntries,
+        skipped,
+        collisions,
+    };
+}
+export function formatPreparedCatalogInstall(prepared) {
+    const targetDirectories = prepared.entries.reduce((total, entry) => total + entry.plan.files.length, 0);
+    const directoriesPerAgent = prepared.agents.length
+        ? Math.ceil(targetDirectories / prepared.agents.length)
+        : 0;
+    const risky = prepared.entries.filter((entry) => entry.safety.approvalRequired);
+    const explicit = prepared.skipped.filter((item) => item.kind === "explicit-setup");
+    const failures = prepared.skipped.filter((item) => item.kind === "preparation-failed");
+    const lines = [
+        `Loadout: ${prepared.selection.mode === "maximum" ? "Maximum Library" : prepared.selection.mode === "power" ? "Power Boost" : prepared.selection.mode === "stable" ? "Stable Boost" : "Custom"}`,
+        `Detected agents: ${prepared.agents.map((agent) => agent.displayName).join(", ")}`,
+        `Catalog selection: ${prepared.resolution.packages.length} repositories`,
+        `Ready to install: ${prepared.entries.length} skill repositories (${targetDirectories} agent skill directories)`,
+        `Explicit setup later: ${explicit.length} repository/repositories`,
+    ];
+    if (directoriesPerAgent > RECOMMENDED_ACTIVE_SKILL_LIMIT)
+        lines.push(`Capacity warning: about ${directoriesPerAgent} skill directories per agent exceeds the recommended active-set limit of ${RECOMMENDED_ACTIVE_SKILL_LIMIT}.${prepared.selection.mode === "maximum" ? " Maximum stores these in the disabled library; use project activation to choose the working set." : " Prefer Stable or project-aware activation for smaller context."}`);
+    if (failures.length)
+        lines.push(`Preparation failures (installation will remain blocked): ${failures.map((item) => item.packageId).join(", ")}`);
+    if (prepared.collisions.length)
+        lines.push(`Overlapping skill targets resolved: ${prepared.collisions.length} lower-ranked duplicate directories deferred`);
+    if (risky.length)
+        lines.push(`Additional risk approval required: ${risky.map((entry) => entry.package.id).join(", ")}`);
+    for (const warning of prepared.resolution.warnings)
+        lines.push(`Warning: ${warning}`);
+    for (const item of prepared.skipped)
+        lines.push(`${item.kind === "preparation-failed" ? "Failed" : "Deferred"} ${item.packageId}: ${item.reason}`);
+    return lines.join("\n");
+}
+export async function applyPreparedCatalogInstall(prepared, options = {}) {
+    if (!prepared.entries.length)
+        throw new Error("No reviewed skill packages could be prepared for installation");
+    const failures = prepared.skipped.filter((item) => item.kind === "preparation-failed");
+    if (failures.length)
+        throw new Error(`Setup is incomplete because reviewed packages failed to prepare: ${failures.map((item) => item.packageId).join(", ")}. Retry when GitHub is reachable; no partial loadout was installed.`);
+    const risky = prepared.entries.filter((entry) => entry.safety.approvalRequired);
+    if (risky.length && !options.approveRisk)
+        throw new Error(`Additional risk approval is required for: ${risky.map((entry) => entry.package.id).join(", ")}. Review the plan, then use --approve-risk.`);
+    return prepared.selection.mode === "maximum"
+        ? applySkillLibraryBatch(prepared.entries)
+        : applySkillInstallBatch(prepared.entries);
+}

package/dist/src/core/catalog-release.js

@@ -0,0 +1,286 @@
+import { readFile, rm, stat } from "node:fs/promises";
+import { createHash } from "node:crypto";
+import { dirname, join, resolve } from "node:path";
+import { isDeepStrictEqual } from "node:util";
+import { writeFileAtomically } from "./atomic-file.js";
+import { catalogTrustPath, loadEffectiveCatalog, readCatalogTrustState, readTrustedCatalogState, trustedCatalogPath, validateCatalog, } from "./catalog.js";
+import { ensureDirectory } from "./paths.js";
+import { loadoutHome } from "./paths.js";
+import { withFileLock } from "./file-lock.js";
+import { createSnapshot } from "./snapshot.js";
+import { verifyEnvelope } from "./signing.js";
+import { beginTransaction, completeTransaction, markTransactionCommitting, rollbackTransaction, recoverPendingTransactions, } from "./transaction.js";
+const MAX_RELEASE_BYTES = 5 * 1024 * 1024;
+const MAX_PUBLIC_KEY_BYTES = 64 * 1024;
+const catalogReleaseLockPath = () => join(loadoutHome(), "catalog-releases", "apply.lock");
+const envelopeDigest = (envelope) => createHash("sha256").update(envelope.signature).digest("hex");
+function parseEnvelope(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error("Signed catalog snapshot must be an object");
+    const envelope = value;
+    if (envelope.schemaVersion !== 1 ||
+        envelope.algorithm !== "Ed25519" ||
+        typeof envelope.createdAt !== "string" ||
+        Number.isNaN(Date.parse(envelope.createdAt)) ||
+        typeof envelope.publicKeyFingerprint !== "string" ||
+        typeof envelope.signature !== "string" ||
+        envelope.payload === undefined)
+        throw new Error("Signed catalog envelope schema is invalid");
+    return envelope;
+}
+async function readReleaseSource(source, fetcher = fetch, requestTimeoutMs = 15_000) {
+    if (/^https:\/\//i.test(source)) {
+        if (!Number.isInteger(requestTimeoutMs) ||
+            requestTimeoutMs < 1 ||
+            requestTimeoutMs > 120_000)
+            throw new Error("Catalog release timeout must be 1-120000 milliseconds");
+        let current = new URL(source);
+        const signal = AbortSignal.timeout(requestTimeoutMs);
+        let response;
+        for (let redirects = 0; redirects <= 5; redirects++) {
+            try {
+                response = await fetcher(current, {
+                    headers: { accept: "application/json" },
+                    redirect: "manual",
+                    signal,
+                });
+            }
+            catch (error) {
+                if (signal.aborted)
+                    throw new Error(`Catalog release request timed out after ${requestTimeoutMs}ms`, { cause: error });
+                throw error;
+            }
+            if (response.status < 300 || response.status >= 400)
+                break;
+            const location = response.headers.get("location");
+            if (!location)
+                throw new Error("Catalog release redirect has no Location");
+            if (redirects === 5)
+                throw new Error("Catalog release exceeded five redirects");
+            const next = new URL(location, current);
+            if (next.protocol !== "https:" || next.username || next.password)
+                throw new Error("Catalog release redirected to a non-HTTPS source");
+            current = next;
+        }
+        if (!response)
+            throw new Error("Catalog release request did not run");
+        if (!response.ok)
+            throw new Error(`Catalog release request failed with HTTP ${response.status}`);
+        if (response.url && new URL(response.url).protocol !== "https:")
+            throw new Error("Catalog release redirected to a non-HTTPS source");
+        const length = Number(response.headers.get("content-length") ?? 0);
+        if (length > MAX_RELEASE_BYTES)
+            throw new Error("Catalog release exceeds the 5 MiB limit");
+        if (!response.body)
+            throw new Error("Catalog release response has no body");
+        const reader = response.body.getReader();
+        const chunks = [];
+        let bytes = 0;
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            bytes += value.byteLength;
+            if (bytes > MAX_RELEASE_BYTES) {
+                await reader.cancel();
+                throw new Error("Catalog release exceeds the 5 MiB limit");
+            }
+            chunks.push(value);
+        }
+        return Buffer.concat(chunks.map((chunk) => Buffer.from(chunk))).toString("utf8");
+    }
+    if (/^[a-z]+:\/\//i.test(source))
+        throw new Error("Remote catalog sources must use HTTPS");
+    return readBoundedFile(resolve(source), MAX_RELEASE_BYTES, "catalog release");
+}
+async function readBoundedFile(path, maximum, label) {
+    const info = await stat(path);
+    if (!info.isFile() || info.size > maximum)
+        throw new Error(`${label} exceeds the ${maximum} byte limit`);
+    const content = await readFile(path, "utf8");
+    if (Buffer.byteLength(content) > maximum)
+        throw new Error(`${label} exceeds the ${maximum} byte limit`);
+    return content;
+}
+function diffCatalogs(current, candidate) {
+    const currentById = new Map(current.map((item) => [item.id, item]));
+    const candidateById = new Map(candidate.map((item) => [item.id, item]));
+    const added = candidate
+        .filter((item) => !currentById.has(item.id))
+        .map((item) => item.id)
+        .sort();
+    const removed = current
+        .filter((item) => !candidateById.has(item.id))
+        .map((item) => item.id)
+        .sort();
+    const updated = candidate
+        .filter((item) => {
+        const previous = currentById.get(item.id);
+        return previous && !isDeepStrictEqual(previous, item);
+    })
+        .map((item) => item.id)
+        .sort();
+    return {
+        added,
+        updated,
+        removed,
+        unchanged: candidate.length - added.length - updated.length,
+    };
+}
+export async function previewCatalogRelease(options) {
+    const [raw, publicKeyPem, trusted, trust] = await Promise.all([
+        readReleaseSource(options.source, options.fetcher, options.requestTimeoutMs),
+        readBoundedFile(resolve(options.publicKeyPath), MAX_PUBLIC_KEY_BYTES, "public key"),
+        readTrustedCatalogState(),
+        readCatalogTrustState(),
+    ]);
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new Error("Catalog release is not valid JSON");
+    }
+    const envelope = parseEnvelope(parsed);
+    const verification = verifyEnvelope(envelope, publicKeyPem);
+    if (!verification.valid)
+        throw new Error(`Catalog release signature is invalid for trusted key ${verification.fingerprint}`);
+    const pendingIsActive = Boolean(trust?.pendingCreatedAt &&
+        trusted?.envelope.createdAt === trust.pendingCreatedAt &&
+        envelopeDigest(trusted.envelope) === trust.pendingEnvelopeSha256);
+    const effectiveTrust = trust?.pendingFirstPin && !pendingIsActive ? undefined : trust;
+    if (effectiveTrust && verification.fingerprint !== effectiveTrust.fingerprint)
+        throw new Error(`Catalog signer ${verification.fingerprint} does not match pinned key ${effectiveTrust.fingerprint}; key rotation requires an explicit trust reset`);
+    validateCatalog(envelope.payload, { requireEvidence: true });
+    const catalogEnvelope = envelope;
+    const previousTime = Math.max(trusted ? Date.parse(trusted.envelope.createdAt) : -Infinity, effectiveTrust ? Date.parse(effectiveTrust.highWaterCreatedAt) : -Infinity);
+    return {
+        source: options.source,
+        createdAt: catalogEnvelope.createdAt,
+        fingerprint: verification.fingerprint,
+        packageCount: catalogEnvelope.payload.length,
+        diff: diffCatalogs(options.currentCatalog, catalogEnvelope.payload),
+        replay: Date.parse(catalogEnvelope.createdAt) <= previousTime,
+        envelope: catalogEnvelope,
+        publicKeyPem,
+    };
+}
+export async function applyCatalogRelease(preview, options = {}) {
+    return withFileLock(catalogReleaseLockPath(), async () => {
+        await recoverPendingTransactions();
+        const verification = verifyEnvelope(preview.envelope, preview.publicKeyPem);
+        if (!verification.valid || verification.fingerprint !== preview.fingerprint)
+            throw new Error("Catalog release preview no longer has a valid trusted signature");
+        validateCatalog(preview.envelope.payload, { requireEvidence: true });
+        let trust = await readCatalogTrustState();
+        const trusted = await readTrustedCatalogState();
+        let exactPending;
+        if (trust?.pendingCreatedAt) {
+            const pendingIsActive = trusted?.envelope.createdAt === trust.pendingCreatedAt &&
+                envelopeDigest(trusted.envelope) === trust.pendingEnvelopeSha256;
+            if (pendingIsActive &&
+                envelopeDigest(preview.envelope) === trust.pendingEnvelopeSha256)
+                exactPending = trusted;
+            const base = { ...trust };
+            delete base.pendingCreatedAt;
+            delete base.pendingEnvelopeSha256;
+            delete base.pendingFirstPin;
+            if (!pendingIsActive && trust.pendingFirstPin) {
+                await rm(catalogTrustPath(), { force: true });
+                trust = undefined;
+            }
+            else {
+                trust = {
+                    ...base,
+                    ...(pendingIsActive
+                        ? {
+                            highWaterCreatedAt: new Date(Math.max(Date.parse(trust.highWaterCreatedAt), Date.parse(trust.pendingCreatedAt))).toISOString(),
+                        }
+                        : {}),
+                };
+                await writeFileAtomically(catalogTrustPath(), `${JSON.stringify(trust, null, 2)}\n`);
+            }
+        }
+        if (exactPending) {
+            if (!exactPending.snapshotId)
+                throw new Error("Finalized the active signed catalog, but its legacy state has no rollback snapshot id");
+            return {
+                path: trustedCatalogPath(),
+                snapshotId: exactPending.snapshotId,
+                diff: diffCatalogs(await loadEffectiveCatalog(), preview.envelope.payload),
+            };
+        }
+        if (trust && verification.fingerprint !== trust.fingerprint)
+            throw new Error(`Catalog signer ${verification.fingerprint} does not match pinned key ${trust.fingerprint}; key rotation requires an explicit trust reset`);
+        const previousTime = Math.max(trusted ? Date.parse(trusted.envelope.createdAt) : -Infinity, trust ? Date.parse(trust.highWaterCreatedAt) : -Infinity);
+        if (Date.parse(preview.envelope.createdAt) <= previousTime)
+            throw new Error("Refusing an older or already-applied signed catalog release");
+        const diff = diffCatalogs(await loadEffectiveCatalog(), preview.envelope.payload);
+        if (diff.removed.length && !options.allowRemovals)
+            throw new Error(`Release removes ${diff.removed.length} package(s); review and pass --allow-removals explicitly`);
+        const now = options.now ?? new Date();
+        const target = trustedCatalogPath();
+        const pinned = trust ??
+            {
+                schemaVersion: 1,
+                fingerprint: verification.fingerprint,
+                publicKeyPem: preview.publicKeyPem,
+                highWaterCreatedAt: new Date(0).toISOString(),
+                pinnedAt: now.toISOString(),
+            };
+        await ensureDirectory(dirname(target));
+        const snapshot = await createSnapshot([target], { persist: false });
+        const transaction = await beginTransaction(snapshot, [target]);
+        const state = {
+            schemaVersion: 1,
+            appliedAt: now.toISOString(),
+            source: preview.source,
+            publicKeyPem: pinned.publicKeyPem,
+            envelope: preview.envelope,
+            snapshotId: snapshot.id,
+        };
+        try {
+            await writeFileAtomically(catalogTrustPath(), `${JSON.stringify({
+                ...pinned,
+                pendingCreatedAt: preview.envelope.createdAt,
+                pendingEnvelopeSha256: envelopeDigest(preview.envelope),
+                ...(!trust ? { pendingFirstPin: true } : {}),
+            }, null, 2)}\n`);
+            await markTransactionCommitting(transaction);
+            await writeFileAtomically(target, `${JSON.stringify(state, null, 2)}\n`);
+            await completeTransaction(transaction, { releaseLock: false });
+            await writeFileAtomically(catalogTrustPath(), `${JSON.stringify({
+                ...pinned,
+                highWaterCreatedAt: preview.envelope.createdAt,
+            }, null, 2)}\n`);
+            await transaction.mutationLock.release();
+        }
+        catch (error) {
+            await rollbackTransaction(transaction);
+            if (!trust)
+                await rm(catalogTrustPath(), { force: true });
+            throw error;
+        }
+        return { path: target, snapshotId: snapshot.id, diff };
+    });
+}
+export function formatCatalogReleasePreview(preview) {
+    return [
+        `Signed catalog: ${preview.packageCount} package(s)`,
+        `Created: ${preview.createdAt}`,
+        `Trusted key: ${preview.fingerprint}`,
+        `Diff: +${preview.diff.added.length} ~${preview.diff.updated.length} -${preview.diff.removed.length} =${preview.diff.unchanged}`,
+        ...(preview.diff.added.length
+            ? [`Added: ${preview.diff.added.join(", ")}`]
+            : []),
+        ...(preview.diff.updated.length
+            ? [`Updated: ${preview.diff.updated.join(", ")}`]
+            : []),
+        ...(preview.diff.removed.length
+            ? [`Removed: ${preview.diff.removed.join(", ")}`]
+            : []),
+        preview.replay
+            ? "Status: older or already applied; apply will be refused"
+            : "Status: signature and evidence valid; no changes applied yet",
+    ].join("\n");
+}