@moewolf/moe-icons-cli 0.0.10 → 0.0.14

package/dist/core/free-small-package-download.js

@@ -0,0 +1,344 @@
+import * as fs from 'node:fs';
+import { join } from 'node:path';
+import { cacheArtifact } from './cache.js';
+import { downloadArtifact } from '../project/download.js';
+import { FREE_DOWNLOAD_HOSTS, githubReleaseAssetUrl } from './release-descriptor.js';
+import { parseCandidateSet, sha256 } from './small-pack/candidate-set.cjs';
+import { readSelectedCandidate, consumeSelectedPackages, planSelectedPackages, verifySelectedPackage } from './small-package-selection.js';
+import { parseFreeCandidateVersionPointer } from './candidate-version-pointer.js';
+function check(ok, message) { if (!ok)
+    throw new Error(`Free package download: ${message}`); }
+function readCache(file, maximum, exact) {
+    let handle;
+    try {
+        const entry = fs.lstatSync(file);
+        check(entry.isFile() && !entry.isSymbolicLink(), 'cached object must be a regular non-link file');
+        handle = fs.openSync(file, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW | fs.constants.O_NONBLOCK);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return undefined;
+        throw error;
+    }
+    try {
+        const stat = fs.fstatSync(handle);
+        check(stat.isFile() && stat.size > 0 && stat.size <= maximum && (exact === undefined || stat.size === exact), 'cached object size/type invalid');
+        const bytes = Buffer.alloc(stat.size + 1);
+        let count = 0;
+        while (count < bytes.length) {
+            const read = fs.readSync(handle, bytes, count, bytes.length - count, count);
+            if (!read)
+                break;
+            count += read;
+        }
+        check(count === stat.size, 'cache changed during bounded read');
+        return bytes.subarray(0, count);
+    }
+    finally {
+        fs.closeSync(handle);
+    }
+}
+export async function downloadFreeSelectedPackages(options) {
+    options.signal?.throwIfAborted();
+    check((options.resourceKeys !== undefined) !== (options.resolveResourceKeys !== undefined), 'provide exactly one explicit selection or candidate-based planner');
+    if (options.resourceKeys)
+        check(options.resourceKeys.length > 0 && new Set(options.resourceKeys).size === options.resourceKeys.length, 'explicit unique resource selection required');
+    const expected = options.expected;
+    check(expected.tier === 'free' && /^[a-f0-9]{64}$/.test(expected.packageSetSha256) && /^[a-f0-9]{40}$/.test(expected.sourceCommit) && /^[a-f0-9]{40}$/.test(expected.generatorCommit) && /^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)(?:-(?:alpha|beta)(?:\.(?:0|[1-9]\d*))?)?$/.test(expected.fullVersion), 'exact Free candidate pin required');
+    if (options.expectedRootSha256 !== undefined)
+        check(/^[a-f0-9]{64}$/.test(options.expectedRootSha256), 'candidate root pin must be lowercase SHA-256');
+    if (options.expectedRootBytes !== undefined)
+        check(Number.isSafeInteger(options.expectedRootBytes) && options.expectedRootBytes > 0 && options.expectedRootBytes <= 1024 ** 2, 'candidate root byte pin is invalid');
+    let fixture;
+    if (options.fixtureOrigin) {
+        fixture = new URL(options.fixtureOrigin);
+        check(fixture.protocol === 'http:' && ['127.0.0.1', 'localhost', '[::1]'].includes(fixture.hostname) && !fixture.username && !fixture.password && !fixture.search && !fixture.hash && fixture.pathname === '/', 'fixture must be an explicit loopback origin');
+    }
+    const apiBase = resolveFreeApiBase(options.apiBaseUrl, fixture);
+    const url = (tag, filename) => fixture ? new URL(`/moewolf-dev/moe-icons/releases/download/${tag}/${filename}`, fixture).href : githubReleaseAssetUrl(tag, filename);
+    let transferRetryCount = 0;
+    const fetchBytes = async (address, maximum) => {
+        for (let attempt = 0; attempt < 3; attempt++) {
+            options.signal?.throwIfAborted();
+            const result = await downloadArtifact(address, { maxBytes: maximum, timeoutMs: 120000, maxRedirects: 3, allowedHosts: fixture ? [fixture.host] : apiBase.protocol === 'http:' ? [apiBase.host] : [...FREE_DOWNLOAD_HOSTS, apiBase.host], ...(fixture || apiBase.protocol === 'http:' ? { allowHttpLoopback: true } : {}), userAgent: 'moeicons/small-package' }, { ...(options.fetchFn ? { fetchFn: options.fetchFn } : {}), ...(options.signal ? { signal: options.signal } : {}) });
+            if (result.ok)
+                return result.bytes;
+            const transient = result.code === 'NETWORK_ERROR' || result.code === 'HTTP_ERROR' && /\b(?:429|500|502|503|504)\b/.test(result.message);
+            if (!transient || attempt === 2)
+                throw new Error(`Free package download: ${result.code}: ${result.message}`);
+            transferRetryCount++;
+            await new Promise((resolve, reject) => {
+                const aborted = () => { clearTimeout(timer); options.signal?.removeEventListener('abort', aborted); reject(new Error('Free package download cancelled')); };
+                const timer = setTimeout(() => { options.signal?.removeEventListener('abort', aborted); resolve(); }, 250 * (attempt + 1));
+                options.signal?.addEventListener('abort', aborted, { once: true });
+                if (options.signal?.aborted)
+                    aborted();
+            });
+        }
+        throw new Error('Free package download retry budget exhausted');
+    };
+    const cache = join(options.cacheDir, 'small-pack-v1', 'free');
+    const io = { mkdirSync: (dir) => { fs.mkdirSync(dir, { recursive: true }); }, writeFileSync: fs.writeFileSync, renameSync: fs.renameSync, existsSync: fs.existsSync, rmSync: fs.rmSync, readFileSync: fs.readFileSync, readdirSync: fs.readdirSync };
+    const persist = (name, bytes, digest) => cacheArtifact(io, join(cache, name), bytes, digest);
+    const tag = `candidate-set-v1-free-${expected.packageSetSha256}`;
+    const rootName = `candidate-set-${expected.packageSetSha256}.json`;
+    let metadataNetworkBytes = 0, metadataCacheHits = 0;
+    let rootBytes = readCache(join(cache, rootName), 1024 ** 2);
+    const rootCached = rootBytes !== undefined;
+    if (rootBytes)
+        metadataCacheHits++;
+    else {
+        const address = fixture ? url(tag, 'candidate-set-free.json') : freePackageSetAssetUrl(apiBase, expected, 'root');
+        rootBytes = await fetchBytes(address, 1024 ** 2);
+        metadataNetworkBytes += rootBytes.length;
+    }
+    if (options.expectedRootSha256)
+        check(sha256(rootBytes) === options.expectedRootSha256, 'candidate root differs from immutable version pointer');
+    if (options.expectedRootBytes !== undefined)
+        check(rootBytes.length === options.expectedRootBytes, 'candidate root size differs from immutable identity');
+    const root = parseCandidateSet(rootBytes);
+    // Reject identity drift before any page request or cache write.
+    for (const key of ['fullVersion', 'tier', 'sourceCommit', 'generatorCommit', 'packageSetSha256'])
+        check(root[key] === expected[key], 'root differs from pinned Free identity');
+    const pending = [];
+    const candidate = await readSelectedCandidate(rootBytes, expected, async (ref) => {
+        const name = `page-${ref.sha256}.json`;
+        let bytes = readCache(join(cache, name), ref.sizeBytes, ref.sizeBytes);
+        if (bytes)
+            metadataCacheHits++;
+        else {
+            const index = root.packagePages.findIndex((item) => item.filename === ref.filename && item.sha256 === ref.sha256) + 1;
+            check(index > 0, 'page reference is not in the verified root');
+            const address = fixture ? url(tag, ref.filename) : freePackageSetAssetUrl(apiBase, expected, `pages/${index}`);
+            bytes = await fetchBytes(address, ref.sizeBytes);
+            metadataNetworkBytes += bytes.length;
+            pending.push({ name, bytes, digest: ref.sha256 });
+        }
+        return bytes;
+    });
+    if (!rootCached)
+        persist(rootName, rootBytes, sha256(rootBytes));
+    for (const page of pending)
+        persist(page.name, page.bytes, page.digest);
+    let bootstrapNetworkBytes = 0;
+    const prefetched = new Map();
+    const loadVerifiedPackage = async (row) => {
+        const trusted = candidate.rows.find(item => item.resourceKey === row.resourceKey);
+        check(trusted && trusted.packageSha256 === row.packageSha256 && trusted.compressedBytes === row.compressedBytes, 'bootstrap package is outside exact candidate rows');
+        const cached = readCache(join(cache, `${row.packageSha256}.tgz`), row.compressedBytes, row.compressedBytes);
+        const address = fixture ? url(`free-package-v1-${row.packageSha256}`, `${row.packageSha256}.tgz`) : freePackageSetAssetUrl(apiBase, expected, `packages/${row.packageSha256}.tgz`);
+        const bytes = cached ?? await fetchBytes(address, row.compressedBytes);
+        const files = verifySelectedPackage(trusted, bytes);
+        if (!cached) {
+            bootstrapNetworkBytes += bytes.length;
+            persist(`${row.packageSha256}.tgz`, bytes, row.packageSha256);
+        }
+        prefetched.set(row.packageSha256, { bytes, row: trusted, network: !cached });
+        return files;
+    };
+    const resourceKeys = options.resolveResourceKeys
+        ? await options.resolveResourceKeys(candidate, loadVerifiedPackage)
+        : options.resourceKeys;
+    check(resourceKeys && resourceKeys.length > 0 && new Set(resourceKeys).size === resourceKeys.length, 'candidate planner must return explicit unique resource keys');
+    const selectedRows = planSelectedPackages(candidate, resourceKeys);
+    const prefetchedNetworkDigests = new Set([...prefetched].filter(([, value]) => value.network).map(([digest]) => digest));
+    const report = await consumeSelectedPackages(candidate, resourceKeys, {
+        readCache: row => Promise.resolve(prefetched.get(row.packageSha256)?.bytes ?? readCache(join(cache, `${row.packageSha256}.tgz`), row.compressedBytes, row.compressedBytes)),
+        writeCache: (row, bytes) => { persist(`${row.packageSha256}.tgz`, bytes, row.packageSha256); return Promise.resolve(); },
+        download: row => fetchBytes(fixture ? url(`free-package-v1-${row.packageSha256}`, `${row.packageSha256}.tgz`) : freePackageSetAssetUrl(apiBase, expected, `packages/${row.packageSha256}.tgz`), row.compressedBytes),
+        consume: options.consume,
+        ...(options.signal ? { signal: options.signal } : {}),
+    });
+    const prefetchedSelectedNetworkCount = selectedRows.filter(row => prefetchedNetworkDigests.has(row.packageSha256)).length;
+    return { ...report, networkBytes: report.networkBytes + bootstrapNetworkBytes, cacheHits: report.cacheHits - prefetchedSelectedNetworkCount, metadataNetworkBytes, metadataCacheHits, transferRetryCount };
+}
+/** Resolve a version through its immutable public pointer, then use the same
+ * exact-pin package reader. The pointer is cached only after the candidate
+ * root and all requested units have passed verification. */
+export async function downloadFreeVersionPackages(options) {
+    options.signal?.throwIfAborted();
+    check((options.resourceKeys !== undefined) !== (options.resolveResourceKeys !== undefined), 'provide exactly one explicit selection or candidate-based planner');
+    if (options.resourceKeys)
+        check(options.resourceKeys.length > 0 && new Set(options.resourceKeys).size === options.resourceKeys.length, 'explicit unique resource selection required');
+    check(/^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)(?:-(?:alpha|beta)(?:\.(?:0|[1-9]\d*))?)?$/.test(options.fullVersion), 'exact Free version required');
+    let fixture;
+    if (options.fixtureOrigin) {
+        fixture = new URL(options.fixtureOrigin);
+        check(fixture.protocol === 'http:' && ['127.0.0.1', 'localhost', '[::1]'].includes(fixture.hostname) && !fixture.username && !fixture.password && !fixture.search && !fixture.hash && fixture.pathname === '/', 'fixture must be an explicit loopback origin');
+    }
+    const cache = join(options.cacheDir, 'small-pack-v1', 'free');
+    const apiBase = resolveFreeApiBase(options.apiBaseUrl, fixture);
+    if (options.expectedPackageSetSha256 !== undefined) {
+        check(/^[a-f0-9]{64}$/.test(options.expectedPackageSetSha256), 'expected package-set digest must be lowercase SHA-256');
+        const identity = await fetchFreePackageSetIdentity({
+            version: options.fullVersion,
+            packageSetSha256: options.expectedPackageSetSha256,
+            apiBase,
+            ...(fixture ? { fixture } : {}),
+            ...(options.fetchFn ? { fetchFn: options.fetchFn } : {}),
+            ...(options.signal ? { signal: options.signal } : {}),
+        });
+        const downloadOptions = {
+            expected: identity,
+            cacheDir: options.cacheDir,
+            ...(options.resourceKeys ? { resourceKeys: options.resourceKeys } : {}),
+            ...(options.resolveResourceKeys ? { resolveResourceKeys: options.resolveResourceKeys } : {}),
+            consume: options.consume,
+            ...(options.signal ? { signal: options.signal } : {}),
+            ...(options.fetchFn ? { fetchFn: options.fetchFn } : {}),
+            ...(options.fixtureOrigin ? { fixtureOrigin: options.fixtureOrigin } : {}),
+            ...(options.apiBaseUrl ? { apiBaseUrl: options.apiBaseUrl } : {}),
+            expectedRootSha256: identity.candidateRootSha256,
+            expectedRootBytes: identity.candidateRootBytes,
+        };
+        const report = await downloadFreeSelectedPackages({
+            ...downloadOptions,
+        });
+        return { ...report, metadataNetworkBytes: report.metadataNetworkBytes + identity.networkBytes, metadataCacheHits: report.metadataCacheHits };
+    }
+    const pointerFile = join(cache, `version-${options.fullVersion}.json`);
+    let pointerBytes = readCache(pointerFile, 16 * 1024);
+    const pointerCached = pointerBytes !== undefined;
+    if (!pointerBytes) {
+        const tag = `candidate-version-v1-free-${options.fullVersion}`;
+        const address = fixture
+            ? new URL(`/moewolf-dev/moe-icons/releases/download/${tag}/candidate-version-free.json`, fixture).href
+            : githubReleaseAssetUrl(tag, 'candidate-version-free.json');
+        for (let attempt = 0; attempt < 3; attempt++) {
+            options.signal?.throwIfAborted();
+            const result = await downloadArtifact(address, {
+                maxBytes: 16 * 1024,
+                timeoutMs: 120000,
+                maxRedirects: 3,
+                allowedHosts: fixture ? [fixture.host] : FREE_DOWNLOAD_HOSTS,
+                ...(fixture ? { allowHttpLoopback: true } : {}),
+                userAgent: 'moeicons/small-package',
+            }, { ...(options.fetchFn ? { fetchFn: options.fetchFn } : {}), ...(options.signal ? { signal: options.signal } : {}) });
+            if (result.ok) {
+                pointerBytes = result.bytes;
+                break;
+            }
+            const transient = result.code === 'NETWORK_ERROR' || result.code === 'HTTP_ERROR' && /\b(?:429|500|502|503|504)\b/.test(result.message);
+            if (!transient || attempt === 2)
+                throw new Error(`Free candidate version pointer: ${result.code}: ${result.message}`);
+            await new Promise((resolve, reject) => {
+                const aborted = () => { clearTimeout(timer); options.signal?.removeEventListener('abort', aborted); reject(new Error('Free package download cancelled')); };
+                const timer = setTimeout(() => { options.signal?.removeEventListener('abort', aborted); resolve(); }, 250 * (attempt + 1));
+                options.signal?.addEventListener('abort', aborted, { once: true });
+                if (options.signal?.aborted)
+                    aborted();
+            });
+        }
+    }
+    check(pointerBytes, 'version pointer download returned no bytes');
+    const pointer = parseFreeCandidateVersionPointer(pointerBytes, options.fullVersion);
+    const { fullVersion, ...downloadOptions } = options;
+    const report = await downloadFreeSelectedPackages({
+        ...downloadOptions,
+        expected: {
+            fullVersion,
+            tier: 'free',
+            sourceCommit: pointer.sourceCommit,
+            generatorCommit: pointer.generatorCommit,
+            packageSetSha256: pointer.packageSetSha256,
+        },
+        expectedRootSha256: pointer.candidateRootSha256,
+        expectedRootBytes: pointer.candidateRootBytes,
+    });
+    if (!pointerCached) {
+        const io = { mkdirSync: (dir) => { fs.mkdirSync(dir, { recursive: true }); }, writeFileSync: fs.writeFileSync, renameSync: fs.renameSync, existsSync: fs.existsSync, rmSync: fs.rmSync, readFileSync: fs.readFileSync, readdirSync: fs.readdirSync };
+        cacheArtifact(io, pointerFile, pointerBytes, sha256(pointerBytes));
+    }
+    return {
+        ...report,
+        metadataNetworkBytes: report.metadataNetworkBytes + (pointerCached ? 0 : pointerBytes.length),
+        metadataCacheHits: report.metadataCacheHits + (pointerCached ? 1 : 0),
+    };
+}
+const FREE_API_DEFAULT = 'https://api.moeicons.com';
+const VERSION_PATTERN = /^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)(?:-(?:alpha|beta)(?:\.(?:0|[1-9]\d*))?)?$/;
+function resolveFreeApiBase(value, fixture) {
+    const base = new URL(value ?? fixture?.origin ?? FREE_API_DEFAULT);
+    const loopback = base.protocol === 'http:' && ['127.0.0.1', 'localhost', '[::1]'].includes(base.hostname);
+    check((base.protocol === 'https:' || loopback) && !base.username && !base.password && !base.search && !base.hash && base.pathname === '/', 'API base must be HTTPS or an explicit loopback origin');
+    return base;
+}
+function freePackageSetApiUrl(apiBase, query) {
+    const url = new URL('/v1/icon-library/free/package-set', apiBase);
+    url.search = query.toString();
+    return url.href;
+}
+function freePackageSetAssetUrl(apiBase, identity, path) {
+    const url = new URL(`/v1/icon-library/free/package-set/${path}`, apiBase);
+    url.searchParams.set('version', identity.fullVersion);
+    url.searchParams.set('packageSetSha256', identity.packageSetSha256);
+    return url.href;
+}
+async function fetchFreePackageSetIdentity(input) {
+    const query = new URLSearchParams({ version: input.version });
+    if (input.packageSetSha256)
+        query.set('packageSetSha256', input.packageSetSha256);
+    let address;
+    if (input.fixture) {
+        address = input.version === 'stable'
+            ? new URL('/v1/icon-library/free/package-set?version=stable', input.fixture).href
+            : new URL(`/v1/icon-library/free/package-set?version=${encodeURIComponent(input.version)}&packageSetSha256=${encodeURIComponent(input.packageSetSha256 ?? '')}`, input.fixture).href;
+    }
+    else
+        address = freePackageSetApiUrl(input.apiBase, query);
+    const result = await downloadArtifact(address, {
+        maxBytes: 16 * 1024,
+        timeoutMs: 120000,
+        maxRedirects: 0,
+        allowedHosts: input.fixture ? [input.fixture.host] : [input.apiBase.host],
+        ...(input.fixture || input.apiBase.protocol === 'http:' ? { allowHttpLoopback: true } : {}),
+        userAgent: 'moeicons/small-package',
+    }, { ...(input.fetchFn ? { fetchFn: input.fetchFn } : {}), ...(input.signal ? { signal: input.signal } : {}) });
+    if (!result.ok)
+        throw new Error(`Free package-set identity: ${result.code}: ${result.message}`);
+    let raw;
+    try {
+        raw = JSON.parse(Buffer.from(result.bytes).toString('utf8'));
+    }
+    catch {
+        throw new Error('Free package-set identity: invalid JSON');
+    }
+    check(raw !== null && typeof raw === 'object' && !Array.isArray(raw), 'identity object required');
+    const value = raw;
+    const keys = ['schemaVersion', 'tier', 'fullVersion', 'sourceCommit', 'generatorCommit', 'packageSetSha256', 'candidateRootSha256', 'candidateRootBytes', 'updatedAt'];
+    check(Object.keys(value).sort().join(',') === [...keys].sort().join(','), 'identity fields differ from the Free package-set contract');
+    check(value.schemaVersion === 1 && value.tier === 'free' && typeof value.fullVersion === 'string' && VERSION_PATTERN.test(value.fullVersion), 'Free version identity invalid');
+    check(input.version === 'stable' || value.fullVersion === input.version, 'identity version differs from request');
+    check(typeof value.sourceCommit === 'string' && /^[a-f0-9]{40}$/.test(value.sourceCommit), 'Source commit invalid');
+    check(typeof value.generatorCommit === 'string' && /^[a-f0-9]{40}$/.test(value.generatorCommit), 'Generator commit invalid');
+    check(typeof value.packageSetSha256 === 'string' && /^[a-f0-9]{64}$/.test(value.packageSetSha256), 'package-set digest invalid');
+    check(input.packageSetSha256 === undefined || value.packageSetSha256 === input.packageSetSha256, 'identity package-set digest differs from request');
+    check(typeof value.candidateRootSha256 === 'string' && /^[a-f0-9]{64}$/.test(value.candidateRootSha256), 'candidate root digest invalid');
+    check(Number.isSafeInteger(value.candidateRootBytes) && Number(value.candidateRootBytes) > 0 && Number(value.candidateRootBytes) <= 1024 ** 2, 'candidate root size invalid');
+    check(typeof value.updatedAt === 'string' && /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?Z$/.test(value.updatedAt) && !Number.isNaN(Date.parse(value.updatedAt)), 'identity update timestamp invalid');
+    return { ...value, networkBytes: result.bytes.length };
+}
+export async function fetchFreeStablePackageSet(options = {}) {
+    let fixture;
+    if (options.fixtureOrigin) {
+        fixture = new URL(options.fixtureOrigin);
+        check(fixture.protocol === 'http:' && ['127.0.0.1', 'localhost', '[::1]'].includes(fixture.hostname) && !fixture.username && !fixture.password && !fixture.search && !fixture.hash && fixture.pathname === '/', 'fixture must be an explicit loopback origin');
+    }
+    const apiBase = resolveFreeApiBase(options.apiBaseUrl, fixture);
+    return fetchFreePackageSetIdentity({ version: 'stable', apiBase, ...(fixture ? { fixture } : {}), ...(options.fetchFn ? { fetchFn: options.fetchFn } : {}), ...(options.signal ? { signal: options.signal } : {}) });
+}
+export async function downloadFreeStablePackages(options) {
+    const identity = await fetchFreeStablePackageSet({ ...(options.apiBaseUrl ? { apiBaseUrl: options.apiBaseUrl } : {}), ...(options.fixtureOrigin ? { fixtureOrigin: options.fixtureOrigin } : {}), ...(options.fetchFn ? { fetchFn: options.fetchFn } : {}), ...(options.signal ? { signal: options.signal } : {}) });
+    const { apiBaseUrl, fixtureOrigin, fetchFn, signal, ...rest } = options;
+    const report = await downloadFreeSelectedPackages({
+        ...rest,
+        ...(apiBaseUrl ? { apiBaseUrl } : {}),
+        ...(fixtureOrigin ? { fixtureOrigin } : {}),
+        ...(fetchFn ? { fetchFn } : {}),
+        ...(signal ? { signal } : {}),
+        expected: identity,
+        expectedRootSha256: identity.candidateRootSha256,
+        expectedRootBytes: identity.candidateRootBytes,
+    });
+    return { ...report, metadataNetworkBytes: report.metadataNetworkBytes + identity.networkBytes };
+}

package/dist/core/generate.js

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

package/dist/core/install.d.ts

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

package/dist/core/install.js

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

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

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