@moewolf/moe-icons-cli 0.0.10 → 0.0.14

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 {};

package/dist/core/pro-install.js

@@ -14,6 +14,8 @@ import { catalog as bundledCatalog, parseCatalog } from "../catalog/catalog.js";
 import { resolveBitmapTuples, resolveConfiguredBitmapShards } from "./bitmap-shard-resolver.js";
 import { mergeBitmapShardCacheManifest, readBitmapShardCacheManifest, writeBitmapShardCacheManifest, } from "./bitmap-shard-cache.js";
 import { allowLocalTestFromEnv } from "./local-test-env.js";
+import { runSmallPackageInstall } from "./small-package-install.js";
+import { fetchProStablePackageSet } from "./pro-small-package-download.js";
 function toCacheIo(fs_) {
     return {
         // Shard cache keys are nested several levels deep; the CacheIo contract
@@ -64,6 +66,51 @@ export async function runProInstallUseCase(context, deps, expected) {
     if (target !== bootstrap.config.target) {
         throw new CliError("VALIDATION_ERROR", `config target is "${bootstrap.config.target}" but install target is "${target}"; set target to "${target}" in moeicons.config before installing`);
     }
+    if (expected.allowLocalTest !== true) {
+        const accessToken = await runAccessTokenUseCase(context, deps.auth);
+        const identity = await fetchProStablePackageSet({
+            accessToken,
+            ...(context.env.MOEICONS_API_BASE_URL ? { apiBaseUrl: context.env.MOEICONS_API_BASE_URL } : {}),
+            ...(deps.fetch ? { fetchFn: deps.fetch } : {}),
+            ...(context.signal ? { signal: context.signal } : {}),
+        });
+        if (expected.version && expected.version !== identity.fullVersion) {
+            throw new CliError("VALIDATION_ERROR", "published Pro package-set changed after version selection; retry the install");
+        }
+        const installed = await runSmallPackageInstall({
+            projectRoot: project.root,
+            fullVersion: identity.fullVersion,
+            expectedPackageSetSha256: identity.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: resolveCacheDir(context.env),
+            now: context.now,
+            proAccessToken: accessToken,
+            ...(context.signal ? { signal: context.signal } : {}),
+            ...(deps.fetch ? { fetchFn: deps.fetch } : {}),
+        });
+        return {
+            projectRoot: project.root,
+            artifactVersion: installed.artifactVersion,
+            candidateRootSha256: installed.candidateRootSha256,
+            packageSetSha256: installed.packageSetSha256,
+            catalogSha256: installed.catalogSha256,
+            artifactBytes: installed.artifactBytes,
+            downloadMode: "packages",
+            downloadNotes: installed.fallbacks.map((fallback) => `Theme fallback: ${fallback}`),
+            networkBytes: installed.networkBytes + identity.networkBytes,
+            selectedFiles: installed.selectedFiles,
+            packageCount: installed.packageCount,
+            cacheHits: installed.cacheHits,
+            metadataCacheHits: installed.metadataCacheHits,
+            transferRetryCount: installed.transferRetryCount,
+        };
+    }
+    if (!expected.version || !expected.descriptorSha256) {
+        throw new CliError("VALIDATION_ERROR", "local Pro test install requires an exact legacy fixture pin");
+    }
     const downloaded = await downloadProArtifact(context, deps.auth, {
         version: expected.version,
         descriptorSha256: expected.descriptorSha256,

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

@@ -48,6 +48,8 @@ export declare function runProPredownloadUseCase(context: CommandContext, auth:
     readonly fetch?: typeof fetch;
     readonly allowedProHosts?: readonly string[];
     readonly force?: boolean;
+    /** Explicitly isolate the retired aggregate archive path to test fixtures. */
+    readonly allowLocalTest?: boolean;
     readonly onProgress?: (event: {
         readonly downloadedBytes: number;
         readonly totalBytes?: number;
@@ -65,11 +67,32 @@ export interface ProWarmupDeps {
     readonly descriptorSha256: string;
     readonly metadataSha256: string;
     readonly catalogSha256: string;
+    /** Explicit test-fixture opt-in for the retired legacy shard route. */
+    readonly allowLocalTest?: boolean;
     readonly fetch?: typeof fetch;
     readonly allowedProHosts?: readonly string[];
     readonly onPlan?: (plan: WarmupPlan) => void;
     readonly onProgress?: (event: BitmapShardFetchProgress) => void;
 }
+export interface ProPackageWarmupPlan {
+    readonly version: string;
+    readonly packageSetSha256: string;
+    readonly groups: number;
+    readonly packages: number;
+    readonly compressedBytes: number;
+}
+export interface ProPackageWarmupResult extends ProPackageWarmupPlan {
+    readonly downloaded: number;
+    readonly reused: number;
+    readonly networkBytes: number;
+    readonly metadataNetworkBytes: number;
+}
+/** Warm the explicit default preview tuple (128-WebP) as separate package objects. */
+export declare function runProPreviewPackageWarmupUseCase(context: CommandContext, auth: AuthUseCaseDependencies, deps?: {
+    readonly fetch?: typeof fetch;
+    readonly apiBaseUrl?: string;
+    readonly onPlan?: (plan: ProPackageWarmupPlan) => Promise<void> | void;
+}): Promise<ProPackageWarmupResult>;
 /**
  * W2-A: after the Pro code + metadata are cached, warm the default bitmap shard
  * set (every bitmap style group's 128/webp shard) into the global cache. The

package/dist/core/pro-resources.js

@@ -14,6 +14,8 @@ import { parseCatalog } from "../catalog/catalog.js";
 import { runAccessTokenUseCase } from "./auth.js";
 import { PRO_DOWNLOAD_HOSTS } from "./pro-download.js";
 import { resolveBitmapShardDescriptorEndpoint } from "./bitmap-shard-download.js";
+import { downloadProStablePackages } from "./pro-small-package-download.js";
+import { planSelectedPackages } from "./small-package-selection.js";
 import { warmDefaultBitmapShards, } from "./bitmap-shard-cache.js";
 function cacheDir(env) {
     return env.MOEICONS_CACHE_DIR ?? join(homedir(), ".moeicons", "cache");
@@ -91,6 +93,9 @@ export async function proResourceState(context, auth, deps = {}) {
  * login or from the home screen, without installing anything into a project.
  */
 export async function runProPredownloadUseCase(context, auth, deps = {}) {
+    if (deps.allowLocalTest !== true) {
+        throw new CliError('VALIDATION_ERROR', 'aggregate Pro archive pre-download is retired; use package-set project installs or preview package warm-up');
+    }
     const versions = await fetchLibraryVersions({ ...(deps.fetch ? { fetch: deps.fetch } : {}), signal: context.signal, env: context.env });
     if (!versions.pro)
         throw new CliError("NOT_FOUND", "no pro release is published");
@@ -136,6 +141,49 @@ export async function runProPredownloadUseCase(context, auth, deps = {}) {
         metadataBytes,
     };
 }
+/** Warm the explicit default preview tuple (128-WebP) as separate package objects. */
+export async function runProPreviewPackageWarmupUseCase(context, auth, deps = {}) {
+    const accessToken = await runAccessTokenUseCase(context, auth);
+    const cache = cacheDir(context.env);
+    let plan;
+    const report = await downloadProStablePackages({
+        accessToken,
+        cacheDir: cache,
+        ...(deps.apiBaseUrl ? { apiBaseUrl: deps.apiBaseUrl } : context.env.MOEICONS_API_BASE_URL ? { apiBaseUrl: context.env.MOEICONS_API_BASE_URL } : {}),
+        ...(deps.fetch ? { fetchFn: deps.fetch } : {}),
+        ...(context.signal ? { signal: context.signal } : {}),
+        resolveResourceKeys: async (candidate) => {
+            const selected = candidate.rows.filter((row) => row.kind === 'bitmap' && row.tier === 'pro'
+                && row.variant?.width === 128 && row.variant.height === 128 && row.variant.format === 'webp')
+                .sort((a, b) => a.resourceKey.localeCompare(b.resourceKey, 'en'));
+            if (selected.length === 0)
+                throw new CliError('NOT_FOUND', 'the current Pro package set has no 128-WebP preview packages');
+            const selectedRows = planSelectedPackages(candidate, selected.map((row) => row.resourceKey));
+            const compressedBytes = selectedRows.reduce((sum, row) => sum + row.compressedBytes, 0);
+            if (!Number.isSafeInteger(compressedBytes) || compressedBytes > 4 * 1024 * 1024 * 1024)
+                throw new CliError('VALIDATION_ERROR', 'Pro preview warm-up exceeds the 4 GiB package budget');
+            plan = {
+                version: candidate.root.fullVersion,
+                packageSetSha256: candidate.root.packageSetSha256,
+                groups: new Set(selected.map((row) => row.styleGroupId)).size,
+                packages: selectedRows.length,
+                compressedBytes,
+            };
+            await deps.onPlan?.(plan);
+            return selected.map((row) => row.resourceKey);
+        },
+        consume: () => Promise.resolve(),
+    });
+    if (!plan)
+        throw new CliError('VALIDATION_ERROR', 'Pro preview warm-up did not produce a candidate plan');
+    return {
+        ...plan,
+        downloaded: report.packageCount - report.cacheHits,
+        reused: report.cacheHits,
+        networkBytes: report.networkBytes,
+        metadataNetworkBytes: report.metadataNetworkBytes,
+    };
+}
 function cacheIo() {
     return {
         mkdirSync: (path) => mkdirSync(path, { recursive: true }),
@@ -154,6 +202,9 @@ function cacheIo() {
  * second artifact download is needed.
  */
 export async function runProResourceWarmupUseCase(context, auth, deps) {
+    if (deps.allowLocalTest !== true) {
+        throw new CliError('VALIDATION_ERROR', 'legacy Pro bitmap shard warm-up is retired; use package-set preview package warm-up');
+    }
     const dir = cacheDir(context.env);
     const metadataPath = metadataCachePath(dir, deps.version, deps.metadataSha256);
     if (!existsSync(metadataPath)) {

package/dist/core/pro-selected-download.js

@@ -14,6 +14,12 @@ import { homedir } from "node:os";
 export async function downloadProSelected(context, auth, descriptor, selection, deps) {
     const fetchFn = deps.fetch ?? fetch;
     const endpointInfo = resolveProDescriptorEndpoint(context.env);
+    // CI FLOW RULE (S05): this implementation reads the retired tier-wide
+    // resource-index / `.bin` bundle. Keep it reachable only from an explicitly
+    // declared local-test descriptor served by a loopback endpoint; a descriptor
+    // label alone must never reopen the production reader.
+    if (!endpointInfo.allowLoopback || descriptor.channel !== "local-test")
+        throw new CliError("VALIDATION_ERROR", "legacy Pro resource-bundle downloads require a local-test descriptor and loopback endpoint");
     const endpoint = new URL(endpointInfo.url.replace(/\/artifact-descriptor$/, "/resource-descriptor"));
     if (endpoint.origin !== "https://api.moeicons.com" && !endpointInfo.allowLoopback)
         throw new CliError("VALIDATION_ERROR", "resource descriptor endpoint must be the trusted API or a test loopback");
@@ -150,7 +156,11 @@ export async function downloadProSelected(context, auth, descriptor, selection,
         catch (error) {
             if (!expired(error) || attempt === 2)
                 throw error;
-            const renewed = await fetchProDescriptor(context, auth, { version: descriptor.version, descriptorSha256: descriptor.descriptorSha256 }, deps);
+            const renewed = await fetchProDescriptor(context, auth, {
+                version: descriptor.version,
+                descriptorSha256: descriptor.descriptorSha256,
+                ...(descriptor.channel === "local-test" ? { allowLocalTest: true } : {}),
+            }, deps);
             if (renewed.sha256 !== descriptor.sha256 ||
                 !renewed.metadata ||
                 renewed.metadata.sha256 !== originalMetadata.sha256 ||
@@ -161,7 +171,7 @@ export async function downloadProSelected(context, auth, descriptor, selection,
         }
     if (!metadataBytes)
         throw new CliError("NETWORK_ERROR", "metadata URL renewal failed");
-    const metadata = extractProMetadata(metadataBytes, descriptor.catalogSha256, descriptor.version);
+    const metadata = extractProMetadata(metadataBytes, descriptor.catalogSha256, descriptor.version, descriptor.channel === "local-test");
     const catalog = parseCatalog(JSON.parse(metadata.catalogJson));
     const strict = validateConfigDocument(selection.document, catalog);
     if (strict.kind !== "ok")

package/dist/core/pro-small-package-download.d.ts

@@ -0,0 +1,61 @@
+import { type PackageRow } from './small-pack/candidate-set.cjs';
+import { type CandidateIdentity, type SelectedCandidate } from './small-package-selection.js';
+export interface ProPackageSetIdentity extends CandidateIdentity {
+    readonly schemaVersion: 1;
+    readonly tier: 'pro';
+    readonly candidateRootSha256: string;
+    readonly candidateRootBytes: number;
+    readonly updatedAt: string;
+    readonly networkBytes: number;
+}
+export interface ProSmallPackageOptions {
+    readonly expected: CandidateIdentity & {
+        readonly tier: 'pro';
+    };
+    readonly resourceKeys?: readonly string[];
+    readonly resolveResourceKeys?: (candidate: SelectedCandidate, loadVerifiedPackage: (row: PackageRow) => Promise<Readonly<Record<string, Uint8Array>>>) => Promise<readonly string[]>;
+    readonly cacheDir: string;
+    readonly consume: (row: PackageRow, files: Readonly<Record<string, Uint8Array>>) => Promise<void>;
+    readonly accessToken: string;
+    readonly signal?: AbortSignal;
+    readonly fetchFn?: typeof fetch;
+    readonly apiBaseUrl?: string;
+    readonly expectedRootSha256?: string;
+    readonly expectedRootBytes?: number;
+}
+export declare function fetchProPackageSetIdentity(options: {
+    readonly version: string;
+    readonly packageSetSha256?: string;
+    readonly accessToken: string;
+    readonly apiBaseUrl?: string;
+    readonly fetchFn?: typeof fetch;
+    readonly signal?: AbortSignal;
+}): Promise<ProPackageSetIdentity>;
+export declare function fetchProStablePackageSet(options: Omit<Parameters<typeof fetchProPackageSetIdentity>[0], 'version' | 'packageSetSha256'>): Promise<ProPackageSetIdentity>;
+export declare function downloadProSelectedPackages(options: ProSmallPackageOptions): Promise<{
+    packageCount: number;
+    networkBytes: number;
+    cacheHits: number;
+    metadataNetworkBytes: number;
+    metadataCacheHits: number;
+    transferRetryCount: number;
+}>;
+export declare function downloadProStablePackages(options: Omit<ProSmallPackageOptions, 'expected' | 'expectedRootSha256' | 'expectedRootBytes'>): Promise<{
+    packageCount: number;
+    networkBytes: number;
+    cacheHits: number;
+    metadataNetworkBytes: number;
+    metadataCacheHits: number;
+    transferRetryCount: number;
+}>;
+export declare function downloadProVersionPackages(options: Omit<ProSmallPackageOptions, 'expected' | 'expectedRootSha256' | 'expectedRootBytes'> & {
+    readonly fullVersion: string;
+    readonly expectedPackageSetSha256: string;
+}): Promise<{
+    packageCount: number;
+    networkBytes: number;
+    cacheHits: number;
+    metadataNetworkBytes: number;
+    metadataCacheHits: number;
+    transferRetryCount: number;
+}>;