@moewolf/moe-icons-cli 0.0.10 → 0.0.14

package/dist/core/small-package-install.js

@@ -0,0 +1,252 @@
+import { constants, closeSync, fstatSync, openSync, readSync } from "node:fs";
+import { createHash, randomUUID } from "node:crypto";
+import { dirname, posix } from "node:path";
+import { canonicalBytes, sha256 } from "./small-pack/candidate-set.cjs";
+import { downloadFreeStablePackages, downloadFreeVersionPackages } from "./free-small-package-download.js";
+import { downloadProStablePackages, downloadProVersionPackages } from "./pro-small-package-download.js";
+import { packageTargetFiles, planConfigPackagesFromMetadata } from "./config-package-plan.js";
+import { createInstallPlan, executeInstallPlan, safeManagedPath } from "../project/install.js";
+import { loadConfigDocument } from "../project/config.js";
+import { serializePackageInstallMetadata } from "../project/package-install-metadata.js";
+import { sha256Bytes } from "../project/install-metadata.js";
+import { withProjectLock } from "../project/project-lock.js";
+function targetSubtreeDigest(files) {
+    const hash = createHash("sha256");
+    let fileCount = 0;
+    let byteCount = 0;
+    const namesAt = (prefix) => {
+        const names = new Set();
+        for (const rel of files.keys()) {
+            if (!prefix || rel.startsWith(`${prefix}/`)) {
+                const rest = prefix ? rel.slice(prefix.length + 1) : rel;
+                const slash = rest.indexOf("/");
+                names.add(slash === -1 ? rest : rest.slice(0, slash));
+            }
+        }
+        return [...names].sort((a, b) => a.localeCompare(b));
+    };
+    const appendFile = (entry) => {
+        const descriptor = openSync(entry.absolutePath, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+        try {
+            if (!fstatSync(descriptor).isFile())
+                throw new Error("staged target output is not a regular file");
+            const buffer = Buffer.allocUnsafe(64 * 1024);
+            let position = 0;
+            let count = 1;
+            while (count > 0) {
+                count = readSync(descriptor, buffer, 0, buffer.length, position);
+                if (count === 0)
+                    break;
+                hash.update(buffer.subarray(0, count));
+                position += count;
+            }
+            if (position !== entry.byteSize)
+                throw new Error("staged target output changed while calculating install identity");
+            byteCount += position;
+        }
+        finally {
+            closeSync(descriptor);
+        }
+    };
+    const walk = (prefix) => {
+        for (const name of namesAt(prefix)) {
+            const relative = prefix ? `${prefix}/${name}` : name;
+            const entry = files.get(relative);
+            if (entry) {
+                hash.update(relative).update("\0");
+                appendFile(entry);
+                hash.update("\0");
+                fileCount += 1;
+            }
+            else
+                walk(relative);
+        }
+    };
+    walk("");
+    return { sha256: hash.digest("hex"), fileCount, byteCount };
+}
+function destination(area, target, path) {
+    if (area === "target")
+        return `.moeicons/artifact/${target}/${path}`;
+    if (area === "assets")
+        return `.moeicons/artifact/assets/${path}`;
+    return `.moeicons/package-metadata/${path}`;
+}
+export async function runSmallPackageInstall(options) {
+    if (options.config.downloadMode === "full")
+        throw new Error("package installs require downloadMode=icons; full archive delivery is disabled");
+    if (options.config.tier === "pro" && (!options.proAccessToken || options.proAccessToken.length > 8192 || /[\r\n]/.test(options.proAccessToken))) {
+        throw new Error("Pro package installs require an authenticated access token");
+    }
+    if (options.config.icons.length === 0 || Object.keys(options.config.themes).length === 0)
+        throw new Error("configure at least one icon and theme before installing selected packages");
+    const operationId = randomUUID();
+    const stageRoot = `.moeicons/.package-stage-${operationId}`;
+    const stageRootPath = safeManagedPath(options.projectRoot, stageRoot).target;
+    const controlPath = safeManagedPath(options.projectRoot, ".moeicons").target;
+    let packagePlan;
+    let candidateRoot;
+    let installedFileCount = 0;
+    let nextFile = 0;
+    const installFiles = Object.create(null);
+    const targetFiles = new Map();
+    const assetManifestEntries = [];
+    const stageFile = (installPath, relativeToTarget, bytes) => {
+        if (Object.hasOwn(installFiles, installPath))
+            throw new Error(`selected packages produce a duplicate install path: ${installPath}`);
+        const stagedRelative = `${stageRoot}/files/${String(nextFile++).padStart(6, "0")}`;
+        const stagedPath = safeManagedPath(options.projectRoot, stagedRelative);
+        options.fs.mkdirSync(dirname(stagedPath.target), { recursive: true });
+        options.fs.writeFileSync(stagedPath.target, bytes);
+        const digest = sha256Bytes(bytes);
+        const staged = { kind: "staged-file", path: stagedRelative, sha256: digest };
+        installFiles[installPath] = staged;
+        installedFileCount += 1;
+        if (relativeToTarget !== undefined) {
+            if (targetFiles.has(relativeToTarget))
+                throw new Error(`selected packages produce a duplicate target file: ${relativeToTarget}`);
+            targetFiles.set(relativeToTarget, { absolutePath: stagedPath.target, byteSize: bytes.byteLength });
+        }
+    };
+    options.fs.mkdirSync(controlPath, { recursive: true });
+    options.fs.mkdirSync(stageRootPath, { recursive: false });
+    try {
+        const downloadOptions = {
+            cacheDir: options.cacheDir,
+            ...(options.apiBaseUrl ? { apiBaseUrl: options.apiBaseUrl } : {}),
+            ...(options.signal ? { signal: options.signal } : {}),
+            ...(options.fetchFn ? { fetchFn: options.fetchFn } : {}),
+            ...(options.fixtureOrigin ? { fixtureOrigin: options.fixtureOrigin } : {}),
+            resolveResourceKeys: async (candidate, loadVerifiedPackage) => {
+                candidateRoot = candidate;
+                packagePlan = await planConfigPackagesFromMetadata(options.config, candidate, loadVerifiedPackage);
+                return packagePlan.resourceKeys;
+            },
+            consume: (row, verifiedFiles) => {
+                const mapped = packageTargetFiles(row, verifiedFiles, options.config.target);
+                for (const [relative, bytes] of Object.entries(mapped.files)) {
+                    const installPath = destination(mapped.area, options.config.target, relative);
+                    if (mapped.area === "assets") {
+                        assetManifestEntries.push({ path: relative, size: bytes.byteLength, sha256: sha256Bytes(bytes) });
+                    }
+                    const targetRelative = mapped.area === "target" || options.config.target === "assets" && mapped.area === "assets"
+                        ? relative
+                        : undefined;
+                    stageFile(installPath, targetRelative, bytes);
+                }
+                return Promise.resolve();
+            },
+        };
+        const report = options.config.tier === "free"
+            ? options.fullVersion
+                ? await downloadFreeVersionPackages({ ...downloadOptions, fullVersion: options.fullVersion, ...(options.expectedPackageSetSha256 ? { expectedPackageSetSha256: options.expectedPackageSetSha256 } : {}) })
+                : await downloadFreeStablePackages(downloadOptions)
+            : options.fullVersion && options.expectedPackageSetSha256
+                ? await downloadProVersionPackages({ ...downloadOptions, accessToken: options.proAccessToken, fullVersion: options.fullVersion, expectedPackageSetSha256: options.expectedPackageSetSha256 })
+                : options.fullVersion || options.expectedPackageSetSha256
+                    ? (() => { throw new Error("Pro package-set updates require both exact version and package-set SHA-256"); })()
+                    : await downloadProStablePackages({ ...downloadOptions, accessToken: options.proAccessToken });
+        if (!packagePlan || !candidateRoot)
+            throw new Error("candidate planner did not produce an install plan");
+        if (options.signal?.aborted)
+            throw new Error("package install cancelled");
+        const catalogJson = `${JSON.stringify(packagePlan.catalog, null, 2)}\n`;
+        const catalogSha256 = sha256Bytes(catalogJson);
+        installFiles[".moeicons/catalog.json"] = catalogJson;
+        if (assetManifestEntries.length > 0) {
+            const assets = assetManifestEntries.sort((a, b) => a.path.localeCompare(b.path, "en"));
+            const manifestBytes = Buffer.from(`${JSON.stringify({ schemaVersion: 1, assets }, null, 2)}\n`);
+            if (options.config.target === "assets")
+                stageFile(".moeicons/artifact/assets/manifest.json", "manifest.json", manifestBytes);
+            else
+                installFiles[".moeicons/artifact/assets/manifest.json"] = manifestBytes;
+        }
+        installFiles[".moeicons/artifact/package.json"] = '{"private":true,"type":"module","sideEffects":false}\n';
+        const outputDir = options.config.outputDir.replace(/\\/g, "/").replace(/\/$/, "");
+        installFiles[`${outputDir}/types.ts`] = smallPackageTypesReexport(options.config.target, outputDir);
+        installFiles[`${outputDir}/.moeicons-${options.config.tier}.marker`] = `${options.config.tier}\n`;
+        const tree = targetSubtreeDigest(targetFiles);
+        if (tree.fileCount === 0)
+            throw new Error("selected candidate contains no files for the configured target");
+        const candidateRootSha256 = sha256(canonicalBytes(candidateRoot.root));
+        const packagePins = packagePlan.packages
+            .map((row) => ({ resourceKey: row.resourceKey, packageSha256: row.packageSha256, dependencies: [...row.dependencies] }))
+            .sort((a, b) => a.resourceKey.localeCompare(b.resourceKey, "en"));
+        const metadata = {
+            schemaVersion: 2,
+            candidate: {
+                schemaVersion: 1,
+                tier: options.config.tier,
+                fullVersion: candidateRoot.root.fullVersion,
+                sourceCommit: candidateRoot.root.sourceCommit,
+                generatorCommit: candidateRoot.root.generatorCommit,
+                packageSetSha256: candidateRoot.root.packageSetSha256,
+                candidateRootSha256,
+            },
+            target: options.config.target,
+            resourceKeys: [...packagePlan.resourceKeys].sort((a, b) => a.localeCompare(b, "en")),
+            packages: packagePins,
+            catalogSha256,
+            installedAt: options.now().toISOString(),
+            managedFiles: Object.fromEntries(Object.entries(installFiles).map(([path, content]) => [
+                path,
+                typeof content === "object" && "kind" in content ? content.sha256 : sha256Bytes(content),
+            ])),
+            targetSha256: tree.sha256,
+            targetFileCount: tree.fileCount,
+            targetByteCount: tree.byteCount,
+            generatedOutputDir: outputDir,
+        };
+        const metadataText = serializePackageInstallMetadata(metadata);
+        installFiles[".moeicons/install-metadata.json"] = metadataText;
+        const plan = createInstallPlan(options.projectRoot, installFiles);
+        await withProjectLock(options.projectRoot, "install", () => {
+            if (JSON.stringify(loadConfigDocument(options.projectRoot)) !== options.plannedConfigDocument)
+                throw new Error("config changed while preparing package install; retry");
+            executeInstallPlan(plan, options.fs);
+        });
+        return {
+            artifactVersion: candidateRoot.root.fullVersion,
+            candidateRootSha256,
+            packageSetSha256: candidateRoot.root.packageSetSha256,
+            catalogSha256,
+            metadataSha256: sha256Bytes(metadataText),
+            artifactBytes: packagePlan.packages.reduce((sum, row) => sum + row.compressedBytes, 0),
+            files: Object.keys(installFiles).sort((a, b) => a.localeCompare(b, "en")),
+            packageCount: report.packageCount,
+            planItems: plan.items.length,
+            selectedFiles: installedFileCount,
+            networkBytes: report.networkBytes + report.metadataNetworkBytes,
+            cacheHit: report.networkBytes === 0 && report.metadataNetworkBytes === 0,
+            cacheHits: report.cacheHits,
+            metadataCacheHits: report.metadataCacheHits,
+            transferRetryCount: report.transferRetryCount,
+            target: options.config.target,
+            targetSha256: tree.sha256,
+            targetFileCount: tree.fileCount,
+            targetByteCount: tree.byteCount,
+            fallbacks: packagePlan.fallbacks,
+        };
+    }
+    catch (error) {
+        try {
+            if (options.fs.existsSync(stageRootPath))
+                options.fs.rmSync(stageRootPath, { recursive: true, force: true });
+        }
+        catch (cleanupError) {
+            throw new AggregateError([error, cleanupError], `small package install failed; staging cleanup failed at ${stageRootPath}`);
+        }
+        throw error;
+    }
+}
+function smallPackageTypesReexport(target, outputDir) {
+    const from = posix.relative(outputDir.replace(/\\/g, "/"), `.moeicons/artifact/${target}/types`);
+    const specifier = from.startsWith(".") ? from : `./${from}`;
+    if (target === "react")
+        return `export type { ReactIconProps } from "${specifier}";\n`;
+    if (target === "vue")
+        return `export type { VueIconProps } from "${specifier}";\n`;
+    if (target === "vanilla")
+        return `export type { VanillaIconOptions } from "${specifier}";\n`;
+    return "export {};\n";
+}

package/dist/core/small-package-selection.d.ts

@@ -0,0 +1,27 @@
+import { type CandidateRoot, type PackageRow, type PageRef } from './small-pack/candidate-set.cjs';
+export interface CandidateIdentity {
+    fullVersion: string;
+    tier: 'free' | 'pro';
+    sourceCommit: string;
+    generatorCommit: string;
+    packageSetSha256: string;
+}
+export interface SelectedCandidate {
+    readonly root: CandidateRoot;
+    readonly rows: readonly PackageRow[];
+}
+export declare function readSelectedCandidate(rootBytes: Uint8Array, expected: CandidateIdentity, readPage: (ref: PageRef) => Promise<Uint8Array>): Promise<SelectedCandidate>;
+export declare function planSelectedPackages(candidate: SelectedCandidate, resourceKeys: readonly string[]): readonly PackageRow[];
+export declare function verifySelectedPackage(row: PackageRow, bytes: Uint8Array): Readonly<Record<string, Uint8Array>>;
+export interface SelectedPackageIo {
+    readCache(row: PackageRow): Promise<Uint8Array | undefined>;
+    writeCache(row: PackageRow, bytes: Uint8Array): Promise<void>;
+    download(row: PackageRow): Promise<Uint8Array>;
+    consume(row: PackageRow, files: Readonly<Record<string, Uint8Array>>): Promise<void>;
+    signal?: AbortSignal;
+}
+export declare function consumeSelectedPackages(candidate: SelectedCandidate, resourceKeys: readonly string[], io: SelectedPackageIo): Promise<{
+    packageCount: number;
+    networkBytes: number;
+    cacheHits: number;
+}>;

package/dist/core/small-package-selection.js

@@ -0,0 +1,114 @@
+import { gunzipSync } from 'node:zlib';
+import { canonicalBytes, sha256, parseCandidateSet, validatePackagePages, verifyPackagePayload } from './small-pack/candidate-set.cjs';
+import { readTarEntries } from './small-pack/tar-read.cjs';
+function check(ok, message) { if (!ok)
+    throw new Error(`small-package selection: ${message}`); }
+export async function readSelectedCandidate(rootBytes, expected, readPage) {
+    const root = parseCandidateSet(rootBytes);
+    for (const key of ['fullVersion', 'tier', 'sourceCommit', 'generatorCommit', 'packageSetSha256'])
+        check(root[key] === expected[key], `candidate ${key} differs from exact pin`);
+    check(root.packagePages.reduce((sum, ref) => sum + ref.sizeBytes, 0) <= 16 * 1024 ** 2, 'metadata exceeds 16 MiB budget');
+    const pages = new Map();
+    for (const ref of root.packagePages)
+        pages.set(ref.filename, await readPage({ ...ref }));
+    return { root, rows: validatePackagePages(root, pages) };
+}
+export function planSelectedPackages(candidate, resourceKeys) {
+    check(resourceKeys.length > 0 && new Set(resourceKeys).size === resourceKeys.length, 'explicit unique resource keys required');
+    const keys = new Map(candidate.rows.map(row => [row.resourceKey, row]));
+    const digests = new Map(candidate.rows.map(row => [row.packageSha256, row]));
+    check(digests.size === candidate.rows.length, 'ambiguous package digest across directory');
+    const visited = new Set(), visiting = new Set(), ordered = [];
+    const visit = (row) => {
+        check(row.tier === candidate.root.tier && row.fullVersion === candidate.root.fullVersion, 'selected row identity mismatch');
+        if (visited.has(row.packageSha256))
+            return;
+        check(!visiting.has(row.packageSha256), 'cyclic package dependency');
+        visiting.add(row.packageSha256);
+        for (const digest of row.dependencies) {
+            const dependency = digests.get(digest);
+            check(dependency, 'missing selected dependency');
+            visit(dependency);
+        }
+        visiting.delete(row.packageSha256);
+        visited.add(row.packageSha256);
+        ordered.push(JSON.parse(canonicalBytes(row).toString('utf8')));
+    };
+    for (const key of resourceKeys) {
+        const row = keys.get(key);
+        check(row, `selected resource absent: ${key}`);
+        visit(row);
+    }
+    return ordered;
+}
+function object(value) { check(value && typeof value === 'object' && !Array.isArray(value), 'manifest object required'); return value; }
+export function verifySelectedPackage(row, bytes) {
+    check(['svg', 'code', 'shared', 'metadata', 'bitmap'].includes(row.kind), 'unsupported selected package kind');
+    verifyPackagePayload(row, bytes);
+    const tar = gunzipSync(bytes, { maxOutputLength: row.expandedBytes + (row.fileCount * 4 + 4) * 512 + 10240 });
+    const entries = readTarEntries(tar, { maxEntries: row.fileCount * 4 + 4, maxExpandedBytes: row.expandedBytes + 1024 * 1024 });
+    const files = Object.create(null);
+    const paths = new Set();
+    for (const entry of entries) {
+        if (entry.type === 'dir' && entry.path === '.')
+            continue;
+        const name = entry.path.startsWith('./') ? entry.path.slice(2) : entry.path;
+        check(name.length <= 1024 && !/[\\:]/.test(name) && ![...name].some(char => char.charCodeAt(0) < 32 || char.charCodeAt(0) === 127) && !name.startsWith('/') && name.split('/').every(p => p && p !== '.' && p !== '..'), 'unsafe package path');
+        check(!paths.has(name), 'duplicate package path');
+        paths.add(name);
+        check(entry.type === 'file' || entry.type === 'dir', 'links and special files forbidden');
+        if (entry.type === 'file') {
+            check(entry.data, 'file bytes missing');
+            files[name] = entry.data;
+        }
+    }
+    check(Object.keys(files).length === row.fileCount && Object.values(files).reduce((sum, b) => sum + b.length, 0) === row.expandedBytes, 'package inventory differs from row');
+    const bytesManifest = files['manifest.json'];
+    check(bytesManifest && bytesManifest.length <= 8 * 1024 ** 2, 'bounded package manifest required');
+    const manifest = object(JSON.parse(Buffer.from(bytesManifest).toString('utf8')));
+    check(Buffer.from(bytesManifest).equals(canonicalBytes(manifest)) && manifest.schemaVersion === 1, 'canonical package manifest required');
+    const scope = ['kind', 'tier', 'styleGroupId', 'target', 'variant'];
+    check(Object.keys(manifest).every(k => ['schemaVersion', 'files', ...scope].includes(k)), 'unexpected manifest fields');
+    for (const key of scope)
+        check(canonicalBytes({ value: manifest[key] }).equals(canonicalBytes({ value: row[key] })), 'package scope differs from row');
+    check(Array.isArray(manifest.files) && manifest.files.length === row.fileCount - 1, 'manifest inventory mismatch');
+    const seen = new Set(['manifest.json']);
+    for (const raw of manifest.files) {
+        const item = object(raw);
+        check(Object.keys(item).sort().join(',') === 'byteSize,path,sha256' && typeof item.path === 'string' && !seen.has(item.path), 'invalid manifest file');
+        seen.add(item.path);
+        const data = files[item.path];
+        check(data && data.length === item.byteSize && sha256(data) === item.sha256, 'manifest file SHA/size mismatch');
+        if (row.kind === 'svg')
+            check(/^[a-z0-9]+(?:-[a-z0-9]+)*\.svg$/.test(item.path), 'SVG package contains another resource kind');
+        if (row.kind === 'code' || row.kind === 'shared')
+            check(/\.(js|cjs|mjs|ts|cts|mts|tsx|jsx|json|map|vue)$/.test(item.path), 'code package contains non-code payload');
+        if (row.kind === 'metadata')
+            check(['metadata/MANUAL.md', 'metadata/catalog.json', 'metadata/manifest.json'].includes(item.path), 'unexpected metadata payload');
+        if (row.kind === 'bitmap')
+            check(new RegExp(`^icons/[a-z0-9]+(?:-[a-z0-9]+)*\\.${row.variant?.format}$`).test(item.path), 'bitmap package crosses tuple scope');
+    }
+    return files;
+}
+export async function consumeSelectedPackages(candidate, resourceKeys, io) {
+    const plan = planSelectedPackages(candidate, resourceKeys);
+    let networkBytes = 0, cacheHits = 0;
+    for (const row of plan) {
+        io.signal?.throwIfAborted();
+        let bytes = await io.readCache(row);
+        const cached = bytes !== undefined;
+        if (bytes !== undefined)
+            cacheHits++;
+        else {
+            bytes = await io.download(row);
+            networkBytes += bytes.length;
+        }
+        const files = verifySelectedPackage(row, bytes);
+        // Cache only validated complete packages before consumption, so a later
+        // target write failure can reuse this unit without another network fetch.
+        if (!cached)
+            await io.writeCache(row, bytes);
+        await io.consume(row, files);
+    }
+    return { packageCount: plan.length, networkBytes, cacheHits };
+}

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

@@ -4,6 +4,7 @@ interface ParsedVersion {
     minor: number;
     patch: number;
     channel: "stable" | "alpha" | "beta";
+    prereleaseNumber: number | null;
 }
 export declare function parseVersion(value: string): ParsedVersion | undefined;
 export type UpdateDecision = {

package/dist/core/update-policy.js

@@ -1,9 +1,15 @@
-const VERSION = /^(\d+)\.(\d+)\.(\d+)(?:-(alpha|beta))?$/;
+const VERSION = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-(alpha|beta)(?:\.(0|[1-9]\d*))?)?$/;
 export function parseVersion(value) {
     const match = VERSION.exec(value);
     if (!match)
         return undefined;
-    return { major: Number(match[1]), minor: Number(match[2]), patch: Number(match[3]), channel: match[4] ?? "stable" };
+    return {
+        major: Number(match[1]),
+        minor: Number(match[2]),
+        patch: Number(match[3]),
+        channel: match[4] ?? "stable",
+        prereleaseNumber: match[4] ? Number(match[5] ?? 0) : null,
+    };
 }
 export function decideUpdate(input) {
     if (input.installedTier !== input.remoteTier)
@@ -14,7 +20,8 @@ export function decideUpdate(input) {
         return { kind: "refuse", reason: "invalid-version" };
     if (local.channel !== remote.channel)
         return { kind: "refuse", reason: "channel-mismatch" };
-    const comparison = remote.major - local.major || remote.minor - local.minor || remote.patch - local.patch;
+    const comparison = remote.major - local.major || remote.minor - local.minor || remote.patch - local.patch ||
+        (local.channel === "stable" ? 0 : (remote.prereleaseNumber ?? 0) - (local.prereleaseNumber ?? 0));
     if (comparison === 0)
         return { kind: "current" };
     return comparison > 0 ? { kind: "update" } : { kind: "refuse", reason: "downgrade" };

package/dist/mcp/services.js

@@ -84,7 +84,7 @@ export function createProjectMcpServices(runtime, execute) {
         for (const key of ["dryRun"])
             if (args[key] !== undefined && typeof args[key] !== "boolean")
                 throw new McpArgumentError(`${key} must be boolean`);
-        if (args.target !== undefined && !["react", "vue", "vanilla", "assets"].includes(String(args.target)))
+        if (args.target !== undefined && (typeof args.target !== "string" || !["react", "vue", "vanilla", "assets"].includes(args.target)))
             throw new McpArgumentError("invalid target");
         if (name === "install_icon_group") {
             if (typeof args.groupId !== "string" || typeof args.projectPath !== "string")

package/dist/project/config.js

@@ -106,7 +106,7 @@ function requireCommonConfigFields(obj, sourceCatalog, lenientCatalog) {
         throw new Error("themes must be an object");
     }
     if (obj.downloadMode !== undefined &&
-        !["auto", "icons", "full"].includes(String(obj.downloadMode)))
+        (typeof obj.downloadMode !== "string" || !["auto", "icons", "full"].includes(obj.downloadMode)))
         throw new Error('downloadMode must be "auto", "icons" or "full"');
     if (obj.missingIconPolicy !== undefined &&
         obj.missingIconPolicy !== "fallback" &&

package/dist/project/install-metadata.d.ts

@@ -1,4 +1,5 @@
 import { type BitmapShard } from "../core/bitmap-shards.js";
+import { type PackageInstallMetadata } from "./package-install-metadata.js";
 export interface InstallMetadata {
     readonly schemaVersion: 1;
     readonly delivery?: {
@@ -36,7 +37,7 @@ export interface InstallMetadataParseOptions {
 }
 export type InstalledResourceState = {
     readonly kind: "ok";
-    readonly metadata: InstallMetadata;
+    readonly metadata: InstallMetadata | PackageInstallMetadata;
 } | {
     readonly kind: "missing";
     readonly message: string;

package/dist/project/install-metadata.js

@@ -2,6 +2,7 @@ import { createHash } from "node:crypto";
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { bitmapShardSetSha256, parseBitmapShard } from "../core/bitmap-shards.js";
+import { parsePackageInstallMetadata } from "./package-install-metadata.js";
 const SHA256 = /^[a-f0-9]{64}$/;
 const VERSION = /^\d+\.\d+\.\d+(?:-(?:alpha|beta))?$/;
 const LOCAL_TEST_VERSION = /^\d+\.\d+\.\d+-test$/;
@@ -133,16 +134,18 @@ export function readInstalledResourceState(projectRoot, expectedTier, opts = {})
             kind: "missing",
             message: "managed install metadata is missing; run 'moeicons install' to repair or reinstall",
         };
-    const metadata = parseInstallMetadata(readFileSync(metadataPath, "utf8"), opts);
+    const raw = readFileSync(metadataPath, "utf8");
+    const metadata = parseInstallMetadata(raw, opts) ?? parsePackageInstallMetadata(raw);
     if (!metadata)
         return {
             kind: "invalid",
             message: "managed install metadata is invalid; run 'moeicons install' to repair or reinstall",
         };
-    if (expectedTier && metadata.tier !== expectedTier)
+    const tier = metadata.schemaVersion === 1 ? metadata.tier : metadata.candidate.tier;
+    if (expectedTier && tier !== expectedTier)
         return {
             kind: "invalid",
-            message: `installed tier ${metadata.tier} does not match config tier ${expectedTier}`,
+            message: `installed tier ${tier} does not match config tier ${expectedTier}`,
         };
     for (const [relative, expectedHash] of Object.entries(metadata.managedFiles)) {
         const path = join(projectRoot, relative);

package/dist/project/install.d.ts

@@ -11,7 +11,16 @@ export interface InstallPlanItem {
     readonly rel?: string;
     readonly content?: string;
     readonly bytes?: Uint8Array;
+    /** A verified file in a private .moeicons/.package-stage-<uuid> directory. */
+    readonly staged?: StagedInstallFile;
 }
+export interface StagedInstallFile {
+    readonly kind: "staged-file";
+    /** Project-relative path under .moeicons/.package-stage-<uuid>. */
+    readonly path: string;
+    readonly sha256: string;
+}
+export type ManagedFileContent = string | Uint8Array | StagedInstallFile;
 export interface InstallPlan {
     readonly root?: string;
     readonly items: readonly InstallPlanItem[];
@@ -37,7 +46,7 @@ export declare function safeManagedPath(projectRoot: string, relative: string):
  * Atomically reconcile an explicit cross-directory managed set. `removePaths`
  * must come from trusted metadata; this function never scans or uses globs.
  */
-export declare function executeManagedReconcile(projectRoot: string, writes: Readonly<Record<string, string | Uint8Array>>, removePaths: readonly string[], fs_: TransactionalFsWithCopy, options?: {
+export declare function executeManagedReconcile(projectRoot: string, writes: Readonly<Record<string, ManagedFileContent>>, removePaths: readonly string[], fs_: TransactionalFsWithCopy, options?: {
     readonly expectedText?: Readonly<Record<string, string | undefined>>;
     readonly expectedSha256?: Readonly<Record<string, string | undefined>>;
 }): void;
@@ -47,7 +56,7 @@ export declare function executeManagedReconcile(projectRoot: string, writes: Rea
  */
 export declare function recoverManagedReconcile(projectRoot: string, fs_: TransactionalFsWithCopy): number;
 /** Pure list of install operations with expected checksums. */
-export declare function createInstallPlan(targetRoot: string, files: Readonly<Record<string, string | Uint8Array>>): InstallPlan;
+export declare function createInstallPlan(targetRoot: string, files: Readonly<Record<string, ManagedFileContent>>): InstallPlan;
 /** Create a deterministic ZIP for delivery (fixed mtime). */
 export declare function createArtifactZip(files: Readonly<Record<string, string>>): Uint8Array;
 /** Unzip an artifact, rejecting unsafe paths. */