@moewolf/moe-icons-cli 0.0.1 → 0.0.3

package/dist/core/install.js

@@ -1,10 +1,30 @@
+import { EMPTY_DOWNLOAD_SELECTION_MESSAGE } from "./selected-resources.js";
 import { createInstallPlan, executeInstallPlan } from "../project/install.js";
 import { detectProject } from "../project/detect.js";
-import { readMoeiconsConfig } from "../project/config.js";
+import { readMoeiconsConfig, loadConfigDocument } from "../project/config.js";
+import { CliError, isCliError } from "../errors/index.js";
 import { bundledSourceVersion, downloadFreeRelease } from "./free-download.js";
 import { serializeInstallMetadata, sha256Bytes } from "../project/install-metadata.js";
 import { withProjectLock } from "../project/project-lock.js";
-import { selectTargetSubtree } from "./target-subtree.js";
+import { configuredComponentFiles, selectTargetSubtree, computeSubtreeHash, } from "./target-subtree.js";
+import { parseCatalog } from "../catalog/catalog.js";
+import { posix } from "node:path";
+/**
+ * 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 function typesReexport(tier, target, outputDir = "src/moeicons") {
+    void tier;
+    const from = posix.relative(outputDir.replace(/\\/g, "/"), `.moeicons/artifact/${target}/types`);
+    const specifier = from.startsWith(".") ? from : `./${from}`;
+    if (target === "react")
+        return `export type { ReactIconProps } from "${specifier}";\n`;
+    if (target === "vue")
+        return `export type { VueIconProps } from "${specifier}";\n`;
+    if (target === "vanilla")
+        return `export type { VanillaIconOptions } from "${specifier}";\n`;
+    return "export {};\n";
+}
 function normalizeGroup(group) {
     if (group === undefined || group === "free")
         return "free";
@@ -25,7 +45,14 @@ export async function runInstallUseCase(context, deps, options) {
         return { ok: false, reason: "no-project" };
     const groupArg = options.group;
     if (groupArg !== undefined && groupArg !== "free" && groupArg !== "pro" && groupArg !== "ent") {
-        return { ok: false, reason: "validation", message: `unknown install group: ${groupArg}` };
+        // AUD-CL-01: single style-group install (`moeicons install <styleGroupId>`)
+        // is not supported. Fail closed with explicit guidance instead of silently
+        // treating an unknown group as Free.
+        return {
+            ok: false,
+            reason: "validation",
+            message: `unknown install group "${groupArg}"; single style-group install is not supported — run "moeicons install free" or "moeicons install pro"`,
+        };
     }
     const group = normalizeGroup(groupArg);
     if (group === "pro") {
@@ -35,16 +62,41 @@ export async function runInstallUseCase(context, deps, options) {
             message: "pro install requires the authenticated pro flow",
         };
     }
-    const config = readMoeiconsConfig(project.root);
+    const document = loadConfigDocument(project.root);
+    const plannedConfigDocument = JSON.stringify(document);
+    const config = readMoeiconsConfig(project.root, undefined, { lenientCatalog: true });
     if (config.kind === "invalid" || config.kind === "unsupported") {
         return {
             ok: false,
             reason: "validation",
-            message: config.kind === "invalid" ? config.message : `unsupported config schema version ${config.version}`,
+            message: config.kind === "invalid"
+                ? config.message
+                : `unsupported config schema version ${config.version}`,
         };
     }
+    if (config.kind === "ok" && config.config.tier !== "free")
+        return {
+            ok: false,
+            reason: "validation",
+            message: 'config.tier is pro; run "moeicons install pro" or change tier to free before downloading',
+        };
+    if (config.kind === "ok" && config.config.icons.length === 0)
+        return { ok: false, reason: "validation", message: EMPTY_DOWNLOAD_SELECTION_MESSAGE };
     const target = options.target ?? (config.kind === "ok" ? config.config.target : "react");
-    const downloaded = await downloadFreeRelease({ ...deps.download, signal: context.signal }, options.sourceVersion ?? bundledSourceVersion());
+    if (config.kind === "ok" && config.config.target !== target) {
+        return {
+            ok: false,
+            reason: "validation",
+            message: `config target is "${config.config.target}" but install target is "${target}"; set target to "${target}" in moeicons.config before installing`,
+        };
+    }
+    const downloaded = await downloadFreeRelease({ ...deps.download, signal: context.signal }, options.sourceVersion ?? bundledSourceVersion(), config.kind === "ok"
+        ? {
+            config: config.config,
+            document,
+            onPlan: (message) => context.ui.note(message, context.signal),
+        }
+        : undefined);
     if (!downloaded.ok) {
         return downloaded.reason === "cancelled"
             ? { ok: false, reason: "cancelled", message: downloaded.message }
@@ -59,21 +111,52 @@ export async function runInstallUseCase(context, deps, options) {
             message: "downloaded release identity changed after version check; retry the update",
         };
     }
-    const subtree = selectTargetSubtree(downloaded.artifactBytes, downloaded.descriptor.free, target);
+    const selectedTarget = downloaded.selected
+        ? Object.fromEntries(Object.entries(downloaded.selected.files)
+            .filter(([path]) => path.startsWith(`${target}/`))
+            .map(([path, bytes]) => [path.slice(target.length + 1), bytes]))
+        : undefined;
+    const subtree = selectedTarget
+        ? { ok: true, target, files: selectedTarget, ...computeSubtreeHash(selectedTarget) }
+        : selectTargetSubtree(downloaded.artifactBytes, downloaded.descriptor.free, target);
     if (!subtree.ok) {
         return subtree.reason === "checksum-mismatch"
             ? { ok: false, reason: "checksum-mismatch", message: subtree.message }
             : { ok: false, reason: "validation", message: subtree.message };
     }
+    let installedFiles;
+    try {
+        installedFiles = downloaded.selected
+            ? subtree.files
+            : configuredComponentFiles(subtree.files, target, config.kind === "ok" ? config.config : undefined, parseCatalog(JSON.parse(downloaded.catalogJson)));
+    }
+    catch (error) {
+        return {
+            ok: false,
+            reason: "validation",
+            message: error instanceof Error ? error.message : String(error),
+        };
+    }
     const catalogJson = downloaded.catalogJson;
+    const outputDir = config.kind === "ok"
+        ? config.config.outputDir.replace(/\\/g, "/").replace(/\/$/, "")
+        : "src/moeicons";
     const files = {
         ".moeicons/catalog.json": catalogJson,
-        "src/moeicons/types.ts": `export type { ReactIconProps } from "moe-icons";\n`,
-        "src/moeicons/.moeicons-free.marker": "free\n",
+        ".moeicons/manifest.json": downloaded.manifestJson,
+        ".moeicons/MANUAL.md": downloaded.manualMd,
+        ".moeicons/artifact/package.json": '{"private":true,"type":"module","sideEffects":false}\n',
+        [`${outputDir}/types.ts`]: typesReexport("free", target, outputDir),
+        [`${outputDir}/.moeicons-free.marker`]: "free\n",
     };
-    for (const [rel, bytes] of Object.entries(subtree.files)) {
+    for (const [rel, bytes] of Object.entries(installedFiles)) {
         files[`.moeicons/artifact/${target}/${rel}`] = bytes;
     }
+    if (downloaded.selected) {
+        files[".moeicons/resource-index.json.gz"] = downloaded.selected.indexBytes;
+        for (const [rel, bytes] of Object.entries(downloaded.selected.files))
+            files[`.moeicons/artifact/${rel}`] = bytes;
+    }
     const managedFiles = Object.fromEntries(Object.entries(files).map(([path, content]) => [path, sha256Bytes(content)]));
     files[".moeicons/install-metadata.json"] = serializeInstallMetadata({
         schemaVersion: 1,
@@ -85,18 +168,36 @@ export async function runInstallUseCase(context, deps, options) {
         artifactSha256: downloaded.descriptor.free.sha256,
         installedAt: context.now().toISOString(),
         managedFiles,
+        ...(downloaded.selected
+            ? {
+                delivery: {
+                    mode: "icons",
+                    indexSha256: downloaded.selected.refs.index.sha256,
+                    bundleSha256: downloaded.selected.refs.bundle.sha256,
+                },
+            }
+            : {}),
         targetSha256: subtree.sha256,
         targetFileCount: subtree.fileCount,
         targetByteCount: subtree.byteCount,
+        // Local-test candidates record the declared model so a later generate can
+        // verify the install state (mirrors the Pro install path).
+        ...(downloaded.descriptor.channel === "local-test"
+            ? { channel: "local-test", publishable: false }
+            : {}),
     });
     const plan = createInstallPlan(project.root, files);
     try {
-        await withProjectLock(project.root, "install", () => executeInstallPlan(plan, deps.fs));
+        await withProjectLock(project.root, "install", () => {
+            if (JSON.stringify(loadConfigDocument(project.root)) !== plannedConfigDocument)
+                throw new CliError("VALIDATION_ERROR", "config changed while preparing install; retry");
+            executeInstallPlan(plan, deps.fs);
+        });
     }
     catch (error) {
         return {
             ok: false,
-            reason: "write-failed",
+            reason: isCliError(error) && error.code === "VALIDATION_ERROR" ? "validation" : "write-failed",
             message: error instanceof Error ? error.message : String(error),
         };
     }
@@ -106,12 +207,30 @@ export async function runInstallUseCase(context, deps, options) {
         packageManager: project.packageManager,
         group: "free",
         target,
-        artifactBytes: downloaded.artifactBytes.byteLength,
+        artifactBytes: downloaded.selected?.payloadBytes ?? downloaded.artifactBytes.byteLength,
+        downloadMode: downloaded.selected ? "icons" : "full",
+        ...(downloaded.selected
+            ? {
+                networkBytes: downloaded.selected.networkBytes,
+                selectedFiles: Object.keys(downloaded.selected.files).length,
+            }
+            : {}),
+        downloadNotes: downloaded.selected?.fallbacks ??
+            (config.kind === "ok" && config.config.downloadMode !== "full"
+                ? [
+                    "This release does not support selected downloads; used the verified full archive. Set downloadMode=icons to require selected downloads.",
+                ]
+                : config.kind === "ok"
+                    ? []
+                    : [
+                        "No config was found; installed the full archive. Run moeicons init, select icons/themes, then reinstall for selected downloads.",
+                    ]),
         planItems: plan.items.length,
         config: config.kind,
         artifactVersion: downloaded.descriptor.fullVersion,
         descriptorSha256: downloaded.descriptorSha256,
         catalogSha256: downloaded.descriptor.catalog.sha256,
+        metadataSha256: downloaded.metadataSha256,
         cacheHit: downloaded.cacheHit,
     };
 }

package/dist/core/library-update.d.ts

@@ -4,7 +4,7 @@ import type { CommandContext } from "./context.js";
 import { type FreeDownloadIo } from "./free-download.js";
 export interface LibraryUpdateDeps {
     readonly fs: TransactionalFsWithCopy;
-    readonly free: Omit<FreeDownloadIo, "signal">;
+    readonly free?: Omit<FreeDownloadIo, "signal">;
     readonly auth: AuthUseCaseDependencies;
     readonly fetch?: typeof fetch;
     readonly allowedProHosts?: readonly string[];
@@ -21,4 +21,8 @@ export declare function runLibraryUpdateUseCase(context: CommandContext, deps: L
     readonly projectRoot: string;
     readonly artifactVersion: string;
     readonly files: readonly string[];
+    readonly downloadMode: "icons" | "full";
+    readonly downloadNotes: readonly string[];
+    readonly networkBytes?: number;
+    readonly selectedFiles?: number;
 }>;

package/dist/core/library-update.js

@@ -1,62 +1,97 @@
+import { assertDownloadSelection } from "./selected-resources.js";
 import { join, relative, resolve } from "node:path";
 import { homedir } from "node:os";
 import { parseCatalog } from "../catalog/catalog.js";
 import { CliError } from "../errors/index.js";
 import { planGeneratedFiles } from "../generator/generate.js";
-import { readMoeiconsConfig } from "../project/config.js";
+import { readMoeiconsConfig, loadConfigDocument, validateConfigDocument, } from "../project/config.js";
 import { detectProject } from "../project/detect.js";
 import { executeManagedReconcile } from "../project/install.js";
 import { parseInstallMetadata, serializeInstallMetadata, sha256Bytes, } from "../project/install-metadata.js";
 import { withProjectLock } from "../project/project-lock.js";
 import { ensureClassMergeDependencies, planTailwindIntegration } from "../project/tailwind.js";
-import { extractTarGz } from "../project/tar-gz.js";
-import { artifactCachePath, downloadFreeRelease } from "./free-download.js";
+import { extractTarGz, ICON_ARCHIVE_MAX_ENTRIES, ICON_ARCHIVE_MAX_EXPANDED_BYTES, } from "../project/tar-gz.js";
+import { artifactCachePath, downloadFreeRelease, metadataCachePath, } from "./free-download.js";
 import { downloadProArtifact } from "./pro-download.js";
-import { selectTargetSubtree } from "./target-subtree.js";
+import { PRO_DOWNLOAD_HOSTS, resolveProDescriptorEndpoint } from "./pro-download.js";
+import { runAccessTokenUseCase } from "./auth.js";
+import { resolveBitmapTuples, resolveConfiguredBitmapShards } from "./bitmap-shard-resolver.js";
+import { mergeBitmapShardCacheManifest, readBitmapShardCacheManifest, writeBitmapShardCacheManifest, } from "./bitmap-shard-cache.js";
+import { configuredComponentFiles, selectTargetSubtree, computeSubtreeHash, } from "./target-subtree.js";
 export async function runLibraryUpdateUseCase(context, deps, expected) {
     const project = detectProject(context.cwd);
     if (!project)
         throw new CliError("VALIDATION_ERROR", "no package.json found in the current directory or parents");
+    const document = loadConfigDocument(project.root);
+    const bootstrap = validateConfigDocument(document, undefined, { lenientCatalog: true });
+    if (bootstrap.kind !== "ok" || bootstrap.config.tier !== expected.tier)
+        throw new CliError("VALIDATION_ERROR", bootstrap.kind === "invalid"
+            ? bootstrap.message
+            : `config.tier must match ${expected.tier}; edit config before updating`);
+    assertDownloadSelection(bootstrap.config);
+    let selected;
     let catalogJson;
     let archiveBytes;
     let artifactSha256;
     let catalogSha256;
+    let manifestJson;
+    let manualMd;
     let tierSource;
     if (expected.tier === "free") {
+        if (!deps.free)
+            throw new CliError("VALIDATION_ERROR", "free release download dependencies are missing");
         const downloaded = await downloadFreeRelease({
             ...deps.free,
             signal: context.signal,
             ...(deps.onProgress ? { onProgress: deps.onProgress } : {}),
-        }, expected.version);
+        }, expected.version, {
+            config: bootstrap.config,
+            document,
+            onPlan: (message) => context.ui.note(message, context.signal),
+        });
         if (!downloaded.ok)
             throw new CliError(downloaded.reason === "cancelled" ? "CANCELLED" : "VALIDATION_ERROR", downloaded.message);
         if (downloaded.descriptorSha256 !== expected.descriptorSha256 ||
             downloaded.descriptor.fullVersion !== expected.version) {
             throw new CliError("VALIDATION_ERROR", "downloaded release identity changed after version check; retry the update");
         }
+        selected = downloaded.selected;
         catalogJson = downloaded.catalogJson;
         archiveBytes = downloaded.artifactBytes;
         artifactSha256 = downloaded.descriptor.free.sha256;
         catalogSha256 = downloaded.descriptor.catalog.sha256;
+        manifestJson = downloaded.manifestJson;
+        manualMd = downloaded.manualMd;
         tierSource = downloaded.descriptor.free;
     }
     else {
         const downloaded = await downloadProArtifact(context, deps.auth, expected, {
+            selection: { config: bootstrap.config, document },
             ...(deps.fetch ? { fetch: deps.fetch } : {}),
             ...(deps.allowedProHosts ? { allowedHosts: deps.allowedProHosts } : {}),
             ...(deps.onProgress ? { onProgress: deps.onProgress } : {}),
         });
+        selected = downloaded.selected;
         catalogJson = downloaded.catalogJson;
         archiveBytes = downloaded.artifactBytes;
         artifactSha256 = downloaded.descriptor.sha256;
         catalogSha256 = downloaded.descriptor.catalogSha256;
+        manifestJson = downloaded.manifestJson;
+        manualMd = downloaded.manualMd;
         tierSource = downloaded.descriptor;
         const cacheDir = context.env.MOEICONS_CACHE_DIR ?? join(homedir(), ".moeicons", "cache");
         const cached = artifactCachePath(cacheDir, downloaded.descriptor.version, downloaded.descriptor.sha256);
-        if (!deps.fs.existsSync(cached)) {
+        if (!selected && !deps.fs.existsSync(cached)) {
             deps.fs.mkdirSync(join(cached, ".."), { recursive: true });
             deps.fs.writeFileSync(cached, downloaded.artifactBytes);
         }
+        if (downloaded.metadataBytes && downloaded.descriptor.metadata) {
+            const metaCached = metadataCachePath(cacheDir, downloaded.descriptor.version, downloaded.descriptor.metadata.sha256);
+            if (!deps.fs.existsSync(metaCached)) {
+                deps.fs.mkdirSync(join(metaCached, ".."), { recursive: true });
+                deps.fs.writeFileSync(metaCached, downloaded.metadataBytes);
+            }
+        }
     }
     let candidateCatalog;
     try {
@@ -69,49 +104,127 @@ export async function runLibraryUpdateUseCase(context, deps, expected) {
         sha256Bytes(catalogJson) !== catalogSha256) {
         throw new CliError("VALIDATION_ERROR", "candidate catalog identity does not match the selected release");
     }
-    const loaded = readMoeiconsConfig(project.root, candidateCatalog);
+    const loaded = validateConfigDocument(document, candidateCatalog);
     if (loaded.kind !== "ok" || loaded.config.tier !== expected.tier)
         throw new CliError("VALIDATION_ERROR", `config is invalid for the ${expected.tier} candidate`);
-    const unpacked = extractTarGz(archiveBytes, {
-        maxEntries: 20_000,
-        maxExpandedBytes: 64 * 1024 * 1024,
-    });
+    const plannedConfig = JSON.stringify(loaded.config);
+    const installMetadataPath = join(project.root, ".moeicons", "install-metadata.json");
+    const plannedMetadata = deps.fs.existsSync(installMetadataPath)
+        ? deps.fs.readFileSync(installMetadataPath, "utf8")
+        : undefined;
+    const unpacked = selected
+        ? { files: selected.files, errors: [] }
+        : extractTarGz(archiveBytes, {
+            maxEntries: ICON_ARCHIVE_MAX_ENTRIES,
+            maxExpandedBytes: ICON_ARCHIVE_MAX_EXPANDED_BYTES,
+        });
     if (unpacked.errors.length)
         throw new CliError("VALIDATION_ERROR", unpacked.errors[0] ?? "invalid artifact");
     const target = loaded.config.target;
-    const subtree = selectTargetSubtree(archiveBytes, tierSource, target);
+    const selectedTarget = selected
+        ? Object.fromEntries(Object.entries(selected.files)
+            .filter(([path]) => path.startsWith(`${target}/`))
+            .map(([path, bytes]) => [path.slice(target.length + 1), bytes]))
+        : undefined;
+    const subtree = selectedTarget
+        ? { ok: true, target, files: selectedTarget, ...computeSubtreeHash(selectedTarget) }
+        : selectTargetSubtree(archiveBytes, tierSource, target);
     if (!subtree.ok)
         throw new CliError("VALIDATION_ERROR", subtree.message);
+    const archiveFiles = { ...unpacked.files };
+    let bitmapPins;
+    let bitmapShardSetSha256;
+    const tuples = resolveBitmapTuples(loaded.config, candidateCatalog);
+    if (!tuples.ok)
+        throw new CliError("VALIDATION_ERROR", tuples.errors.join("; "));
+    if (!selected && tuples.tuples.length > 0 && expected.tier === "pro") {
+        const cacheDir = context.env.MOEICONS_CACHE_DIR ?? join(homedir(), ".moeicons", "cache");
+        const cacheIo = {
+            mkdirSync: (path) => deps.fs.mkdirSync(path, { recursive: true }),
+            writeFileSync: deps.fs.writeFileSync,
+            renameSync: deps.fs.renameSync,
+            existsSync: deps.fs.existsSync,
+            rmSync: deps.fs.rmSync,
+            readFileSync: deps.fs.readFileSync,
+            readdirSync: deps.fs.readdirSync,
+        };
+        const cacheManifest = readBitmapShardCacheManifest(cacheDir, cacheIo);
+        const metadataPath = join(project.root, ".moeicons", "install-metadata.json");
+        const old = deps.fs.existsSync(metadataPath)
+            ? parseInstallMetadata(deps.fs.readFileSync(metadataPath, "utf8"))
+            : undefined;
+        const existingPins = mergeBitmapShardCacheManifest(cacheManifest, old?.bitmapShards ?? []).filter((pin) => pin.resourceVersion === expected.version);
+        const accessToken = await runAccessTokenUseCase(context, deps.auth);
+        const { loopbackHost } = resolveProDescriptorEndpoint(context.env);
+        const allowedHosts = deps.allowedProHosts ??
+            (loopbackHost ? [...PRO_DOWNLOAD_HOSTS, loopbackHost] : PRO_DOWNLOAD_HOSTS);
+        const shards = await resolveConfiguredBitmapShards({
+            config: loaded.config,
+            catalog: candidateCatalog,
+            version: expected.version,
+            descriptorSha256: expected.descriptorSha256,
+            cacheDir,
+            io: cacheIo,
+            accessToken,
+            allowedHosts,
+            existingPins,
+            env: context.env,
+            now: context.now().getTime(),
+            signal: context.signal,
+            ...(deps.fetch ? { fetch: deps.fetch } : {}),
+        });
+        Object.assign(archiveFiles, shards.files);
+        bitmapPins = shards.pins;
+        bitmapShardSetSha256 = shards.bitmapShardSetSha256;
+        writeBitmapShardCacheManifest(cacheDir, cacheIo, mergeBitmapShardCacheManifest(cacheManifest, shards.pins), context.now().getTime());
+    }
     const generated = planGeneratedFiles(loaded.config, loaded.config.outputDir, {
-        archiveFiles: unpacked.files,
+        archiveFiles,
         catalog: candidateCatalog,
     });
     if (!generated.ok)
         throw new CliError("VALIDATION_ERROR", generated.errors.join("; "));
+    const installedFiles = selected
+        ? subtree.files
+        : configuredComponentFiles(subtree.files, target, loaded.config, candidateCatalog);
     const writes = {
         ".moeicons/catalog.json": catalogJson,
+        ".moeicons/manifest.json": manifestJson,
+        ".moeicons/MANUAL.md": manualMd,
+        ".moeicons/artifact/package.json": '{"private":true,"type":"module","sideEffects":false}\n',
         [`${loaded.config.outputDir.replace(/\\/g, "/").replace(/\/$/, "")}/.moeicons-${expected.tier}.marker`]: `${expected.tier}\n`,
     };
     for (const file of generated.files)
         writes[file.path.replace(/\\/g, "/")] = file.content;
-    for (const [rel, bytes] of Object.entries(subtree.files)) {
+    for (const [rel, bytes] of Object.entries(installedFiles)) {
         writes[`.moeicons/artifact/${target}/${rel}`] = bytes;
     }
+    if (selected) {
+        writes[".moeicons/resource-index.json.gz"] = selected.indexBytes;
+        for (const [rel, bytes] of Object.entries(selected.files))
+            writes[`.moeicons/artifact/${rel}`] = bytes;
+    }
     const tailwindPlan = planTailwindIntegration(project.root, loaded.config.outputDir, {
         noTailwind: false,
         target,
     });
+    const expectedSideFiles = {};
     for (const side of tailwindPlan.files) {
         const rel = relative(project.root, resolve(side.path)).replace(/\\/g, "/");
         if (!rel || rel === ".." || rel.startsWith("../"))
             throw new CliError("VALIDATION_ERROR", `side file escapes project: ${side.path}`);
         writes[rel] = side.content;
+        expectedSideFiles[rel] = deps.fs.existsSync(side.path)
+            ? sha256Bytes(deps.fs.readFileSync(side.path))
+            : undefined;
     }
     const pkgPath = join(project.root, "package.json");
     if (deps.fs.existsSync(pkgPath)) {
+        const pkgSource = deps.fs.readFileSync(pkgPath, "utf8");
+        expectedSideFiles["package.json"] = sha256Bytes(pkgSource);
         const dependencyPlan = target === "react" || target === "vue"
-            ? ensureClassMergeDependencies(deps.fs.readFileSync(pkgPath, "utf8"))
-            : { nextSource: deps.fs.readFileSync(pkgPath, "utf8"), changed: false, notes: [] };
+            ? ensureClassMergeDependencies(pkgSource)
+            : { nextSource: pkgSource, changed: false, notes: [] };
         if (dependencyPlan.changed)
             writes["package.json"] = dependencyPlan.nextSource;
     }
@@ -132,13 +245,33 @@ export async function runLibraryUpdateUseCase(context, deps, expected) {
         catalogSha256,
         installedAt: context.now().toISOString(),
         managedFiles,
+        ...(selected
+            ? {
+                delivery: {
+                    mode: "icons",
+                    indexSha256: selected.refs.index.sha256,
+                    bundleSha256: selected.refs.bundle.sha256,
+                },
+            }
+            : {}),
+        generatedOutputDir: loaded.config.outputDir,
         targetSha256: subtree.sha256,
         targetFileCount: subtree.fileCount,
         targetByteCount: subtree.byteCount,
+        ...(bitmapPins && bitmapShardSetSha256
+            ? { bitmapShards: bitmapPins, bitmapShardSetSha256 }
+            : {}),
     };
     writes[".moeicons/install-metadata.json"] = serializeInstallMetadata(nextMetadata);
     await withProjectLock(project.root, "update", () => {
+        const currentConfig = readMoeiconsConfig(project.root, candidateCatalog);
+        if (currentConfig.kind !== "ok" || JSON.stringify(currentConfig.config) !== plannedConfig)
+            throw new CliError("VALIDATION_ERROR", "config changed while preparing update; retry");
         const metadataPath = join(project.root, ".moeicons", "install-metadata.json");
+        if (!plannedMetadata ||
+            !deps.fs.existsSync(metadataPath) ||
+            deps.fs.readFileSync(metadataPath, "utf8") !== plannedMetadata)
+            throw new CliError("VALIDATION_ERROR", "installation changed while preparing update; retry");
         if (!deps.fs.existsSync(metadataPath))
             throw new CliError("VALIDATION_ERROR", "managed install metadata is missing");
         const old = parseInstallMetadata(deps.fs.readFileSync(metadataPath, "utf8"));
@@ -151,11 +284,37 @@ export async function runLibraryUpdateUseCase(context, deps, expected) {
                 throw new CliError("VALIDATION_ERROR", `managed file was modified or removed: ${path}`);
             }
         }
-        executeManagedReconcile(project.root, writes, Object.keys(old.managedFiles).filter((path) => !(path in managedFiles)), deps.fs);
+        for (const path of Object.keys(managedFiles)) {
+            if (deps.fs.existsSync(join(project.root, path)) && !(path in old.managedFiles)) {
+                throw new CliError("VALIDATION_ERROR", `update path collides with an unowned user file: ${path}`);
+            }
+        }
+        executeManagedReconcile(project.root, writes, Object.keys(old.managedFiles).filter((path) => !(path in managedFiles)), deps.fs, {
+            expectedSha256: {
+                ...Object.fromEntries([...Object.keys(writes), ...Object.keys(old.managedFiles)].map((path) => [
+                    path,
+                    old.managedFiles[path] ??
+                        (path === ".moeicons/install-metadata.json"
+                            ? sha256Bytes(plannedMetadata)
+                            : undefined),
+                ])),
+                ...expectedSideFiles,
+            },
+        });
     });
     return {
         projectRoot: project.root,
         artifactVersion: expected.version,
         files: generated.files.map((file) => file.path),
+        downloadMode: selected ? "icons" : "full",
+        downloadNotes: selected?.fallbacks ??
+            (bootstrap.config.downloadMode === "full"
+                ? []
+                : [
+                    "Release does not advertise selected downloads; auto used the verified full archive. Set downloadMode=icons to require selected downloads.",
+                ]),
+        ...(selected
+            ? { networkBytes: selected.networkBytes, selectedFiles: Object.keys(selected.files).length }
+            : {}),
     };
 }

package/dist/core/local-test-env.d.ts

@@ -0,0 +1,24 @@
+/**
+ * A-1b (DEC-A1): a strictly gated seam that lets the packed CLI consume a
+ * declared local-test candidate (`X.Y.Z-test`, channel `local-test`,
+ * `publishable: false`) through the Pro flow, without touching the production
+ * version parsers. `allowLocalTest` is true only when ALL hold:
+ *   - MOEICONS_ENV=local
+ *   - the resolved versions endpoint is loopback HTTP
+ *   - the resolved Pro descriptor endpoint is loopback HTTP
+ * Any other combination fails closed, so a production endpoint returning
+ * `X.Y.Z-test` is still rejected.
+ */
+export declare const LOCAL_TEST_ENV_VALUE = "local";
+export declare function isLoopbackHttpUrl(value: string): boolean;
+export declare function resolveLocalTestContext(env: Readonly<Record<string, string | undefined>>): {
+    readonly allowLocalTest: boolean;
+};
+/**
+ * Read-side local-test context for an already-installed project. The Pro network
+ * seam above is strict; parsing a *local* install metadata file may also be a
+ * Free fixture install driven by `MOEICONS_FREE_RELEASE_DIR` (the existing local
+ * release-directory seam). Both are local-only and never set on a production
+ * endpoint, so they share the read-side allowance.
+ */
+export declare function allowLocalTestFromEnv(env: Readonly<Record<string, string | undefined>>): boolean;

package/dist/core/local-test-env.js

@@ -0,0 +1,43 @@
+import { resolveProDescriptorEndpoint } from "./pro-download.js";
+import { resolveVersionsEndpoint } from "./version-service.js";
+/**
+ * A-1b (DEC-A1): a strictly gated seam that lets the packed CLI consume a
+ * declared local-test candidate (`X.Y.Z-test`, channel `local-test`,
+ * `publishable: false`) through the Pro flow, without touching the production
+ * version parsers. `allowLocalTest` is true only when ALL hold:
+ *   - MOEICONS_ENV=local
+ *   - the resolved versions endpoint is loopback HTTP
+ *   - the resolved Pro descriptor endpoint is loopback HTTP
+ * Any other combination fails closed, so a production endpoint returning
+ * `X.Y.Z-test` is still rejected.
+ */
+export const LOCAL_TEST_ENV_VALUE = "local";
+const LOOPBACK_HOSTS = new Set(["127.0.0.1", "localhost", "::1"]);
+export function isLoopbackHttpUrl(value) {
+    try {
+        const url = new URL(value);
+        return url.protocol === "http:" && LOOPBACK_HOSTS.has(url.hostname);
+    }
+    catch {
+        return false;
+    }
+}
+export function resolveLocalTestContext(env) {
+    if (env.MOEICONS_ENV !== LOCAL_TEST_ENV_VALUE)
+        return { allowLocalTest: false };
+    if (!isLoopbackHttpUrl(resolveVersionsEndpoint(env)))
+        return { allowLocalTest: false };
+    if (!resolveProDescriptorEndpoint(env).allowLoopback)
+        return { allowLocalTest: false };
+    return { allowLocalTest: true };
+}
+/**
+ * Read-side local-test context for an already-installed project. The Pro network
+ * seam above is strict; parsing a *local* install metadata file may also be a
+ * Free fixture install driven by `MOEICONS_FREE_RELEASE_DIR` (the existing local
+ * release-directory seam). Both are local-only and never set on a production
+ * endpoint, so they share the read-side allowance.
+ */
+export function allowLocalTestFromEnv(env) {
+    return resolveLocalTestContext(env).allowLocalTest || env.MOEICONS_FREE_RELEASE_DIR !== undefined;
+}

package/dist/core/metadata-sync.d.ts

@@ -0,0 +1,30 @@
+import { type TransactionalFsWithCopy } from "../project/install.js";
+import type { CommandContext } from "./context.js";
+import type { AuthUseCaseDependencies } from "./auth.js";
+import { type FreeDownloadIo } from "./free-download.js";
+export interface MetadataSyncDeps {
+    readonly fs: TransactionalFsWithCopy;
+    readonly free: Omit<FreeDownloadIo, "signal">;
+    readonly auth: AuthUseCaseDependencies;
+    readonly fetch?: typeof fetch;
+    readonly allowedProHosts?: readonly string[];
+    readonly onProgress?: (event: {
+        readonly downloadedBytes: number;
+        readonly totalBytes?: number;
+    }) => void;
+}
+/**
+ * Metadata-only sync: downloads only the small metadata archive for the
+ * already-installed code version and reconciles `.moeicons/{MANUAL.md,
+ * catalog.json, manifest.json}`. Never downloads the code archive and never
+ * changes the installed code version.
+ */
+export declare function runMetadataSyncUseCase(context: CommandContext, deps: MetadataSyncDeps, options?: {
+    readonly tier?: "free" | "pro";
+}): Promise<{
+    readonly projectRoot: string;
+    readonly tier: "free" | "pro";
+    readonly artifactVersion: string;
+    readonly metadataSha256: string;
+    readonly files: readonly string[];
+}>;