@moewolf/moe-icons-cli 0.0.1

package/dist/core/pro-install.js

@@ -0,0 +1,72 @@
+import { detectProject } from "../project/detect.js";
+import { readMoeiconsConfig } from "../project/config.js";
+import { createInstallPlan, executeInstallPlan } from "../project/install.js";
+import { serializeInstallMetadata, sha256Bytes } from "../project/install-metadata.js";
+import { withProjectLock } from "../project/project-lock.js";
+import { downloadProArtifact } from "./pro-download.js";
+import { artifactCachePath } from "./free-download.js";
+import { selectTargetSubtree } from "./target-subtree.js";
+import { CliError } from "../errors/index.js";
+import { homedir } from "node:os";
+import { join } from "node:path";
+function resolveCacheDir(env) {
+    return env.MOEICONS_CACHE_DIR ?? join(homedir(), ".moeicons", "cache");
+}
+/** Persist the full verified archive so vanilla/bitmap generate can read assets/. */
+function cacheVerifiedArtifact(fs_, cacheDir, version, sha256, bytes) {
+    const cached = artifactCachePath(cacheDir, version, sha256);
+    if (fs_.existsSync(cached))
+        return;
+    fs_.mkdirSync(join(cached, ".."), { recursive: true });
+    fs_.writeFileSync(cached, bytes);
+}
+export async function runProInstallUseCase(context, deps, expected) {
+    const project = detectProject(context.cwd);
+    if (!project)
+        throw new CliError("VALIDATION_ERROR", "no package.json found in the current directory or parents");
+    const config = readMoeiconsConfig(project.root);
+    if (config.kind !== "ok" || config.config.tier !== "pro")
+        throw new CliError("VALIDATION_ERROR", "pro install requires a valid tier=pro config");
+    const target = expected.target ?? config.config.target;
+    const downloaded = await downloadProArtifact(context, deps.auth, expected, {
+        ...(deps.fetch ? { fetch: deps.fetch } : {}),
+        ...(deps.allowedHosts ? { allowedHosts: deps.allowedHosts } : {}),
+        ...(deps.onProgress ? { onProgress: deps.onProgress } : {}),
+    });
+    const subtree = selectTargetSubtree(downloaded.artifactBytes, downloaded.descriptor, target);
+    if (!subtree.ok) {
+        throw new CliError("VALIDATION_ERROR", subtree.message);
+    }
+    cacheVerifiedArtifact(deps.fs, resolveCacheDir(context.env), downloaded.descriptor.version, downloaded.descriptor.sha256, downloaded.artifactBytes);
+    const files = {
+        ".moeicons/catalog.json": downloaded.catalogJson,
+        "src/moeicons/types.ts": `export type { ReactIconProps } from "moe-icons";\n`,
+        "src/moeicons/.moeicons-pro.marker": "pro\n",
+    };
+    for (const [rel, bytes] of Object.entries(subtree.files)) {
+        files[`.moeicons/artifact/${target}/${rel}`] = bytes;
+    }
+    const managedFiles = Object.fromEntries(Object.entries(files).map(([path, content]) => [path, sha256Bytes(content)]));
+    files[".moeicons/install-metadata.json"] = serializeInstallMetadata({
+        schemaVersion: 1,
+        artifactVersion: downloaded.descriptor.version,
+        tier: "pro",
+        target,
+        descriptorSha256: downloaded.descriptor.descriptorSha256,
+        artifactSha256: downloaded.descriptor.sha256,
+        catalogSha256: downloaded.descriptor.catalogSha256,
+        installedAt: context.now().toISOString(),
+        managedFiles,
+        targetSha256: subtree.sha256,
+        targetFileCount: subtree.fileCount,
+        targetByteCount: subtree.byteCount,
+    });
+    await withProjectLock(project.root, "install", () => executeInstallPlan(createInstallPlan(project.root, files), deps.fs));
+    return {
+        projectRoot: project.root,
+        artifactVersion: downloaded.descriptor.version,
+        descriptorSha256: downloaded.descriptor.descriptorSha256,
+        catalogSha256: downloaded.descriptor.catalogSha256,
+        artifactBytes: downloaded.artifactBytes.byteLength,
+    };
+}

package/dist/core/release-descriptor.d.ts

@@ -0,0 +1,40 @@
+export type ReleaseTarget = "react" | "vue" | "vanilla" | "assets";
+export declare const RELEASE_TARGETS: readonly ReleaseTarget[];
+/** Per-target subtree metadata written by the code-library release packer. */
+export interface ReleaseTargetMetadata {
+    readonly path: string;
+    readonly sha256: string;
+    readonly fileCount: number;
+    readonly byteCount: number;
+}
+export interface ReleaseTierArtifact {
+    readonly filename: string;
+    readonly sha256: string;
+    readonly styleGroups?: readonly string[];
+    readonly styleGroupCount?: number;
+    readonly targets?: readonly ReleaseTarget[];
+    readonly targetMetadata?: Readonly<Partial<Record<ReleaseTarget, ReleaseTargetMetadata>>>;
+}
+export interface ReleaseCatalogRef {
+    readonly filename: string;
+    readonly sha256: string;
+    readonly schemaVersion: number;
+    readonly iconCount?: number;
+    readonly styleGroupCount?: number;
+}
+export interface ReleaseDescriptor {
+    readonly fullVersion: string;
+    readonly free: ReleaseTierArtifact;
+    readonly catalog: ReleaseCatalogRef;
+}
+/** Parse release-descriptor.json. Never invent free.filename. */
+export declare function parseReleaseDescriptor(bytes: Uint8Array): ReleaseDescriptor;
+/** Parse `hex  filename` sidecar produced next to the descriptor. */
+export declare function parseSha256Sidecar(text: string): string;
+export declare const PUBLIC_FREE_REPO: {
+    readonly owner: "moewolf-dev";
+    readonly name: "moe-icons";
+};
+export declare const FREE_DOWNLOAD_HOSTS: readonly ["github.com", "objects.githubusercontent.com"];
+export declare function githubReleaseAssetUrl(tag: string, filename: string): string;
+export declare function cacheKey(fullVersion: string, sha256: string): string;

package/dist/core/release-descriptor.js

@@ -0,0 +1,114 @@
+const SHA256_HEX = /^[0-9a-f]{64}$/i;
+const SAFE_FILENAME = /^[A-Za-z0-9._-]+$/;
+const SAFE_SUBTREE_PATH = /^[A-Za-z0-9._/-]+$/;
+export const RELEASE_TARGETS = ["react", "vue", "vanilla", "assets"];
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function requireSha(value, field) {
+    if (typeof value !== "string" || !SHA256_HEX.test(value)) {
+        throw new Error(`${field} must be a 64-character SHA-256 hex digest`);
+    }
+    return value.toLowerCase();
+}
+function requireFilename(value, field) {
+    if (typeof value !== "string" || !SAFE_FILENAME.test(value)) {
+        throw new Error(`${field} must be a basename without path separators`);
+    }
+    return value;
+}
+function requireTarget(value, field) {
+    if (value !== "react" && value !== "vue" && value !== "vanilla" && value !== "assets") {
+        throw new Error(`${field} must be one of react, vue, vanilla, assets`);
+    }
+    return value;
+}
+function parseTargetMetadata(value, field) {
+    if (!isRecord(value))
+        throw new Error(`${field} must be an object`);
+    const result = {};
+    for (const [key, entry] of Object.entries(value)) {
+        const target = requireTarget(key, `${field}.${key}`);
+        if (!isRecord(entry))
+            throw new Error(`${field}.${key} must be an object`);
+        if (typeof entry.path !== "string" || !SAFE_SUBTREE_PATH.test(entry.path)) {
+            throw new Error(`${field}.${key}.path must be a safe subtree path`);
+        }
+        if (typeof entry.fileCount !== "number" || !Number.isSafeInteger(entry.fileCount) || entry.fileCount < 0) {
+            throw new Error(`${field}.${key}.fileCount must be a non-negative integer`);
+        }
+        if (typeof entry.byteCount !== "number" || !Number.isSafeInteger(entry.byteCount) || entry.byteCount < 0) {
+            throw new Error(`${field}.${key}.byteCount must be a non-negative integer`);
+        }
+        result[target] = {
+            path: entry.path,
+            sha256: requireSha(entry.sha256, `${field}.${key}.sha256`),
+            fileCount: entry.fileCount,
+            byteCount: entry.byteCount,
+        };
+    }
+    return result;
+}
+function parseTier(value, field) {
+    if (!isRecord(value))
+        throw new Error(`${field} must be an object`);
+    return {
+        filename: requireFilename(value.filename, `${field}.filename`),
+        sha256: requireSha(value.sha256, `${field}.sha256`),
+        ...(Array.isArray(value.styleGroups) && value.styleGroups.every((item) => typeof item === "string")
+            ? { styleGroups: value.styleGroups }
+            : {}),
+        ...(typeof value.styleGroupCount === "number" ? { styleGroupCount: value.styleGroupCount } : {}),
+        ...(Array.isArray(value.targets)
+            ? { targets: value.targets.map((item) => requireTarget(item, `${field}.targets[]`)) }
+            : {}),
+        ...(value.targetMetadata !== undefined
+            ? { targetMetadata: parseTargetMetadata(value.targetMetadata, `${field}.targetMetadata`) }
+            : {}),
+    };
+}
+/** Parse release-descriptor.json. Never invent free.filename. */
+export function parseReleaseDescriptor(bytes) {
+    let parsed;
+    try {
+        parsed = JSON.parse(Buffer.from(bytes).toString("utf8"));
+    }
+    catch {
+        throw new Error("release-descriptor.json is not valid JSON");
+    }
+    if (!isRecord(parsed))
+        throw new Error("release-descriptor.json must be an object");
+    if (typeof parsed.fullVersion !== "string" || parsed.fullVersion.length === 0) {
+        throw new Error("release-descriptor.json missing fullVersion");
+    }
+    if (!isRecord(parsed.catalog))
+        throw new Error("release-descriptor.json missing catalog");
+    return {
+        fullVersion: parsed.fullVersion,
+        free: parseTier(parsed.free, "free"),
+        catalog: {
+            filename: requireFilename(parsed.catalog.filename, "catalog.filename"),
+            sha256: requireSha(parsed.catalog.sha256, "catalog.sha256"),
+            schemaVersion: typeof parsed.catalog.schemaVersion === "number" ? parsed.catalog.schemaVersion : 1,
+            ...(typeof parsed.catalog.iconCount === "number" ? { iconCount: parsed.catalog.iconCount } : {}),
+            ...(typeof parsed.catalog.styleGroupCount === "number" ? { styleGroupCount: parsed.catalog.styleGroupCount } : {}),
+        },
+    };
+}
+/** Parse `hex  filename` sidecar produced next to the descriptor. */
+export function parseSha256Sidecar(text) {
+    const token = text.trim().split(/\s+/)[0] ?? "";
+    if (!SHA256_HEX.test(token))
+        throw new Error("descriptor sha256 sidecar is not a 64-character hex digest");
+    return token.toLowerCase();
+}
+export const PUBLIC_FREE_REPO = { owner: "moewolf-dev", name: "moe-icons" };
+export const FREE_DOWNLOAD_HOSTS = ["github.com", "objects.githubusercontent.com"];
+export function githubReleaseAssetUrl(tag, filename) {
+    if (!tag.startsWith("v"))
+        throw new Error("release tag must be v<fullVersion>");
+    return `https://github.com/${PUBLIC_FREE_REPO.owner}/${PUBLIC_FREE_REPO.name}/releases/download/${encodeURIComponent(tag)}/${encodeURIComponent(filename)}`;
+}
+export function cacheKey(fullVersion, sha256) {
+    return `${PUBLIC_FREE_REPO.owner}/${PUBLIC_FREE_REPO.name}/${fullVersion}/${sha256.toLowerCase()}`;
+}

package/dist/core/resource-variant.d.ts

@@ -0,0 +1,35 @@
+/**
+ * G0/G1/G2: styleGroupId vs resourceVariantId.
+ * Variant ids are deterministic: `<styleGroupId>-<webp|png>-<64|128|256|512>`.
+ * Parse from the right: size, then format, remainder is styleGroupId.
+ */
+export declare const BITMAP_STYLE_GROUP_RE: RegExp;
+export declare const BITMAP_FORMATS: readonly ["webp", "png"];
+export declare const BITMAP_SIZES: readonly [64, 128, 256, 512];
+export type BitmapFormat = (typeof BITMAP_FORMATS)[number];
+export type BitmapSize = (typeof BITMAP_SIZES)[number];
+export interface ResourceVariant {
+    readonly styleGroupId: string;
+    readonly format: BitmapFormat;
+    readonly imageSize: BitmapSize;
+    readonly resourceVariantId: string;
+}
+export declare const DEFAULT_BITMAP_FORMAT: BitmapFormat;
+export declare const DEFAULT_BITMAP_SIZE: BitmapSize;
+export declare function isBitmapStyleGroupId(id: string): boolean;
+export declare function isBitmapFormat(value: string): value is BitmapFormat;
+export declare function isBitmapSize(value: number): value is BitmapSize;
+/** Build a resourceVariantId; never invent aliases. */
+export declare function buildResourceVariantId(styleGroupId: string, format?: BitmapFormat, imageSize?: BitmapSize): string;
+/**
+ * Parse `<styleGroupId>-<format>-<size>` from the right.
+ * Rejects guessing by scanning for an arbitrary `-3d` substring.
+ */
+export declare function parseResourceVariantId(resourceVariantId: string): ResourceVariant;
+/** Resolve format/size for a bitmap theme, applying catalog defaults when omitted. */
+export declare function resolveResourceVariant(styleGroupId: string, options?: {
+    readonly format?: string;
+    readonly imageSize?: number;
+}): ResourceVariant;
+/** Relative managed asset path under outputDir (POSIX). */
+export declare function assetRelativePath(resourceVariantId: string, iconId: string, format: BitmapFormat): string;

package/dist/core/resource-variant.js

@@ -0,0 +1,70 @@
+/**
+ * G0/G1/G2: styleGroupId vs resourceVariantId.
+ * Variant ids are deterministic: `<styleGroupId>-<webp|png>-<64|128|256|512>`.
+ * Parse from the right: size, then format, remainder is styleGroupId.
+ */
+export const BITMAP_STYLE_GROUP_RE = /^moe-[a-z0-9]+(?:-[a-z0-9]+)*-3d$/;
+export const BITMAP_FORMATS = ["webp", "png"];
+export const BITMAP_SIZES = [64, 128, 256, 512];
+export const DEFAULT_BITMAP_FORMAT = "webp";
+export const DEFAULT_BITMAP_SIZE = 256;
+export function isBitmapStyleGroupId(id) {
+    return BITMAP_STYLE_GROUP_RE.test(id);
+}
+export function isBitmapFormat(value) {
+    return BITMAP_FORMATS.includes(value);
+}
+export function isBitmapSize(value) {
+    return BITMAP_SIZES.includes(value);
+}
+/** Build a resourceVariantId; never invent aliases. */
+export function buildResourceVariantId(styleGroupId, format = DEFAULT_BITMAP_FORMAT, imageSize = DEFAULT_BITMAP_SIZE) {
+    if (!isBitmapStyleGroupId(styleGroupId)) {
+        throw new Error(`styleGroupId "${styleGroupId}" is not a bitmap style group`);
+    }
+    return `${styleGroupId}-${format}-${imageSize}`;
+}
+/**
+ * Parse `<styleGroupId>-<format>-<size>` from the right.
+ * Rejects guessing by scanning for an arbitrary `-3d` substring.
+ */
+export function parseResourceVariantId(resourceVariantId) {
+    const parts = resourceVariantId.split("-");
+    if (parts.length < 4) {
+        throw new Error(`invalid resourceVariantId "${resourceVariantId}"`);
+    }
+    const sizeToken = parts[parts.length - 1] ?? "";
+    const formatToken = parts[parts.length - 2] ?? "";
+    const imageSize = Number(sizeToken);
+    if (!isBitmapSize(imageSize)) {
+        throw new Error(`invalid imageSize in resourceVariantId "${resourceVariantId}"`);
+    }
+    if (!isBitmapFormat(formatToken)) {
+        throw new Error(`invalid format in resourceVariantId "${resourceVariantId}"`);
+    }
+    const styleGroupId = parts.slice(0, -2).join("-");
+    if (!isBitmapStyleGroupId(styleGroupId)) {
+        throw new Error(`invalid styleGroupId derived from "${resourceVariantId}"`);
+    }
+    return {
+        styleGroupId,
+        format: formatToken,
+        imageSize,
+        resourceVariantId: buildResourceVariantId(styleGroupId, formatToken, imageSize),
+    };
+}
+/** Resolve format/size for a bitmap theme, applying catalog defaults when omitted. */
+export function resolveResourceVariant(styleGroupId, options = {}) {
+    const format = options.format === undefined ? DEFAULT_BITMAP_FORMAT : options.format;
+    const imageSize = options.imageSize === undefined ? DEFAULT_BITMAP_SIZE : options.imageSize;
+    if (!isBitmapFormat(format))
+        throw new Error(`unsupported bitmap format "${format}"`);
+    if (!isBitmapSize(imageSize))
+        throw new Error(`unsupported bitmap imageSize ${String(imageSize)}`);
+    const resourceVariantId = buildResourceVariantId(styleGroupId, format, imageSize);
+    return { styleGroupId, format, imageSize, resourceVariantId };
+}
+/** Relative managed asset path under outputDir (POSIX). */
+export function assetRelativePath(resourceVariantId, iconId, format) {
+    return `assets/${resourceVariantId}/${iconId}.${format}`;
+}

package/dist/core/signed-artifact.d.ts

@@ -0,0 +1,29 @@
+export interface SignedArtifactDescriptor {
+    readonly url: string;
+    readonly expiresAt: string;
+    readonly size: number;
+    readonly sha256: string;
+}
+/**
+ * Exchange an access token for a descriptor. The caller supplies only the
+ * frozen API path; credentials can never be sent to another origin.
+ */
+export declare function fetchSignedArtifactDescriptor(apiPath: string, accessToken: string, deps?: {
+    readonly fetch?: typeof fetch;
+    readonly signal?: AbortSignal;
+    readonly timeoutMs?: number;
+    readonly now?: number;
+}): Promise<SignedArtifactDescriptor>;
+/** Download signed bytes without forwarding API credentials or cookies. */
+export declare function downloadSignedArtifact(descriptor: SignedArtifactDescriptor, options: {
+    readonly allowedHosts: readonly string[];
+    readonly fetch?: typeof fetch;
+    readonly signal?: AbortSignal;
+    readonly timeoutMs?: number;
+    readonly maxRedirects?: number;
+    readonly now?: number;
+    readonly onProgress?: (event: {
+        readonly downloadedBytes: number;
+        readonly totalBytes?: number;
+    }) => void;
+}): Promise<Uint8Array>;

package/dist/core/signed-artifact.js

@@ -0,0 +1,81 @@
+import { CliError } from "../errors/index.js";
+import { downloadArtifact, verifyArtifact } from "../project/install.js";
+const API_ORIGIN = "https://api.moeicons.com";
+const SHA256 = /^[a-f0-9]{64}$/;
+function parseDescriptor(value, now) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        throw new CliError("VALIDATION_ERROR", "invalid signed artifact descriptor");
+    const item = value;
+    if (Object.keys(item).some((key) => !["url", "expiresAt", "size", "sha256"].includes(key)) ||
+        typeof item.url !== "string" || typeof item.expiresAt !== "string" ||
+        typeof item.size !== "number" || !Number.isSafeInteger(item.size) || item.size < 1 ||
+        typeof item.sha256 !== "string" || !SHA256.test(item.sha256)) {
+        throw new CliError("VALIDATION_ERROR", "invalid signed artifact descriptor");
+    }
+    let url;
+    try {
+        url = new URL(item.url);
+    }
+    catch {
+        throw new CliError("VALIDATION_ERROR", "invalid signed artifact URL");
+    }
+    const expires = Date.parse(item.expiresAt);
+    if (url.protocol !== "https:" || !Number.isFinite(expires) || expires <= now)
+        throw new CliError("VALIDATION_ERROR", "signed artifact descriptor is expired or insecure");
+    return item;
+}
+/**
+ * Exchange an access token for a descriptor. The caller supplies only the
+ * frozen API path; credentials can never be sent to another origin.
+ */
+export async function fetchSignedArtifactDescriptor(apiPath, accessToken, deps = {}) {
+    const url = new URL(apiPath, API_ORIGIN);
+    if (url.origin !== API_ORIGIN || !apiPath.startsWith("/"))
+        throw new CliError("VALIDATION_ERROR", "pro descriptor path must use the trusted API origin");
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), deps.timeoutMs ?? 5_000);
+    const abort = () => controller.abort();
+    if (deps.signal?.aborted)
+        controller.abort();
+    deps.signal?.addEventListener("abort", abort, { once: true });
+    try {
+        const response = await (deps.fetch ?? fetch)(url, {
+            method: "GET", redirect: "error", signal: controller.signal,
+            headers: { accept: "application/json", authorization: `Bearer ${accessToken}` },
+        });
+        if (!response.ok)
+            throw new CliError(response.status === 401 ? "AUTH_ERROR" : response.status === 403 ? "FORBIDDEN" : "NETWORK_ERROR", `pro descriptor request failed with ${response.status}`);
+        return parseDescriptor(await response.json(), deps.now ?? Date.now());
+    }
+    catch (error) {
+        if (error instanceof CliError)
+            throw error;
+        throw new CliError(deps.signal?.aborted ? "CANCELLED" : "NETWORK_ERROR", deps.signal?.aborted ? "pro descriptor request cancelled" : "pro descriptor request failed");
+    }
+    finally {
+        clearTimeout(timer);
+        deps.signal?.removeEventListener("abort", abort);
+    }
+}
+/** Download signed bytes without forwarding API credentials or cookies. */
+export async function downloadSignedArtifact(descriptor, options) {
+    const checked = parseDescriptor(descriptor, options.now ?? Date.now());
+    const result = await downloadArtifact(checked.url, {
+        maxBytes: checked.size,
+        timeoutMs: options.timeoutMs ?? 30_000,
+        maxRedirects: options.maxRedirects ?? 5,
+        allowedHosts: options.allowedHosts,
+        ...(options.onProgress ? { onProgress: options.onProgress } : {}),
+    }, {
+        ...(options.fetch ? { fetchFn: options.fetch } : {}),
+        ...(options.signal ? { signal: options.signal } : {}),
+    });
+    if (!result.ok)
+        throw new CliError(result.code === "NETWORK_ERROR" ? "NETWORK_ERROR" : "VALIDATION_ERROR", result.message);
+    if (result.bytes.byteLength !== checked.size)
+        throw new CliError("VALIDATION_ERROR", `artifact size mismatch: expected ${checked.size}, got ${result.bytes.byteLength}`);
+    const verified = verifyArtifact(result.bytes, checked.sha256);
+    if (!verified.ok)
+        throw new CliError("VALIDATION_ERROR", `artifact SHA-256 mismatch: expected ${checked.sha256}, got ${verified.actual}`);
+    return result.bytes;
+}

package/dist/core/target-subtree.d.ts

@@ -0,0 +1,49 @@
+import type { ReleaseTarget, ReleaseTargetMetadata } from "./release-descriptor.js";
+import type { Target } from "../commands/parser.js";
+/**
+ * Select the target subtree the CLI must install. Mirrors the archive layout
+ * frozen in the code-library contract: each tier archive contains
+ * `react/`, `vue/`, `vanilla/` and `assets/` subtrees and the CLI installs only
+ * the selected one. When the source carries per-target subtree metadata
+ * (`targetMetadata[target] = { path, sha256, fileCount, byteCount }`) the
+ * subtree hash/size is verified against the downloaded archive bytes.
+ */
+export interface TargetSubtreeSource {
+    readonly targets?: readonly ReleaseTarget[];
+    readonly targetMetadata?: Readonly<Partial<Record<ReleaseTarget, ReleaseTargetMetadata>>>;
+}
+export interface TargetSubtreeSelection {
+    readonly ok: true;
+    readonly target: Target;
+    /** Subtree-relative file map (e.g. `moe-outline/foo.svg` for the assets subtree). */
+    readonly files: Readonly<Record<string, Uint8Array>>;
+    readonly sha256: string;
+    readonly fileCount: number;
+    readonly byteCount: number;
+}
+export type TargetSubtreeFailure = {
+    readonly ok: false;
+    readonly reason: "validation" | "checksum-mismatch";
+    readonly message: string;
+};
+export type TargetSubtreeResult = TargetSubtreeSelection | TargetSubtreeFailure;
+/**
+ * Deterministic subtree hash over subtree-relative files. Files and directories
+ * are visited depth-first sorted by `localeCompare`, and each file contributes
+ * `<relative>\0<bytes>\0` — the same algorithm used by the code-library release
+ * packer (`subtreeHash` in scripts/pack-release-artifacts.cjs).
+ */
+export declare function computeSubtreeHash(files: Readonly<Record<string, Uint8Array>>): {
+    readonly sha256: string;
+    readonly fileCount: number;
+    readonly byteCount: number;
+};
+/**
+ * Extract and verify the selected target's subtree from an archive.
+ *
+ * Modern descriptors (those that declare `targets` and/or `targetMetadata`)
+ * must include the selected target, provide matching metadata, and yield a
+ * non-empty subtree. Legacy `{ filename, sha256 }` descriptors skip hash
+ * verification for backward compatibility but still reject an empty subtree.
+ */
+export declare function selectTargetSubtree(archiveBytes: Uint8Array, source: TargetSubtreeSource, target: Target): TargetSubtreeResult;

package/dist/core/target-subtree.js

@@ -0,0 +1,132 @@
+import { createHash } from "node:crypto";
+import { extractTarGz } from "../project/tar-gz.js";
+/**
+ * Deterministic subtree hash over subtree-relative files. Files and directories
+ * are visited depth-first sorted by `localeCompare`, and each file contributes
+ * `<relative>\0<bytes>\0` — the same algorithm used by the code-library release
+ * packer (`subtreeHash` in scripts/pack-release-artifacts.cjs).
+ */
+export function computeSubtreeHash(files) {
+    const hash = createHash("sha256");
+    let fileCount = 0;
+    let byteCount = 0;
+    const namesAt = (prefix) => {
+        const names = new Set();
+        for (const rel of Object.keys(files)) {
+            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 walk = (prefix) => {
+        for (const name of namesAt(prefix)) {
+            const rel = prefix ? `${prefix}/${name}` : name;
+            const bytes = files[rel];
+            if (bytes) {
+                hash.update(rel).update("\0").update(bytes).update("\0");
+                fileCount += 1;
+                byteCount += bytes.byteLength;
+            }
+            else {
+                walk(rel);
+            }
+        }
+    };
+    walk("");
+    return { sha256: hash.digest("hex"), fileCount, byteCount };
+}
+function subtreeFilesOf(extracted, target) {
+    const prefix = `${target}/`;
+    const files = {};
+    for (const [path, bytes] of Object.entries(extracted)) {
+        if (path === target || path.startsWith(prefix)) {
+            files[path.slice(prefix.length)] = bytes;
+        }
+    }
+    return files;
+}
+function hasModernTargetContract(source) {
+    if (source.targets !== undefined && source.targets.length > 0)
+        return true;
+    if (source.targetMetadata !== undefined && Object.keys(source.targetMetadata).length > 0)
+        return true;
+    return false;
+}
+/**
+ * Extract and verify the selected target's subtree from an archive.
+ *
+ * Modern descriptors (those that declare `targets` and/or `targetMetadata`)
+ * must include the selected target, provide matching metadata, and yield a
+ * non-empty subtree. Legacy `{ filename, sha256 }` descriptors skip hash
+ * verification for backward compatibility but still reject an empty subtree.
+ */
+export function selectTargetSubtree(archiveBytes, source, target) {
+    const extracted = extractTarGz(archiveBytes, {
+        maxEntries: 20_000,
+        maxExpandedBytes: 64 * 1024 * 1024,
+    });
+    if (extracted.errors.length > 0) {
+        return { ok: false, reason: "validation", message: extracted.errors[0] ?? "invalid archive" };
+    }
+    const files = subtreeFilesOf(extracted.files, target);
+    const computed = computeSubtreeHash(files);
+    const modern = hasModernTargetContract(source);
+    if (modern) {
+        if (source.targets !== undefined && !source.targets.includes(target)) {
+            return {
+                ok: false,
+                reason: "validation",
+                message: `descriptor does not declare target "${target}"`,
+            };
+        }
+        const expected = source.targetMetadata?.[target];
+        if (!expected) {
+            return {
+                ok: false,
+                reason: "validation",
+                message: `descriptor is missing targetMetadata for "${target}"`,
+            };
+        }
+        const normalizedPath = expected.path.replace(/\/$/, "");
+        if (normalizedPath !== target) {
+            return {
+                ok: false,
+                reason: "validation",
+                message: `targetMetadata["${target}"].path must be "${target}" (got "${expected.path}")`,
+            };
+        }
+    }
+    if (computed.fileCount === 0) {
+        return {
+            ok: false,
+            reason: "validation",
+            message: `target subtree "${target}" is empty or missing from the archive`,
+        };
+    }
+    if (modern) {
+        const expected = source.targetMetadata?.[target];
+        if (expected &&
+            (computed.sha256 !== expected.sha256 ||
+                computed.fileCount !== expected.fileCount ||
+                computed.byteCount !== expected.byteCount)) {
+            return {
+                ok: false,
+                reason: "checksum-mismatch",
+                message: `target subtree "${target}" mismatch: ` +
+                    `expected sha256=${expected.sha256} files=${expected.fileCount} bytes=${expected.byteCount}, ` +
+                    `got sha256=${computed.sha256} files=${computed.fileCount} bytes=${computed.byteCount}`,
+            };
+        }
+    }
+    return {
+        ok: true,
+        target,
+        files,
+        sha256: computed.sha256,
+        fileCount: computed.fileCount,
+        byteCount: computed.byteCount,
+    };
+}

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

@@ -0,0 +1,31 @@
+export type Tier = "free" | "pro";
+interface ParsedVersion {
+    major: number;
+    minor: number;
+    patch: number;
+    channel: "stable" | "alpha" | "beta";
+}
+export declare function parseVersion(value: string): ParsedVersion | undefined;
+export type UpdateDecision = {
+    readonly kind: "update";
+} | {
+    readonly kind: "current";
+} | {
+    readonly kind: "refuse";
+    readonly reason: "tier-mismatch" | "channel-mismatch" | "downgrade" | "invalid-version";
+};
+export declare function decideUpdate(input: {
+    installedTier: Tier;
+    remoteTier: Tier;
+    installedVersion: string;
+    remoteVersion: string;
+}): UpdateDecision;
+export interface UpdateCandidateIdentity {
+    readonly tier: Tier;
+    readonly version: string;
+    readonly descriptorSha256: string;
+    readonly artifactSha256: string;
+}
+/** Recheck the downloaded candidate immediately before commit to prevent TOCTOU. */
+export declare function verifyCandidateIdentity(expected: UpdateCandidateIdentity, actual: UpdateCandidateIdentity): boolean;
+export {};