@moewolf/moe-icons-cli 0.0.11 → 0.0.15

package/README.md

@@ -16,8 +16,8 @@ moeicons generate           generate target-specific project files
 moeicons doctor --check     check configuration and integration
 moeicons recover            recover an interrupted transaction
 moeicons init               create moeicons.config.jsonc
-moeicons update metadata    sync MANUAL.md/catalog.json/manifest.json only
-moeicons update             full code + metadata update
+moeicons update metadata    sync metadata for supported legacy installs
+moeicons update             update the installed Free or Pro package set
 moeicons mcp                start the MCP stdio server
 moeicons --version          show version
 moeicons --help             show help
@@ -73,10 +73,12 @@ first, then run `moeicons install free --target <target>` and `moeicons generate
 For React/Vue, installation now keeps only the configured SVG component modules
 and their required files in `.moeicons/artifact`. After adding icon IDs to the
 config, run `moeicons install` again before `moeicons generate`; generate reports
-the missing installed component if this step is skipped. New releases support
-selected-resource downloads as well as full archives; `downloadMode` controls
-this choice. Legacy releases without resource indexes still use a full archive
-in `auto` mode. See Download modes and resource selection below.
+the missing installed component if this step is skipped. Published releases
+must provide bounded selected packages. A legacy descriptor without the new
+package-set contract is rejected; the CLI never downloads a complete tier
+archive as a fallback. See Download modes and resource selection below.
+In this branch, Free and Pro installs resolve their stable package-set identity, verify the root and pages, then download only the selected package closure before the transactional install. Pro requests use the logged-in access token; the Worker checks current entitlement on identity, root, page, and package requests. Pro package cache files are private to the current OS user. `moeicons update` compares the installed package-set identity with the tier's Worker stable pointer and pins the exact set before reconciling files. `moeicons update metadata` refreshes only the selected metadata packages for the exact installed package-set, verifies the installed selection still matches the project config, and transactionally restores the derived catalog without fetching code or icon packages. The global Pro preview warm-up also uses separately addressed packages from the current package set. These changes are local to this branch; the Worker and CLI have not been deployed or published.
+
 Each theme may select a subset of the registered project icons:
 
 ```json
@@ -138,16 +140,21 @@ Installing or updating a tier writes `<project>/.moeicons/`:
 └── artifact/<target>/
 ```
 
-`moeicons update metadata` re-downloads only the small metadata archive for the
-installed code version and reconciles the three files, without touching the
-code artifact.
+`moeicons update metadata` refreshes metadata for a pinned package-set install
+by reading only its selected scoped metadata packages. Legacy installs continue
+to use their version-pinned metadata archive. Neither path changes the installed
+code or resource package selection.
 
 ## Pro resources
 
-After an authenticated login (TTY) the CLI offers a one-time pre-download of the
-full Pro code + metadata. If skipped, the authenticated home screen shows the
-resource state and offers `Download / Update / Repair Pro resources`. Logging
-out keeps cached archives but blocks new unauthenticated installs/updates.
+Project-level Pro installation uses authenticated, selected package sets and
+does not require pre-downloading the full Pro library. The separate global
+`Warm default Pro previews` action downloads only the current package set's
+separately addressed 128-WebP bitmap tuple packages, after showing their total
+compressed size and asking for confirmation. It does not pre-download a Pro
+code archive. Project installs continue to fetch only their configured package
+closure. Logging out keeps cached objects but blocks new package-set installs,
+updates, and Pro preview warm-ups.
 
 ## Security
 
@@ -179,7 +186,8 @@ out keeps cached archives but blocks new unauthenticated installs/updates.
 
 Metadata distribution (`MANUAL-DIST`) implemented: builder-generated manual,
 catalog and manifest, per-tier archives and descriptors, Free bootstrap,
-metadata-only sync, and authenticated Pro pre-download/update.
+metadata-only sync, and authenticated Pro package-set install/update and
+bounded preview warm-up.
 
 ### Download modes and resource selection
 
@@ -202,17 +210,17 @@ Set `downloadMode` in `moeicons.config.jsonc` (schemaVersion 3):
 }
 ```
 
-- `auto` (default): selected resources when the fixed release advertises them. A legacy release without this capability uses the full archive and explains why.
-- `icons`: require selected resources. Unsupported releases, authorization failures, bad ranges and invalid digests stop the operation; they never trigger a full archive download.
-- `full`: download and verify the complete archive, then install the configured target/resources.
+- `auto` (default): resolve only the fixed release's selected package set. A legacy descriptor without that contract fails before resource transfer.
+- `icons`: require selected packages. Unsupported releases, authorization failures, invalid package identities and bad digests stop the operation; they never trigger a full archive download.
+- `full`: retained only for explicit local `-test` fixtures. Published releases reject this mode because tier-wide archives are retired.
 
 `icons` registers the allowed icon IDs. Install/update requires at least one global icon ID; an empty global list stops before version queries or downloads and preserves the existing installation. An individual theme may still use `icons: []`. A theme's `icons` restricts that theme to a subset; omitting it selects every registered ID available in the style group, and `[]` selects none. Fallback chooses the requested theme, then the default theme, then theme names in ASCII order. An icon with no selected variant fails validation. Bitmap themes also select `format` and `imageSize`; changing these fields may require new resources.
 
-The CLI reads the release metadata before planning resources, so validation uses that release's catalog. It shows the target, registered icon/theme counts, required file count and compressed payload budget before reading the data object. Verified cache entries reduce traffic. `--json` reports `downloadMode`, `downloadNotes`, `selectedFiles` and `networkBytes` (resource payload only; descriptor/metadata/index traffic is separate).
+For package-set installs, the CLI reads the Worker identity and candidate root/pages before planning resources, so validation uses that candidate's catalog. It shows the target, registered icon/theme counts, required file count and compressed payload budget before reading selected package objects. Verified cache entries reduce traffic. `--json` reports `downloadMode`, `downloadNotes`, `selectedFiles` and `networkBytes` (resource payload only; identity and metadata traffic is separate).
 
 Run `moeicons install free` or `moeicons install pro` after changing the selected icons, themes, bitmap format or size, then `moeicons generate`. `moeicons update` also reconciles the configuration when the release version is unchanged. Missing resources name the affected path and ask for reinstall; stale resources are removed only if still owned and unmodified. A configuration change during download stops before project writes; retry with the final configuration.
 
-Generation works offline from the project's verified installed resources; `moeicons recover` also needs no network. Install/update still consult the fixed descriptor and metadata, and Pro checks current entitlement. A resource cache hit does not bypass authorization, and there is no offline install flag. Corrupt cache entries are rejected and fetched again online. Interrupted downloads retain only verified cache members; project files change in one recoverable transaction after all required resources have verified.
+Generation works offline from the project's verified installed resources; `moeicons recover` also needs no network. Package-set installs and updates pin a verified tier candidate; every Pro identity and payload read checks current entitlement. A resource cache hit does not bypass the authenticated stable identity check, and there is no offline install flag. Corrupt cache entries are rejected and fetched again online. Interrupted downloads retain only verified cache members; project files change in one recoverable transaction after all required resources have verified.
 
 Version queries have a deadline covering both response headers and body, with bounded JSON sizes. Invalid or unavailable version responses make update fail explicitly. Cache cleanup preserves staging files owned by a live process; disk-full and permission failures report actionable errors.
 

package/dist/cli.js

@@ -17,7 +17,7 @@ import { createCommandUi } from "./ui/create-ui.js";
 import { CLI_VERSION, MOEICONS_BANNER, renderNoticeBox, renderProjectNotice, renderWordmarkText, } from "./ui/banner.js";
 import { createTheme, isThemeEnabled } from "./ui/theme.js";
 import { renderHistoryBar } from "./tui/components.js";
-import { describeAuthEnvironment, runAccountUseCase, runLoginUseCase, runLogoutUseCase, runRemoteAccountUseCase, runSessionStatusUseCase, } from "./core/auth.js";
+import { describeAuthEnvironment, runAccountUseCase, runLoginUseCase, runLogoutUseCase, runRemoteAccountUseCase, runSessionStatusUseCase, runAccessTokenUseCase, } from "./core/auth.js";
 import { formatLibraryVersionStatus, getLibraryVersionStatus } from "./core/manage.js";
 import { runCliUpdateCheck } from "./core/cli-update.js";
 import { fetchLibraryVersions } from "./core/version-service.js";
@@ -25,9 +25,11 @@ import { runProInstallUseCase } from "./core/pro-install.js";
 import { resolveLocalTestContext } from "./core/local-test-env.js";
 import { runLibraryUpdateUseCase } from "./core/library-update.js";
 import { runMetadataSyncUseCase } from "./core/metadata-sync.js";
+import { fetchFreeStablePackageSet } from "./core/free-small-package-download.js";
+import { fetchProStablePackageSet } from "./core/pro-small-package-download.js";
+import { decideUpdate } from "./core/update-policy.js";
 import { runBootstrapUseCase } from "./core/bootstrap.js";
-import { fetchProDescriptor } from "./core/pro-download.js";
-import { proResourceState, runProPredownloadUseCase, runProResourceWarmupUseCase, } from "./core/pro-resources.js";
+import { runProPreviewPackageWarmupUseCase } from "./core/pro-resources.js";
 import { formatBytes } from "./metadata/version.js";
 import { isLocalTestVersion } from "./core/release-descriptor.js";
 import { buildInitPlan, checkRequiresFix, collectSafeFixes, doctorJson, formatDoctorReport, formatPlannedDiffs, plannedDiffsJson, runDoctorApply, runDoctorDiagnose, } from "./core/doctor.js";
@@ -91,6 +93,9 @@ function freeDownloadDeps(runtime) {
         ...(runtime.env.MOEICONS_FREE_RELEASE_DIR
             ? { fixtureDir: runtime.env.MOEICONS_FREE_RELEASE_DIR }
             : {}),
+        ...(runtime.env.MOEICONS_FREE_PACKAGE_SET_FIXTURE_ORIGIN
+            ? { fixtureBaseUrl: runtime.env.MOEICONS_FREE_PACKAGE_SET_FIXTURE_ORIGIN }
+            : {}),
         cacheDir: runtime.env.MOEICONS_CACHE_DIR ?? join(homedir(), ".moeicons", "cache"),
         cliVersion: versionString(),
     };
@@ -241,52 +246,36 @@ async function runLogin(runtime, json, yes) {
     else
         runtime.stdout(`Environment: ${environment}\nLogged in as ${session.accountId}\n`);
     if (!json && runtime.isTTY())
-        await offerProPredownload(runtime);
+        await offerProPreviewWarmup(runtime);
     return 0;
 }
 /**
- * After a successful interactive login, offer to pre-download the full Pro
- * code + metadata. Cancelling or a failed probe never logs the user out.
+ * After login, offer an explicit bounded warm-up of default Pro preview units.
+ * Cancelling or a failed probe never logs the user out.
  */
-async function offerProPredownload(runtime) {
+async function offerProPreviewWarmup(runtime) {
     const context = commandContext(runtime, { json: false, yes: false });
+    const progress = startResourceProgress(context, "Warming Pro preview packages");
     try {
-        const versions = await fetchLibraryVersions({
+        const result = await runProPreviewPackageWarmupUseCase(context, runtime.auth ?? {}, {
             ...(runtime.auth?.fetch ? { fetch: runtime.auth.fetch } : {}),
-            signal: context.signal,
-            env: runtime.env,
+            onPlan: async (plan) => {
+                progress.phase(`${plan.groups} preview groups · ${plan.packages} packages · ${formatBytes(plan.compressedBytes)}`);
+                const accepted = await context.ui.confirm(`Warm ${plan.groups} Pro preview groups (${formatBytes(plan.compressedBytes)} compressed package data)?`, context.signal);
+                if (accepted !== true)
+                    throw new CliError("CANCELLED", "Pro preview warm-up cancelled");
+            },
         });
-        if (!versions.pro) {
-            runtime.stdout("No Pro release is published yet.\n");
-            return;
-        }
-        const descriptor = await fetchProDescriptor(context, runtime.auth ?? {}, { version: versions.pro.version, descriptorSha256: versions.pro.descriptorSha256 }, runtime.auth?.fetch ? { fetch: runtime.auth.fetch } : {});
-        const sizes = `${formatBytes(descriptor.size)} code + ${descriptor.metadata ? formatBytes(descriptor.metadata.size) : "0 B"} metadata`;
-        runtime.stdout(`Pro ${versions.pro.version} available (${sizes}).\n`);
-        const accepted = await context.ui.confirm("Download Pro resources now? (code + metadata)", context.signal);
-        if (accepted !== true) {
-            runtime.stdout("Skipped Pro download; you can download it later from the home screen.\n");
+        progress.stop("Pro preview package warm-up complete");
+        runtime.stdout(`Warmed ${result.groups} Pro preview groups (${result.downloaded} downloaded, ${result.reused} cached).\n`);
+    }
+    catch (error) {
+        progress.stop("Pro preview warm-up stopped");
+        if (error instanceof CliError && error.code === "CANCELLED") {
+            runtime.stdout("Skipped Pro preview warm-up; project installs still fetch only configured packages.\n");
             return;
         }
-        const progress = startResourceProgress(context, "Downloading Pro resources");
-        try {
-            const result = await runProPredownloadUseCase(context, runtime.auth ?? {}, {
-                ...(runtime.auth?.fetch ? { fetch: runtime.auth.fetch } : {}),
-                onProgress: ({ downloadedBytes, totalBytes }) => progress.bytes({ downloadedBytes, ...(totalBytes !== undefined ? { totalBytes } : {}) }),
-            });
-            const warmed = await warmProBitmapShards(runtime, result, runtime.auth?.fetch ? { fetch: runtime.auth.fetch } : {}, progress);
-            progress.stop("Pro resources downloaded");
-            runtime.stdout(`Cached Pro ${result.version} code + metadata.\n`);
-            if (warmed)
-                runtime.stdout(`${warmed}\n`);
-        }
-        catch (error) {
-            progress.stop("Pro download stopped");
-            runtime.stderr(`warning: Pro download failed (${error instanceof Error ? error.message : String(error)}). You can retry from the home screen.\n`);
-        }
-    }
-    catch {
-        // A failed probe must not make login fail.
+        runtime.stderr(`warning: Pro preview warm-up skipped (${error instanceof Error ? error.message : String(error)}).\n`);
     }
 }
 /**
@@ -313,84 +302,34 @@ function startResourceProgress(context, label) {
         stop: (message) => legacy.stop(message),
     };
 }
-/**
- * W2-A: best-effort warm-up of the default bitmap shard set after the Pro code
- * and metadata are cached. Never fails the surrounding download.
- */
-async function warmProBitmapShards(runtime, result, fetchDeps, progress) {
-    if (!result.metadataSha256)
-        return undefined;
-    try {
-        const warm = await runProResourceWarmupUseCase(commandContext(runtime, { json: false, yes: false }), runtime.auth ?? {}, {
-            version: result.version,
-            descriptorSha256: result.descriptorSha256,
-            metadataSha256: result.metadataSha256,
-            catalogSha256: result.catalogSha256,
-            ...fetchDeps,
-            onPlan: (plan) => progress.phase(`Default bitmap shards: ${plan.missing.length} to download, ${plan.reused} cached`),
-            onProgress: (event) => progress.phase(`Shard ${event.index}/${event.total} ${event.phase} — ${event.tuple.styleGroupId} ${event.tuple.imageSize.width}x${event.tuple.imageSize.height} ${event.tuple.format}`),
-        });
-        return `Warmed ${warm.shards} default bitmap shards (${warm.downloaded} downloaded, ${warm.reused} cached).`;
-    }
-    catch (error) {
-        runtime.stderr(`warning: default bitmap shard warm-up skipped (${error instanceof Error ? error.message : String(error)}).\n`);
-        return undefined;
-    }
-}
-/**
- * Home-screen Pro resources flow: show the current cache state and drive the
- * matching action (download / update / repair / verify). Requires auth.
- */
+/** The Pro resource action warms only separately addressed 128-WebP tuple packages. */
 async function runProResources(runtime, yes) {
     const context = commandContext(runtime, { json: false, yes });
-    const fetchDeps = runtime.auth?.fetch ? { fetch: runtime.auth.fetch } : {};
-    const state = await proResourceState(context, runtime.auth ?? {}, fetchDeps);
-    if (state.kind === "unavailable") {
-        runtime.stdout(`Pro resources unavailable: ${state.reason}\n`);
-        return 0;
-    }
-    let action = "";
-    if (state.kind === "current") {
-        runtime.stdout(`Pro resources are up to date (v${state.version}).\n`);
-        return 0;
-    }
-    if (state.kind === "not-cached") {
-        runtime.stdout(`Pro ${state.version}: ${formatBytes(state.codeBytes)} code + ${formatBytes(state.metadataBytes)} metadata.\n`);
-        action = "Download";
-    }
-    else if (state.kind === "outdated") {
-        runtime.stdout(`Pro ${state.version} → ${state.latestVersion}: ${formatBytes(state.codeBytes)} code + ${formatBytes(state.metadataBytes)} metadata.\n`);
-        action = "Update";
-    }
-    else {
-        runtime.stdout(`Pro ${state.version} cache is corrupt; re-downloading.\n`);
-        action = "Repair";
-    }
-    const confirmed = await context.ui.confirm(`${action} Pro resources now? (code + metadata)`, context.signal);
-    if (confirmed !== true) {
-        runtime.stdout("Cancelled; Pro resources were not downloaded.\n");
-        return 0;
-    }
-    const progress = startResourceProgress(context, "Downloading Pro resources");
+    const progress = startResourceProgress(context, "Warming Pro preview packages");
     try {
-        const result = await runProPredownloadUseCase(context, runtime.auth ?? {}, {
-            ...fetchDeps,
-            force: state.kind === "corrupt",
-            onProgress: ({ downloadedBytes, totalBytes }) => progress.bytes({ downloadedBytes, ...(totalBytes !== undefined ? { totalBytes } : {}) }),
+        const result = await runProPreviewPackageWarmupUseCase(context, runtime.auth ?? {}, {
+            ...(runtime.auth?.fetch ? { fetch: runtime.auth.fetch } : {}),
+            onPlan: async (plan) => {
+                progress.phase(`${plan.groups} preview groups · ${plan.packages} packages · ${formatBytes(plan.compressedBytes)}`);
+                const confirmed = await context.ui.confirm(`Warm ${plan.groups} Pro preview groups (${formatBytes(plan.compressedBytes)} compressed package data)?`, context.signal);
+                if (confirmed !== true)
+                    throw new CliError("CANCELLED", "Pro preview warm-up cancelled");
+            },
         });
-        const warmed = await warmProBitmapShards(runtime, result, fetchDeps, progress);
-        progress.stop("Pro resources downloaded");
-        runtime.stdout(`Cached Pro ${result.version} code + metadata.\n`);
-        if (warmed)
-            runtime.stdout(`${warmed}\n`);
+        progress.stop("Pro preview package warm-up complete");
+        runtime.stdout(`Warmed ${result.groups} Pro preview groups (${result.downloaded} downloaded, ${result.reused} cached).\n`);
         return 0;
     }
     catch (error) {
-        progress.stop("Pro download stopped");
+        progress.stop("Pro preview warm-up stopped");
+        if (error instanceof CliError && error.code === "CANCELLED") {
+            runtime.stdout("Cancelled; no Pro preview packages were downloaded.\n");
+            return 0;
+        }
         if (error instanceof CliError && (error.code === "FORBIDDEN" || error.code === "AUTH_ERROR")) {
             throw error;
         }
-        runtime.stderr(`warning: Pro download failed (${error instanceof Error ? error.message : String(error)}). Retry from this menu.\n`);
+        runtime.stderr(`Pro preview warm-up failed (${error instanceof Error ? error.message : String(error)}).\n`);
         return 0;
     }
 }
@@ -411,8 +350,11 @@ async function runAccount(runtime, json) {
     catch (error) {
         remoteError = error;
     }
-    if (json && remoteError)
-        throw remoteError;
+    if (json && remoteError) {
+        if (remoteError instanceof Error)
+            throw remoteError;
+        throw new Error("remote account command failed", { cause: remoteError });
+    }
     const account = { ...session, ...(remote ?? {}) };
     if (json)
         writeJson(runtime, { ok: true, environment, account });
@@ -638,21 +580,10 @@ async function runWizard(runtime, json, yes) {
             session: session.kind,
             ...(historyLine ? { historyLine } : {}),
             getLibraryStatus: getStatus,
-            getProResourceLabel: async () => {
+            getProResourceLabel: () => {
                 if (session.kind !== "authenticated")
-                    return undefined;
-                const state = await proResourceState(context, runtime.auth ?? {}, {
-                    ...(runtime.auth?.fetch ? { fetch: runtime.auth.fetch } : {}),
-                }).catch(() => undefined);
-                if (!state || state.kind === "unavailable")
-                    return undefined;
-                if (state.kind === "not-cached")
-                    return "Download Pro resources";
-                if (state.kind === "outdated")
-                    return `Update Pro resources (${state.version} → ${state.latestVersion})`;
-                if (state.kind === "corrupt")
-                    return "Repair Pro resources";
-                return "Pro resources are up to date";
+                    return Promise.resolve(undefined);
+                return Promise.resolve("Warm default Pro previews");
             },
         });
         if (!result.ok) {
@@ -789,7 +720,7 @@ async function runWizardLogin(runtime, yes) {
         }
     }
 }
-async function runLibraryUpdate(runtime, tier, version, descriptorSha256, json = false) {
+async function runLibraryUpdate(runtime, tier, version, descriptorSha256, json = false, packageSetSha256, preflightIdentityBytes) {
     const context = commandContext(runtime, { json, yes: false });
     // W3-A: a single progress surface. `task` is deliberately NOT used here: the
     // clack adapter implements both with `p.spinner()`, so stacking them would
@@ -812,14 +743,17 @@ async function runLibraryUpdate(runtime, tier, version, descriptorSha256, json =
             auth: runtime.auth ?? {},
             fetch: runtime.auth?.fetch ?? globalThis.fetch.bind(globalThis),
             onProgress: ({ downloadedBytes, totalBytes }) => progress.bytes({ downloadedBytes, ...(totalBytes !== undefined ? { totalBytes } : {}) }),
-        }, { tier, version, descriptorSha256 });
+        }, { tier, version, descriptorSha256, ...(packageSetSha256 ? { packageSetSha256 } : {}) });
+        const output = preflightIdentityBytes === undefined
+            ? result
+            : { ...result, networkBytes: (result.networkBytes ?? 0) + preflightIdentityBytes };
         progress.stop("Icon library update complete");
         if (json)
-            writeJson(runtime, { ok: true, ...result });
+            writeJson(runtime, { ok: true, ...output });
         else {
-            runtime.stdout(`Updated ${tier} artifact to ${result.artifactVersion}; reconciled ${result.files.length} generated files.\n`);
-            runtime.stdout(`Download mode: ${result.downloadMode}${result.selectedFiles !== undefined ? `; ${result.selectedFiles} resource files; ${result.networkBytes} resource bytes received` : ""}.\n`);
-            for (const note of result.downloadNotes)
+            runtime.stdout(`Updated ${tier} artifact to ${output.artifactVersion}; reconciled ${output.files.length} generated files.\n`);
+            runtime.stdout(`Download mode: ${output.downloadMode}${output.selectedFiles !== undefined ? `; ${output.selectedFiles} resource files; ${output.networkBytes} resource bytes received` : ""}.\n`);
+            for (const note of output.downloadNotes)
                 runtime.stdout(`${note}\n`);
         }
         return 0;
@@ -888,6 +822,41 @@ async function runUpdate(runtime, json, yes, metadataOnly) {
         throw new CliError("NETWORK_ERROR", status.message);
     if (status.kind === "installation-invalid")
         throw new CliError("VALIDATION_ERROR", status.message);
+    if (status.kind === "package-set-update-check-required") {
+        const tier = status.metadata.candidate.tier;
+        const identity = tier === "free"
+            ? await fetchFreeStablePackageSet({
+                ...(runtime.env.MOEICONS_API_BASE_URL ? { apiBaseUrl: runtime.env.MOEICONS_API_BASE_URL } : {}),
+                ...(runtime.auth?.fetch ? { fetchFn: runtime.auth.fetch } : {}),
+                signal: context.signal,
+            })
+            : await fetchProStablePackageSet({
+                accessToken: await runAccessTokenUseCase(context, runtime.auth ?? {}),
+                ...(runtime.env.MOEICONS_API_BASE_URL ? { apiBaseUrl: runtime.env.MOEICONS_API_BASE_URL } : {}),
+                ...(runtime.auth?.fetch ? { fetchFn: runtime.auth.fetch } : {}),
+                signal: context.signal,
+            });
+        const current = status.metadata.candidate;
+        const decision = decideUpdate({ installedTier: tier, remoteTier: tier, installedVersion: current.fullVersion, remoteVersion: identity.fullVersion });
+        if (decision.kind === "current") {
+            if (current.packageSetSha256 !== identity.packageSetSha256 || current.candidateRootSha256 !== identity.candidateRootSha256)
+                throw new CliError("VALIDATION_ERROR", "published package-set identity changed for the installed version; refusing replacement");
+            if (json)
+                writeJson(runtime, { ok: true, status: "current", version: current.fullVersion, packageSetSha256: current.packageSetSha256 });
+            else
+                runtime.stdout(`Current: ${current.fullVersion} / Latest: ${identity.fullVersion} / Status: up to date\n`);
+            return 0;
+        }
+        if (decision.kind !== "update") {
+            const label = decision.reason === "channel-mismatch" ? "prerelease channel differs" : "remote version is older";
+            if (json)
+                writeJson(runtime, { ok: true, status: decision.reason === "channel-mismatch" ? "channel-mismatch" : "remote-older", currentVersion: current.fullVersion, latestVersion: identity.fullVersion });
+            else
+                runtime.stdout(`Current: ${current.fullVersion} / Latest: ${identity.fullVersion} / Status: ${label}\n`);
+            return 0;
+        }
+        return runLibraryUpdate(runtime, tier, identity.fullVersion, identity.packageSetSha256, json, identity.packageSetSha256, identity.networkBytes);
+    }
     if (status.kind === "current" &&
         status.latestDescriptorSha256 !== status.metadata.descriptorSha256)
         throw new CliError("VALIDATION_ERROR", "published identity changed for the installed version; refusing to replace the pinned release");
@@ -921,21 +890,23 @@ async function runInstall(group, runtime, json, noTailwind, sourceVersion, expec
     const progress = context.ui.progress("Downloading icon library", context.signal);
     if (group === "pro" || group === "ent") {
         const { allowLocalTest } = resolveLocalTestContext(runtime.env);
-        const identity = sourceVersion && expectedDescriptorSha256
-            ? { version: sourceVersion, descriptorSha256: expectedDescriptorSha256 }
-            : await fetchLibraryVersions({
-                signal: context.signal,
-                env: runtime.env,
-                allowLocalTest,
-                ...(runtime.auth?.fetch ? { fetch: runtime.auth.fetch } : {}),
-            }).then((versions) => {
-                if (!versions.pro)
-                    throw new CliError("NOT_FOUND", "no pro release is published");
-                return {
-                    version: versions.pro.version,
-                    descriptorSha256: versions.pro.descriptorSha256,
-                };
-            });
+        const identity = allowLocalTest
+            ? sourceVersion && expectedDescriptorSha256
+                ? { version: sourceVersion, descriptorSha256: expectedDescriptorSha256 }
+                : await fetchLibraryVersions({
+                    signal: context.signal,
+                    env: runtime.env,
+                    allowLocalTest,
+                    ...(runtime.auth?.fetch ? { fetch: runtime.auth.fetch } : {}),
+                }).then((versions) => {
+                    if (!versions.pro)
+                        throw new CliError("NOT_FOUND", "no pro release is published");
+                    return {
+                        version: versions.pro.version,
+                        descriptorSha256: versions.pro.descriptorSha256,
+                    };
+                })
+            : {};
         try {
             const result = await runProInstallUseCase(context, {
                 fs: {
@@ -958,6 +929,7 @@ async function runInstall(group, runtime, json, noTailwind, sourceVersion, expec
                 },
             }, {
                 ...identity,
+                ...(!allowLocalTest && sourceVersion ? { version: sourceVersion } : {}),
                 ...(allowLocalTest ? { allowLocalTest: true } : {}),
                 ...(target ? { target } : {}),
             });
@@ -1025,12 +997,15 @@ async function runInstall(group, runtime, json, noTailwind, sourceVersion, expec
             projectRoot: result.projectRoot,
             packageManager: result.packageManager,
             group: result.group,
-            zipBytes: result.artifactBytes,
+            ...(result.downloadMode === "packages" ? {} : { zipBytes: result.artifactBytes }),
             artifactBytes: result.artifactBytes,
             planItems: result.planItems,
             config: result.config,
             artifactVersion: result.artifactVersion,
             descriptorSha256: result.descriptorSha256,
+            candidateRootSha256: result.candidateRootSha256,
+            packageSetSha256: result.packageSetSha256,
+            packageCount: result.packageCount,
             catalogSha256: result.catalogSha256,
             metadataSha256: result.metadataSha256,
             cacheHit: result.cacheHit,
@@ -1038,6 +1013,9 @@ async function runInstall(group, runtime, json, noTailwind, sourceVersion, expec
             downloadNotes: result.downloadNotes,
             networkBytes: result.networkBytes,
             selectedFiles: result.selectedFiles,
+            cacheHits: result.cacheHits,
+            metadataCacheHits: result.metadataCacheHits,
+            transferRetryCount: result.transferRetryCount,
         });
     }
     else {
@@ -1048,7 +1026,7 @@ async function runInstall(group, runtime, json, noTailwind, sourceVersion, expec
         runtime.stdout(`Download mode: ${result.downloadMode}${result.selectedFiles !== undefined ? `; ${result.selectedFiles} resource files; ${result.networkBytes} resource bytes received` : ""}.\n`);
         for (const note of result.downloadNotes ?? [])
             runtime.stdout(`${note}\n`);
-        runtime.stdout(`Installed free artifact metadata to .moeicons (cacheHit=${String(result.cacheHit)}).\n`);
+        runtime.stdout(`${result.downloadMode === "packages" ? `Installed ${result.packageCount ?? 0} selected packages` : "Installed free artifact metadata"} to .moeicons (cacheHit=${String(result.cacheHit)}).\n`);
     }
     return 0;
 }

package/dist/config-package/generated/SOURCE.json

@@ -2,7 +2,7 @@
   "schemaVersion": 1,
   "sourceRepo": "moewolf-dev/moe-icons-code-library",
   "sourceDir": "config-package",
-  "sourceCommit": "76d9924b2114afc317d0a630cde536fb035a908c",
+  "sourceCommit": "8a14d3e05a6073896708413bef31b3793b718021",
   "sourceCommitExact": true,
   "files": {
     "render-config.cjs": {
@@ -14,8 +14,8 @@
       "sha256": "36c35b686335eab4e7db002afb631aa631c80f66656f137b1e2437317b126b0f"
     },
     "moeicons-config.schema.json": {
-      "size": 4769,
-      "sha256": "0e15c0cf7c282abad7d7399e4a52b7804dc8211b427490fca5efc6c53d9319df"
+      "size": 4854,
+      "sha256": "aa0a688104fd66431d91bb089ae70c3306cc289b0a4d5a24c9786062b6ae56ab"
     },
     "moeicons.config.jsonc": {
       "size": 1207,

package/dist/config-package/generated/moeicons-config.schema.json

@@ -185,7 +185,7 @@
         "full"
       ],
       "default": "auto",
-      "description": "Prefer configuration-selected resources (auto), require them (icons), or download the full archive (full)."
+      "description": "Resolve selected packages (auto), require selected packages (icons), or use full archives only with explicit local test fixtures (full). Published releases never download a tier-wide archive."
     }
   }
 }

package/dist/core/bootstrap.js

@@ -32,9 +32,11 @@ export async function runBootstrapUseCase(context, deps) {
         return { kind: "skipped", reason: "no-project" };
     const state = readInstalledResourceState(project.root, "free");
     if (state.kind === "ok" &&
-        deps.fs.existsSync(join(project.root, ".moeicons", "MANUAL.md")) &&
-        deps.fs.existsSync(join(project.root, ".moeicons", "manifest.json"))) {
-        writeMarker(deps, context.env, { cliVersion: deps.cliVersion, libraryVersion: state.metadata.artifactVersion, completedAt: new Date().toISOString() });
+        (state.metadata.schemaVersion === 2 ||
+            (deps.fs.existsSync(join(project.root, ".moeicons", "MANUAL.md")) &&
+                deps.fs.existsSync(join(project.root, ".moeicons", "manifest.json"))))) {
+        const version = state.metadata.schemaVersion === 1 ? state.metadata.artifactVersion : state.metadata.candidate.fullVersion;
+        writeMarker(deps, context.env, { cliVersion: deps.cliVersion, libraryVersion: version, completedAt: new Date().toISOString() });
         return { kind: "already" };
     }
     const confirmed = await context.ui.confirm("Set up moeicons Free icons in this project now? (recommended)", context.signal);

package/dist/core/candidate-version-pointer.d.ts

@@ -0,0 +1,13 @@
+import { type CandidateRoot } from './small-pack/candidate-set.cjs';
+export interface FreeCandidateVersionPointer {
+    readonly schemaVersion: 1;
+    readonly tier: 'free';
+    readonly fullVersion: string;
+    readonly sourceCommit: string;
+    readonly generatorCommit: string;
+    readonly packageSetSha256: string;
+    readonly candidateRootSha256: string;
+    readonly candidateRootBytes: number;
+}
+export declare function parseFreeCandidateVersionPointer(input: Uint8Array, expectedVersion: string): FreeCandidateVersionPointer;
+export declare function pointerMatchesCandidateRoot(pointer: FreeCandidateVersionPointer, root: CandidateRoot): boolean;

package/dist/core/candidate-version-pointer.js

@@ -0,0 +1,37 @@
+import { canonicalBytes } from './small-pack/candidate-set.cjs';
+const VERSION = /^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)(?:-(?:alpha|beta)(?:\.(?:0|[1-9]\d*))?)?$/;
+const SHA256 = /^[a-f0-9]{64}$/;
+const COMMIT = /^[a-f0-9]{40}$/;
+const MAX_POINTER_BYTES = 16 * 1024;
+function check(ok, message) {
+    if (!ok)
+        throw new Error(`Free candidate version pointer: ${message}`);
+}
+export function parseFreeCandidateVersionPointer(input, expectedVersion) {
+    check(VERSION.test(expectedVersion), 'requested version is invalid');
+    const bytes = Buffer.from(input);
+    check(bytes.length > 0 && bytes.length <= MAX_POINTER_BYTES, 'pointer exceeds 16 KiB');
+    let raw;
+    try {
+        raw = JSON.parse(bytes.toString('utf8'));
+    }
+    catch {
+        throw new Error('Free candidate version pointer: invalid JSON');
+    }
+    check(raw !== null && typeof raw === 'object' && !Array.isArray(raw), 'pointer object required');
+    const value = raw;
+    const fields = ['schemaVersion', 'tier', 'fullVersion', 'sourceCommit', 'generatorCommit', 'packageSetSha256', 'candidateRootSha256', 'candidateRootBytes'];
+    check(Object.keys(value).sort().join(',') === [...fields].sort().join(','), 'unexpected pointer fields');
+    check(bytes.equals(canonicalBytes(value)), 'pointer must use canonical JSON');
+    check(value.schemaVersion === 1 && value.tier === 'free' && value.fullVersion === expectedVersion, 'pointer differs from exact Free version');
+    check(typeof value.sourceCommit === 'string' && COMMIT.test(value.sourceCommit), 'Source commit is invalid');
+    check(typeof value.generatorCommit === 'string' && COMMIT.test(value.generatorCommit), 'generator commit is invalid');
+    check(typeof value.packageSetSha256 === 'string' && SHA256.test(value.packageSetSha256), 'package-set digest is invalid');
+    check(typeof value.candidateRootSha256 === 'string' && SHA256.test(value.candidateRootSha256), 'candidate root digest is invalid');
+    check(Number.isSafeInteger(value.candidateRootBytes) && Number(value.candidateRootBytes) > 0 && Number(value.candidateRootBytes) <= 1024 ** 2, 'candidate root size is invalid');
+    return value;
+}
+export function pointerMatchesCandidateRoot(pointer, root) {
+    return pointer.tier === root.tier && pointer.fullVersion === root.fullVersion && pointer.sourceCommit === root.sourceCommit
+        && pointer.generatorCommit === root.generatorCommit && pointer.packageSetSha256 === root.packageSetSha256;
+}

package/dist/core/config-package-plan.d.ts

@@ -0,0 +1,25 @@
+import { type IconCatalog } from '../catalog/catalog.js';
+import type { MoeiconsConfigFile } from '../project/config.js';
+import { type SelectedCandidate } from './small-package-selection.js';
+import type { PackageRow } from './small-pack/candidate-set.cjs';
+export declare function planConfigPackages(config: MoeiconsConfigFile, catalog: IconCatalog, candidate: SelectedCandidate): {
+    resourceKeys: readonly string[];
+    packages: readonly PackageRow[];
+    fallbacks: readonly string[];
+};
+/** Bootstrap only the scoped metadata needed by this project's themes, then
+ * plan exact content units against the resulting candidate-bound catalog. The
+ * loader must return bytes from the selected-package verifier. */
+export declare function planConfigPackagesFromMetadata(config: MoeiconsConfigFile, candidate: SelectedCandidate, loadVerifiedPackage: (row: PackageRow) => Promise<Readonly<Record<string, Uint8Array>>>): Promise<{
+    catalog: IconCatalog;
+    resourceKeys: readonly string[];
+    packages: readonly PackageRow[];
+    fallbacks: readonly string[];
+}>;
+export interface PackageTargetFiles {
+    readonly area: 'target' | 'assets' | 'metadata';
+    readonly files: Readonly<Record<string, Uint8Array>>;
+}
+/** Map one already verified unit; never accumulate multiple packages or invent
+ * an all-tier archive identity. Callers stage these files transactionally. */
+export declare function packageTargetFiles(row: PackageRow, files: Readonly<Record<string, Uint8Array>>, target: MoeiconsConfigFile['target']): PackageTargetFiles;