@moewolf/moe-icons-cli 0.0.1 → 0.0.3

package/dist/core/free-download.js

@@ -1,15 +1,27 @@
+import { isCliError } from "../errors/index.js";
+import { openSync, readSync, closeSync } from "node:fs";
+import { parseResourceIndex, planSelectedResources, downloadSelectedResources, } from "./selected-resources.js";
+import { parseCatalog } from "../catalog/catalog.js";
+import { validateConfigDocument, } from "../project/config.js";
 import { join } from "node:path";
 import { createHash } from "node:crypto";
 import { downloadArtifact, verifyArtifact } from "../project/install.js";
-import { decodeUtf8, extractTarGz } from "../project/tar-gz.js";
+import { decodeUtf8, extractTarGz, ICON_ARCHIVE_MAX_ENTRIES, ICON_ARCHIVE_MAX_EXPANDED_BYTES, } from "../project/tar-gz.js";
 import { catalog as bundledCatalog } from "../catalog/catalog.js";
-import { cacheKey, FREE_DOWNLOAD_HOSTS, githubReleaseAssetUrl, parseReleaseDescriptor, parseSha256Sidecar, } from "./release-descriptor.js";
+import { cacheArtifact } from "./cache.js";
+import { extractAndVerifyMetadataArchive } from "../metadata/archive.js";
+import { assertLocalCandidateAllowed, cacheKey, FREE_DOWNLOAD_HOSTS, githubReleaseAssetUrl, parseReleaseDescriptor, parseSha256Sidecar, } from "./release-descriptor.js";
 export const DESCRIPTOR_MAX_BYTES = 256 * 1024;
 export const ARTIFACT_MAX_BYTES = 64 * 1024 * 1024;
-export const DOWNLOAD_TIMEOUT_MS = 30_000;
+export const METADATA_MAX_BYTES = 8 * 1024 * 1024;
+// GitHub Release downloads can be slow on constrained or distant networks.
+// Keep the operation bounded, but allow enough time for the 64 MiB Free limit.
+export const DOWNLOAD_TIMEOUT_MS = 120_000;
 export const MAX_REDIRECTS = 5;
 export const DESCRIPTOR_NAME = "release-descriptor.json";
 export const DESCRIPTOR_SHA_NAME = "release-descriptor.json.sha256";
+export const RELEASE_LATEST_NAME = "release-latest.json";
+export const MAX_DOWNLOAD_ATTEMPTS = 3;
 function sha256Hex(bytes) {
     return createHash("sha256").update(bytes).digest("hex");
 }
@@ -38,6 +50,17 @@ function artifactLimits(cliVersion, onProgress, fixtureBaseUrl, timeoutMs = DOWN
         ...(onProgress ? { onProgress } : {}),
     };
 }
+function metadataLimits(cliVersion, onProgress, fixtureBaseUrl, timeoutMs = DOWNLOAD_TIMEOUT_MS) {
+    return {
+        maxBytes: METADATA_MAX_BYTES,
+        timeoutMs,
+        maxRedirects: MAX_REDIRECTS,
+        allowedHosts: fixtureBaseUrl ? [new URL(fixtureBaseUrl).host] : FREE_DOWNLOAD_HOSTS,
+        ...(fixtureBaseUrl ? { allowHttpLoopback: true } : {}),
+        userAgent: userAgent(cliVersion),
+        ...(onProgress ? { onProgress } : {}),
+    };
+}
 function mapDownloadError(code, message) {
     if (code === "HTTP_ERROR" && / 404$/.test(message)) {
         return { ok: false, reason: "not-found", message };
@@ -49,12 +72,50 @@ function mapDownloadError(code, message) {
 function readFixture(io, name) {
     return io.readFileSync(join(io.fixtureDir ?? "", name));
 }
+function parseLatestDescriptorSha(bytes, sourceVersion) {
+    let parsed;
+    try {
+        parsed = JSON.parse(decodeUtf8(bytes));
+    }
+    catch {
+        throw new Error("release-latest.json is not valid JSON");
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        throw new Error("release-latest.json must be an object");
+    }
+    const latest = parsed;
+    if (latest.schemaVersion !== 1 ||
+        latest.tier !== "free" ||
+        latest.fullVersion !== sourceVersion) {
+        throw new Error("release-latest.json identity does not match the requested Free release");
+    }
+    if (typeof latest.descriptorSha256 !== "string" ||
+        !/^[a-f0-9]{64}$/i.test(latest.descriptorSha256)) {
+        throw new Error("release-latest.json descriptorSha256 must be a 64-character SHA-256 hex digest");
+    }
+    return latest.descriptorSha256.toLowerCase();
+}
 export function artifactCachePath(cacheDir, fullVersion, sha256) {
     return join(cacheDir, ...cacheKey(fullVersion, sha256).split("/"), "artifact.tgz");
 }
+export function metadataCachePath(cacheDir, fullVersion, sha256) {
+    return join(cacheDir, ...cacheKey(fullVersion, sha256).split("/"), "metadata.tgz");
+}
 function cachePath(io, fullVersion, sha256) {
     return artifactCachePath(io.cacheDir, fullVersion, sha256);
 }
+/** Best-effort disk-space preflight; missing statfs support is treated as "enough". */
+export function hasEnoughFreeSpace(io, dir, requiredBytes) {
+    try {
+        const state = io.statfs?.(dir);
+        if (state)
+            return state.availableBytes >= requiredBytes;
+    }
+    catch {
+        // statfs unsupported or the dir does not exist yet; assume enough.
+    }
+    return true;
+}
 async function loadBytes(io, filename, limits, tag) {
     if (io.signal.aborted)
         return { ok: false, reason: "cancelled", message: "download cancelled" };
@@ -63,17 +124,35 @@ async function loadBytes(io, filename, limits, tag) {
             return { ok: true, bytes: readFixture(io, filename) };
         }
         catch (error) {
-            return { ok: false, reason: "validation", message: error instanceof Error ? error.message : String(error) };
+            return {
+                ok: false,
+                reason: "validation",
+                message: error instanceof Error ? error.message : String(error),
+            };
         }
     }
-    const url = io.fixtureBaseUrl ? new URL(filename, io.fixtureBaseUrl.endsWith("/") ? io.fixtureBaseUrl : `${io.fixtureBaseUrl}/`).toString() : githubReleaseAssetUrl(tag, filename);
-    const result = await downloadArtifact(url, limits, { fetchFn: io.fetchFn, signal: io.signal });
-    if (!result.ok)
-        return mapDownloadError(result.code, result.message);
-    return { ok: true, bytes: result.bytes };
+    const url = io.fixtureBaseUrl
+        ? new URL(filename, io.fixtureBaseUrl.endsWith("/") ? io.fixtureBaseUrl : `${io.fixtureBaseUrl}/`).toString()
+        : githubReleaseAssetUrl(tag, filename);
+    for (let attempt = 1; attempt <= MAX_DOWNLOAD_ATTEMPTS; attempt += 1) {
+        const result = await downloadArtifact(url, limits, { fetchFn: io.fetchFn, signal: io.signal });
+        if (result.ok)
+            return { ok: true, bytes: result.bytes };
+        if (result.code !== "NETWORK_ERROR" || io.signal.aborted || attempt === MAX_DOWNLOAD_ATTEMPTS) {
+            return mapDownloadError(result.code, result.message);
+        }
+    }
+    return {
+        ok: false,
+        reason: "network",
+        message: `download failed after ${MAX_DOWNLOAD_ATTEMPTS} attempts`,
+    };
 }
 function catalogFromArchive(artifactBytes, catalogFilename, expectedSha) {
-    const unpacked = extractTarGz(artifactBytes, { maxEntries: 20_000, maxExpandedBytes: ARTIFACT_MAX_BYTES });
+    const unpacked = extractTarGz(artifactBytes, {
+        maxEntries: ICON_ARCHIVE_MAX_ENTRIES,
+        maxExpandedBytes: ICON_ARCHIVE_MAX_EXPANDED_BYTES,
+    });
     if (unpacked.errors.length > 0) {
         return { ok: false, reason: "validation", message: unpacked.errors[0] ?? "extract failed" };
     }
@@ -92,27 +171,130 @@ function catalogFromArchive(artifactBytes, catalogFilename, expectedSha) {
     return { ok: true, json: decodeUtf8(catalogBytes) };
 }
 /**
- * Fetch descriptor sidecar → verify descriptor → download free.filename from
- * the descriptor (never guessed) → verify archive + nested catalog checksums.
- * Local `fixtureDir` stands in for a GitHub Release directory.
+ * Download the small metadata archive, verify the whole-archive SHA-256 plus
+ * size and every nested file digest, then cache it atomically.
+ */
+export async function downloadMetadataArchive(io, metadataRef, expectedCatalogSha, expectedTier, expectedVersion, tag, allowLocalTest = false) {
+    const cachedPath = metadataCachePath(io.cacheDir, expectedVersion, metadataRef.sha256);
+    if (io.existsSync(cachedPath)) {
+        const cached = io.readFileSync(cachedPath);
+        const verified = verifyArtifact(cached, metadataRef.sha256);
+        if (verified.ok && cached.byteLength === metadataRef.size) {
+            const extracted = extractAndVerifyMetadataArchive(cached, {
+                expectedCatalogSha,
+                expectedTier,
+                expectedVersion,
+                perFileDigests: metadataRef.files,
+                allowLocalTest,
+            });
+            if (extracted.kind === "ok") {
+                return {
+                    ok: true,
+                    value: { ...extracted.value, metadataSha256: metadataRef.sha256 },
+                    cacheHit: true,
+                };
+            }
+        }
+    }
+    if (!hasEnoughFreeSpace(io, io.cacheDir, metadataRef.size)) {
+        return {
+            ok: false,
+            reason: "disk-full",
+            message: `not enough free disk space for ${metadataRef.size} bytes of metadata`,
+        };
+    }
+    const downloaded = await loadBytes(io, metadataRef.filename, metadataLimits(io.cliVersion, io.onProgress, io.fixtureBaseUrl, io.timeoutMs), tag);
+    if (!downloaded.ok) {
+        if (!io.fixtureDir && downloaded.reason === "network") {
+            return { ok: false, reason: "offline-no-cache", message: downloaded.message };
+        }
+        return downloaded;
+    }
+    const verified = verifyArtifact(downloaded.bytes, metadataRef.sha256);
+    if (!verified.ok) {
+        return {
+            ok: false,
+            reason: "checksum-mismatch",
+            message: `metadata archive SHA-256 mismatch: expected ${metadataRef.sha256}, got ${verified.actual}`,
+        };
+    }
+    if (downloaded.bytes.byteLength !== metadataRef.size) {
+        return {
+            ok: false,
+            reason: "checksum-mismatch",
+            message: `metadata archive size mismatch: expected ${metadataRef.size}, got ${downloaded.bytes.byteLength}`,
+        };
+    }
+    const extracted = extractAndVerifyMetadataArchive(downloaded.bytes, {
+        expectedCatalogSha,
+        expectedTier,
+        expectedVersion,
+        perFileDigests: metadataRef.files,
+        allowLocalTest,
+    });
+    if (extracted.kind !== "ok") {
+        return { ok: false, reason: extracted.reason, message: extracted.message };
+    }
+    try {
+        cacheArtifact(io, cachedPath, downloaded.bytes, metadataRef.sha256);
+    }
+    catch {
+        // Cache is best-effort; the verified bytes are still used for this install.
+    }
+    return {
+        ok: true,
+        value: { ...extracted.value, metadataSha256: metadataRef.sha256 },
+        cacheHit: false,
+    };
+}
+/**
+ * Fetch the published release index → verify descriptor. Older releases that
+ * predate release-latest.json fall back to the descriptor SHA sidecar. Does not
+ * download the code artifact; used by metadata-only sync and by the full download.
  */
-export async function downloadFreeRelease(io, sourceVersion) {
+export async function fetchFreeDescriptor(io, sourceVersion) {
     if (io.signal.aborted)
         return { ok: false, reason: "cancelled", message: "download cancelled" };
     const tag = `v${sourceVersion}`;
-    const shaFile = await loadBytes(io, DESCRIPTOR_SHA_NAME, descriptorLimits(io.cliVersion, io.onProgress, io.fixtureBaseUrl, io.timeoutMs), tag);
-    if (!shaFile.ok) {
-        if (!io.fixtureDir && shaFile.reason === "network") {
-            return { ok: false, reason: "offline-no-cache", message: shaFile.message };
-        }
-        return shaFile;
-    }
+    const limits = descriptorLimits(io.cliVersion, io.onProgress, io.fixtureBaseUrl, io.timeoutMs);
+    const latestFile = await loadBytes(io, RELEASE_LATEST_NAME, limits, tag);
     let expectedDescriptorSha;
-    try {
-        expectedDescriptorSha = parseSha256Sidecar(decodeUtf8(shaFile.bytes));
+    if (latestFile.ok) {
+        try {
+            expectedDescriptorSha = parseLatestDescriptorSha(latestFile.bytes, sourceVersion);
+        }
+        catch (error) {
+            return {
+                ok: false,
+                reason: "validation",
+                message: error instanceof Error ? error.message : String(error),
+            };
+        }
     }
-    catch (error) {
-        return { ok: false, reason: "validation", message: error instanceof Error ? error.message : String(error) };
+    else {
+        if (latestFile.reason !== "not-found") {
+            if (!io.fixtureDir && latestFile.reason === "network") {
+                return { ok: false, reason: "offline-no-cache", message: latestFile.message };
+            }
+            return latestFile;
+        }
+        const shaFile = await loadBytes(io, DESCRIPTOR_SHA_NAME, limits, tag);
+        if (!shaFile.ok) {
+            if (!io.fixtureDir && shaFile.reason === "network") {
+                return { ok: false, reason: "offline-no-cache", message: shaFile.message };
+            }
+            return shaFile;
+        }
+        try {
+            expectedDescriptorSha = parseSha256Sidecar(decodeUtf8(shaFile.bytes));
+        }
+        catch (error) {
+            return {
+                ok: false,
+                reason: "validation",
+                message: error instanceof Error ? error.message : String(error),
+            };
+        }
     }
     const descriptorFile = await loadBytes(io, DESCRIPTOR_NAME, descriptorLimits(io.cliVersion, io.onProgress, io.fixtureBaseUrl, io.timeoutMs), tag);
     if (!descriptorFile.ok)
@@ -128,9 +310,14 @@ export async function downloadFreeRelease(io, sourceVersion) {
     let descriptor;
     try {
         descriptor = parseReleaseDescriptor(descriptorFile.bytes);
+        assertLocalCandidateAllowed(descriptor, Boolean(io.fixtureDir));
     }
     catch (error) {
-        return { ok: false, reason: "validation", message: error instanceof Error ? error.message : String(error) };
+        return {
+            ok: false,
+            reason: "validation",
+            message: error instanceof Error ? error.message : String(error),
+        };
     }
     if (descriptor.fullVersion !== sourceVersion) {
         return {
@@ -139,6 +326,164 @@ export async function downloadFreeRelease(io, sourceVersion) {
             message: `descriptor fullVersion ${descriptor.fullVersion} does not match catalog sourceVersion ${sourceVersion}`,
         };
     }
+    return { ok: true, descriptor, descriptorSha256: actualDescriptorSha, tag };
+}
+/**
+ * Fetch descriptor sidecar → verify descriptor → download free.filename from
+ * the descriptor (never guessed) → verify archive + nested catalog checksums →
+ * download/verify/cache the matching metadata archive.
+ */
+export async function downloadFreeRelease(io, sourceVersion, selection) {
+    const fetched = await fetchFreeDescriptor(io, sourceVersion);
+    if (!fetched.ok)
+        return fetched;
+    const { descriptor, descriptorSha256, tag } = fetched;
+    const metadataRef = descriptor.free.metadata;
+    if (!metadataRef) {
+        return {
+            ok: false,
+            reason: "validation",
+            message: "release descriptor is missing free metadata; the release predates metadata support",
+        };
+    }
+    const mode = selection?.config.downloadMode ?? "auto";
+    let preflightMetadata;
+    if (selection && (mode !== "icons" || descriptor.free.resources)) {
+        try {
+            const metadata = await downloadMetadataArchive(io, metadataRef, descriptor.catalog.sha256, "free", descriptor.fullVersion, tag, descriptor.channel === "local-test");
+            if (!metadata.ok)
+                return metadata;
+            const strict = validateConfigDocument(selection.document, parseCatalog(JSON.parse(metadata.value.catalogJson)));
+            if (strict.kind !== "ok")
+                return {
+                    ok: false,
+                    reason: "validation",
+                    message: strict.kind === "invalid" ? strict.message : `config state: ${strict.kind}`,
+                };
+            preflightMetadata = metadata.value;
+        }
+        catch (error) {
+            return {
+                ok: false,
+                reason: io.signal.aborted ? "cancelled" : "validation",
+                message: error instanceof Error ? error.message : String(error),
+            };
+        }
+    }
+    if (selection && mode !== "full" && descriptor.free.resources) {
+        try {
+            const metadata = preflightMetadata
+                ? { ok: true, value: preflightMetadata, cacheHit: true }
+                : await downloadMetadataArchive(io, metadataRef, descriptor.catalog.sha256, "free", descriptor.fullVersion, tag, descriptor.channel === "local-test");
+            if (!metadata.ok)
+                return metadata;
+            const catalog = parseCatalog(JSON.parse(metadata.value.catalogJson));
+            const strict = validateConfigDocument(selection.document, catalog);
+            if (strict.kind !== "ok")
+                return {
+                    ok: false,
+                    reason: "validation",
+                    message: strict.kind === "invalid" ? strict.message : `config state: ${strict.kind}`,
+                };
+            const refs = descriptor.free.resources;
+            const indexCache = join(io.cacheDir, "resources", "free", descriptor.fullVersion, refs.index.sha256, "index.json.gz");
+            let indexBytes = io.existsSync(indexCache)
+                ? io.readFileSync(indexCache)
+                : undefined;
+            if (!indexBytes ||
+                indexBytes.length !== refs.index.size ||
+                sha256Hex(indexBytes) !== refs.index.sha256) {
+                const downloaded = await loadBytes(io, refs.index.filename, {
+                    ...metadataLimits(io.cliVersion, undefined, io.fixtureBaseUrl, io.timeoutMs),
+                    maxBytes: 8 * 1024 * 1024,
+                }, tag);
+                if (!downloaded.ok)
+                    return downloaded;
+                indexBytes = downloaded.bytes;
+            }
+            const index = parseResourceIndex(indexBytes, refs, {
+                version: descriptor.fullVersion,
+                tier: "free",
+                artifactSha256: descriptor.free.sha256,
+            });
+            const plan = planSelectedResources(strict.config, catalog, index);
+            selection.onPlan?.(`Download plan: ${strict.config.target}, ${strict.config.icons.length} registered icons, ${Object.keys(strict.config.themes).length} themes, ${plan.paths.length} resource files, up to ${plan.payloadBytes} compressed bytes (verified cache reduces network traffic).${plan.fallbacks.length ? ` Fallbacks: ${plan.fallbacks.join("; ")}` : ""}`);
+            cacheArtifact(io, indexCache, indexBytes, refs.index.sha256);
+            const fetched = await downloadSelectedResources(index, refs.index.sha256, plan.paths, {
+                io,
+                cacheDir: io.cacheDir,
+                fetch: io.fetchFn,
+                signal: io.signal,
+                allowedHosts: io.fixtureBaseUrl ? [new URL(io.fixtureBaseUrl).host] : FREE_DOWNLOAD_HOSTS,
+                ...(io.fixtureBaseUrl ? { allowLoopback: true } : {}),
+                getBundleUrl: () => Promise.resolve(io.fixtureBaseUrl
+                    ? new URL(refs.bundle.filename, io.fixtureBaseUrl.endsWith("/") ? io.fixtureBaseUrl : `${io.fixtureBaseUrl}/`).toString()
+                    : githubReleaseAssetUrl(tag, refs.bundle.filename)),
+                ...(io.fixtureDir
+                    ? {
+                        readRange: (start, size) => {
+                            const fd = openSync(join(io.fixtureDir, refs.bundle.filename), "r");
+                            try {
+                                const bytes = Buffer.alloc(size);
+                                let read = 0;
+                                while (read < size) {
+                                    const count = readSync(fd, bytes, read, size - read, start + read);
+                                    if (!count)
+                                        throw new Error("truncated resource bundle");
+                                    read += count;
+                                }
+                                return Promise.resolve(bytes);
+                            }
+                            finally {
+                                closeSync(fd);
+                            }
+                        },
+                    }
+                    : {}),
+            });
+            return {
+                ok: true,
+                descriptor,
+                descriptorSha256,
+                tag,
+                artifactBytes: new Uint8Array(),
+                cacheHit: fetched.cacheHits === plan.paths.length,
+                catalogJson: metadata.value.catalogJson,
+                manifestJson: metadata.value.manifestJson,
+                manualMd: metadata.value.manualMd,
+                metadataSha256: metadata.value.metadataSha256,
+                selected: {
+                    ...fetched,
+                    refs,
+                    indexBytes,
+                    payloadBytes: plan.payloadBytes,
+                    fallbacks: plan.fallbacks,
+                },
+            };
+        }
+        catch (error) {
+            return {
+                ok: false,
+                reason: io.signal.aborted || (isCliError(error) && error.code === "CANCELLED")
+                    ? "cancelled"
+                    : isCliError(error) && error.code === "DISK_FULL"
+                        ? "disk-full"
+                        : isCliError(error) && error.code === "NETWORK_ERROR"
+                            ? "network"
+                            : "validation",
+                message: error instanceof Error ? error.message : String(error),
+            };
+        }
+    }
+    if (mode === "icons")
+        return {
+            ok: false,
+            reason: "validation",
+            message: "this release has no selected-resource index; choose a newer release or explicitly set downloadMode=full",
+        };
+    selection?.onPlan?.(mode === "full"
+        ? "Download mode: full (explicitly configured); the complete target archive will be verified before selection."
+        : "This release does not advertise selected downloads; auto uses the verified full archive. Set downloadMode=icons to require selected downloads.");
     const artifactCache = cachePath(io, descriptor.fullVersion, descriptor.free.sha256);
     if (io.existsSync(artifactCache)) {
         const cached = io.readFileSync(artifactCache);
@@ -147,17 +492,32 @@ export async function downloadFreeRelease(io, sourceVersion) {
             const catalog = catalogFromArchive(cached, descriptor.catalog.filename, descriptor.catalog.sha256);
             if (!catalog.ok)
                 return catalog;
+            const metadata = preflightMetadata
+                ? { ok: true, value: preflightMetadata, cacheHit: true }
+                : await downloadMetadataArchive(io, metadataRef, descriptor.catalog.sha256, "free", descriptor.fullVersion, tag, descriptor.channel === "local-test");
+            if (!metadata.ok)
+                return metadata;
             return {
                 ok: true,
                 descriptor,
-                descriptorSha256: actualDescriptorSha,
+                descriptorSha256,
                 artifactBytes: cached,
                 catalogJson: catalog.json,
                 cacheHit: true,
                 tag,
+                metadataSha256: metadata.value.metadataSha256,
+                manifestJson: metadata.value.manifestJson,
+                manualMd: metadata.value.manualMd,
             };
         }
     }
+    if (!hasEnoughFreeSpace(io, io.cacheDir, ARTIFACT_MAX_BYTES + METADATA_MAX_BYTES)) {
+        return {
+            ok: false,
+            reason: "disk-full",
+            message: "not enough free disk space to cache the icon library",
+        };
+    }
     const artifact = await loadBytes(io, descriptor.free.filename, artifactLimits(io.cliVersion, io.onProgress, io.fixtureBaseUrl, io.timeoutMs), tag);
     if (!artifact.ok) {
         if (!io.fixtureDir && artifact.reason === "network") {
@@ -176,16 +536,28 @@ export async function downloadFreeRelease(io, sourceVersion) {
     const catalog = catalogFromArchive(artifact.bytes, descriptor.catalog.filename, descriptor.catalog.sha256);
     if (!catalog.ok)
         return catalog;
-    io.mkdirSync(join(artifactCache, ".."));
-    io.writeFileSync(artifactCache, artifact.bytes);
+    const metadata = preflightMetadata
+        ? { ok: true, value: preflightMetadata, cacheHit: true }
+        : await downloadMetadataArchive(io, metadataRef, descriptor.catalog.sha256, "free", descriptor.fullVersion, tag, descriptor.channel === "local-test");
+    if (!metadata.ok)
+        return metadata;
+    try {
+        cacheArtifact(io, artifactCache, artifact.bytes, descriptor.free.sha256);
+    }
+    catch {
+        // Cache is best-effort; verified bytes are still used for this install.
+    }
     return {
         ok: true,
         descriptor,
-        descriptorSha256: actualDescriptorSha,
+        descriptorSha256,
         artifactBytes: artifact.bytes,
         catalogJson: catalog.json,
         cacheHit: false,
         tag,
+        metadataSha256: metadata.value.metadataSha256,
+        manifestJson: metadata.value.manifestJson,
+        manualMd: metadata.value.manualMd,
     };
 }
 export function bundledSourceVersion() {

package/dist/core/generate.d.ts

@@ -1,5 +1,7 @@
 import { type TransactionalFsWithCopy } from "../project/install.js";
+import { type IconCatalog } from "../catalog/catalog.js";
 import type { CommandContext } from "./context.js";
+import { type InstallMetadataParseOptions } from "../project/install-metadata.js";
 import type { Target } from "../commands/parser.js";
 export type GenerateResult = {
     readonly ok: true;
@@ -12,6 +14,32 @@ export type GenerateResult = {
     readonly errors?: readonly string[];
     readonly code?: string;
 };
+/**
+ * B7A/B5: prefer the catalog written by install / pro-install / library update
+ * (`.moeicons/catalog.json`) over the bundled catalog. The installed catalog
+ * carries the resourceVersion's real style groups (including migrated
+ * `moe-colored` free+pro and bitmap variants), so generate/reconcile must not
+ * validate against a stale bundled allowlist. Missing/corrupt catalogs fall
+ * back to the bundled catalog; the reconcile path still hash-verifies it.
+ */
+export type InstalledCatalogState = {
+    readonly status: "absent";
+} | {
+    readonly status: "ok";
+    readonly catalog: IconCatalog;
+} | {
+    readonly status: "invalid";
+    readonly message: string;
+};
+/**
+ * B7A/B5/DEV-20-02: load the catalog written by install / pro-install / library
+ * update and verify it against the install metadata hash. A missing catalog
+ * falls back to the bundled contract; a corrupt or drifting one must surface a
+ * repair/reinstall error instead of silently switching entitlement semantics.
+ */
+export declare function loadInstalledCatalogState(projectRoot: string, fs_: Pick<TransactionalFsWithCopy, "readFileSync" | "existsSync">, opts?: InstallMetadataParseOptions): InstalledCatalogState;
+/** Backwards-compatible accessor used by tests: returns the catalog or undefined. */
+export declare function loadInstalledCatalog(projectRoot: string, fs_: Pick<TransactionalFsWithCopy, "readFileSync" | "existsSync">): IconCatalog | undefined;
 /**
  * Load installed artifact bytes for generate. Prefers `.moeicons/artifact/<target>/`
  * when that subtree already contains the assets the generator needs (assets target).
@@ -29,5 +57,6 @@ export declare function runGenerateUseCase(context: CommandContext, fs_: Transac
     readonly noTailwind?: boolean;
     readonly target?: Target;
     readonly archiveFiles?: Readonly<Record<string, Uint8Array>>;
+    /** Kept for older callers; installed resources always reconcile through metadata. */
     readonly reconcileInstalled?: boolean;
 }): Promise<GenerateResult>;