@moewolf/moe-icons-cli 0.0.1 → 0.0.3

package/dist/core/bitmap-shard-resolver.js

@@ -0,0 +1,262 @@
+/**
+ * DEV-G07 (DEC-100/101/107): normalize configured bitmap references to canonical
+ * tuples, fetch exactly those shards (one descriptor each, bearer only to the
+ * API), and map verified shard bytes back to the existing local `assets/`
+ * layout so generated code/imports never change.
+ */
+import { catalog as defaultCatalog } from "../catalog/catalog.js";
+import { findCatalogStyleGroup } from "../catalog/catalog.js";
+import { isVariantAvailable } from "../generator/theme-resolve.js";
+import { buildResourceVariantId, DEFAULT_BITMAP_FORMAT, DEFAULT_BITMAP_SIZE, resolveResourceVariant, } from "./resource-variant.js";
+import { bitmapShardSetSha256, buildBitmapShardFilename, buildBitmapShardObjectKey, } from "./bitmap-shards.js";
+import { bitmapShardPinFromVerified, bitmapShardVerificationTargetFromPin, downloadAndCacheBitmapShard, fetchBitmapShardDescriptor, loadCachedBitmapShard, resolveBitmapShardDescriptorEndpoint, } from "./bitmap-shard-download.js";
+import { BITMAP_SHARD_BUDGET } from "./bitmap-shard-budget.js";
+import { CliError } from "../errors/index.js";
+import { themeHasIcon } from "./icon-selection.js";
+function tupleKey(tuple) {
+    return `${tuple.styleGroupId}/${tuple.imageSize.width}x${tuple.imageSize.height}/${tuple.format}`;
+}
+function compareTuples(a, b) {
+    if (a.styleGroupId !== b.styleGroupId)
+        return a.styleGroupId < b.styleGroupId ? -1 : 1;
+    if (a.imageSize.width !== b.imageSize.width)
+        return a.imageSize.width - b.imageSize.width;
+    if (a.imageSize.height !== b.imageSize.height)
+        return a.imageSize.height - b.imageSize.height;
+    if (a.format !== b.format)
+        return a.format < b.format ? -1 : 1;
+    return 0;
+}
+/**
+ * Resolve every bitmap variant the config actually references into unique,
+ * canonically sorted tuples. Same tuple used by many icons/themes appears once.
+ */
+export function resolveBitmapTuples(config, sourceCatalog = defaultCatalog) {
+    const errors = [];
+    const seen = new Set();
+    const tuples = [];
+    for (const [theme, entry] of Object.entries(config.themes)) {
+        const group = findCatalogStyleGroup(entry.styleGroup, sourceCatalog);
+        // Non-bitmap and unknown groups are out of scope here; install/generate
+        // validate theme/catalog consistency separately.
+        if (!group || group.type !== "bitmap")
+            continue;
+        if (!config.icons.some((iconId) => themeHasIcon(config, sourceCatalog, theme, iconId)))
+            continue;
+        try {
+            let variant;
+            if (entry.format === undefined && entry.imageSize === undefined) {
+                const defaultId = buildResourceVariantId(group.id, DEFAULT_BITMAP_FORMAT, DEFAULT_BITMAP_SIZE);
+                if (!isVariantAvailable(group, defaultId)) {
+                    errors.push(`bitmap group "${group.id}" does not include the default ${DEFAULT_BITMAP_FORMAT}/${String(DEFAULT_BITMAP_SIZE)} variant; set format and imageSize explicitly`);
+                    continue;
+                }
+                variant = resolveResourceVariant(group.id);
+            }
+            else {
+                variant = resolveResourceVariant(group.id, {
+                    ...(entry.format !== undefined ? { format: entry.format } : {}),
+                    ...(entry.imageSize !== undefined ? { imageSize: entry.imageSize } : {}),
+                });
+            }
+            if (!isVariantAvailable(group, variant.resourceVariantId)) {
+                errors.push(`variant ${variant.resourceVariantId} is unavailable for ${group.id}`);
+                continue;
+            }
+            const tuple = {
+                styleGroupId: variant.styleGroupId,
+                imageSize: { width: variant.imageSize, height: variant.imageSize },
+                format: variant.format,
+            };
+            const key = tupleKey(tuple);
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            tuples.push(tuple);
+        }
+        catch (error) {
+            errors.push(`theme "${theme}": ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    if (errors.length > 0)
+        return { ok: false, errors };
+    tuples.sort(compareTuples);
+    return { ok: true, tuples };
+}
+/** Pure canonical request plan (one immutable key per selected tuple). */
+export function planBitmapShardRequests(tuples, version) {
+    const seen = new Set();
+    const requests = [];
+    for (const tuple of tuples) {
+        const key = tupleKey(tuple);
+        if (seen.has(key))
+            throw new Error(`duplicate bitmap tuple in plan: ${key}`);
+        seen.add(key);
+        const filename = buildBitmapShardFilename({ ...tuple, tier: "pro", resourceVersion: version });
+        requests.push({
+            ...tuple,
+            filename,
+            objectKey: buildBitmapShardObjectKey({ ...tuple, tier: "pro", resourceVersion: version, filename }),
+        });
+    }
+    requests.sort(compareTuples);
+    return requests;
+}
+/** Map verified shard bytes to the canonical local `assets/` layout. */
+export function shardAssetsToLocalLayout(shard) {
+    const variantId = buildResourceVariantId(shard.descriptor.styleGroupId, shard.descriptor.format, shard.descriptor.imageSize.width);
+    const out = {};
+    for (const [path, bytes] of Object.entries(shard.files)) {
+        const iconId = path.slice("icons/".length, path.length - (shard.descriptor.format.length + 1));
+        out[`assets/${variantId}/${iconId}.${shard.descriptor.format}`] = bytes;
+    }
+    return out;
+}
+/**
+ * Fetch exactly the selected shards, sequentially (concurrency 1 per DEC-102/
+ * 107), verify each, and return the merged local-layout file map. Never
+ * prefetches unselected tuples/formats/sizes.
+ */
+export async function fetchSelectedBitmapShards(tuples, deps) {
+    const requests = planBitmapShardRequests(tuples, deps.version);
+    const shards = [];
+    const pins = [];
+    const files = {};
+    const existingByTuple = new Map();
+    for (const pin of deps.existingPins ?? []) {
+        existingByTuple.set(tupleKey({ styleGroupId: pin.styleGroupId, imageSize: pin.imageSize, format: pin.format }), pin);
+    }
+    let downloadedBytes = 0;
+    for (const [offset, request] of requests.entries()) {
+        const index = offset + 1;
+        const total = requests.length;
+        const tuple = { styleGroupId: request.styleGroupId, imageSize: request.imageSize, format: request.format };
+        const published = existingByTuple.get(tupleKey(request));
+        if (published) {
+            // Re-verify the cached pinned shard; a miss/poison falls through to fetch.
+            try {
+                const cached = loadPinnedBitmapShardAssets([published], [{ styleGroupId: request.styleGroupId, imageSize: request.imageSize, format: request.format }], deps.cacheDir, deps.io);
+                Object.assign(files, cached.files);
+                pins.push(cached.pins[0]);
+                deps.onProgress?.({ tuple, index, total, phase: "reuse" });
+                continue;
+            }
+            catch {
+                // Fall through: re-fetch this tuple online.
+            }
+        }
+        deps.onProgress?.({ tuple, index, total, phase: "descriptor" });
+        const descriptor = await fetchBitmapShardDescriptor({
+            version: deps.version,
+            descriptorSha256: deps.descriptorSha256,
+            styleGroupId: request.styleGroupId,
+            imageSize: request.imageSize,
+            format: request.format,
+        }, deps.accessToken, {
+            ...(deps.fetch ? { fetch: deps.fetch } : {}),
+            ...(deps.now !== undefined ? { now: deps.now } : {}),
+            ...(deps.allowLoopback ? { allowLoopback: true } : {}),
+            ...(deps.endpoint ? { endpoint: deps.endpoint } : {}),
+            ...(deps.signal ? { signal: deps.signal } : {}),
+        });
+        // The descriptor must describe exactly the requested tuple.
+        if (descriptor.filename !== request.filename) {
+            throw new Error(`bitmap shard descriptor ${descriptor.filename} does not match request ${request.filename}`);
+        }
+        const verified = await downloadAndCacheBitmapShard(descriptor, {
+            cacheDir: deps.cacheDir,
+            io: deps.io,
+            ...(deps.fetch ? { fetch: deps.fetch } : {}),
+            ...(deps.allowedHosts ? { allowedHosts: deps.allowedHosts } : {}),
+            ...(deps.now !== undefined ? { now: deps.now } : {}),
+            ...(deps.allowLoopback ? { allowLoopback: true } : {}),
+            ...(deps.signal ? { signal: deps.signal } : {}),
+            ...(deps.statfs ? { statfs: deps.statfs } : {}),
+            onProgress: ({ downloadedBytes: shardBytes, totalBytes }) => deps.onProgress?.({ tuple, index, total, phase: "download", downloadedBytes: shardBytes, ...(totalBytes !== undefined ? { totalBytes } : {}) }),
+        });
+        deps.onProgress?.({ tuple, index, total, phase: "done", downloadedBytes: descriptor.size, totalBytes: descriptor.size });
+        downloadedBytes += verified.descriptor.size;
+        if (downloadedBytes > BITMAP_SHARD_BUDGET.totalDownloadBytes) {
+            throw new CliError("VALIDATION_ERROR", `bitmap shard total download exceeds the budget (${BITMAP_SHARD_BUDGET.totalDownloadBytes})`);
+        }
+        Object.assign(files, shardAssetsToLocalLayout(verified));
+        shards.push(verified);
+        pins.push(bitmapShardPinFromVerified(verified));
+    }
+    return { requests, shards, pins, files };
+}
+/**
+ * DEV-G07: resolve the config's bitmap tuples, then obtain each selected shard.
+ * Online (an access token is available) fetches one descriptor per tuple from
+ * the API and downloads it from the signed R2 host. Offline (no token) loads
+ * the already-pinned cache and fails closed when any shard is missing.
+ */
+export async function resolveConfiguredBitmapShards(deps) {
+    const resolved = resolveBitmapTuples(deps.config, deps.catalog);
+    if (!resolved.ok)
+        throw new CliError("VALIDATION_ERROR", resolved.errors.join("; "));
+    const tuples = resolved.tuples;
+    if (tuples.length === 0) {
+        return { tuples, requests: [], pins: [], files: {}, bitmapShardSetSha256: bitmapShardSetSha256([]) };
+    }
+    const requests = planBitmapShardRequests(tuples, deps.version);
+    const endpoint = resolveBitmapShardDescriptorEndpoint(deps.env ?? {});
+    const fetched = await fetchSelectedBitmapShards(tuples, {
+        version: deps.version,
+        descriptorSha256: deps.descriptorSha256,
+        accessToken: deps.accessToken,
+        cacheDir: deps.cacheDir,
+        io: deps.io,
+        ...(deps.fetch ? { fetch: deps.fetch } : {}),
+        ...(deps.allowedHosts ? { allowedHosts: deps.allowedHosts } : {}),
+        ...(deps.now !== undefined ? { now: deps.now } : {}),
+        ...(endpoint.allowLoopback ? { allowLoopback: true } : {}),
+        endpoint: endpoint.url,
+        ...(deps.signal ? { signal: deps.signal } : {}),
+        ...(deps.statfs ? { statfs: deps.statfs } : {}),
+        ...(deps.existingPins ? { existingPins: deps.existingPins } : {}),
+        ...(deps.onProgress ? { onProgress: deps.onProgress } : {}),
+    });
+    return {
+        tuples,
+        requests,
+        pins: fetched.pins,
+        files: fetched.files,
+        bitmapShardSetSha256: bitmapShardSetSha256(fetched.pins),
+    };
+}
+/**
+ * Offline path: re-verify every configured tuple's shard against its pinned
+ * identity. The pin supplies the archive SHA, manifest SHA and size, so a
+ * truncated/poisoned cache can never be accepted, and every unselected tuple
+ * is never read.
+ */
+export function loadPinnedBitmapShardAssets(pins, selectedTuples, cacheDir, io) {
+    const wanted = new Map(selectedTuples.map((tuple) => [tupleKey(tuple), tuple]));
+    const files = {};
+    const loaded = [];
+    for (const pin of pins) {
+        const key = tupleKey({
+            styleGroupId: pin.styleGroupId,
+            imageSize: pin.imageSize,
+            format: pin.format,
+        });
+        if (selectedTuples.length > 0 && !wanted.has(key))
+            continue;
+        const target = bitmapShardVerificationTargetFromPin(pin);
+        const cached = loadCachedBitmapShard(target, cacheDir, io);
+        const variantId = buildResourceVariantId(pin.styleGroupId, pin.format, pin.imageSize.width);
+        for (const [path, bytes] of Object.entries(cached.files)) {
+            const iconId = path.slice("icons/".length, path.length - (pin.format.length + 1));
+            files[`assets/${variantId}/${iconId}.${pin.format}`] = bytes;
+        }
+        loaded.push(pin);
+    }
+    if (selectedTuples.length > 0 && loaded.length !== selectedTuples.length) {
+        const missing = selectedTuples
+            .filter((tuple) => !loaded.some((pin) => tupleKey({ styleGroupId: pin.styleGroupId, imageSize: pin.imageSize, format: pin.format }) === tupleKey(tuple)))
+            .map((tuple) => tupleKey(tuple));
+        throw new CliError("VALIDATION_ERROR", `bitmap shards are not all cached: ${missing.join(", ")}; run install while online`);
+    }
+    return { files, pins: loaded, bitmapShardSetSha256: bitmapShardSetSha256(loaded) };
+}

package/dist/core/bitmap-shards.d.ts

@@ -0,0 +1,70 @@
+/**
+ * BITMAP-SHARD-V1 (DEC-97..DEC-108): CLI-side identities for the frozen bitmap
+ * shard contract. Filename/key/canonical-JSON rules must match
+ * `docs/contracts/bitmap-shard-v1.md` and the code-library producer exactly.
+ */
+export declare const BITMAP_SHARD_SCHEMA_VERSION = 1;
+export type BitmapShardTier = "free" | "pro";
+export type BitmapShardFormat = "png" | "webp";
+export interface BitmapShardImageSize {
+    readonly width: number;
+    readonly height: number;
+}
+export interface BitmapShard {
+    readonly schemaVersion: number;
+    readonly resourceVersion: string;
+    readonly tier: BitmapShardTier;
+    readonly styleGroupId: string;
+    readonly imageSize: BitmapShardImageSize;
+    readonly format: BitmapShardFormat;
+    readonly filename: string;
+    readonly objectKey: string;
+    readonly compressedSize: number;
+    readonly expandedSize: number;
+    readonly sha256: string;
+    readonly fileCount: number;
+    readonly manifestSha256: string;
+}
+export interface BitmapShardTuple {
+    readonly tier: BitmapShardTier;
+    readonly styleGroupId: string;
+    readonly imageSize: BitmapShardImageSize;
+    readonly format: BitmapShardFormat;
+}
+export declare function canonicalJson(value: unknown): string;
+export declare function sha256Hex(input: string | Uint8Array): string;
+export declare function buildBitmapShardFilename(input: {
+    tier: BitmapShardTier;
+    styleGroupId: string;
+    imageSize: BitmapShardImageSize;
+    format: BitmapShardFormat;
+    resourceVersion: string;
+}): string;
+export declare function parseBitmapShardFilename(filename: string): (BitmapShardTuple & {
+    readonly resourceVersion: string;
+}) | undefined;
+export declare function buildBitmapShardObjectKey(input: {
+    tier: BitmapShardTier;
+    styleGroupId: string;
+    imageSize: BitmapShardImageSize;
+    format: BitmapShardFormat;
+    resourceVersion: string;
+    filename?: string;
+}): string;
+export declare function sortBitmapShards(shards: readonly BitmapShard[]): BitmapShard[];
+export declare function bitmapShardIdentity(shard: BitmapShard): Record<string, unknown>;
+export declare function bitmapShardSetSha256(shards: readonly BitmapShard[]): string;
+export declare function computeBitmapShardSetSha256(shards: readonly BitmapShard[]): string;
+/** Fail-closed parse of one descriptor shard entry. */
+export declare function parseBitmapShard(raw: unknown): BitmapShard;
+export interface BitmapShardSetValidation {
+    readonly shards: readonly BitmapShard[];
+    readonly bitmapShardSetSha256: string;
+}
+/** Validate uniqueness + canonical order; verify the complete-set digest. */
+export declare function validateBitmapShardSet(shards: readonly BitmapShard[], options?: {
+    readonly resourceVersion?: string;
+    readonly styleGroupIds?: Iterable<string>;
+}): BitmapShardSetValidation;
+/** Verify a descriptor's declared set digest against the actual shard list. */
+export declare function assertBitmapShardSetSha256(shards: readonly BitmapShard[], expected: string): string;

package/dist/core/bitmap-shards.js

@@ -0,0 +1,249 @@
+/**
+ * BITMAP-SHARD-V1 (DEC-97..DEC-108): CLI-side identities for the frozen bitmap
+ * shard contract. Filename/key/canonical-JSON rules must match
+ * `docs/contracts/bitmap-shard-v1.md` and the code-library producer exactly.
+ */
+import { createHash } from "node:crypto";
+export const BITMAP_SHARD_SCHEMA_VERSION = 1;
+const SHA256_RE = /^[a-f0-9]{64}$/;
+const GROUP_RE = /^moe-[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const RESOURCE_VERSION_RE = /^[0-9]+\.[0-9]+\.[0-9]+(?:-(?:alpha|beta))?$/;
+const BITMAP_SIZES = new Set([64, 128, 256, 512]);
+const IDENTITY_FIELDS = [
+    "tier",
+    "styleGroupId",
+    "imageSize",
+    "format",
+    "filename",
+    "objectKey",
+    "compressedSize",
+    "expandedSize",
+    "sha256",
+    "fileCount",
+    "manifestSha256",
+];
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function fail(message) {
+    throw new Error(message);
+}
+/** Canonical JSON per bitmap-shard-v1.md section 4. */
+function canonicalize(value) {
+    if (value === null || typeof value === "boolean" || typeof value === "number") {
+        if (typeof value === "number" && !Number.isFinite(value))
+            fail("canonicalJson: non-finite number");
+        return value;
+    }
+    if (typeof value === "string")
+        return value.normalize("NFC");
+    if (Array.isArray(value))
+        return value.map(canonicalize);
+    if (isRecord(value)) {
+        const out = {};
+        for (const key of Object.keys(value).sort()) {
+            if (value[key] === undefined)
+                fail(`canonicalJson: undefined value at ${key}`);
+            out[key] = canonicalize(value[key]);
+        }
+        return out;
+    }
+    return fail(`canonicalJson: unsupported type ${typeof value}`);
+}
+export function canonicalJson(value) {
+    return JSON.stringify(canonicalize(value));
+}
+export function sha256Hex(input) {
+    return createHash("sha256").update(input).digest("hex");
+}
+function normalizeTuple(input) {
+    const tier = input.tier;
+    const styleGroupId = input.styleGroupId;
+    const format = input.format;
+    const size = input.imageSize;
+    if (tier !== "free" && tier !== "pro")
+        fail(`invalid shard tier: ${String(tier)}`);
+    if (typeof styleGroupId !== "string" || !GROUP_RE.test(styleGroupId))
+        fail(`invalid styleGroupId: ${String(styleGroupId)}`);
+    if (format !== "png" && format !== "webp")
+        fail(`invalid bitmap format: ${String(format)}`);
+    if (!size
+        || !Number.isInteger(size.width)
+        || !Number.isInteger(size.height)
+        || size.width !== size.height
+        || !BITMAP_SIZES.has(size.width)) {
+        fail(`invalid bitmap imageSize for ${String(styleGroupId)}`);
+    }
+    return { tier, styleGroupId, width: size.width, height: size.height, format };
+}
+function assertResourceVersion(resourceVersion) {
+    if (!RESOURCE_VERSION_RE.test(resourceVersion))
+        fail(`invalid resourceVersion: ${String(resourceVersion)}`);
+}
+export function buildBitmapShardFilename(input) {
+    const tuple = normalizeTuple(input);
+    assertResourceVersion(input.resourceVersion);
+    return `moe-icons-bitmap-${tuple.tier}-${tuple.styleGroupId}-${tuple.width}x${tuple.height}-${tuple.format}-${input.resourceVersion}.tgz`;
+}
+export function parseBitmapShardFilename(filename) {
+    const match = /^moe-icons-bitmap-(free|pro)-(.+)-(\d{1,4})x(\d{1,4})-(png|webp)-(\d+\.\d+\.\d+(?:-(?:alpha|beta))?)\.tgz$/.exec(filename);
+    if (!match)
+        return undefined;
+    const [, tier, styleGroupId, width, height, format, resourceVersion] = match;
+    if (!GROUP_RE.test(styleGroupId ?? "") || !RESOURCE_VERSION_RE.test(resourceVersion ?? ""))
+        return undefined;
+    const widthNumber = Number(width);
+    const heightNumber = Number(height);
+    if (widthNumber !== heightNumber || !BITMAP_SIZES.has(widthNumber))
+        return undefined;
+    const rebuilt = buildBitmapShardFilename({
+        tier: tier,
+        styleGroupId: styleGroupId,
+        imageSize: { width: widthNumber, height: heightNumber },
+        format: format,
+        resourceVersion: resourceVersion,
+    });
+    if (rebuilt !== filename)
+        return undefined;
+    return {
+        tier: tier,
+        styleGroupId: styleGroupId,
+        imageSize: { width: widthNumber, height: heightNumber },
+        format: format,
+        resourceVersion: resourceVersion,
+    };
+}
+export function buildBitmapShardObjectKey(input) {
+    const tuple = normalizeTuple(input);
+    assertResourceVersion(input.resourceVersion);
+    const canonical = buildBitmapShardFilename({
+        tier: tuple.tier,
+        styleGroupId: tuple.styleGroupId,
+        imageSize: { width: tuple.width, height: tuple.height },
+        format: tuple.format,
+        resourceVersion: input.resourceVersion,
+    });
+    const name = input.filename ?? canonical;
+    if (name !== canonical)
+        fail("shard filename does not match its tuple");
+    return `moeicons/v1/releases/${input.resourceVersion}/${tuple.tier}/bitmap-shards/${tuple.styleGroupId}/${tuple.width}x${tuple.height}/${tuple.format}/${name}`;
+}
+function compareShards(a, b) {
+    if (a.styleGroupId !== b.styleGroupId)
+        return a.styleGroupId < b.styleGroupId ? -1 : 1;
+    if (a.imageSize.width !== b.imageSize.width)
+        return a.imageSize.width - b.imageSize.width;
+    if (a.imageSize.height !== b.imageSize.height)
+        return a.imageSize.height - b.imageSize.height;
+    if (a.format !== b.format)
+        return a.format < b.format ? -1 : 1;
+    return 0;
+}
+export function sortBitmapShards(shards) {
+    return [...shards].sort(compareShards);
+}
+export function bitmapShardIdentity(shard) {
+    const out = {};
+    for (const field of IDENTITY_FIELDS)
+        out[field] = shard[field];
+    return canonicalize(out);
+}
+export function bitmapShardSetSha256(shards) {
+    return sha256Hex(canonicalJson(sortBitmapShards(shards).map(bitmapShardIdentity)));
+}
+export function computeBitmapShardSetSha256(shards) {
+    return bitmapShardSetSha256(shards);
+}
+/** Fail-closed parse of one descriptor shard entry. */
+export function parseBitmapShard(raw) {
+    if (!isRecord(raw))
+        fail("bitmapShard must be an object");
+    const allowed = ["schemaVersion", "resourceVersion", ...IDENTITY_FIELDS];
+    const extra = Object.keys(raw).filter((key) => !allowed.includes(key));
+    if (extra.length)
+        fail(`bitmapShard has unknown field(s): ${extra.join(", ")}`);
+    if (raw.schemaVersion !== BITMAP_SHARD_SCHEMA_VERSION)
+        fail("bitmapShard schemaVersion must be 1");
+    const resourceVersion = raw.resourceVersion;
+    if (typeof resourceVersion !== "string")
+        fail("bitmapShard resourceVersion required");
+    assertResourceVersion(resourceVersion);
+    const tuple = normalizeTuple({
+        tier: raw.tier,
+        styleGroupId: raw.styleGroupId,
+        imageSize: raw.imageSize,
+        format: raw.format,
+    });
+    const expectedFilename = buildBitmapShardFilename({
+        tier: tuple.tier,
+        styleGroupId: tuple.styleGroupId,
+        imageSize: { width: tuple.width, height: tuple.height },
+        format: tuple.format,
+        resourceVersion,
+    });
+    if (raw.filename !== expectedFilename)
+        fail(`bitmapShard filename is not canonical: ${String(raw.filename)}`);
+    const expectedKey = buildBitmapShardObjectKey({
+        tier: tuple.tier,
+        styleGroupId: tuple.styleGroupId,
+        imageSize: { width: tuple.width, height: tuple.height },
+        format: tuple.format,
+        resourceVersion,
+        filename: raw.filename,
+    });
+    if (raw.objectKey !== expectedKey)
+        fail(`bitmapShard objectKey is not canonical: ${String(raw.objectKey)}`);
+    if (typeof raw.sha256 !== "string" || !SHA256_RE.test(raw.sha256))
+        fail("bitmapShard sha256 must be 64 lowercase hex");
+    if (typeof raw.manifestSha256 !== "string" || !SHA256_RE.test(raw.manifestSha256)) {
+        fail("bitmapShard manifestSha256 must be 64 lowercase hex");
+    }
+    for (const field of ["compressedSize", "expandedSize", "fileCount"]) {
+        const value = raw[field];
+        if (typeof value !== "number" || !Number.isInteger(value) || value <= 0) {
+            fail(`bitmapShard ${field} must be a positive integer`);
+        }
+    }
+    return raw;
+}
+/** Validate uniqueness + canonical order; verify the complete-set digest. */
+export function validateBitmapShardSet(shards, options = {}) {
+    const seen = new Set();
+    for (const shard of shards) {
+        if (options.resourceVersion !== undefined && shard.resourceVersion !== options.resourceVersion) {
+            fail("bitmapShard resourceVersion mismatch");
+        }
+        const key = `${shard.tier}/${shard.styleGroupId}/${shard.imageSize.width}x${shard.imageSize.height}/${shard.format}`;
+        if (seen.has(key))
+            fail(`duplicate bitmap shard tuple: ${key}`);
+        seen.add(key);
+    }
+    const sorted = sortBitmapShards(shards);
+    for (let index = 0; index < shards.length; index += 1) {
+        const a = shards[index];
+        const b = sorted[index];
+        if (a.styleGroupId !== b.styleGroupId
+            || a.imageSize.width !== b.imageSize.width
+            || a.imageSize.height !== b.imageSize.height
+            || a.format !== b.format) {
+            fail(`bitmapShards is not in canonical order at index ${index}`);
+        }
+    }
+    if (options.styleGroupIds) {
+        const declared = new Set(options.styleGroupIds);
+        for (const shard of shards) {
+            if (!declared.has(shard.styleGroupId))
+                fail(`bitmap shard for unknown style group: ${shard.styleGroupId}`);
+        }
+    }
+    return { shards: sorted, bitmapShardSetSha256: bitmapShardSetSha256(shards) };
+}
+/** Verify a descriptor's declared set digest against the actual shard list. */
+export function assertBitmapShardSetSha256(shards, expected) {
+    if (!SHA256_RE.test(expected))
+        fail("bitmapShardSetSha256 must be 64 lowercase hex");
+    const actual = bitmapShardSetSha256(shards);
+    if (actual !== expected)
+        fail(`bitmapShardSetSha256 mismatch: expected ${expected}, got ${actual}`);
+    return actual;
+}

package/dist/core/bootstrap.d.ts

@@ -0,0 +1,37 @@
+import type { TransactionalFs } from "../project/install.js";
+import type { CommandContext } from "./context.js";
+import type { FreeDownloadIo } from "./free-download.js";
+export interface BootstrapFs {
+    readonly existsSync: (path: string) => boolean;
+    readonly readFileSync: (path: string) => string;
+    readonly writeFileSync: (path: string, content: string) => void;
+    readonly mkdirSync: (path: string) => void;
+}
+export interface BootstrapDeps {
+    readonly fs: BootstrapFs;
+    readonly installFs: TransactionalFs;
+    readonly free: Omit<FreeDownloadIo, "signal">;
+    readonly cliVersion: string;
+}
+export type BootstrapResult = {
+    readonly kind: "skipped";
+    readonly reason: string;
+} | {
+    readonly kind: "already";
+} | {
+    readonly kind: "installed";
+    readonly version: string;
+} | {
+    readonly kind: "failed";
+    readonly message: string;
+    readonly retry: string;
+};
+export declare function bootstrapMarkerPath(env: Readonly<Record<string, string | undefined>>): string;
+/**
+ * First-run bootstrap: on an interactive first start inside a project, install
+ * Free code + Free metadata without an extra metadata prompt. The marker is
+ * written only after a fully successful install (or when a valid free install
+ * already exists), so a half-completed run never suppresses retry. A declined
+ * prompt writes a `declined` marker so the CLI does not nag on every start.
+ */
+export declare function runBootstrapUseCase(context: CommandContext, deps: BootstrapDeps): Promise<BootstrapResult>;

package/dist/core/bootstrap.js

@@ -0,0 +1,54 @@
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { detectProject } from "../project/detect.js";
+import { readInstalledResourceState } from "../project/install-metadata.js";
+import { runInstallUseCase } from "./install.js";
+export function bootstrapMarkerPath(env) {
+    return (env.MOEICONS_BOOTSTRAP_FILE ??
+        join(env.MOEICONS_CACHE_DIR ?? join(homedir(), ".moeicons", "cache"), "bootstrap.json"));
+}
+function writeMarker(deps, env, content) {
+    const marker = bootstrapMarkerPath(env);
+    const body = `${JSON.stringify({ schemaVersion: 1, ...content }, null, 2)}\n`;
+    const parent = marker.replace(/[\\/][^\\/]*$/, "") || "/";
+    deps.fs.mkdirSync(parent);
+    deps.fs.writeFileSync(marker, body);
+}
+/**
+ * First-run bootstrap: on an interactive first start inside a project, install
+ * Free code + Free metadata without an extra metadata prompt. The marker is
+ * written only after a fully successful install (or when a valid free install
+ * already exists), so a half-completed run never suppresses retry. A declined
+ * prompt writes a `declined` marker so the CLI does not nag on every start.
+ */
+export async function runBootstrapUseCase(context, deps) {
+    if (!context.ui.confirm)
+        return { kind: "skipped", reason: "non-interactive" };
+    const marker = bootstrapMarkerPath(context.env);
+    if (deps.fs.existsSync(marker))
+        return { kind: "already" };
+    const project = detectProject(context.cwd);
+    if (!project)
+        return { kind: "skipped", reason: "no-project" };
+    const state = readInstalledResourceState(project.root, "free");
+    if (state.kind === "ok" &&
+        deps.fs.existsSync(join(project.root, ".moeicons", "MANUAL.md")) &&
+        deps.fs.existsSync(join(project.root, ".moeicons", "manifest.json"))) {
+        writeMarker(deps, context.env, { cliVersion: deps.cliVersion, libraryVersion: state.metadata.artifactVersion, completedAt: new Date().toISOString() });
+        return { kind: "already" };
+    }
+    const confirmed = await context.ui.confirm("Set up moeicons Free icons in this project now? (recommended)", context.signal);
+    if (confirmed !== true) {
+        writeMarker(deps, context.env, { cliVersion: deps.cliVersion, declinedAt: new Date().toISOString() });
+        return { kind: "skipped", reason: "declined" };
+    }
+    const result = await runInstallUseCase(context, { fs: deps.installFs, download: deps.free }, {});
+    if (!result.ok) {
+        if (result.reason === "no-project" || result.reason === "cancelled") {
+            return { kind: "skipped", reason: result.reason };
+        }
+        return { kind: "failed", message: result.message, retry: "moeicons install free" };
+    }
+    writeMarker(deps, context.env, { cliVersion: deps.cliVersion, libraryVersion: result.artifactVersion, completedAt: new Date().toISOString() });
+    return { kind: "installed", version: result.artifactVersion };
+}