@moewolf/moe-icons-cli 0.0.1 → 0.0.3

package/dist/core/pro-install.js

@@ -1,20 +1,44 @@
+import { assertDownloadSelection } from "./selected-resources.js";
 import { detectProject } from "../project/detect.js";
-import { readMoeiconsConfig } from "../project/config.js";
-import { createInstallPlan, executeInstallPlan } from "../project/install.js";
-import { serializeInstallMetadata, sha256Bytes } from "../project/install-metadata.js";
+import { loadConfigDocument, validateConfigDocument } from "../project/config.js";
+import { createInstallPlan, executeInstallPlan, } from "../project/install.js";
+import { parseInstallMetadata, serializeInstallMetadata, sha256Bytes, } from "../project/install-metadata.js";
 import { withProjectLock } from "../project/project-lock.js";
-import { downloadProArtifact } from "./pro-download.js";
-import { artifactCachePath } from "./free-download.js";
-import { selectTargetSubtree } from "./target-subtree.js";
+import { runAccessTokenUseCase } from "./auth.js";
+import { downloadProArtifact, PRO_DOWNLOAD_HOSTS, resolveProDescriptorEndpoint, } from "./pro-download.js";
+import { artifactCachePath, metadataCachePath } from "./free-download.js";
+import { configuredComponentFiles, selectTargetSubtree, computeSubtreeHash, } from "./target-subtree.js";
+import { typesReexport } from "./install.js";
 import { CliError } from "../errors/index.js";
+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";
+function toCacheIo(fs_) {
+    return {
+        // Shard cache keys are nested several levels deep; the CacheIo contract
+        // requires recursive creation.
+        mkdirSync: (path) => {
+            fs_.mkdirSync(path, { recursive: true });
+        },
+        writeFileSync: fs_.writeFileSync,
+        renameSync: fs_.renameSync,
+        existsSync: fs_.existsSync,
+        rmSync: fs_.rmSync,
+        ...(fs_.readFileSync ? { readFileSync: fs_.readFileSync } : {}),
+        ...(fs_.readdirSync ? { readdirSync: fs_.readdirSync } : {}),
+    };
+}
 import { homedir } from "node:os";
 import { join } from "node:path";
 function resolveCacheDir(env) {
     return env.MOEICONS_CACHE_DIR ?? join(homedir(), ".moeicons", "cache");
 }
 /** Persist the full verified archive so vanilla/bitmap generate can read assets/. */
-function cacheVerifiedArtifact(fs_, cacheDir, version, sha256, bytes) {
-    const cached = artifactCachePath(cacheDir, version, sha256);
+function cacheVerifiedArtifact(fs_, cacheDir, version, sha256, bytes, kind = "code") {
+    const cached = kind === "metadata"
+        ? metadataCachePath(cacheDir, version, sha256)
+        : artifactCachePath(cacheDir, version, sha256);
     if (fs_.existsSync(cached))
         return;
     fs_.mkdirSync(join(cached, ".."), { recursive: true });
@@ -24,28 +48,133 @@ export async function runProInstallUseCase(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 config = readMoeiconsConfig(project.root);
-    if (config.kind !== "ok" || config.config.tier !== "pro")
+    // DEV-G10-R2: snapshot the config ONCE. Both the bootstrap and the strict
+    // phase validate this same document, so a rewrite during download can never
+    // combine an old target with new bitmap tuples.
+    const document = loadConfigDocument(project.root);
+    const plannedConfigDocument = JSON.stringify(document);
+    // DEV-G10-R1 phase 1: catalog-independent bootstrap. A Pro bitmap config
+    // references groups the bundled catalog does not ship, so validate only the
+    // safe fields (tier/target/syntax) before the release catalog is available.
+    const bootstrap = validateConfigDocument(document, bundledCatalog, { lenientCatalog: true });
+    if (bootstrap.kind !== "ok" || bootstrap.config.tier !== "pro")
         throw new CliError("VALIDATION_ERROR", "pro install requires a valid tier=pro config");
-    const target = expected.target ?? config.config.target;
-    const downloaded = await downloadProArtifact(context, deps.auth, expected, {
+    assertDownloadSelection(bootstrap.config);
+    const target = expected.target ?? bootstrap.config.target;
+    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`);
+    }
+    const downloaded = await downloadProArtifact(context, deps.auth, {
+        version: expected.version,
+        descriptorSha256: expected.descriptorSha256,
+        ...(expected.allowLocalTest === true ? { allowLocalTest: true } : {}),
+    }, {
+        selection: { config: bootstrap.config, document },
         ...(deps.fetch ? { fetch: deps.fetch } : {}),
         ...(deps.allowedHosts ? { allowedHosts: deps.allowedHosts } : {}),
         ...(deps.onProgress ? { onProgress: deps.onProgress } : {}),
     });
-    const subtree = selectTargetSubtree(downloaded.artifactBytes, downloaded.descriptor, target);
+    const selectedTarget = downloaded.selected
+        ? Object.fromEntries(Object.entries(downloaded.selected.files)
+            .filter(([path]) => path.startsWith(`${target}/`))
+            .map(([path, bytes]) => [path.slice(target.length + 1), bytes]))
+        : undefined;
+    const subtree = selectedTarget
+        ? { ok: true, target, files: selectedTarget, ...computeSubtreeHash(selectedTarget) }
+        : selectTargetSubtree(downloaded.artifactBytes, downloaded.descriptor, target);
     if (!subtree.ok) {
         throw new CliError("VALIDATION_ERROR", subtree.message);
     }
-    cacheVerifiedArtifact(deps.fs, resolveCacheDir(context.env), downloaded.descriptor.version, downloaded.descriptor.sha256, downloaded.artifactBytes);
+    const cacheDir = resolveCacheDir(context.env);
+    let bitmapPins;
+    let bitmapShardSetSha256Value;
+    let installedCatalog;
+    try {
+        installedCatalog = parseCatalog(JSON.parse(downloaded.catalogJson));
+    }
+    catch (error) {
+        throw new CliError("VALIDATION_ERROR", error instanceof Error ? error.message : "invalid pro catalog");
+    }
+    // DEV-G10-R1 phase 2: re-validate the SAME snapshot against the verified
+    // release catalog. A style group / icon / variant the release does not ship
+    // fails closed here, before ANY cache write, shard fetch or metadata write.
+    const strict = validateConfigDocument(document, installedCatalog);
+    if (strict.kind !== "ok") {
+        throw new CliError("VALIDATION_ERROR", strict.kind === "invalid" ? strict.message : `config state: ${strict.kind}`);
+    }
+    const config = strict.config;
+    const installedFiles = downloaded.selected
+        ? subtree.files
+        : configuredComponentFiles(subtree.files, target, config, installedCatalog);
+    // Only after the snapshot passes strict validation do we persist the
+    // content-addressed code/metadata caches. A rejected config writes nothing.
+    if (!downloaded.selected)
+        cacheVerifiedArtifact(deps.fs, cacheDir, downloaded.descriptor.version, downloaded.descriptor.sha256, downloaded.artifactBytes);
+    if (downloaded.metadataBytes && downloaded.descriptor.metadata) {
+        cacheVerifiedArtifact(deps.fs, cacheDir, downloaded.descriptor.version, downloaded.descriptor.metadata.sha256, downloaded.metadataBytes, "metadata");
+    }
+    const resolvedTuples = resolveBitmapTuples(config, installedCatalog);
+    if (!resolvedTuples.ok)
+        throw new CliError("VALIDATION_ERROR", resolvedTuples.errors.join("; "));
+    if (!downloaded.selected &&
+        resolvedTuples.tuples.length > 0 &&
+        downloaded.descriptor.channel !== "local-test") {
+        const accessToken = await runAccessTokenUseCase(context, deps.auth);
+        const { loopbackHost } = resolveProDescriptorEndpoint(context.env);
+        const allowedHosts = loopbackHost ? [...PRO_DOWNLOAD_HOSTS, loopbackHost] : PRO_DOWNLOAD_HOSTS;
+        // DEV-G10: reuse verified pinned shards at the same resourceVersion so a
+        // size switch only fetches the newly selected tuple. A version bump always
+        // yields new shard identities, so no cross-version reuse is possible.
+        // W2-B2/B7: a shard already present in EITHER the project's install metadata
+        // OR the global CLI shard cache (e.g. warmed with the 128/webp default set)
+        // is reused after re-verification; only genuinely missing tuples are fetched.
+        let existingPins = [];
+        const cacheIo = toCacheIo(deps.fs);
+        const cacheManifest = readBitmapShardCacheManifest(cacheDir, cacheIo);
+        const metadataPath = join(project.root, ".moeicons", "install-metadata.json");
+        if (deps.fs.existsSync(metadataPath) && deps.fs.readFileSync) {
+            const existing = parseInstallMetadata(deps.fs.readFileSync(metadataPath, "utf8"), {
+                allowLocalTest: allowLocalTestFromEnv(context.env),
+            });
+            existingPins = existing?.bitmapShards ?? [];
+        }
+        existingPins = mergeBitmapShardCacheManifest(cacheManifest, existingPins).filter((pin) => pin.resourceVersion === downloaded.descriptor.version);
+        const shards = await resolveConfiguredBitmapShards({
+            existingPins,
+            config,
+            catalog: installedCatalog,
+            version: downloaded.descriptor.version,
+            descriptorSha256: downloaded.descriptor.descriptorSha256,
+            cacheDir,
+            io: cacheIo,
+            accessToken,
+            allowedHosts,
+            env: context.env,
+            now: context.now().getTime(),
+            signal: context.signal,
+            ...(deps.fetch ? { fetch: deps.fetch } : {}),
+        });
+        bitmapPins = shards.pins;
+        bitmapShardSetSha256Value = shards.bitmapShardSetSha256;
+        // Record every verified shard in the global cache manifest (idempotent).
+        writeBitmapShardCacheManifest(cacheDir, cacheIo, mergeBitmapShardCacheManifest(cacheManifest, shards.pins), context.now().getTime());
+    }
     const files = {
         ".moeicons/catalog.json": downloaded.catalogJson,
-        "src/moeicons/types.ts": `export type { ReactIconProps } from "moe-icons";\n`,
-        "src/moeicons/.moeicons-pro.marker": "pro\n",
+        ".moeicons/manifest.json": downloaded.manifestJson,
+        ".moeicons/MANUAL.md": downloaded.manualMd,
+        ".moeicons/artifact/package.json": '{"private":true,"type":"module","sideEffects":false}\n',
+        [`${config.outputDir.replace(/\\/g, "/").replace(/\/$/, "")}/types.ts`]: typesReexport("pro", target, config.outputDir),
+        [`${config.outputDir.replace(/\\/g, "/").replace(/\/$/, "")}/.moeicons-pro.marker`]: "pro\n",
     };
-    for (const [rel, bytes] of Object.entries(subtree.files)) {
+    for (const [rel, bytes] of Object.entries(installedFiles)) {
         files[`.moeicons/artifact/${target}/${rel}`] = bytes;
     }
+    if (downloaded.selected) {
+        files[".moeicons/resource-index.json.gz"] = downloaded.selected.indexBytes;
+        for (const [rel, bytes] of Object.entries(downloaded.selected.files))
+            files[`.moeicons/artifact/${rel}`] = bytes;
+    }
     const managedFiles = Object.fromEntries(Object.entries(files).map(([path, content]) => [path, sha256Bytes(content)]));
     files[".moeicons/install-metadata.json"] = serializeInstallMetadata({
         schemaVersion: 1,
@@ -57,16 +186,49 @@ export async function runProInstallUseCase(context, deps, expected) {
         catalogSha256: downloaded.descriptor.catalogSha256,
         installedAt: context.now().toISOString(),
         managedFiles,
+        ...(downloaded.selected
+            ? {
+                delivery: {
+                    mode: "icons",
+                    indexSha256: downloaded.selected.refs.index.sha256,
+                    bundleSha256: downloaded.selected.refs.bundle.sha256,
+                },
+            }
+            : {}),
         targetSha256: subtree.sha256,
         targetFileCount: subtree.fileCount,
         targetByteCount: subtree.byteCount,
+        ...(bitmapPins && bitmapShardSetSha256Value
+            ? { bitmapShards: bitmapPins, bitmapShardSetSha256: bitmapShardSetSha256Value }
+            : {}),
+        // A-1b: record the accepted local-test model so a later generate can verify it.
+        ...(downloaded.descriptor.channel === "local-test"
+            ? { channel: "local-test", publishable: false }
+            : {}),
+    });
+    await withProjectLock(project.root, "install", () => {
+        if (JSON.stringify(loadConfigDocument(project.root)) !== plannedConfigDocument)
+            throw new CliError("VALIDATION_ERROR", "config changed while preparing install; retry");
+        executeInstallPlan(createInstallPlan(project.root, files), deps.fs);
     });
-    await withProjectLock(project.root, "install", () => executeInstallPlan(createInstallPlan(project.root, files), deps.fs));
     return {
         projectRoot: project.root,
         artifactVersion: downloaded.descriptor.version,
         descriptorSha256: downloaded.descriptor.descriptorSha256,
         catalogSha256: downloaded.descriptor.catalogSha256,
-        artifactBytes: downloaded.artifactBytes.byteLength,
+        artifactBytes: downloaded.selected?.payloadBytes ?? downloaded.artifactBytes.byteLength,
+        downloadMode: downloaded.selected ? "icons" : "full",
+        downloadNotes: downloaded.selected?.fallbacks ??
+            (config.downloadMode === "full"
+                ? []
+                : [
+                    "Release does not advertise selected downloads; auto used the verified full archive. Set downloadMode=icons to require selected downloads.",
+                ]),
+        ...(downloaded.selected
+            ? {
+                networkBytes: downloaded.selected.networkBytes,
+                selectedFiles: Object.keys(downloaded.selected.files).length,
+            }
+            : {}),
     };
 }

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

@@ -0,0 +1,79 @@
+import type { AuthUseCaseDependencies } from "./auth.js";
+import type { CommandContext } from "./context.js";
+import { type WarmupPlan } from "./bitmap-shard-cache.js";
+import type { BitmapShardFetchProgress } from "./bitmap-shard-resolver.js";
+export type ProResourceState = {
+    readonly kind: "not-cached";
+    readonly version: string;
+    readonly codeBytes: number;
+    readonly metadataBytes: number;
+} | {
+    readonly kind: "current";
+    readonly version: string;
+} | {
+    readonly kind: "outdated";
+    readonly version: string;
+    readonly latestVersion: string;
+    readonly codeBytes: number;
+    readonly metadataBytes: number;
+} | {
+    readonly kind: "corrupt";
+    readonly version: string;
+} | {
+    readonly kind: "unavailable";
+    readonly reason: string;
+};
+/**
+ * Read-only state of cached Pro resources relative to the published latest
+ * version. Used by the authenticated home screen (Download/Update/Repair).
+ */
+export declare function proResourceState(context: CommandContext, auth: AuthUseCaseDependencies, deps?: {
+    readonly fetch?: typeof fetch;
+    readonly allowedProHosts?: readonly string[];
+}): Promise<ProResourceState>;
+export interface ProPredownloadResult {
+    readonly version: string;
+    readonly codeSha256: string;
+    readonly descriptorSha256: string;
+    readonly metadataSha256?: string;
+    readonly catalogSha256: string;
+    readonly codeBytes: number;
+    readonly metadataBytes: number;
+}
+/**
+ * Pre-download (and verify + cache) the full Pro code + metadata archives after
+ * login or from the home screen, without installing anything into a project.
+ */
+export declare function runProPredownloadUseCase(context: CommandContext, auth: AuthUseCaseDependencies, deps?: {
+    readonly fetch?: typeof fetch;
+    readonly allowedProHosts?: readonly string[];
+    readonly force?: boolean;
+    readonly onProgress?: (event: {
+        readonly downloadedBytes: number;
+        readonly totalBytes?: number;
+    }) => void;
+}): Promise<ProPredownloadResult>;
+export interface ProWarmupResult {
+    readonly version: string;
+    readonly groups: number;
+    readonly shards: number;
+    readonly downloaded: number;
+    readonly reused: number;
+}
+export interface ProWarmupDeps {
+    readonly version: string;
+    readonly descriptorSha256: string;
+    readonly metadataSha256: string;
+    readonly catalogSha256: string;
+    readonly fetch?: typeof fetch;
+    readonly allowedProHosts?: readonly string[];
+    readonly onPlan?: (plan: WarmupPlan) => void;
+    readonly onProgress?: (event: BitmapShardFetchProgress) => void;
+}
+/**
+ * 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
+ * release catalog comes from the already-verified metadata archive, so no
+ * second artifact download is needed.
+ */
+export declare function runProResourceWarmupUseCase(context: CommandContext, auth: AuthUseCaseDependencies, deps: ProWarmupDeps): Promise<ProWarmupResult>;

package/dist/core/pro-resources.js

@@ -0,0 +1,204 @@
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { readdirSync, existsSync, readFileSync, writeFileSync, mkdirSync, rmSync, renameSync } from "node:fs";
+import { CliError } from "../errors/index.js";
+import { artifactCachePath, metadataCachePath } from "./free-download.js";
+import { downloadSignedArtifact } from "./signed-artifact.js";
+import { fetchProDescriptor, proSignedDownloadOptions } from "./pro-download.js";
+import { fetchLibraryVersions } from "./version-service.js";
+import { isVersionNewer } from "../metadata/version.js";
+import { verifyArtifact } from "../project/install.js";
+import { cacheArtifact } from "./cache.js";
+import { extractAndVerifyMetadataArchive } from "../metadata/archive.js";
+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 { warmDefaultBitmapShards, } from "./bitmap-shard-cache.js";
+function cacheDir(env) {
+    return env.MOEICONS_CACHE_DIR ?? join(homedir(), ".moeicons", "cache");
+}
+/** Versions of pro archives currently present in the global cache. */
+function cachedProVersions(dir) {
+    const base = join(dir, "moewolf-dev", "moe-icons");
+    if (!existsSync(base))
+        return [];
+    let names;
+    try {
+        names = readdirSync(base);
+    }
+    catch {
+        return [];
+    }
+    return names.filter((name) => /^\d+\.\d+\.\d+(?:-(?:alpha|beta))?$/.test(name));
+}
+/**
+ * Read-only state of cached Pro resources relative to the published latest
+ * version. Used by the authenticated home screen (Download/Update/Repair).
+ */
+export async function proResourceState(context, auth, deps = {}) {
+    let versions;
+    try {
+        versions = await fetchLibraryVersions({ ...(deps.fetch ? { fetch: deps.fetch } : {}), signal: context.signal, env: context.env });
+    }
+    catch {
+        return { kind: "unavailable", reason: "version check failed" };
+    }
+    if (!versions.pro)
+        return { kind: "unavailable", reason: "no pro release is published" };
+    const latest = versions.pro;
+    let descriptor;
+    try {
+        descriptor = await fetchProDescriptor(context, auth, { version: latest.version, descriptorSha256: latest.descriptorSha256 }, { ...(deps.fetch ? { fetch: deps.fetch } : {}) });
+    }
+    catch (error) {
+        return {
+            kind: "unavailable",
+            reason: error instanceof CliError ? error.message : "pro resources unavailable",
+        };
+    }
+    const dir = cacheDir(context.env);
+    const codePath = artifactCachePath(dir, descriptor.version, descriptor.sha256);
+    const metaPath = descriptor.metadata
+        ? metadataCachePath(dir, descriptor.version, descriptor.metadata.sha256)
+        : undefined;
+    if (existsSync(codePath) && (metaPath === undefined || existsSync(metaPath))) {
+        const codeOk = verifyArtifact(readFileSync(codePath), descriptor.sha256).ok;
+        const metaOk = metaPath === undefined || verifyArtifact(readFileSync(metaPath), descriptor.metadata.sha256).ok;
+        if (codeOk && metaOk)
+            return { kind: "current", version: descriptor.version };
+        return { kind: "corrupt", version: descriptor.version };
+    }
+    const cached = cachedProVersions(dir).find((version) => version !== descriptor.version && isVersionNewer(descriptor.version, version));
+    if (cached) {
+        return {
+            kind: "outdated",
+            version: cached,
+            latestVersion: descriptor.version,
+            codeBytes: descriptor.size,
+            metadataBytes: descriptor.metadata?.size ?? 0,
+        };
+    }
+    return {
+        kind: "not-cached",
+        version: descriptor.version,
+        codeBytes: descriptor.size,
+        metadataBytes: descriptor.metadata?.size ?? 0,
+    };
+}
+/**
+ * Pre-download (and verify + cache) the full Pro code + metadata archives after
+ * login or from the home screen, without installing anything into a project.
+ */
+export async function runProPredownloadUseCase(context, auth, deps = {}) {
+    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");
+    const latest = versions.pro;
+    const descriptor = await fetchProDescriptor(context, auth, { version: latest.version, descriptorSha256: latest.descriptorSha256 }, { ...(deps.fetch ? { fetch: deps.fetch } : {}) });
+    const dir = cacheDir(context.env);
+    const downloadOptions = proSignedDownloadOptions(context, {
+        ...(deps.fetch ? { fetch: deps.fetch } : {}),
+        ...(deps.allowedProHosts ? { allowedHosts: deps.allowedProHosts } : {}),
+        ...(deps.onProgress ? { onProgress: deps.onProgress } : {}),
+    });
+    const persist = (path, bytes, expectedSha256) => {
+        if (deps.force && existsSync(path))
+            rmSync(path, { force: true });
+        if (!existsSync(path) || deps.force) {
+            cacheArtifact({
+                mkdirSync: (dir) => mkdirSync(dir, { recursive: true }),
+                writeFileSync,
+                renameSync,
+                existsSync,
+                rmSync,
+            }, path, bytes, expectedSha256);
+        }
+    };
+    const codeRef = { url: descriptor.url, expiresAt: descriptor.expiresAt, size: descriptor.size, sha256: descriptor.sha256 };
+    const codeBytes = await downloadSignedArtifact(codeRef, downloadOptions);
+    persist(artifactCachePath(dir, descriptor.version, descriptor.sha256), codeBytes, descriptor.sha256);
+    let metadataSha256;
+    let metadataBytes = 0;
+    if (descriptor.metadata) {
+        const metaBytes = await downloadSignedArtifact(descriptor.metadata, downloadOptions);
+        metadataSha256 = descriptor.metadata.sha256;
+        metadataBytes = metaBytes.byteLength;
+        persist(metadataCachePath(dir, descriptor.version, descriptor.metadata.sha256), metaBytes, descriptor.metadata.sha256);
+    }
+    return {
+        version: descriptor.version,
+        codeSha256: descriptor.sha256,
+        descriptorSha256: descriptor.descriptorSha256,
+        ...(metadataSha256 ? { metadataSha256 } : {}),
+        catalogSha256: descriptor.catalogSha256,
+        codeBytes: codeBytes.byteLength,
+        metadataBytes,
+    };
+}
+function cacheIo() {
+    return {
+        mkdirSync: (path) => mkdirSync(path, { recursive: true }),
+        writeFileSync,
+        renameSync,
+        existsSync,
+        rmSync,
+        readFileSync,
+        readdirSync,
+    };
+}
+/**
+ * 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
+ * release catalog comes from the already-verified metadata archive, so no
+ * second artifact download is needed.
+ */
+export async function runProResourceWarmupUseCase(context, auth, deps) {
+    const dir = cacheDir(context.env);
+    const metadataPath = metadataCachePath(dir, deps.version, deps.metadataSha256);
+    if (!existsSync(metadataPath)) {
+        throw new CliError("NOT_FOUND", "Pro metadata is not cached; download Pro resources first");
+    }
+    const extracted = extractAndVerifyMetadataArchive(readFileSync(metadataPath), {
+        expectedCatalogSha: deps.catalogSha256,
+        expectedTier: "pro",
+        expectedVersion: deps.version,
+    });
+    if (extracted.kind !== "ok")
+        throw new CliError("VALIDATION_ERROR", extracted.message);
+    let catalog;
+    try {
+        catalog = parseCatalog(JSON.parse(extracted.value.catalogJson));
+    }
+    catch (error) {
+        throw new CliError("VALIDATION_ERROR", error instanceof Error ? error.message : "invalid pro catalog");
+    }
+    const accessToken = await runAccessTokenUseCase(context, auth);
+    const endpoint = resolveBitmapShardDescriptorEndpoint(context.env);
+    const allowedHosts = endpoint.allowLoopback
+        ? [...PRO_DOWNLOAD_HOSTS, new URL(endpoint.url).host]
+        : deps.allowedProHosts ?? PRO_DOWNLOAD_HOSTS;
+    const result = await warmDefaultBitmapShards({
+        catalog,
+        version: deps.version,
+        descriptorSha256: deps.descriptorSha256,
+        accessToken,
+        cacheDir: dir,
+        io: cacheIo(),
+        endpoint: endpoint.url,
+        allowedHosts,
+        signal: context.signal,
+        now: context.now().getTime(),
+        ...(endpoint.allowLoopback ? { allowLoopback: true } : {}),
+        ...(deps.fetch ? { fetch: deps.fetch } : {}),
+        ...(deps.onPlan ? { onPlan: deps.onPlan } : {}),
+        ...(deps.onProgress ? { onProgress: deps.onProgress } : {}),
+    });
+    return {
+        version: deps.version,
+        groups: new Set(result.tuples.map((tuple) => tuple.styleGroupId)).size,
+        shards: result.tuples.length,
+        downloaded: result.downloaded,
+        reused: result.reused,
+    };
+}

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

@@ -0,0 +1,18 @@
+import { type AuthUseCaseDependencies } from "./auth.js";
+import { type ProArtifactDescriptor } from "./pro-download.js";
+import { type ConfigDocument, type MoeiconsConfigFile } from "../project/config.js";
+import type { CommandContext } from "./context.js";
+import type { SelectedResourceDownload } from "./free-download.js";
+export declare function downloadProSelected(context: CommandContext, auth: AuthUseCaseDependencies, descriptor: ProArtifactDescriptor, selection: {
+    config: MoeiconsConfigFile;
+    document: ConfigDocument;
+}, deps: {
+    fetch?: typeof fetch;
+    allowedHosts?: readonly string[];
+}): Promise<{
+    selected: SelectedResourceDownload;
+    catalogJson: string;
+    manifestJson: string;
+    manualMd: string;
+    metadataBytes: Uint8Array;
+} | undefined>;