@moewolf/moe-icons-cli 0.0.11 → 0.0.14

package/dist/core/small-pack/tar-read.cjs

@@ -0,0 +1,220 @@
+'use strict';
+
+/**
+ * PATCH-24-C: strict structured tar reader.
+ *
+ * Validates header checksum, strict octal/base-256 size, payload truncation and
+ * padding, the end-of-archive marker with no non-zero trailing bytes, PAX record
+ * lengths/scopes and GNU long names. Returns entries with the raw path plus the
+ * file bytes so callers never have to hand the same archive to a second parser
+ * (e.g. system tar) that might interpret it differently.
+ */
+
+const BLOCK = 512;
+const DEFAULT_MAX_ENTRIES = 200000;
+// CI FLOW RULE: parse one bounded resource package per invocation, not a
+// concatenated tier archive.
+const DEFAULT_MAX_EXPANDED_BYTES = 128 * 1024 * 1024;
+const MAX_METADATA_BYTES = 1024 * 1024;
+
+function readString(buffer, offset, length) {
+  const slice = buffer.subarray(offset, offset + length);
+  const end = slice.indexOf(0);
+  return (end >= 0 ? slice.subarray(0, end) : slice).toString('utf8');
+}
+
+function roundUp(size) {
+  return Math.ceil(size / BLOCK) * BLOCK;
+}
+
+function isZeroBlock(buffer, offset) {
+  for (let index = offset; index < offset + BLOCK; index += 1) {
+    if (buffer[index] !== 0) return false;
+  }
+  return true;
+}
+
+function parseOctal(field, label) {
+  const text = field.toString('latin1').replace(/\0.*$/, '').trim();
+  if (text === '') return 0;
+  if (!/^[0-7]+$/.test(text)) throw new Error(`tar ${label} is not valid octal: ${JSON.stringify(text)}`);
+  const value = Number.parseInt(text, 8);
+  if (!Number.isSafeInteger(value) || value < 0) throw new Error(`tar ${label} is out of range`);
+  return value;
+}
+
+/** GNU base-256 encoding when the high bit of the first byte is set. */
+function parseSize(field) {
+  if (field[0] & 0x80) {
+    let value = 0n;
+    for (const byte of field) value = (value << 8n) | BigInt(byte & 0x7f);
+    if (value > BigInt(Number.MAX_SAFE_INTEGER)) throw new Error('tar size overflows safe integer');
+    return Number(value);
+  }
+  return parseOctal(field, 'size');
+}
+
+function parseChecksum(field) {
+  const text = field.toString('latin1').replace(/\0.*$/, '').trim();
+  if (!/^[0-7]+$/.test(text)) throw new Error(`tar checksum is not valid octal: ${JSON.stringify(text)}`);
+  return Number.parseInt(text, 8);
+}
+
+function computeChecksums(header) {
+  let unsigned = 0;
+  let signed = 0;
+  for (let index = 0; index < BLOCK; index += 1) {
+    const byte = index >= 148 && index < 156 ? 0x20 : header[index];
+    unsigned += byte;
+    signed += byte < 0x80 ? byte : byte - 0x100;
+  }
+  return { unsigned, signed };
+}
+
+function verifyChecksum(header, offset) {
+  const stored = parseChecksum(header.subarray(148, 156));
+  const { unsigned, signed } = computeChecksums(header);
+  if (stored !== unsigned && stored !== signed) {
+    throw new Error(`tar checksum mismatch at block ${offset / BLOCK}: stored ${stored}, computed ${unsigned}`);
+  }
+}
+
+function parsePax(data) {
+  const record = {};
+  let cursor = 0;
+  while (cursor < data.length) {
+    const space = data.indexOf(0x20, cursor);
+    if (space < 0) throw new Error('malformed pax record: missing length separator');
+    const lengthText = data.subarray(cursor, space).toString('latin1');
+    if (!/^\d+$/.test(lengthText)) throw new Error('malformed pax record: non-numeric length');
+    const length = Number.parseInt(lengthText, 10);
+    if (length <= 0 || cursor + length > data.length) throw new Error('malformed pax record: length overruns payload');
+    const raw = data.subarray(space + 1, cursor + length);
+    if (raw.length === 0 || raw[raw.length - 1] !== 0x0a) throw new Error('malformed pax record: missing newline');
+    // Lengths are UTF-8 byte counts; decode only the value bytes.
+    const body = raw.subarray(0, raw.length - 1).toString('utf8');
+    const equals = body.indexOf('=');
+    if (equals < 0) throw new Error('malformed pax record: missing "="');
+    record[body.slice(0, equals)] = body.slice(equals + 1);
+    cursor += length;
+  }
+  if (cursor !== data.length) throw new Error('malformed pax record: trailing bytes');
+  return record;
+}
+
+/**
+ * @param {Buffer} buffer full tar archive bytes
+ * @param {{maxEntries?:number,maxExpandedBytes?:number}} [options]
+ */
+function readTarEntries(buffer, options = {}) {
+  const maxEntries = options.maxEntries || DEFAULT_MAX_ENTRIES;
+  const maxExpandedBytes = options.maxExpandedBytes || DEFAULT_MAX_EXPANDED_BYTES;
+  const entries = [];
+  let offset = 0;
+  let pendingLongName = null;
+  let pendingPax = null;
+  let globalPax = {};
+  let expandedBytes = 0;
+  let metadataCount = 0;
+  let terminated = false;
+
+  while (offset < buffer.length) {
+    if (offset + BLOCK > buffer.length) throw new Error(`tar truncated header at offset ${offset}`);
+    if (isZeroBlock(buffer, offset)) {
+      // POSIX requires two consecutive 512-byte zero blocks; anything after the
+      // two blocks must be zero record padding.
+      const second = offset + BLOCK;
+      if (second + BLOCK > buffer.length || !isZeroBlock(buffer, second)) {
+        throw new Error('tar is missing the two-block end-of-archive marker');
+      }
+      for (let index = second; index < buffer.length; index += 1) {
+        if (buffer[index] !== 0) throw new Error('tar has trailing data after the end-of-archive marker');
+      }
+      terminated = true;
+      break;
+    }
+    const header = buffer.subarray(offset, offset + BLOCK);
+    verifyChecksum(header, offset);
+
+    const name = readString(header, 0, 100);
+    const type = String.fromCharCode(header[156]);
+    const linkname = readString(header, 157, 100);
+    const prefix = readString(header, 345, 155);
+    const size = parseSize(header.subarray(124, 136));
+    const dataStart = offset + BLOCK;
+    const paddedSize = roundUp(size);
+    if (dataStart + paddedSize > buffer.length) {
+      throw new Error(`tar payload truncated for ${name || '<unnamed>'} (size ${size})`);
+    }
+    if (size < 0) throw new Error('tar negative size');
+    expandedBytes += size;
+    if (expandedBytes > maxExpandedBytes) throw new Error('tar expanded size exceeds limit');
+    const data = buffer.subarray(dataStart, dataStart + size);
+    // Padding bytes must be zero.
+    for (let index = dataStart + size; index < dataStart + paddedSize; index += 1) {
+      if (buffer[index] !== 0) throw new Error(`tar non-zero padding for ${name || '<unnamed>'}`);
+    }
+
+    let filePath = prefix ? `${prefix}/${name}` : name;
+    if (pendingLongName !== null) filePath = pendingLongName;
+    const pax = pendingPax ? { ...globalPax, ...pendingPax } : globalPax;
+    if (pax.path) filePath = pax.path;
+    const entryLink = pax.linkpath || linkname;
+
+    const isMetadata = type === 'L' || type === 'x' || type === 'g';
+    if (isMetadata) {
+      // Metadata headers count toward the entry budget and are size-capped.
+      metadataCount += 1;
+      if (entries.length + metadataCount > maxEntries) throw new Error('tar entry count exceeds limit');
+      if (size > MAX_METADATA_BYTES) throw new Error('tar metadata entry exceeds size limit');
+    }
+    if (type === 'L') {
+      pendingLongName = data.toString('utf8').replace(/\0+$/, '');
+      pendingPax = null;
+      offset = dataStart + paddedSize;
+      continue;
+    }
+    if (type === 'x' || type === 'g') {
+      const parsed = parsePax(data);
+      if (type === 'x') pendingPax = parsed;
+      else globalPax = parsed;
+      offset = dataStart + paddedSize;
+      continue;
+    }
+    pendingLongName = null;
+    pendingPax = null;
+
+    if (entries.length >= maxEntries) throw new Error('tar entry count exceeds limit');
+
+    let kind;
+    if (type === '5') kind = 'dir';
+    else if (type === '0' || type === '\0' || type === '\u0000') kind = 'file';
+    else if (type === '2') kind = 'symlink';
+    else if (type === '1') kind = 'hardlink';
+    else if (type === '6') kind = 'fifo';
+    else kind = `other:${type}`;
+
+    if (!isMetadata && (!filePath || filePath.length === 0)) throw new Error('tar entry has an empty path');
+
+    entries.push({
+      path: kind === 'dir' ? filePath.replace(/\/$/, '') : filePath,
+      type: kind,
+      linkname: entryLink || null,
+      size,
+      data: kind === 'file' ? data : null,
+    });
+    offset = dataStart + paddedSize;
+  }
+
+  if (!terminated) throw new Error('tar is missing the end-of-archive marker');
+  return entries;
+}
+
+module.exports = {
+  BLOCK,
+  DEFAULT_MAX_ENTRIES,
+  DEFAULT_MAX_EXPANDED_BYTES,
+  readTarEntries,
+  parsePax,
+  parseOctal,
+};

package/dist/core/small-pack/tar-read.d.cts

@@ -0,0 +1,2 @@
+export interface TarEntry { path: string; type: string; linkname: string | null; size: number; data: Buffer | null }
+export function readTarEntries(bytes: Uint8Array, limits: { maxEntries: number; maxExpandedBytes: number }): TarEntry[];

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

@@ -0,0 +1,40 @@
+import { type TransactionalFs } from "../project/install.js";
+import { type MoeiconsConfigFile } from "../project/config.js";
+import type { Target } from "../commands/parser.js";
+export interface SmallPackageInstallResult {
+    readonly artifactVersion: string;
+    readonly candidateRootSha256: string;
+    readonly packageSetSha256: string;
+    readonly catalogSha256: string;
+    readonly metadataSha256: string;
+    readonly artifactBytes: number;
+    readonly files: readonly string[];
+    readonly packageCount: number;
+    readonly planItems: number;
+    readonly selectedFiles: number;
+    readonly networkBytes: number;
+    readonly cacheHit: boolean;
+    readonly cacheHits: number;
+    readonly metadataCacheHits: number;
+    readonly transferRetryCount: number;
+    readonly target: Target;
+    readonly targetSha256: string;
+    readonly targetFileCount: number;
+    readonly targetByteCount: number;
+    readonly fallbacks: readonly string[];
+}
+export declare function runSmallPackageInstall(options: {
+    readonly projectRoot: string;
+    readonly fullVersion?: string;
+    readonly expectedPackageSetSha256?: string;
+    readonly proAccessToken?: string;
+    readonly apiBaseUrl?: string;
+    readonly config: MoeiconsConfigFile;
+    readonly plannedConfigDocument: string;
+    readonly fs: TransactionalFs;
+    readonly cacheDir: string;
+    readonly now: () => Date;
+    readonly signal?: AbortSignal;
+    readonly fetchFn?: typeof fetch;
+    readonly fixtureOrigin?: string;
+}): Promise<SmallPackageInstallResult>;

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 = {