@moewolf/moe-icons-cli 0.0.1 → 0.0.2

package/dist/core/generate.js

@@ -1,25 +1,119 @@
 import { join, relative, resolve } from "node:path";
 import { homedir } from "node:os";
-import { executeGeneratedFilesDir, executeManagedReconcile, } from "../project/install.js";
+import { executeManagedReconcile, safeManagedPath, } from "../project/install.js";
 import { detectProject } from "../project/detect.js";
-import { readMoeiconsConfig } from "../project/config.js";
+import { readMoeiconsConfig, loadConfigDocument, } from "../project/config.js";
+import { catalog as defaultCatalog, parseCatalog } from "../catalog/catalog.js";
+import { toProxyName } from "./icon-names.js";
 import { planGeneratedFiles } from "../generator/generate.js";
 import { ensureClassMergeDependencies, planTailwindIntegration } from "../project/tailwind.js";
-import { CliError, isCliError } from "../errors/index.js";
-import { extractTarGz } from "../project/tar-gz.js";
+import { isCliError } from "../errors/index.js";
+import { extractTarGz, ICON_ARCHIVE_MAX_ENTRIES, ICON_ARCHIVE_MAX_EXPANDED_BYTES, } from "../project/tar-gz.js";
 import { artifactCachePath } from "./free-download.js";
 import { resolveThemes } from "../generator/theme-resolve.js";
+import { loadPinnedBitmapShardAssets } from "./bitmap-shard-resolver.js";
 import { parseInstallMetadata, serializeInstallMetadata, sha256Bytes, } from "../project/install-metadata.js";
 import { withProjectLockSync } from "../project/project-lock.js";
-function hasBitmapThemes(config) {
-    const resolved = resolveThemes(config);
+import { allowLocalTestFromEnv } from "./local-test-env.js";
+import { resolveIconTheme, themeHasIcon } from "./icon-selection.js";
+function hasBitmapThemes(config, sourceCatalog) {
+    const resolved = resolveThemes(config, sourceCatalog);
     return resolved.ok && resolved.themes.some((theme) => theme.kind === "bitmap");
 }
+/**
+ * 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 function loadInstalledCatalogState(projectRoot, fs_, opts = {}) {
+    const catalogPath = join(projectRoot, ".moeicons", "catalog.json");
+    const metadataPath = join(projectRoot, ".moeicons", "install-metadata.json");
+    const catalogExists = fs_.existsSync(catalogPath);
+    const metadataExists = fs_.existsSync(metadataPath);
+    // FIX-22-B: an installed project (metadata present) must have a parseable,
+    // hash-consistent catalog. Only a truly un-installed project falls back to
+    // the bundled contract.
+    if (!catalogExists) {
+        if (metadataExists) {
+            return {
+                status: "invalid",
+                message: "install metadata exists but the catalog is missing; run 'moeicons install' to repair or reinstall",
+            };
+        }
+        return { status: "absent" };
+    }
+    let catalog;
+    let catalogBytes;
+    try {
+        catalogBytes = fs_.readFileSync(catalogPath, "utf8");
+        if (typeof catalogBytes !== "string")
+            return { status: "invalid", message: "installed catalog is not text" };
+        catalog = parseCatalog(JSON.parse(catalogBytes));
+    }
+    catch (error) {
+        return {
+            status: "invalid",
+            message: `installed catalog cannot be parsed: ${error instanceof Error ? error.message : String(error)}; run 'moeicons install' to repair or reinstall`,
+        };
+    }
+    if (!metadataExists) {
+        return {
+            status: "invalid",
+            message: "installed catalog is present without install metadata; run 'moeicons install' to repair or reinstall",
+        };
+    }
+    let metadata;
+    try {
+        const rawMetadata = fs_.readFileSync(metadataPath, "utf8");
+        if (typeof rawMetadata !== "string")
+            throw new Error("metadata is not text");
+        metadata = parseInstallMetadata(rawMetadata, opts);
+    }
+    catch (error) {
+        return {
+            status: "invalid",
+            message: `install metadata is invalid: ${error instanceof Error ? error.message : String(error)}; run 'moeicons install' to repair or reinstall`,
+        };
+    }
+    if (!metadata) {
+        return {
+            status: "invalid",
+            message: "install metadata could not be parsed; run 'moeicons install' to repair or reinstall",
+        };
+    }
+    const actual = sha256Bytes(catalogBytes);
+    const managed = metadata.managedFiles?.[".moeicons/catalog.json"];
+    if (typeof metadata.catalogSha256 !== "string" || typeof managed !== "string") {
+        return {
+            status: "invalid",
+            message: "install metadata is missing the catalog digest; run 'moeicons install' to repair or reinstall",
+        };
+    }
+    if (metadata.catalogSha256 !== managed) {
+        return {
+            status: "invalid",
+            message: "install metadata catalog digest is inconsistent; run 'moeicons install' to repair or reinstall",
+        };
+    }
+    if (actual !== metadata.catalogSha256) {
+        return {
+            status: "invalid",
+            message: "installed catalog hash does not match install metadata; run 'moeicons install' to repair or reinstall",
+        };
+    }
+    return { status: "ok", catalog };
+}
+/** Backwards-compatible accessor used by tests: returns the catalog or undefined. */
+export function loadInstalledCatalog(projectRoot, fs_) {
+    const state = loadInstalledCatalogState(projectRoot, fs_);
+    return state.status === "ok" ? state.catalog : undefined;
+}
 /** Vanilla/Assets generate from raw SVG; bitmap themes need variant binaries. */
-function needsArchiveFiles(config) {
+function needsArchiveFiles(config, sourceCatalog) {
     if (config.target === "vanilla" || config.target === "assets")
         return true;
-    return hasBitmapThemes(config);
+    return hasBitmapThemes(config, sourceCatalog);
 }
 function archiveHasAssetsManifest(files) {
     return Object.keys(files).some((path) => /(?:^|\/)assets\/manifest\.json$/.test(path));
@@ -57,6 +151,87 @@ function readBinaryFile(fs_, path) {
     const data = fs_.readFileSync(path);
     return typeof data === "string" ? Buffer.from(data, "utf8") : new Uint8Array(data);
 }
+/** Unique bitmap variants the config selects, in canonical order. */
+function requiredBitmapVariants(config, sourceCatalog) {
+    const resolved = resolveThemes(config, sourceCatalog);
+    if (!resolved.ok)
+        return [];
+    const variants = resolved.themes
+        .filter((theme) => theme.kind === "bitmap" && theme.variant)
+        .flatMap((theme) => (theme.variant ? [theme.variant] : []));
+    return [...new Map(variants.map((variant) => [variant.resourceVariantId, variant])).values()];
+}
+function archiveHasVariantAssets(archiveFiles, variant, icons) {
+    return icons.every((iconId) => archiveFiles[`assets/${variant.resourceVariantId}/${iconId}.${variant.format}`] !== undefined);
+}
+/**
+ * DEV-G07: a v4 code archive carries no bitmap payload, so bitmap variants are
+ * restored from the pinned shards. Only the config's selected tuples are read;
+ * each cached shard is re-verified against its pinned identity (archive SHA,
+ * manifest SHA, size, dimensions) before any bytes are handed to the generator.
+ */
+function mergePinnedBitmapShardAssets(archiveFiles, effectiveConfig, sourceCatalog, projectRoot, env, fs_) {
+    const variants = requiredBitmapVariants(effectiveConfig, sourceCatalog);
+    const missing = variants.filter((variant) => !archiveHasVariantAssets(archiveFiles, variant, effectiveConfig.icons.filter((iconId) => Object.entries(effectiveConfig.themes).some(([name, theme]) => theme.styleGroup === variant.styleGroupId &&
+        themeHasIcon(effectiveConfig, sourceCatalog ?? defaultCatalog, name, iconId) &&
+        (() => {
+            const resolved = resolveThemes(effectiveConfig, sourceCatalog);
+            return (resolved.ok &&
+                resolved.themes.some((item) => item.theme === name &&
+                    item.variant?.resourceVariantId === variant.resourceVariantId));
+        })()))));
+    if (missing.length === 0)
+        return { ok: true };
+    const metadataPath = join(projectRoot, ".moeicons", "install-metadata.json");
+    if (!fs_.existsSync(metadataPath)) {
+        return {
+            ok: false,
+            errors: ["bitmap shards require an installed pro artifact; run `moeicons install` first"],
+        };
+    }
+    const metadata = parseInstallMetadata(fs_.readFileSync(metadataPath, "utf8"), {
+        allowLocalTest: allowLocalTestFromEnv(env),
+    });
+    if (!metadata) {
+        return {
+            ok: false,
+            errors: ["install metadata is invalid; run 'moeicons install' to repair or reinstall"],
+        };
+    }
+    if (metadata.delivery?.mode === "icons") {
+        return {
+            ok: false,
+            errors: [
+                "selected bitmap resources are missing for this configuration; run `moeicons install` to download the configured icons, format and imageSize",
+            ],
+        };
+    }
+    if (!metadata.bitmapShards || metadata.bitmapShards.length === 0) {
+        return {
+            ok: false,
+            errors: [
+                "bitmap shards are not pinned in install metadata; run 'moeicons install' to repair or reinstall",
+            ],
+        };
+    }
+    const missingTuples = missing.map((variant) => ({
+        styleGroupId: variant.styleGroupId,
+        imageSize: { width: variant.imageSize, height: variant.imageSize },
+        format: variant.format,
+    }));
+    const cacheDir = env.MOEICONS_CACHE_DIR ?? join(homedir(), ".moeicons", "cache");
+    try {
+        const loaded = loadPinnedBitmapShardAssets(metadata.bitmapShards, missingTuples, cacheDir, fs_);
+        Object.assign(archiveFiles, loaded.files);
+        return { ok: true };
+    }
+    catch (error) {
+        return {
+            ok: false,
+            errors: [error instanceof Error ? error.message : "bitmap shard verification failed"],
+        };
+    }
+}
 /**
  * Load installed artifact bytes for generate. Prefers `.moeicons/artifact/<target>/`
  * when that subtree already contains the assets the generator needs (assets target).
@@ -67,15 +242,45 @@ export function loadArchiveFiles(projectRoot, env, fs_, injected) {
     if (injected)
         return { ok: true, files: injected };
     const fixtureTgz = env.MOEICONS_BITMAP_ARCHIVE;
+    // DEV-G08: the aggregate-archive fixture is a local-test-only seam. It must
+    // never bypass the shard contract in a production context, so a set variable
+    // outside a local environment fails closed instead of being silently used.
+    if (fixtureTgz && !allowLocalTestFromEnv(env)) {
+        return { ok: false, reason: "MOEICONS_BITMAP_ARCHIVE is only honored in a local-test context" };
+    }
     if (fixtureTgz && fs_.existsSync(fixtureTgz)) {
         const unpacked = extractTarGz(readBinaryFile(fs_, fixtureTgz), {
-            maxEntries: 20_000,
-            maxExpandedBytes: 64 * 1024 * 1024,
+            maxEntries: ICON_ARCHIVE_MAX_ENTRIES,
+            maxExpandedBytes: ICON_ARCHIVE_MAX_EXPANDED_BYTES,
         });
         if (unpacked.errors.length > 0)
             return { ok: false, reason: unpacked.errors[0] ?? "invalid bitmap archive fixture" };
         return { ok: true, files: unpacked.files };
     }
+    const selectionMetadataPath = join(projectRoot, ".moeicons", "install-metadata.json");
+    if (fs_.existsSync(selectionMetadataPath)) {
+        const pinned = parseInstallMetadata(fs_.readFileSync(selectionMetadataPath, "utf8"), {
+            allowLocalTest: allowLocalTestFromEnv(env),
+        });
+        if (pinned?.delivery?.mode === "icons") {
+            const files = {};
+            for (const [name, hash] of Object.entries(pinned.managedFiles)) {
+                if (!name.startsWith(".moeicons/artifact/"))
+                    continue;
+                const target = safeManagedPath(projectRoot, name).target;
+                if (!fs_.existsSync(target))
+                    return { ok: false, reason: `selected resource missing: ${name}; run moeicons install` };
+                const bytes = readBinaryFile(fs_, target);
+                if (sha256Bytes(bytes) !== hash)
+                    return {
+                        ok: false,
+                        reason: `selected resource modified: ${name}; preserve your edit before reinstalling`,
+                    };
+                files[name.slice(".moeicons/artifact/".length)] = bytes;
+            }
+            return { ok: true, files };
+        }
+    }
     const meta = readInstallMetadata(projectRoot, fs_.readFileSync, fs_.existsSync);
     if (meta?.target) {
         const subtreeRoot = join(projectRoot, ".moeicons", "artifact", meta.target);
@@ -105,7 +310,8 @@ export function loadArchiveFiles(projectRoot, env, fs_, injected) {
             walk(subtreeRoot, "");
             // assets install lands the raw tree; reuse it. Package subtrees (react/vue/
             // vanilla) do not contain assets/manifest.json — fall through to the cache.
-            if (Object.keys(files).length > 0 && (meta.target === "assets" || archiveHasAssetsManifest(files))) {
+            if (Object.keys(files).length > 0 &&
+                (meta.target === "assets" || archiveHasAssetsManifest(files))) {
                 return { ok: true, files };
             }
         }
@@ -115,8 +321,8 @@ export function loadArchiveFiles(projectRoot, env, fs_, injected) {
         const cached = artifactCachePath(cacheDir, meta.artifactVersion, meta.artifactSha256);
         if (fs_.existsSync(cached)) {
             const unpacked = extractTarGz(readBinaryFile(fs_, cached), {
-                maxEntries: 20_000,
-                maxExpandedBytes: 64 * 1024 * 1024,
+                maxEntries: ICON_ARCHIVE_MAX_ENTRIES,
+                maxExpandedBytes: ICON_ARCHIVE_MAX_EXPANDED_BYTES,
             });
             if (unpacked.errors.length > 0)
                 return { ok: false, reason: unpacked.errors[0] ?? "invalid cached artifact" };
@@ -125,49 +331,46 @@ export function loadArchiveFiles(projectRoot, env, fs_, injected) {
     }
     return { ok: false, reason: "installed artifact not found" };
 }
-/**
- * B5: switching the configured target over an existing install is a destructive
- * migration (generated files are replaced and the install subtree changes).
- * Interactive TTY prompts for explicit confirmation; non-interactive/JSON mode
- * fails with VALIDATION_ERROR unless `--yes` was passed (the non-interactive
- * UI resolves `--yes` confirmations to true). Fresh projects with no install
- * metadata never prompt.
- */
-async function confirmTargetSwitch(context, installedTarget, configuredTarget) {
-    const message = `Existing install targets "${installedTarget}" but the config now targets "${configuredTarget}". ` +
-        "Switching targets is a destructive migration that replaces generated files. Continue?";
-    try {
-        return (await context.ui.confirm(message, context.signal)) === true;
-    }
-    catch (error) {
-        if (isCliError(error) && error.code === "NOT_TTY") {
-            throw new CliError("VALIDATION_ERROR", `target switch from "${installedTarget}" to "${configuredTarget}" is destructive and requires confirmation; pass --yes in non-interactive mode`);
-        }
-        throw error;
-    }
-}
+// Keep the public asynchronous command contract while all filesystem work is synchronous.
+// eslint-disable-next-line @typescript-eslint/require-await
 export async function runGenerateUseCase(context, fs_, options = {}) {
     const project = detectProject(context.cwd);
     if (!project)
         return { ok: false, reason: "no-project" };
-    const loaded = readMoeiconsConfig(project.root);
+    const allowLocalTest = allowLocalTestFromEnv(context.env);
+    const catalogState = loadInstalledCatalogState(project.root, fs_, { allowLocalTest });
+    if (catalogState.status === "invalid") {
+        return { ok: false, reason: "validation", errors: [catalogState.message] };
+    }
+    const sourceCatalog = catalogState.status === "ok" ? catalogState.catalog : undefined;
+    const plannedConfigDocument = JSON.stringify(loadConfigDocument(project.root));
+    const loaded = readMoeiconsConfig(project.root, sourceCatalog);
+    if (loaded.kind === "invalid")
+        return { ok: false, reason: "validation", errors: [loaded.message] };
     if (loaded.kind !== "ok")
         return { ok: false, reason: `config state: ${loaded.kind}` };
     const effectiveConfig = options.target
         ? { ...loaded.config, target: options.target }
         : loaded.config;
+    const plannedMetadataPath = join(project.root, ".moeicons", "install-metadata.json");
+    const plannedMetadataText = fs_.existsSync(plannedMetadataPath)
+        ? fs_.readFileSync(plannedMetadataPath, "utf8")
+        : undefined;
     const installedMeta = readInstallMetadata(project.root, fs_.readFileSync, fs_.existsSync);
+    if (!installedMeta) {
+        return {
+            ok: false,
+            reason: "generate requires an installed, version-pinned icon artifact; run 'moeicons install' first",
+        };
+    }
     if (installedMeta?.target && installedMeta.target !== effectiveConfig.target) {
-        const confirmed = await confirmTargetSwitch(context, installedMeta.target, effectiveConfig.target);
-        if (!confirmed)
-            return {
-                ok: false,
-                reason: "cancelled",
-                errors: [`target switch from "${installedMeta.target}" to "${effectiveConfig.target}" cancelled`],
-            };
+        return {
+            ok: false,
+            reason: `installed artifact targets "${installedMeta.target}" while config targets "${effectiveConfig.target}"; set config target to "${effectiveConfig.target}" and run 'moeicons install ${loaded.config.tier} --target ${effectiveConfig.target}' before generate`,
+        };
     }
     let archiveFiles = options.archiveFiles;
-    if (needsArchiveFiles(effectiveConfig) && archiveFiles === undefined) {
+    if (needsArchiveFiles(effectiveConfig, sourceCatalog) && archiveFiles === undefined) {
         const loadedArchive = loadArchiveFiles(project.root, context.env, fs_, undefined);
         if (!loadedArchive.ok) {
             return {
@@ -178,11 +381,22 @@ export async function runGenerateUseCase(context, fs_, options = {}) {
         }
         archiveFiles = loadedArchive.files;
     }
-    const plan = planGeneratedFiles(effectiveConfig, effectiveConfig.outputDir, archiveFiles ? { archiveFiles } : {});
+    if (archiveFiles !== undefined) {
+        const merged = { ...archiveFiles };
+        const shardMerge = mergePinnedBitmapShardAssets(merged, effectiveConfig, sourceCatalog, project.root, context.env, fs_);
+        if (!shardMerge.ok)
+            return { ok: false, reason: "validation", errors: [...shardMerge.errors] };
+        archiveFiles = merged;
+    }
+    const plan = planGeneratedFiles(effectiveConfig, effectiveConfig.outputDir, {
+        ...(archiveFiles ? { archiveFiles } : {}),
+        ...(sourceCatalog ? { catalog: sourceCatalog } : {}),
+    });
     if (!plan.ok)
         return { ok: false, reason: "validation", errors: plan.errors };
     const notes = [];
     const sideFiles = [];
+    const expectedSideFiles = {};
     try {
         const tw = planTailwindIntegration(project.root, loaded.config.outputDir, {
             noTailwind: options.noTailwind === true,
@@ -190,6 +404,10 @@ export async function runGenerateUseCase(context, fs_, options = {}) {
         });
         notes.push(...tw.notes);
         sideFiles.push(...tw.files);
+        for (const file of tw.files)
+            expectedSideFiles[relative(project.root, file.path).replace(/\\/g, "/")] = fs_.existsSync(file.path)
+                ? sha256Bytes(fs_.readFileSync(file.path))
+                : undefined;
     }
     catch (error) {
         if (isCliError(error) && error.code === "TAILWIND_VERSION_UNSUPPORTED") {
@@ -200,6 +418,7 @@ export async function runGenerateUseCase(context, fs_, options = {}) {
     const pkgPath = join(project.root, "package.json");
     if (fs_.existsSync(pkgPath)) {
         const pkgSource = fs_.readFileSync(pkgPath, "utf8");
+        expectedSideFiles["package.json"] = sha256Bytes(pkgSource);
         const target = effectiveConfig.target;
         const deps = target === "react" || target === "vue"
             ? ensureClassMergeDependencies(pkgSource)
@@ -211,21 +430,35 @@ export async function runGenerateUseCase(context, fs_, options = {}) {
         notes.push(...deps.notes);
         if (deps.changed) {
             sideFiles.push({ path: pkgPath, content: deps.nextSource });
+            const installCommand = project.packageManager === "pnpm"
+                ? "pnpm install"
+                : project.packageManager === "yarn"
+                    ? "yarn install"
+                    : project.packageManager === "npm"
+                        ? "npm install"
+                        : "your package manager's install command";
+            notes.push(`package.json changed; run ${installCommand} to update the lockfile and install dependencies`);
         }
     }
     try {
-        if (options.reconcileInstalled) {
+        return withProjectLockSync(project.root, "reload", () => {
+            if (JSON.stringify(loadConfigDocument(project.root)) !== plannedConfigDocument)
+                return { ok: false, reason: "config changed while preparing generate; retry" };
             const metadataPath = join(project.root, ".moeicons", "install-metadata.json");
             if (!fs_.existsSync(metadataPath))
                 return {
                     ok: false,
-                    reason: "managed install metadata is missing; run repair or reinstall",
+                    reason: "managed install metadata is missing; run 'moeicons install' to repair or reinstall",
                 };
-            const metadata = parseInstallMetadata(fs_.readFileSync(metadataPath, "utf8"));
+            const metadata = parseInstallMetadata(fs_.readFileSync(metadataPath, "utf8"), {
+                allowLocalTest,
+            });
+            if (fs_.readFileSync(metadataPath, "utf8") !== plannedMetadataText)
+                return { ok: false, reason: "installation changed while preparing generate; retry" };
             if (!metadata || metadata.tier !== loaded.config.tier)
                 return {
                     ok: false,
-                    reason: "managed install metadata is invalid or does not match config tier; run repair or reinstall",
+                    reason: "managed install metadata is invalid or does not match config tier; run 'moeicons install' to repair or reinstall",
                 };
             for (const [managedPath, expected] of Object.entries(metadata.managedFiles)) {
                 const absolute = join(project.root, managedPath);
@@ -237,17 +470,62 @@ export async function runGenerateUseCase(context, fs_, options = {}) {
             if (metadata.managedFiles[".moeicons/catalog.json"] !== metadata.catalogSha256)
                 return {
                     ok: false,
-                    reason: "managed catalog hash is inconsistent; run repair or reinstall",
+                    reason: "managed catalog hash is inconsistent; run 'moeicons install' to repair or reinstall",
                 };
+            const hasInstalledComponents = Object.keys(metadata.managedFiles).some((path) => path.startsWith(`.moeicons/artifact/${effectiveConfig.target}/`) && path.endsWith(".js"));
+            if (hasInstalledComponents &&
+                (effectiveConfig.target === "react" || effectiveConfig.target === "vue")) {
+                const resolved = resolveThemes(effectiveConfig, sourceCatalog);
+                if (!resolved.ok)
+                    return { ok: false, reason: resolved.errors.join("; ") };
+                for (const iconId of effectiveConfig.icons) {
+                    for (const theme of resolved.themes) {
+                        const selected = resolveIconTheme(effectiveConfig, sourceCatalog, theme.theme, iconId);
+                        if (!selected)
+                            return {
+                                ok: false,
+                                reason: `icon "${iconId}" has no selected variant for theme "${theme.theme}"`,
+                            };
+                        const group = effectiveConfig.themes[selected].styleGroup;
+                        const kind = resolved.themes.find((candidate) => candidate.entry.styleGroup === group)?.kind;
+                        if (kind === "bitmap")
+                            continue;
+                        const suffix = effectiveConfig.target === "vue" ? ".vue.js" : ".js";
+                        const rel = `.moeicons/artifact/${effectiveConfig.target}/${group}/${toProxyName(iconId)}${suffix}`;
+                        if (!fs_.existsSync(join(project.root, rel))) {
+                            return {
+                                ok: false,
+                                reason: `icon "${iconId}" is configured but its ${group} component is not installed (${rel}); run 'moeicons install' before generate`,
+                            };
+                        }
+                    }
+                }
+            }
             const outputPrefix = loaded.config.outputDir.replace(/\\/g, "/").replace(/\/$/, "") + "/";
+            const previousPrefix = (metadata.generatedOutputDir ?? loaded.config.outputDir)
+                .replace(/\\/g, "/")
+                .replace(/\/$/, "") + "/";
             const generated = Object.fromEntries(plan.files.map((file) => [file.path.replace(/\\/g, "/"), file.content]));
+            for (const generatedPath of Object.keys(generated)) {
+                if (fs_.existsSync(join(project.root, generatedPath)) &&
+                    !(generatedPath in metadata.managedFiles)) {
+                    return {
+                        ok: false,
+                        reason: `generated path collides with an unowned user file: ${generatedPath}`,
+                    };
+                }
+            }
             const nextManaged = {};
             for (const [managedPath, hash] of Object.entries(metadata.managedFiles))
-                if (!managedPath.startsWith(outputPrefix))
+                if (!managedPath.startsWith(outputPrefix) && !managedPath.startsWith(previousPrefix))
                     nextManaged[managedPath] = hash;
             for (const [path, content] of Object.entries(generated))
                 nextManaged[path] = sha256Bytes(content);
-            const nextMetadata = { ...metadata, managedFiles: nextManaged };
+            const nextMetadata = {
+                ...metadata,
+                managedFiles: nextManaged,
+                generatedOutputDir: loaded.config.outputDir,
+            };
             const writes = { ...generated };
             for (const file of sideFiles) {
                 const absolute = resolve(file.path);
@@ -257,8 +535,17 @@ export async function runGenerateUseCase(context, fs_, options = {}) {
                 writes[rel] = file.content;
             }
             writes[".moeicons/install-metadata.json"] = serializeInstallMetadata(nextMetadata);
-            const stale = Object.keys(metadata.managedFiles).filter((path) => path.startsWith(outputPrefix) && !(path in generated));
-            withProjectLockSync(project.root, "reload", () => executeManagedReconcile(project.root, writes, stale, fs_));
+            const stale = Object.keys(metadata.managedFiles).filter((path) => (path.startsWith(outputPrefix) || path.startsWith(previousPrefix)) &&
+                !(path in generated));
+            const expectedSha256 = {
+                ...metadata.managedFiles,
+                ...expectedSideFiles,
+                ".moeicons/install-metadata.json": sha256Bytes(fs_.readFileSync(metadataPath)),
+            };
+            for (const path of Object.keys(generated))
+                if (!(path in expectedSha256))
+                    expectedSha256[path] = undefined;
+            executeManagedReconcile(project.root, writes, stale, fs_, { expectedSha256 });
             return {
                 ok: true,
                 files: plan.files.map((file) => file.path),
@@ -266,18 +553,7 @@ export async function runGenerateUseCase(context, fs_, options = {}) {
                     ? { warnings: [...loaded.warnings, ...notes] }
                     : {}),
             };
-        }
-        executeGeneratedFilesDir(plan.files, project.root, loaded.config.outputDir, fs_);
-        for (const file of sideFiles) {
-            fs_.writeFileSync(file.path, file.content);
-        }
-        return {
-            ok: true,
-            files: plan.files.map((file) => file.path),
-            ...(loaded.warnings.length > 0 || notes.length > 0
-                ? { warnings: [...loaded.warnings, ...notes] }
-                : {}),
-        };
+        });
     }
     catch (error) {
         return { ok: false, reason: error instanceof Error ? error.message : String(error) };

package/dist/core/icon-selection.d.ts

@@ -0,0 +1,8 @@
+import { type IconCatalog } from "../catalog/catalog.js";
+import type { MoeiconsConfigFile } from "../project/config.js";
+/** A theme owns a variant only when it is selected and shipped by the catalog. */
+export declare function themeHasIcon(config: MoeiconsConfigFile, catalog: IconCatalog, theme: string, iconId: string): boolean;
+/** Stable fallback: requested theme, default theme, then theme keys in ASCII order.
+ * Unregistered icons and an empty configured variant set never resolve.
+ */
+export declare function resolveIconTheme(config: MoeiconsConfigFile, catalog: IconCatalog, requested: string, iconId: string): string | undefined;

package/dist/core/icon-selection.js

@@ -0,0 +1,19 @@
+import { findCatalogIcon } from "../catalog/catalog.js";
+/** A theme owns a variant only when it is selected and shipped by the catalog. */
+export function themeHasIcon(config, catalog, theme, iconId) {
+    const entry = config.themes[theme];
+    return Boolean(entry && config.icons.includes(iconId) &&
+        (entry.icons === undefined || entry.icons.includes(iconId)) &&
+        findCatalogIcon(iconId, catalog)?.availableIn.includes(entry.styleGroup));
+}
+/** Stable fallback: requested theme, default theme, then theme keys in ASCII order.
+ * Unregistered icons and an empty configured variant set never resolve.
+ */
+export function resolveIconTheme(config, catalog, requested, iconId) {
+    if (themeHasIcon(config, catalog, requested, iconId))
+        return requested;
+    if (config.missingIconPolicy !== "fallback")
+        return undefined;
+    const candidates = [config.defaultTheme, ...Object.keys(config.themes).sort()];
+    return candidates.find((theme) => themeHasIcon(config, catalog, theme, iconId));
+}

package/dist/core/install.d.ts

@@ -15,7 +15,12 @@ export type InstallResult = {
     readonly artifactVersion: string;
     readonly descriptorSha256: string;
     readonly catalogSha256: string;
+    readonly metadataSha256: string;
     readonly cacheHit: boolean;
+    readonly downloadMode?: "icons" | "full";
+    readonly downloadNotes?: readonly string[];
+    readonly networkBytes?: number;
+    readonly selectedFiles?: number;
 } | {
     readonly ok: false;
     readonly reason: "no-project";
@@ -39,6 +44,10 @@ export type InstallResult = {
     readonly ok: false;
     readonly reason: "offline-no-cache";
     readonly message: string;
+} | {
+    readonly ok: false;
+    readonly reason: "disk-full";
+    readonly message: string;
 } | {
     readonly ok: false;
     readonly reason: "validation";
@@ -52,6 +61,11 @@ export interface InstallUseCaseDeps {
     readonly fs: TransactionalFs;
     readonly download: Omit<FreeDownloadIo, "signal">;
 }
+/**
+ * P0-3: the project `types.ts` must re-export a type that actually exists in the
+ * installed `moe-icons` package. Assets have no component type, so it is empty.
+ */
+export declare function typesReexport(tier: "free" | "pro", target: Target, outputDir?: string): string;
 /**
  * Free install: resolve the catalog sourceVersion tag, download/verify the
  * GitHub Release (or a local release fixture), verify the selected target's