@moewolf/moe-icons-cli 0.0.10 → 0.0.14

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

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

package/dist/core/config-package-plan.js

@@ -0,0 +1,156 @@
+import { findCatalogStyleGroup, parseCatalog } from '../catalog/catalog.js';
+import { resolveIconTheme } from './icon-selection.js';
+import { resolveResourceVariant } from './resource-variant.js';
+import { planSelectedPackages } from './small-package-selection.js';
+function check(ok, message) { if (!ok)
+    throw new Error(`config package plan: ${message}`); }
+export function planConfigPackages(config, catalog, candidate) {
+    check(config.icons.length > 0 && Object.keys(config.themes).length > 0, 'registered icons and themes required');
+    check(config.downloadMode !== 'full', 'published package installs cannot use downloadMode=full');
+    check(config.tier === candidate.root.tier, 'config tier differs from pinned candidate');
+    check(catalog.sourceVersion === candidate.root.fullVersion && catalog.sourceCommit === candidate.root.sourceCommit && catalog.generatorCommit === candidate.root.generatorCommit, 'catalog differs from pinned candidate identity');
+    const keys = new Set(), fallbacks = new Set();
+    for (const iconId of config.icons)
+        for (const requested of Object.keys(config.themes)) {
+            const actual = resolveIconTheme(config, catalog, requested, iconId);
+            check(actual, `no selected variant for ${requested}/${iconId}`);
+            if (actual !== requested)
+                fallbacks.add(`${iconId}: ${requested} -> ${actual}`);
+            const theme = config.themes[actual];
+            check(theme, 'resolved theme missing');
+            const group = findCatalogStyleGroup(theme.styleGroup, catalog);
+            check(group && group.tiers.includes(config.tier), 'group is unavailable in selected tier');
+            keys.add(`metadata/${config.tier}/${group.id}`);
+            if (group.type === 'bitmap') {
+                check(config.target !== 'vanilla', 'Vanilla does not support bitmap icons');
+                const variant = resolveResourceVariant(group.id, { ...(theme.format ? { format: theme.format } : {}), ...(theme.imageSize ? { imageSize: theme.imageSize } : {}) });
+                check(group.formats.includes(variant.format) && group.imageSizes.includes(variant.imageSize) && group.variants?.includes(variant.resourceVariantId), 'bitmap tuple is not declared by pinned catalog');
+                keys.add(`bitmap/${config.tier}/${group.id}/${variant.imageSize}x${variant.imageSize}/${variant.format}`);
+            }
+            else {
+                if (config.target === 'assets' || config.target === 'vanilla')
+                    keys.add(`svg/${config.tier}/${group.id}`);
+                if (config.target !== 'assets')
+                    keys.add(`code/${config.tier}/${config.target}/${group.id}`);
+            }
+        }
+    const resourceKeys = [...keys].sort();
+    return { resourceKeys, packages: planSelectedPackages(candidate, resourceKeys), fallbacks: [...fallbacks].sort() };
+}
+function stable(value) {
+    if (Array.isArray(value))
+        return value.map(stable);
+    if (value && typeof value === 'object')
+        return Object.fromEntries(Object.entries(value).sort(([a], [b]) => a.localeCompare(b, 'en')).map(([key, item]) => [key, stable(item)]));
+    return value;
+}
+function stringArray(value) {
+    return Array.isArray(value) && value.every((item) => typeof item === 'string');
+}
+/** Bootstrap only the scoped metadata needed by this project's themes, then
+ * plan exact content units against the resulting candidate-bound catalog. The
+ * loader must return bytes from the selected-package verifier. */
+export async function planConfigPackagesFromMetadata(config, candidate, loadVerifiedPackage) {
+    check(config.icons.length > 0 && Object.keys(config.themes).length > 0, 'registered icons and themes required');
+    check(config.downloadMode !== 'full', 'published package installs cannot use downloadMode=full');
+    check(config.tier === candidate.root.tier, 'config tier differs from pinned candidate');
+    const groupIds = [...new Set(Object.values(config.themes)
+            .filter(theme => theme.icons === undefined || theme.icons.some(icon => config.icons.includes(icon)))
+            .map(theme => theme.styleGroup))].sort();
+    check(groupIds.length > 0, 'configured themes required');
+    const groups = new Map();
+    const icons = new Map();
+    for (const groupId of groupIds) {
+        const row = candidate.rows.find(item => item.resourceKey === `metadata/${config.tier}/${groupId}`);
+        check(row && row.kind === 'metadata' && row.styleGroupId === groupId && row.tier === config.tier, `scoped metadata missing for ${groupId}`);
+        const files = await loadVerifiedPackage(row);
+        const bytes = files['metadata/catalog.json'];
+        check(bytes, `scoped catalog missing for ${groupId}`);
+        let raw;
+        try {
+            raw = JSON.parse(Buffer.from(bytes).toString('utf8'));
+        }
+        catch {
+            throw new Error(`config package plan: invalid scoped catalog for ${groupId}`);
+        }
+        check(raw !== null && typeof raw === 'object' && !Array.isArray(raw), `scoped catalog object required for ${groupId}`);
+        const scoped = raw;
+        check(Object.keys(scoped).sort().join(',') === 'icons,schemaVersion,styleGroups' && scoped.schemaVersion === 1 && Array.isArray(scoped.styleGroups) && scoped.styleGroups.length === 1 && Array.isArray(scoped.icons), `scoped catalog schema/scope invalid for ${groupId}`);
+        const group = scoped.styleGroups[0];
+        check(group && group.id === groupId && !groups.has(groupId), `scoped style group differs for ${groupId}`);
+        groups.set(groupId, group);
+        check(scoped.icons.length > 0, `scoped catalog has no icons for ${groupId}`);
+        for (const value of scoped.icons) {
+            check(value !== null && typeof value === 'object' && !Array.isArray(value), `invalid scoped icon in ${groupId}`);
+            const icon = value;
+            check(typeof icon.id === 'string' && Array.isArray(icon.availableIn) && icon.availableIn.length === 1 && icon.availableIn[0] === groupId, `scoped icon crosses group boundary in ${groupId}`);
+            if (icon.variants !== undefined)
+                check(stringArray(icon.variants), `invalid scoped icon variants in ${groupId}`);
+            const previous = icons.get(icon.id);
+            if (!previous) {
+                icons.set(icon.id, { ...icon, availableIn: [groupId], ...(stringArray(icon.variants) ? { variants: [...icon.variants] } : {}) });
+                continue;
+            }
+            const stripScope = (entry) => Object.fromEntries(Object.entries(entry).filter(([key]) => key !== 'availableIn' && key !== 'variants'));
+            check(JSON.stringify(stable(stripScope(previous))) === JSON.stringify(stable(stripScope(icon))), `icon metadata conflicts across scoped catalogs: ${icon.id}`);
+            previous.availableIn = [...new Set([...previous.availableIn, groupId])].sort();
+            if (stringArray(icon.variants))
+                previous.variants = [...new Set([...(stringArray(previous.variants) ? previous.variants : []), ...icon.variants])].sort();
+        }
+    }
+    const catalog = parseCatalog({
+        schemaVersion: 1,
+        catalogVersion: candidate.root.fullVersion,
+        sourceVersion: candidate.root.fullVersion,
+        sourceCommit: candidate.root.sourceCommit,
+        generatorCommit: candidate.root.generatorCommit,
+        styleGroups: [...groups.values()],
+        icons: [...icons.values()],
+    });
+    return { catalog, ...planConfigPackages(config, catalog, candidate) };
+}
+/** Map one already verified unit; never accumulate multiple packages or invent
+ * an all-tier archive identity. Callers stage these files transactionally. */
+export function packageTargetFiles(row, files, target) {
+    check(Object.hasOwn(files, 'manifest.json'), 'verified unit manifest required');
+    const output = Object.create(null);
+    let area;
+    if (row.kind === 'code' || row.kind === 'shared') {
+        check(row.target === target, `package target mismatch for ${row.resourceKey}: expected ${target}, received ${row.target}`);
+        area = 'target';
+    }
+    else if (row.kind === 'svg' || row.kind === 'bitmap') {
+        check(row.kind !== 'svg' || target === 'assets' || target === 'vanilla', 'raw SVG unit is not required by compiled target');
+        check(target !== 'vanilla' || row.kind !== 'bitmap', 'Vanilla bitmap unsupported');
+        area = 'assets';
+    }
+    else {
+        check(row.kind === 'metadata', 'unsupported installation package kind');
+        area = 'metadata';
+    }
+    for (const [name, bytes] of Object.entries(files)) {
+        if (name === 'manifest.json')
+            continue;
+        check(!/[\\:]/.test(name) && name.split('/').every(part => part && part !== '.' && part !== '..'), 'unsafe unit path');
+        let destination;
+        if (row.kind === 'shared')
+            destination = name;
+        else if (row.kind === 'code' || row.kind === 'svg') {
+            check(row.styleGroupId, 'group scope missing');
+            destination = `${row.styleGroupId}/${name}`;
+        }
+        else if (row.kind === 'metadata') {
+            check(row.styleGroupId && name.startsWith('metadata/'), 'metadata scope missing');
+            destination = `${row.styleGroupId}/${name.slice(9)}`;
+        }
+        else {
+            check(row.styleGroupId && row.variant && name.startsWith('icons/'), 'bitmap tuple scope missing');
+            const variant = resolveResourceVariant(row.styleGroupId, { format: row.variant.format, imageSize: row.variant.width });
+            destination = `${variant.resourceVariantId}/${name.slice(6)}`;
+        }
+        check(!Object.hasOwn(output, destination), 'duplicate target file');
+        output[destination] = bytes;
+    }
+    check(Object.keys(output).length > 0, 'empty installation unit');
+    return { area, files: output };
+}

package/dist/core/doctor.js

@@ -4,6 +4,7 @@ import { diagnoseProject } from "../project/anchors/diagnose.js";
 import { applyPlannedChanges } from "../project/anchors/apply.js";
 import { withProjectLockSync } from "../project/project-lock.js";
 import { loadInstalledCatalogState } from "./generate.js";
+import { readInstalledResourceState } from "../project/install-metadata.js";
 const STATUS_LABEL = {
     ok: "OK",
     missing: "MISSING",
@@ -92,6 +93,9 @@ export function checkRequiresFix(report) {
     return report.anchors.some((a) => required.includes(a.kind) && a.status !== "ok" && a.status !== "not-required");
 }
 function diagnosticCatalog(cwd) {
+    const installed = readInstalledResourceState(cwd);
+    if (installed.kind === "invalid")
+        throw new Error(installed.message);
     const state = loadInstalledCatalogState(cwd, { readFileSync, existsSync });
     if (state.status === "invalid")
         throw new Error(state.message);

package/dist/core/free-download.js

@@ -12,7 +12,9 @@ import { cacheArtifact } from "./cache.js";
 import { extractAndVerifyMetadataArchive } from "../metadata/archive.js";
 import { assertLocalCandidateAllowed, cacheKey, FREE_DOWNLOAD_HOSTS, githubReleaseAssetUrl, parseReleaseDescriptor, parseSha256Sidecar, } from "./release-descriptor.js";
 export const DESCRIPTOR_MAX_BYTES = 256 * 1024;
-export const ARTIFACT_MAX_BYTES = 64 * 1024 * 1024;
+// Full release archives are retired for published versions. This bound only
+// preserves small local-test fixtures until package-scoped target delivery lands.
+export const ARTIFACT_MAX_BYTES = 128 * 1024 * 1024;
 export const METADATA_MAX_BYTES = 8 * 1024 * 1024;
 // GitHub Release downloads can be slow on constrained or distant networks.
 // Keep the operation bounded, but allow enough time for the 64 MiB Free limit.
@@ -342,6 +344,27 @@ export async function downloadFreeRelease(io, sourceVersion, selection) {
     if (!fetched.ok)
         return fetched;
     const { descriptor, descriptorSha256, tag } = fetched;
+    // CI FLOW RULE (S05): the old Free descriptor points at a tier-wide archive.
+    // Never silently download that complete library when the group package
+    // directory or selected package support is missing.
+    const localFixture = Boolean(io.fixtureDir || io.fixtureBaseUrl || descriptor.channel === "local-test");
+    if (!localFixture && (descriptor.schemaVersion === undefined || descriptor.schemaVersion < 5)) {
+        return {
+            ok: false,
+            reason: "validation",
+            message: "this release uses the retired full-library package format; install requires the small-package release protocol",
+        };
+    }
+    // CI FLOW RULE (S05): a current-looking descriptor must not make the CLI
+    // fetch the retired tier-wide index/`.bin`. Published installs require the
+    // candidate-set package directory and its bounded dependency closure.
+    if (!localFixture && descriptor.free.resources !== undefined) {
+        return {
+            ok: false,
+            reason: "validation",
+            message: "this release advertises the retired tier-wide resource bundle; refusing to download it",
+        };
+    }
     const metadataRef = descriptor.free.metadata;
     if (!metadataRef) {
         return {
@@ -479,15 +502,22 @@ export async function downloadFreeRelease(io, sourceVersion, selection) {
             };
         }
     }
+    if (!localFixture) {
+        return {
+            ok: false,
+            reason: "validation",
+            message: "published Free release has no supported bounded package directory; refusing the full-library fallback",
+        };
+    }
     if (mode === "icons")
         return {
             ok: false,
             reason: "validation",
-            message: "this release has no selected-resource index; choose a newer release or explicitly set downloadMode=full",
+            message: "this local fixture has no selected-resource index",
         };
     selection?.onPlan?.(mode === "full"
-        ? "Download mode: full (explicitly configured); the complete target archive will be verified before selection."
-        : "This release does not advertise selected downloads; auto uses the verified full archive. Set downloadMode=icons to require selected downloads.");
+        ? "Download mode: full (local fixture only)."
+        : "Using a local-test fixture archive.");
     const artifactCache = cachePath(io, descriptor.fullVersion, descriptor.free.sha256);
     if (io.existsSync(artifactCache)) {
         const cached = io.readFileSync(artifactCache);

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

@@ -0,0 +1,67 @@
+import { type PackageRow } from './small-pack/candidate-set.cjs';
+import { type CandidateIdentity, type SelectedCandidate } from './small-package-selection.js';
+export interface FreeSmallPackageOptions {
+    expected: CandidateIdentity;
+    resourceKeys?: readonly string[];
+    resolveResourceKeys?: (candidate: SelectedCandidate, loadVerifiedPackage: (row: PackageRow) => Promise<Readonly<Record<string, Uint8Array>>>) => Promise<readonly string[]>;
+    cacheDir: string;
+    consume: (row: PackageRow, files: Readonly<Record<string, Uint8Array>>) => Promise<void>;
+    signal?: AbortSignal;
+    fetchFn?: typeof fetch;
+    /** Explicit loopback fixture origin, never a published remote override. */
+    fixtureOrigin?: string;
+    /** Bound by a public immutable version pointer when resolving by version. */
+    expectedRootSha256?: string;
+    expectedRootBytes?: number;
+    /** Public Worker API base; production defaults to https://api.moeicons.com. */
+    apiBaseUrl?: string;
+}
+export declare function downloadFreeSelectedPackages(options: FreeSmallPackageOptions): Promise<{
+    packageCount: number;
+    networkBytes: number;
+    cacheHits: number;
+    metadataNetworkBytes: number;
+    metadataCacheHits: number;
+    transferRetryCount: number;
+}>;
+export interface FreeSmallPackageVersionOptions extends Omit<FreeSmallPackageOptions, 'expected' | 'expectedRootSha256' | 'expectedRootBytes'> {
+    fullVersion: string;
+    expectedPackageSetSha256?: string;
+}
+/** 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 declare function downloadFreeVersionPackages(options: FreeSmallPackageVersionOptions): Promise<{
+    packageCount: number;
+    networkBytes: number;
+    cacheHits: number;
+    metadataNetworkBytes: number;
+    metadataCacheHits: number;
+    transferRetryCount: number;
+}>;
+export interface FreePackageSetIdentity {
+    readonly schemaVersion: 1;
+    readonly tier: 'free';
+    readonly fullVersion: string;
+    readonly sourceCommit: string;
+    readonly generatorCommit: string;
+    readonly packageSetSha256: string;
+    readonly candidateRootSha256: string;
+    readonly candidateRootBytes: number;
+    readonly updatedAt: string;
+    readonly networkBytes: number;
+}
+export declare function fetchFreeStablePackageSet(options?: {
+    apiBaseUrl?: string;
+    fixtureOrigin?: string;
+    fetchFn?: typeof fetch;
+    signal?: AbortSignal;
+}): Promise<FreePackageSetIdentity>;
+export declare function downloadFreeStablePackages(options: Omit<FreeSmallPackageOptions, 'expected' | 'expectedRootSha256' | 'expectedRootBytes'>): Promise<{
+    packageCount: number;
+    networkBytes: number;
+    cacheHits: number;
+    metadataNetworkBytes: number;
+    metadataCacheHits: number;
+    transferRetryCount: number;
+}>;