@moewolf/moe-icons-cli 0.0.11 → 0.0.15

package/dist/core/generate.js

@@ -13,6 +13,7 @@ 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 { parsePackageInstallMetadata, serializePackageInstallMetadata } from "../project/package-install-metadata.js";
 import { withProjectLockSync } from "../project/project-lock.js";
 import { allowLocalTestFromEnv } from "./local-test-env.js";
 import { resolveIconTheme, themeHasIcon } from "./icon-selection.js";
@@ -68,7 +69,7 @@ export function loadInstalledCatalogState(projectRoot, fs_, opts = {}) {
         const rawMetadata = fs_.readFileSync(metadataPath, "utf8");
         if (typeof rawMetadata !== "string")
             throw new Error("metadata is not text");
-        metadata = parseInstallMetadata(rawMetadata, opts);
+        metadata = parseInstallMetadata(rawMetadata, opts) ?? parsePackageInstallMetadata(rawMetadata);
     }
     catch (error) {
         return {
@@ -124,24 +125,19 @@ function missingArchiveMessage(config) {
     }
     return "bitmap themes require a downloaded free artifact; run `moeicons install` or set MOEICONS_BITMAP_ARCHIVE";
 }
-function readInstallMetadata(projectRoot, readFileSync, existsSync) {
+function readInstallMetadata(projectRoot, readFileSync, existsSync, opts = {}) {
     const path = join(projectRoot, ".moeicons", "install-metadata.json");
     if (!existsSync(path))
         return undefined;
     try {
-        const parsed = JSON.parse(readFileSync(path, "utf8"));
-        return {
-            ...(typeof parsed.artifactVersion === "string"
-                ? { artifactVersion: parsed.artifactVersion }
-                : {}),
-            ...(typeof parsed.artifactSha256 === "string"
-                ? { artifactSha256: parsed.artifactSha256 }
-                : {}),
-            ...(typeof parsed.target === "string" &&
-                ["react", "vue", "vanilla", "assets"].includes(parsed.target)
-                ? { target: parsed.target }
-                : {}),
-        };
+        const raw = readFileSync(path, "utf8");
+        const parsed = parseInstallMetadata(raw, opts);
+        if (parsed)
+            return { artifactVersion: parsed.artifactVersion, artifactSha256: parsed.artifactSha256, target: parsed.target };
+        const packageMetadata = parsePackageInstallMetadata(raw);
+        if (packageMetadata)
+            return { artifactVersion: packageMetadata.candidate.fullVersion, target: packageMetadata.target };
+        return undefined;
     }
     catch {
         return undefined;
@@ -189,10 +185,17 @@ function mergePinnedBitmapShardAssets(archiveFiles, effectiveConfig, sourceCatal
             errors: ["bitmap shards require an installed pro artifact; run `moeicons install` first"],
         };
     }
-    const metadata = parseInstallMetadata(fs_.readFileSync(metadataPath, "utf8"), {
+    const rawMetadata = fs_.readFileSync(metadataPath, "utf8");
+    const metadata = parseInstallMetadata(rawMetadata, {
         allowLocalTest: allowLocalTestFromEnv(env),
     });
     if (!metadata) {
+        if (parsePackageInstallMetadata(rawMetadata)) {
+            return {
+                ok: false,
+                errors: ["selected bitmap packages are missing for this configuration; run `moeicons install` to download the configured icons, format and imageSize"],
+            };
+        }
         return {
             ok: false,
             errors: ["install metadata is invalid; run 'moeicons install' to repair or reinstall"],
@@ -259,10 +262,10 @@ export async function loadArchiveFiles(projectRoot, env, fs_, injected, signal)
     }
     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 raw = fs_.readFileSync(selectionMetadataPath, "utf8");
+        const parseOptions = { allowLocalTest: allowLocalTestFromEnv(env) };
+        const pinned = parseInstallMetadata(raw, parseOptions) ?? parsePackageInstallMetadata(raw);
+        if (pinned?.schemaVersion === 1 && pinned.delivery?.mode === "icons") {
             const files = {};
             for (const [name, hash] of Object.entries(pinned.managedFiles)) {
                 if (!name.startsWith(".moeicons/artifact/"))
@@ -280,8 +283,23 @@ export async function loadArchiveFiles(projectRoot, env, fs_, injected, signal)
             }
             return { ok: true, files };
         }
+        if (pinned?.schemaVersion === 2) {
+            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);
+    const meta = readInstallMetadata(projectRoot, fs_.readFileSync, fs_.existsSync, { allowLocalTest: allowLocalTestFromEnv(env) });
     if (meta?.target) {
         const subtreeRoot = join(projectRoot, ".moeicons", "artifact", meta.target);
         if (fs_.existsSync(subtreeRoot)) {
@@ -356,7 +374,7 @@ export async function runGenerateUseCase(context, fs_, options = {}) {
     const plannedMetadataText = fs_.existsSync(plannedMetadataPath)
         ? fs_.readFileSync(plannedMetadataPath, "utf8")
         : undefined;
-    const installedMeta = readInstallMetadata(project.root, fs_.readFileSync, fs_.existsSync);
+    const installedMeta = readInstallMetadata(project.root, fs_.readFileSync, fs_.existsSync, { allowLocalTest });
     if (!installedMeta) {
         return {
             ok: false,
@@ -450,12 +468,12 @@ export async function runGenerateUseCase(context, fs_, options = {}) {
                     ok: false,
                     reason: "managed install metadata is missing; run 'moeicons install' to repair or reinstall",
                 };
-            const metadata = parseInstallMetadata(fs_.readFileSync(metadataPath, "utf8"), {
-                allowLocalTest,
-            });
-            if (fs_.readFileSync(metadataPath, "utf8") !== plannedMetadataText)
+            const currentMetadataText = fs_.readFileSync(metadataPath, "utf8");
+            const metadata = parseInstallMetadata(currentMetadataText, { allowLocalTest }) ?? parsePackageInstallMetadata(currentMetadataText);
+            if (currentMetadataText !== plannedMetadataText)
                 return { ok: false, reason: "installation changed while preparing generate; retry" };
-            if (!metadata || metadata.tier !== loaded.config.tier)
+            const metadataTier = metadata?.schemaVersion === 1 ? metadata.tier : metadata?.candidate.tier;
+            if (!metadata || metadataTier !== loaded.config.tier)
                 return {
                     ok: false,
                     reason: "managed install metadata is invalid or does not match config tier; run 'moeicons install' to repair or reinstall",
@@ -521,11 +539,9 @@ export async function runGenerateUseCase(context, fs_, options = {}) {
                     nextManaged[managedPath] = hash;
             for (const [path, content] of Object.entries(generated))
                 nextManaged[path] = sha256Bytes(content);
-            const nextMetadata = {
-                ...metadata,
-                managedFiles: nextManaged,
-                generatedOutputDir: loaded.config.outputDir,
-            };
+            const nextMetadataText = metadata.schemaVersion === 1
+                ? serializeInstallMetadata({ ...metadata, managedFiles: nextManaged, generatedOutputDir: loaded.config.outputDir })
+                : serializePackageInstallMetadata({ ...metadata, managedFiles: nextManaged, generatedOutputDir: loaded.config.outputDir });
             const writes = { ...generated };
             for (const file of sideFiles) {
                 const absolute = resolve(file.path);
@@ -534,7 +550,7 @@ export async function runGenerateUseCase(context, fs_, options = {}) {
                     return { ok: false, reason: `side file escapes project: ${file.path}` };
                 writes[rel] = file.content;
             }
-            writes[".moeicons/install-metadata.json"] = serializeInstallMetadata(nextMetadata);
+            writes[".moeicons/install-metadata.json"] = nextMetadataText;
             const stale = Object.keys(metadata.managedFiles).filter((path) => (path.startsWith(outputPrefix) || path.startsWith(previousPrefix)) &&
                 !(path in generated));
             const expectedSha256 = {

package/dist/core/install.d.ts

@@ -13,14 +13,20 @@ export type InstallResult = {
     readonly planItems: number;
     readonly config: string;
     readonly artifactVersion: string;
-    readonly descriptorSha256: string;
+    readonly descriptorSha256?: string;
+    readonly candidateRootSha256?: string;
+    readonly packageSetSha256?: string;
+    readonly packageCount?: number;
     readonly catalogSha256: string;
     readonly metadataSha256: string;
     readonly cacheHit: boolean;
-    readonly downloadMode?: "icons" | "full";
+    readonly downloadMode?: "icons" | "full" | "packages";
     readonly downloadNotes?: readonly string[];
     readonly networkBytes?: number;
     readonly selectedFiles?: number;
+    readonly cacheHits?: number;
+    readonly metadataCacheHits?: number;
+    readonly transferRetryCount?: number;
 } | {
     readonly ok: false;
     readonly reason: "no-project";

package/dist/core/install.js

@@ -9,6 +9,7 @@ import { withProjectLock } from "../project/project-lock.js";
 import { configuredComponentFiles, selectTargetSubtreeAsync, selectTargetSubtreeFromFiles, computeSubtreeHash, } from "./target-subtree.js";
 import { parseCatalog } from "../catalog/catalog.js";
 import { posix } from "node:path";
+import { runSmallPackageInstall } from "./small-package-install.js";
 /**
  * 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.
@@ -90,6 +91,75 @@ export async function runInstallUseCase(context, deps, options) {
             message: `config target is "${config.config.target}" but install target is "${target}"; set target to "${target}" in moeicons.config before installing`,
         };
     }
+    // Production Free installs use the immutable package-set pointer and exact
+    // configured dependency closure. Aggregate archives remain available only to
+    // the isolated local archive-fixture harness while old fixtures are retired.
+    if (!deps.download.fixtureDir) {
+        if (config.kind !== "ok") {
+            return { ok: false, reason: "validation", message: "run 'moeicons init' and select icons/themes before installing the package set" };
+        }
+        if (config.config.downloadMode === "full") {
+            return { ok: false, reason: "validation", message: "full archive installs are disabled; set downloadMode to icons and select the required resources" };
+        }
+        if (options.expectedDescriptorSha256) {
+            return { ok: false, reason: "validation", message: "legacy descriptor pins cannot identify a package-set candidate; retry through the package-set update command" };
+        }
+        try {
+            const result = await runSmallPackageInstall({
+                projectRoot: project.root,
+                ...(options.sourceVersion ? { fullVersion: options.sourceVersion } : {}),
+                ...(context.env.MOEICONS_API_BASE_URL ? { apiBaseUrl: context.env.MOEICONS_API_BASE_URL } : {}),
+                config: config.config,
+                plannedConfigDocument,
+                fs: deps.fs,
+                cacheDir: deps.download.cacheDir,
+                now: context.now,
+                ...(context.signal ? { signal: context.signal } : {}),
+                ...(deps.download.fetchFn ? { fetchFn: deps.download.fetchFn } : {}),
+                ...(deps.download.fixtureBaseUrl ? { fixtureOrigin: deps.download.fixtureBaseUrl } : {}),
+            });
+            return {
+                ok: true,
+                projectRoot: project.root,
+                packageManager: project.packageManager,
+                group: "free",
+                target,
+                artifactBytes: result.artifactBytes,
+                planItems: result.planItems,
+                config: config.kind,
+                artifactVersion: result.artifactVersion,
+                candidateRootSha256: result.candidateRootSha256,
+                packageSetSha256: result.packageSetSha256,
+                packageCount: result.packageCount,
+                catalogSha256: result.catalogSha256,
+                metadataSha256: result.metadataSha256,
+                cacheHit: result.cacheHit,
+                downloadMode: "packages",
+                downloadNotes: result.fallbacks.map((fallback) => `Theme fallback: ${fallback}`),
+                networkBytes: result.networkBytes,
+                selectedFiles: result.selectedFiles,
+                cacheHits: result.cacheHits,
+                metadataCacheHits: result.metadataCacheHits,
+                transferRetryCount: result.transferRetryCount,
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            if (context.signal?.aborted || /CANCELLED|cancelled/i.test(message))
+                return { ok: false, reason: "cancelled", message };
+            if (/ENOSPC|no space left/i.test(message))
+                return { ok: false, reason: "disk-full", message };
+            if (/HTTP_ERROR[^\n]*\b404\b/i.test(message))
+                return { ok: false, reason: "not-found", message };
+            if (/HTTP_ERROR[^\n]*\b5\d\d\b|NETWORK_ERROR|network|fetch failed|timed out/i.test(message))
+                return { ok: false, reason: "network", message };
+            if (/checksum|SHA-256|digest mismatch|differs from immutable version pointer/i.test(message))
+                return { ok: false, reason: "checksum-mismatch", message };
+            if (/config changed|unsafe|invalid|requires downloadMode|candidate-set:|config package plan:|small package install currently/i.test(message))
+                return { ok: false, reason: "validation", message };
+            return { ok: false, reason: "write-failed", message };
+        }
+    }
     const downloaded = await downloadFreeRelease({ ...deps.download, signal: context.signal }, options.sourceVersion ?? bundledSourceVersion(), config.kind === "ok"
         ? {
             config: config.config,

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

@@ -17,12 +17,17 @@ export declare function runLibraryUpdateUseCase(context: CommandContext, deps: L
     readonly tier: "free" | "pro";
     readonly version: string;
     readonly descriptorSha256: string;
+    readonly packageSetSha256?: string;
 }): Promise<{
     readonly projectRoot: string;
     readonly artifactVersion: string;
     readonly files: readonly string[];
-    readonly downloadMode: "icons" | "full";
+    readonly downloadMode: "icons" | "full" | "packages";
     readonly downloadNotes: readonly string[];
     readonly networkBytes?: number;
     readonly selectedFiles?: number;
+    readonly packageCount?: number;
+    readonly cacheHits?: number;
+    readonly metadataCacheHits?: number;
+    readonly transferRetryCount?: number;
 }>;

package/dist/core/library-update.js

@@ -8,9 +8,11 @@ import { readMoeiconsConfig, loadConfigDocument, validateConfigDocument, } from
 import { detectProject } from "../project/detect.js";
 import { executeManagedReconcile } from "../project/install.js";
 import { parseInstallMetadata, serializeInstallMetadata, sha256Bytes, } from "../project/install-metadata.js";
+import { parsePackageInstallMetadata } from "../project/package-install-metadata.js";
 import { withProjectLock } from "../project/project-lock.js";
 import { ensureClassMergeDependencies, planTailwindIntegration } from "../project/tailwind.js";
 import { extractTarGzAsync, ICON_ARCHIVE_MAX_ENTRIES, ICON_ARCHIVE_MAX_EXPANDED_BYTES, } from "../project/tar-gz.js";
+import { runSmallPackageInstall } from "./small-package-install.js";
 import { artifactCachePath, downloadFreeRelease, metadataCachePath, } from "./free-download.js";
 import { downloadProArtifact } from "./pro-download.js";
 import { PRO_DOWNLOAD_HOSTS, resolveProDescriptorEndpoint } from "./pro-download.js";
@@ -22,6 +24,18 @@ 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 installedMetadataPath = join(project.root, ".moeicons", "install-metadata.json");
+    let packageSetInstalled = false;
+    if (deps.fs.existsSync(installedMetadataPath)) {
+        let schemaVersion;
+        try {
+            const parsed = JSON.parse(deps.fs.readFileSync(installedMetadataPath, "utf8"));
+            if (parsed && typeof parsed === "object" && !Array.isArray(parsed))
+                schemaVersion = parsed.schemaVersion;
+        }
+        catch { /* validated by the normal install path below */ }
+        packageSetInstalled = schemaVersion === 2;
+    }
     const document = loadConfigDocument(project.root);
     const bootstrap = validateConfigDocument(document, undefined, { lenientCatalog: true });
     if (bootstrap.kind !== "ok" || bootstrap.config.tier !== expected.tier)
@@ -29,6 +43,46 @@ export async function runLibraryUpdateUseCase(context, deps, expected) {
             ? bootstrap.message
             : `config.tier must match ${expected.tier}; edit config before updating`);
     assertDownloadSelection(bootstrap.config);
+    if (packageSetInstalled) {
+        const installed = parsePackageInstallMetadata(deps.fs.readFileSync(installedMetadataPath, "utf8"));
+        if (!installed || installed.candidate.tier !== expected.tier) {
+            const tierLabel = expected.tier === "free" ? "Free" : "Pro";
+            throw new CliError("VALIDATION_ERROR", `package-set update requires a valid installed ${tierLabel} candidate`);
+        }
+        if ((expected.tier === "free" && !deps.free) || !expected.packageSetSha256 || !/^[a-f0-9]{64}$/.test(expected.packageSetSha256))
+            throw new CliError("VALIDATION_ERROR", "package-set update requires an exact Worker package-set identity");
+        if (installed.candidate.fullVersion === expected.version && installed.candidate.packageSetSha256 !== expected.packageSetSha256)
+            throw new CliError("VALIDATION_ERROR", "published package-set identity changed for the installed version; refusing replacement");
+        const proAccessToken = expected.tier === "pro" ? await runAccessTokenUseCase(context, deps.auth) : undefined;
+        const result = await runSmallPackageInstall({
+            projectRoot: project.root,
+            fullVersion: expected.version,
+            expectedPackageSetSha256: expected.packageSetSha256,
+            ...(context.env.MOEICONS_API_BASE_URL ? { apiBaseUrl: context.env.MOEICONS_API_BASE_URL } : {}),
+            config: bootstrap.config,
+            plannedConfigDocument: JSON.stringify(document),
+            fs: deps.fs,
+            cacheDir: deps.free?.cacheDir ?? join(homedir(), ".moeicons", "cache"),
+            now: context.now,
+            ...(proAccessToken ? { proAccessToken } : {}),
+            ...(expected.tier === "free" && deps.free?.fixtureBaseUrl ? { fixtureOrigin: deps.free.fixtureBaseUrl } : {}),
+            ...(context.signal ? { signal: context.signal } : {}),
+            ...(deps.fetch ? { fetchFn: deps.fetch } : {}),
+        });
+        return {
+            projectRoot: project.root,
+            artifactVersion: result.artifactVersion,
+            files: result.files,
+            downloadMode: "packages",
+            downloadNotes: result.fallbacks.map((fallback) => `Theme fallback: ${fallback}`),
+            networkBytes: result.networkBytes,
+            selectedFiles: result.selectedFiles,
+            packageCount: result.packageCount,
+            cacheHits: result.cacheHits,
+            metadataCacheHits: result.metadataCacheHits,
+            transferRetryCount: result.transferRetryCount,
+        };
+    }
     let selected;
     let catalogJson;
     let fullArchiveFiles;

package/dist/core/manage.d.ts

@@ -1,4 +1,5 @@
 import { readInstalledResourceState, type InstallMetadata } from "../project/install-metadata.js";
+import type { PackageInstallMetadata } from "../project/package-install-metadata.js";
 import { type PublicLibraryVersions } from "./version-service.js";
 export type LibraryVersionStatus = {
     readonly kind: "installation-invalid";
@@ -11,6 +12,9 @@ export type LibraryVersionStatus = {
     readonly kind: "unavailable";
     readonly metadata: InstallMetadata;
     readonly message: string;
+} | {
+    readonly kind: "package-set-update-check-required";
+    readonly metadata: PackageInstallMetadata;
 } | {
     readonly kind: "current" | "update" | "channel-mismatch" | "remote-older";
     readonly metadata: InstallMetadata;

package/dist/core/manage.js

@@ -5,6 +5,8 @@ export async function getLibraryVersionStatus(projectRoot, configTier, deps = {}
     const installed = (deps.readState ?? readInstalledResourceState)(projectRoot, configTier);
     if (installed.kind !== "ok")
         return { kind: "installation-invalid", message: installed.message };
+    if (installed.metadata.schemaVersion === 2)
+        return { kind: "package-set-update-check-required", metadata: installed.metadata };
     let versions;
     try {
         versions = await (deps.fetchVersions ?? (() => fetchLibraryVersions()))();
@@ -31,6 +33,8 @@ export async function getLibraryVersionStatus(projectRoot, configTier, deps = {}
 export function formatLibraryVersionStatus(status) {
     if (status.kind === "installation-invalid")
         return `Current: invalid / Latest: unavailable / Status: installation invalid (${status.message})`;
+    if (status.kind === "package-set-update-check-required")
+        return `Current: ${status.metadata.candidate.fullVersion} / Latest: unavailable / Status: package-set update check required`;
     if (status.kind === "check-failed" || status.kind === "unavailable")
         return `Current: ${status.metadata.artifactVersion} / Latest: unavailable / Status: ${status.message}`;
     const label = status.kind === "current" ? "up to date" : status.kind === "update" ? "update available" : status.kind === "channel-mismatch" ? "prerelease channel differs" : "remote version is older";

package/dist/core/metadata-sync.js

@@ -2,13 +2,20 @@ import { join } from "node:path";
 import { homedir } from "node:os";
 import { CliError } from "../errors/index.js";
 import { detectProject } from "../project/detect.js";
+import { loadConfigDocument, validateConfigDocument } from "../project/config.js";
 import { parseInstallMetadata, serializeInstallMetadata, sha256Bytes, } from "../project/install-metadata.js";
+import { parsePackageInstallMetadata, serializePackageInstallMetadata } from "../project/package-install-metadata.js";
 import { executeManagedReconcile } from "../project/install.js";
 import { withProjectLock } from "../project/project-lock.js";
 import { cacheArtifact } from "./cache.js";
 import { downloadMetadataArchive, fetchFreeDescriptor, metadataCachePath, } from "./free-download.js";
 import { downloadSignedArtifact } from "./signed-artifact.js";
 import { extractProMetadata, fetchProDescriptor, proSignedDownloadOptions } from "./pro-download.js";
+import { downloadFreeVersionPackages } from "./free-small-package-download.js";
+import { downloadProVersionPackages } from "./pro-small-package-download.js";
+import { runAccessTokenUseCase } from "./auth.js";
+import { packageTargetFiles, planConfigPackagesFromMetadata } from "./config-package-plan.js";
+import { canonicalBytes, sha256 } from "./small-pack/candidate-set.cjs";
 function toCliError(result) {
     return new CliError(result.reason === "cancelled" ? "CANCELLED" : "VALIDATION_ERROR", result.message);
 }
@@ -25,7 +32,18 @@ export async function runMetadataSyncUseCase(context, deps, options = {}) {
     const metadataPath = join(project.root, ".moeicons", "install-metadata.json");
     if (!deps.fs.existsSync(metadataPath))
         throw new CliError("VALIDATION_ERROR", "managed install metadata is missing; run install first");
-    const old = parseInstallMetadata(deps.fs.readFileSync(metadataPath, "utf8"));
+    const rawMetadata = deps.fs.readFileSync(metadataPath, "utf8");
+    let schemaVersion;
+    try {
+        const parsed = JSON.parse(rawMetadata);
+        if (parsed && typeof parsed === "object" && !Array.isArray(parsed))
+            schemaVersion = parsed.schemaVersion;
+    }
+    catch { /* reported as invalid metadata below */ }
+    if (schemaVersion === 2) {
+        return runPackageSetMetadataSync(context, deps, project.root, rawMetadata, options);
+    }
+    const old = parseInstallMetadata(rawMetadata);
     if (!old)
         throw new CliError("VALIDATION_ERROR", "managed install metadata is invalid; run install first");
     const tier = options.tier ?? old.tier;
@@ -95,3 +113,103 @@ export async function runMetadataSyncUseCase(context, deps, options = {}) {
         files: [".moeicons/MANUAL.md", ".moeicons/catalog.json", ".moeicons/manifest.json"],
     };
 }
+async function runPackageSetMetadataSync(context, deps, projectRoot, rawMetadata, options) {
+    const installed = parsePackageInstallMetadata(rawMetadata);
+    if (!installed)
+        throw new CliError("VALIDATION_ERROR", "package-set install metadata is invalid; run install first");
+    const tier = installed.candidate.tier;
+    if (options.tier && options.tier !== tier)
+        throw new CliError("VALIDATION_ERROR", "metadata refresh tier differs from the installed package-set");
+    const document = loadConfigDocument(projectRoot);
+    const bootstrap = validateConfigDocument(document, undefined, { lenientCatalog: true });
+    if (bootstrap.kind !== "ok")
+        throw new CliError("VALIDATION_ERROR", bootstrap.kind === "invalid" ? bootstrap.message : "project config is missing");
+    if (bootstrap.config.tier !== tier || bootstrap.config.target !== installed.target)
+        throw new CliError("VALIDATION_ERROR", "metadata refresh config differs from the installed package-set; run update");
+    const plannedConfigDocument = JSON.stringify(document);
+    const expectedPins = installed.packages
+        .map(({ resourceKey, packageSha256, dependencies }) => ({ resourceKey, packageSha256, dependencies: [...dependencies] }))
+        .sort((a, b) => a.resourceKey.localeCompare(b.resourceKey, "en"));
+    let packagePlan;
+    const writes = Object.create(null);
+    const resolveResourceKeys = async (candidate, loadVerifiedPackage) => {
+        const identity = candidate.root;
+        if (identity.fullVersion !== installed.candidate.fullVersion ||
+            identity.tier !== tier ||
+            identity.packageSetSha256 !== installed.candidate.packageSetSha256 ||
+            identity.sourceCommit !== installed.candidate.sourceCommit ||
+            identity.generatorCommit !== installed.candidate.generatorCommit ||
+            sha256(canonicalBytes(identity)) !== installed.candidate.candidateRootSha256)
+            throw new CliError("VALIDATION_ERROR", "published package-set identity differs from the installed pin; refusing metadata refresh");
+        packagePlan = await planConfigPackagesFromMetadata(bootstrap.config, candidate, loadVerifiedPackage);
+        const actualPins = packagePlan.packages
+            .map(({ resourceKey, packageSha256, dependencies }) => ({ resourceKey, packageSha256, dependencies: [...dependencies] }))
+            .sort((a, b) => a.resourceKey.localeCompare(b.resourceKey, "en"));
+        if (JSON.stringify(actualPins) !== JSON.stringify(expectedPins))
+            throw new CliError("VALIDATION_ERROR", "configured package selection differs from the installed candidate; run update before metadata refresh");
+        return packagePlan.resourceKeys.filter((key) => key.startsWith(`metadata/${tier}/`));
+    };
+    const consume = (row, files) => {
+        if (row.kind !== "metadata")
+            throw new CliError("VALIDATION_ERROR", "metadata refresh selected a non-metadata package");
+        const mapped = packageTargetFiles(row, files, bootstrap.config.target);
+        for (const [path, bytes] of Object.entries(mapped.files)) {
+            const installPath = `.moeicons/package-metadata/${path}`;
+            if (Object.hasOwn(writes, installPath))
+                throw new CliError("VALIDATION_ERROR", "metadata package paths overlap");
+            writes[installPath] = bytes;
+        }
+        return Promise.resolve();
+    };
+    const cacheDir = deps.free.cacheDir ?? join(homedir(), ".moeicons", "cache");
+    const downloadOptions = {
+        cacheDir,
+        fullVersion: installed.candidate.fullVersion,
+        expectedPackageSetSha256: installed.candidate.packageSetSha256,
+        resolveResourceKeys,
+        consume,
+        ...(context.env.MOEICONS_API_BASE_URL ? { apiBaseUrl: context.env.MOEICONS_API_BASE_URL } : {}),
+        ...(deps.fetch ? { fetchFn: deps.fetch } : {}),
+        ...(context.signal ? { signal: context.signal } : {}),
+    };
+    const report = tier === "free"
+        ? await downloadFreeVersionPackages({
+            ...downloadOptions,
+            ...(deps.free.fixtureBaseUrl ? { fixtureOrigin: deps.free.fixtureBaseUrl } : {}),
+        })
+        : await downloadProVersionPackages({
+            ...downloadOptions,
+            accessToken: await runAccessTokenUseCase(context, deps.auth),
+        });
+    if (!packagePlan)
+        throw new CliError("VALIDATION_ERROR", "metadata refresh did not produce a verified package plan");
+    const catalogJson = `${JSON.stringify(packagePlan.catalog, null, 2)}\n`;
+    const catalogSha256 = sha256Bytes(catalogJson);
+    writes[".moeicons/catalog.json"] = catalogJson;
+    const managedFiles = {
+        ...installed.managedFiles,
+        ...Object.fromEntries(Object.entries(writes).map(([path, content]) => [path, sha256Bytes(content)])),
+    };
+    const nextMetadata = {
+        ...installed,
+        catalogSha256,
+        installedAt: context.now().toISOString(),
+        managedFiles,
+    };
+    writes[".moeicons/install-metadata.json"] = serializePackageInstallMetadata(nextMetadata);
+    await withProjectLock(projectRoot, "update", () => {
+        if (deps.fs.readFileSync(join(projectRoot, ".moeicons", "install-metadata.json"), "utf8") !== rawMetadata)
+            throw new CliError("VALIDATION_ERROR", "installed package-set changed during metadata refresh; retry");
+        if (JSON.stringify(loadConfigDocument(projectRoot)) !== plannedConfigDocument)
+            throw new CliError("VALIDATION_ERROR", "config changed during metadata refresh; retry");
+        executeManagedReconcile(projectRoot, writes, [], deps.fs);
+    });
+    return {
+        projectRoot,
+        tier,
+        artifactVersion: installed.candidate.fullVersion,
+        metadataSha256: catalogSha256,
+        files: Object.keys(writes).sort((a, b) => a.localeCompare(b, "en")),
+        networkBytes: report.networkBytes + report.metadataNetworkBytes,
+    };
+}

package/dist/core/pro-download.js

@@ -264,10 +264,24 @@ export function proSignedDownloadOptions(context, deps = {}) {
 export async function downloadProArtifact(context, auth, expected, deps = {}) {
     const fetchFn = deps.fetch ?? fetch;
     const descriptor = await fetchProDescriptor(context, auth, expected, { fetch: fetchFn });
+    const localFixture = descriptor.channel === "local-test" || resolveProDescriptorEndpoint(context.env).allowLoopback;
+    // CI FLOW RULE (S05): tier-wide resource bundles are historical schema only.
+    // Do not fall through to `descriptor.url` when selected packages are absent;
+    // that URL points at the full Pro code archive. New installs must resolve the
+    // small package directory and fetch only the configured group/tuple set.
+    if (!localFixture &&
+        descriptor.resources?.bundle) {
+        throw new CliError("VALIDATION_ERROR", "this release uses the retired full-library package format; install requires the small-package release protocol");
+    }
+    if (deps.selection?.config.downloadMode === "full" && !localFixture) {
+        throw new CliError("VALIDATION_ERROR", 'downloadMode="full" is disabled for published releases; resolve bounded style-group/target packages instead');
+    }
+    const localRangeFixture = descriptor.channel === "local-test" &&
+        resolveProDescriptorEndpoint(context.env).allowLoopback;
     if (deps.selection &&
         deps.selection.config.downloadMode !== "full" &&
         descriptor.resources &&
-        descriptor.channel !== "local-test") {
+        localRangeFixture) {
         const selected = await downloadProSelected(context, auth, descriptor, deps.selection, deps);
         if (selected)
             return {
@@ -278,7 +292,10 @@ export async function downloadProArtifact(context, auth, expected, deps = {}) {
             };
     }
     if (deps.selection?.config.downloadMode === "icons")
-        throw new CliError("VALIDATION_ERROR", "this release/backend does not support selected resources; set downloadMode=full or use a newer release");
+        throw new CliError("VALIDATION_ERROR", "this release/backend does not support bounded selected packages; refusing a full-library fallback");
+    if (!localFixture) {
+        throw new CliError("VALIDATION_ERROR", "published Pro release has no supported bounded package directory; refusing the full-library fallback");
+    }
     context.ui.note(deps.selection?.config.downloadMode === "full"
         ? "Download mode: full (explicitly configured)."
         : "Release does not advertise selected downloads; auto uses the verified full archive. Set downloadMode=icons to require selected downloads.", context.signal);

package/dist/core/pro-install.d.ts

@@ -13,20 +13,26 @@ export declare function runProInstallUseCase(context: CommandContext, deps: {
         readonly totalBytes?: number;
     }) => void;
 }, expected: {
-    readonly version: string;
-    readonly descriptorSha256: string;
+    readonly version?: string;
+    readonly descriptorSha256?: string;
     readonly target?: Target;
     /** A-1b: allow a declared local-test candidate (never true for production). */
     readonly allowLocalTest?: boolean;
 }): Promise<{
     readonly projectRoot: string;
     readonly artifactVersion: string;
-    readonly descriptorSha256: string;
+    readonly descriptorSha256?: string;
+    readonly candidateRootSha256?: string;
+    readonly packageSetSha256?: string;
     readonly catalogSha256: string;
     readonly artifactBytes: number;
-    readonly downloadMode: "icons" | "full";
+    readonly downloadMode: "icons" | "full" | "packages";
     readonly downloadNotes: readonly string[];
     readonly networkBytes?: number;
     readonly selectedFiles?: number;
+    readonly packageCount?: number;
+    readonly cacheHits?: number;
+    readonly metadataCacheHits?: number;
+    readonly transferRetryCount?: number;
 }>;
 export {};