@moewolf/moe-icons-cli 0.0.1 → 0.0.3

package/dist/core/metadata-sync.js

@@ -0,0 +1,97 @@
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { CliError } from "../errors/index.js";
+import { detectProject } from "../project/detect.js";
+import { parseInstallMetadata, serializeInstallMetadata, sha256Bytes, } from "../project/install-metadata.js";
+import { executeManagedReconcile } from "../project/install.js";
+import { withProjectLock } from "../project/project-lock.js";
+import { cacheArtifact } from "./cache.js";
+import { downloadMetadataArchive, fetchFreeDescriptor, metadataCachePath, } from "./free-download.js";
+import { downloadSignedArtifact } from "./signed-artifact.js";
+import { extractProMetadata, fetchProDescriptor, proSignedDownloadOptions } from "./pro-download.js";
+function toCliError(result) {
+    return new CliError(result.reason === "cancelled" ? "CANCELLED" : "VALIDATION_ERROR", result.message);
+}
+/**
+ * Metadata-only sync: downloads only the small metadata archive for the
+ * already-installed code version and reconciles `.moeicons/{MANUAL.md,
+ * catalog.json, manifest.json}`. Never downloads the code archive and never
+ * changes the installed code version.
+ */
+export async function runMetadataSyncUseCase(context, deps, options = {}) {
+    const project = detectProject(context.cwd);
+    if (!project)
+        throw new CliError("VALIDATION_ERROR", "no package.json found in the current directory or parents");
+    const metadataPath = join(project.root, ".moeicons", "install-metadata.json");
+    if (!deps.fs.existsSync(metadataPath))
+        throw new CliError("VALIDATION_ERROR", "managed install metadata is missing; run install first");
+    const old = parseInstallMetadata(deps.fs.readFileSync(metadataPath, "utf8"));
+    if (!old)
+        throw new CliError("VALIDATION_ERROR", "managed install metadata is invalid; run install first");
+    const tier = options.tier ?? old.tier;
+    const version = old.artifactVersion;
+    let catalogJson;
+    let manifestJson;
+    let manualMd;
+    let metadataSha256;
+    if (tier === "free") {
+        const fetched = await fetchFreeDescriptor({ ...deps.free, signal: context.signal, ...(deps.onProgress ? { onProgress: deps.onProgress } : {}) }, version);
+        if (!fetched.ok)
+            throw toCliError(fetched);
+        const metaRef = fetched.descriptor.free.metadata;
+        if (!metaRef)
+            throw new CliError("VALIDATION_ERROR", "release descriptor is missing the metadata archive");
+        const meta = await downloadMetadataArchive({ ...deps.free, signal: context.signal, ...(deps.onProgress ? { onProgress: deps.onProgress } : {}) }, metaRef, fetched.descriptor.catalog.sha256, "free", version, fetched.tag);
+        if (!meta.ok)
+            throw toCliError(meta);
+        catalogJson = meta.value.catalogJson;
+        manifestJson = meta.value.manifestJson;
+        manualMd = meta.value.manualMd;
+        metadataSha256 = meta.value.metadataSha256;
+    }
+    else {
+        const descriptor = await fetchProDescriptor(context, deps.auth, { version, descriptorSha256: old.descriptorSha256 }, { ...(deps.fetch ? { fetch: deps.fetch } : {}) });
+        if (!descriptor.metadata)
+            throw new CliError("VALIDATION_ERROR", "pro descriptor is missing the metadata archive");
+        const metaBytes = await downloadSignedArtifact(descriptor.metadata, proSignedDownloadOptions(context, {
+            ...(deps.fetch ? { fetch: deps.fetch } : {}),
+            ...(deps.allowedProHosts ? { allowedHosts: deps.allowedProHosts } : {}),
+            ...(deps.onProgress ? { onProgress: deps.onProgress } : {}),
+        }));
+        const meta = extractProMetadata(metaBytes, descriptor.catalogSha256, descriptor.version);
+        catalogJson = meta.catalogJson;
+        manifestJson = meta.manifestJson;
+        manualMd = meta.manualMd;
+        metadataSha256 = descriptor.metadata.sha256;
+        const cacheDir = context.env.MOEICONS_CACHE_DIR ?? join(homedir(), ".moeicons", "cache");
+        const cached = metadataCachePath(cacheDir, descriptor.version, descriptor.metadata.sha256);
+        if (!deps.fs.existsSync(cached)) {
+            cacheArtifact(deps.fs, cached, metaBytes, descriptor.metadata.sha256);
+        }
+    }
+    const writes = {
+        ".moeicons/MANUAL.md": manualMd,
+        ".moeicons/catalog.json": catalogJson,
+        ".moeicons/manifest.json": manifestJson,
+    };
+    const managedFiles = {
+        ...old.managedFiles,
+        ".moeicons/MANUAL.md": sha256Bytes(manualMd),
+        ".moeicons/catalog.json": sha256Bytes(catalogJson),
+        ".moeicons/manifest.json": sha256Bytes(manifestJson),
+    };
+    const nextMetadata = {
+        ...old,
+        installedAt: context.now().toISOString(),
+        managedFiles,
+    };
+    writes[".moeicons/install-metadata.json"] = serializeInstallMetadata(nextMetadata);
+    await withProjectLock(project.root, "update", () => executeManagedReconcile(project.root, writes, [], deps.fs));
+    return {
+        projectRoot: project.root,
+        tier,
+        artifactVersion: version,
+        metadataSha256,
+        files: [".moeicons/MANUAL.md", ".moeicons/catalog.json", ".moeicons/manifest.json"],
+    };
+}

package/dist/core/pro-download.d.ts

@@ -1,21 +1,79 @@
+import { type ResourceRefs } from "./selected-resources.js";
+import { type ConfigDocument, type MoeiconsConfigFile } from "../project/config.js";
+import type { SelectedResourceDownload } from "./free-download.js";
 import { type SignedArtifactDescriptor } from "./signed-artifact.js";
 import { type AuthUseCaseDependencies } from "./auth.js";
 import type { CommandContext } from "./context.js";
 import type { ReleaseTarget, ReleaseTargetMetadata } from "./release-descriptor.js";
 export declare const PRO_DOWNLOAD_HOSTS: readonly ["06898acc14d0b9633f259fe20145fd49.r2.cloudflarestorage.com"];
+/**
+ * Test seam: `MOEICONS_PRO_DESCRIPTOR_URL` overrides the authenticated Pro
+ * descriptor endpoint. Only an https URL or a loopback http URL is accepted, so
+ * production behavior is unchanged and a local mock can drive the packed CLI
+ * during candidate acceptance.
+ */
+export declare function resolveProDescriptorEndpoint(env: Readonly<Record<string, string | undefined>>): {
+    readonly url: string;
+    readonly allowLoopback: boolean;
+    readonly loopbackHost: string | null;
+};
 export interface ProArtifactDescriptor extends SignedArtifactDescriptor {
+    readonly resources?: ResourceRefs;
     readonly tier: "pro";
     readonly version: string;
     readonly descriptorSha256: string;
     readonly catalogFilename: "catalog.json";
     readonly catalogSha256: string;
+    /** Signed URL for the small metadata archive (MANUAL.md + manifest.json). */
+    readonly metadata?: SignedArtifactDescriptor;
     /** Optional per-target subtree metadata; verified when the API provides it. */
     readonly targetMetadata?: Readonly<Partial<Record<ReleaseTarget, ReleaseTargetMetadata>>>;
+    /** A-1b: present only for an accepted local-test candidate. */
+    readonly channel?: "local-test";
+    readonly publishable?: boolean;
 }
+/** Exchange auth for the Pro descriptor (token dance + error mapping). */
+export declare function fetchProDescriptor(context: CommandContext, auth: AuthUseCaseDependencies, expected: {
+    version: string;
+    descriptorSha256: string;
+    allowLocalTest?: boolean;
+}, deps?: {
+    readonly fetch?: typeof fetch;
+}): Promise<ProArtifactDescriptor>;
+/** Extract + verify the pro metadata archive; the manifest must match the pro release. */
+export declare function extractProMetadata(artifactBytes: Uint8Array, catalogSha256: string, version: string, allowLocalTest?: boolean): {
+    readonly manifestJson: string;
+    readonly manualMd: string;
+    readonly catalogJson: string;
+};
+/** Shared signed-download options for the Pro archive (endpoint-aware loopback). */
+export declare function proSignedDownloadOptions(context: CommandContext, deps?: {
+    readonly fetch?: typeof fetch;
+    readonly allowedHosts?: readonly string[];
+    readonly onProgress?: (event: {
+        readonly downloadedBytes: number;
+        readonly totalBytes?: number;
+    }) => void;
+}): {
+    onProgress?: (event: {
+        readonly downloadedBytes: number;
+        readonly totalBytes?: number;
+    }) => void;
+    allowLoopback?: boolean;
+    signal: AbortSignal;
+    now: number;
+    fetch?: typeof fetch;
+    allowedHosts: readonly string[];
+};
 export declare function downloadProArtifact(context: CommandContext, auth: AuthUseCaseDependencies, expected: {
     version: string;
     descriptorSha256: string;
+    allowLocalTest?: boolean;
 }, deps?: {
+    readonly selection?: {
+        config: MoeiconsConfigFile;
+        document: ConfigDocument;
+    };
     readonly fetch?: typeof fetch;
     readonly allowedHosts?: readonly string[];
     readonly onProgress?: (event: {
@@ -26,4 +84,9 @@ export declare function downloadProArtifact(context: CommandContext, auth: AuthU
     readonly descriptor: ProArtifactDescriptor;
     readonly artifactBytes: Uint8Array;
     readonly catalogJson: string;
+    readonly manifestJson: string;
+    readonly manualMd: string;
+    readonly metadataSha256: string;
+    readonly metadataBytes?: Uint8Array;
+    readonly selected?: SelectedResourceDownload;
 }>;

package/dist/core/pro-download.js

@@ -1,22 +1,60 @@
+import { parseResourceRefs } from "./selected-resources.js";
+import { downloadProSelected } from "./pro-selected-download.js";
+import { validateConfigDocument, } from "../project/config.js";
+import { parseCatalog } from "../catalog/catalog.js";
 import { CliError } from "../errors/index.js";
-import { extractTarGz, decodeUtf8 } from "../project/tar-gz.js";
+import { extractTarGz, decodeUtf8, ICON_ARCHIVE_MAX_ENTRIES, ICON_ARCHIVE_MAX_EXPANDED_BYTES, } from "../project/tar-gz.js";
 import { sha256Bytes } from "../project/install-metadata.js";
-import { downloadSignedArtifact } from "./signed-artifact.js";
+import { downloadSignedArtifact, parseSignedDescriptor, } from "./signed-artifact.js";
 import { runAccessTokenUseCase } from "./auth.js";
+import { extractAndVerifyMetadataArchive } from "../metadata/archive.js";
 const ENDPOINT = "https://api.moeicons.com/v1/icon-library/pro/artifact-descriptor";
-export const PRO_DOWNLOAD_HOSTS = ["06898acc14d0b9633f259fe20145fd49.r2.cloudflarestorage.com"];
+export const PRO_DOWNLOAD_HOSTS = [
+    "06898acc14d0b9633f259fe20145fd49.r2.cloudflarestorage.com",
+];
 const SHA = /^[a-f0-9]{64}$/;
 const VERSION = /^\d+\.\d+\.\d+(?:-(?:alpha|beta))?$/;
+/** A-1b: local-test candidate version; only accepted with an explicit local context. */
+const LOCAL_TEST_VERSION = /^\d+\.\d+\.\d+-test$/;
+const LOOPBACK = new Set(["127.0.0.1", "localhost", "::1"]);
+/**
+ * Test seam: `MOEICONS_PRO_DESCRIPTOR_URL` overrides the authenticated Pro
+ * descriptor endpoint. Only an https URL or a loopback http URL is accepted, so
+ * production behavior is unchanged and a local mock can drive the packed CLI
+ * during candidate acceptance.
+ */
+export function resolveProDescriptorEndpoint(env) {
+    const override = env.MOEICONS_PRO_DESCRIPTOR_URL;
+    if (!override)
+        return { url: ENDPOINT, allowLoopback: false, loopbackHost: null };
+    let parsed;
+    try {
+        parsed = new URL(override);
+    }
+    catch {
+        throw new CliError("VALIDATION_ERROR", "MOEICONS_PRO_DESCRIPTOR_URL is not a valid URL");
+    }
+    const loopback = parsed.protocol === "http:" && LOOPBACK.has(parsed.hostname);
+    if (parsed.protocol !== "https:" && !loopback) {
+        throw new CliError("VALIDATION_ERROR", "MOEICONS_PRO_DESCRIPTOR_URL must be https or loopback http");
+    }
+    return { url: override, allowLoopback: loopback, loopbackHost: loopback ? parsed.host : null };
+}
+/** A-1b: the descriptor is an accepted local-test candidate. */
+function isLocalTestDescriptor(item, allowLocalTest) {
+    return (allowLocalTest &&
+        typeof item.version === "string" &&
+        LOCAL_TEST_VERSION.test(item.version) &&
+        item.channel === "local-test" &&
+        item.publishable === false);
+}
 function parseTargetMetadata(value) {
     if (typeof value !== "object" || value === null || Array.isArray(value))
         return undefined;
     const record = value;
     const result = {};
     for (const [key, entry] of Object.entries(record)) {
-        if (key !== "react" &&
-            key !== "vue" &&
-            key !== "vanilla" &&
-            key !== "assets") {
+        if (key !== "react" && key !== "vue" && key !== "vanilla" && key !== "assets") {
             return undefined;
         }
         if (typeof entry !== "object" || entry === null || Array.isArray(entry))
@@ -39,24 +77,74 @@ function parseTargetMetadata(value) {
     }
     return result;
 }
-function parse(value, expected) {
+function parse(value, expected, now, allowLoopback) {
     if (typeof value !== "object" || value === null || Array.isArray(value))
         throw new CliError("VALIDATION_ERROR", "invalid pro artifact descriptor");
     const item = value;
-    const allowed = ["ok", "tier", "version", "descriptorSha256", "catalogFilename", "catalogSha256", "url", "expiresAt", "size", "sha256", "targetMetadata"];
-    if (Object.keys(item).some((key) => !allowed.includes(key)) || item.ok !== true || item.tier !== "pro" || item.version !== expected.version || item.descriptorSha256 !== expected.descriptorSha256 ||
-        typeof item.version !== "string" || !VERSION.test(item.version) || typeof item.descriptorSha256 !== "string" || !SHA.test(item.descriptorSha256) ||
-        item.catalogFilename !== "catalog.json" || typeof item.catalogSha256 !== "string" || !SHA.test(item.catalogSha256) || typeof item.url !== "string" ||
-        typeof item.expiresAt !== "string" || typeof item.size !== "number" || !Number.isSafeInteger(item.size) || item.size < 1 || typeof item.sha256 !== "string" || !SHA.test(item.sha256)) {
+    const allowLocalTest = expected.allowLocalTest === true;
+    const baseAllowed = [
+        "ok",
+        "tier",
+        "version",
+        "descriptorSha256",
+        "catalogFilename",
+        "catalogSha256",
+        "url",
+        "expiresAt",
+        "size",
+        "sha256",
+        "targetMetadata",
+        "metadata",
+        "resources",
+    ];
+    const allowed = allowLocalTest ? [...baseAllowed, "channel", "publishable"] : baseAllowed;
+    const strictVersion = typeof item.version === "string" && VERSION.test(item.version);
+    // A formal (stable/alpha/beta) version must never carry the local-test marker.
+    if (strictVersion && (item.channel !== undefined || item.publishable !== undefined)) {
+        throw new CliError("VALIDATION_ERROR", "invalid or changed pro artifact descriptor");
+    }
+    const versionAllowed = typeof item.version === "string" &&
+        (strictVersion || isLocalTestDescriptor(item, allowLocalTest));
+    if (Object.keys(item).some((key) => !allowed.includes(key)) ||
+        item.ok !== true ||
+        item.tier !== "pro" ||
+        item.version !== expected.version ||
+        item.descriptorSha256 !== expected.descriptorSha256 ||
+        !versionAllowed ||
+        typeof item.descriptorSha256 !== "string" ||
+        !SHA.test(item.descriptorSha256) ||
+        item.catalogFilename !== "catalog.json" ||
+        typeof item.catalogSha256 !== "string" ||
+        !SHA.test(item.catalogSha256) ||
+        typeof item.url !== "string" ||
+        typeof item.expiresAt !== "string" ||
+        typeof item.size !== "number" ||
+        !Number.isSafeInteger(item.size) ||
+        item.size < 1 ||
+        typeof item.sha256 !== "string" ||
+        !SHA.test(item.sha256)) {
         throw new CliError("VALIDATION_ERROR", "invalid or changed pro artifact descriptor");
     }
+    if (item.resources !== undefined) {
+        const refs = parseResourceRefs(item.resources);
+        if (refs.index.filename !== `moe-icons-pro-resource-index-${item.version}.json.gz` ||
+            refs.bundle.filename !== `moe-icons-pro-resources-${item.version}.bin`)
+            throw new CliError("VALIDATION_ERROR", "pro resource filenames do not match tier/version");
+    }
     const targetMetadata = item.targetMetadata !== undefined ? parseTargetMetadata(item.targetMetadata) : undefined;
+    const metadata = item.metadata !== undefined
+        ? parseSignedDescriptor(item.metadata, now, { allowLoopback })
+        : undefined;
+    const localTest = isLocalTestDescriptor(item, allowLocalTest);
     return {
         ...item,
         ...(targetMetadata ? { targetMetadata } : {}),
+        ...(metadata ? { metadata } : {}),
+        ...(item.resources !== undefined ? { resources: parseResourceRefs(item.resources) } : {}),
+        ...(localTest ? { channel: "local-test", publishable: false } : {}),
     };
 }
-async function requestDescriptor(token, expected, deps) {
+async function requestDescriptor(token, endpoint, expected, deps) {
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), 5_000);
     const abort = () => controller.abort();
@@ -64,14 +152,47 @@ async function requestDescriptor(token, expected, deps) {
         controller.abort();
     deps.signal.addEventListener("abort", abort, { once: true });
     try {
-        const response = await deps.fetch(ENDPOINT, {
-            method: "POST", redirect: "error", signal: controller.signal,
-            headers: { authorization: `Bearer ${token}`, accept: "application/json", "content-type": "application/json" },
+        const response = await deps.fetch(endpoint, {
+            method: "POST",
+            redirect: "error",
+            signal: controller.signal,
+            headers: {
+                authorization: `Bearer ${token}`,
+                accept: "application/json",
+                "content-type": "application/json",
+                "X-Moeicons-Resources": "v1",
+            },
             body: JSON.stringify(expected),
         });
-        if (!response.ok)
+        if (!response.ok) {
+            await response.body?.cancel();
             return { status: response.status };
-        return { status: response.status, value: parse(await response.json(), expected) };
+        }
+        const reader = response.body?.getReader();
+        if (!reader)
+            throw new CliError("NETWORK_ERROR", "empty pro descriptor response");
+        const chunks = [];
+        let size = 0;
+        try {
+            for (;;) {
+                const part = await reader.read();
+                if (part.done)
+                    break;
+                size += part.value.length;
+                if (size > 256 * 1024) {
+                    await reader.cancel();
+                    throw new CliError("VALIDATION_ERROR", "pro descriptor exceeds 256 KiB");
+                }
+                chunks.push(part.value);
+            }
+        }
+        finally {
+            reader.releaseLock();
+        }
+        return {
+            status: response.status,
+            value: parse(JSON.parse(Buffer.concat(chunks).toString("utf8")), expected, deps.now, deps.allowLoopback),
+        };
     }
     catch (error) {
         if (error instanceof CliError)
@@ -83,13 +204,26 @@ async function requestDescriptor(token, expected, deps) {
         deps.signal.removeEventListener("abort", abort);
     }
 }
-export async function downloadProArtifact(context, auth, expected, deps = {}) {
+/** Exchange auth for the Pro descriptor (token dance + error mapping). */
+export async function fetchProDescriptor(context, auth, expected, deps = {}) {
     const fetchFn = deps.fetch ?? fetch;
+    const { url: endpoint, allowLoopback } = resolveProDescriptorEndpoint(context.env);
     let token = await runAccessTokenUseCase(context, auth);
-    let response = await requestDescriptor(token, expected, { fetch: fetchFn, signal: context.signal });
+    const now = () => context.now().getTime();
+    let response = await requestDescriptor(token, endpoint, expected, {
+        fetch: fetchFn,
+        signal: context.signal,
+        now: now(),
+        allowLoopback,
+    });
     if (response.status === 401) {
         token = await runAccessTokenUseCase(context, auth, true);
-        response = await requestDescriptor(token, expected, { fetch: fetchFn, signal: context.signal });
+        response = await requestDescriptor(token, endpoint, expected, {
+            fetch: fetchFn,
+            signal: context.signal,
+            now: now(),
+            allowLoopback,
+        });
     }
     token = "";
     if (response.status === 401)
@@ -100,13 +234,99 @@ export async function downloadProArtifact(context, auth, expected, deps = {}) {
         throw new CliError("NOT_FOUND", "pro artifact not found");
     if (!response.value)
         throw new CliError("NETWORK_ERROR", `pro descriptor request failed with ${response.status}`);
-    const descriptor = response.value;
-    const artifactBytes = await downloadSignedArtifact({ url: descriptor.url, expiresAt: descriptor.expiresAt, size: descriptor.size, sha256: descriptor.sha256 }, { allowedHosts: deps.allowedHosts ?? PRO_DOWNLOAD_HOSTS, fetch: fetchFn, signal: context.signal, now: context.now().getTime(), ...(deps.onProgress ? { onProgress: deps.onProgress } : {}) });
-    const extracted = extractTarGz(artifactBytes, { maxEntries: 20_000, maxExpandedBytes: 64 * 1024 * 1024 });
+    return response.value;
+}
+/** Extract + verify the pro metadata archive; the manifest must match the pro release. */
+export function extractProMetadata(artifactBytes, catalogSha256, version, allowLocalTest = false) {
+    const result = extractAndVerifyMetadataArchive(artifactBytes, {
+        expectedCatalogSha: catalogSha256,
+        expectedTier: "pro",
+        expectedVersion: version,
+        allowLocalTest,
+    });
+    if (result.kind !== "ok")
+        throw new CliError("VALIDATION_ERROR", result.message);
+    return result.value;
+}
+/** Shared signed-download options for the Pro archive (endpoint-aware loopback). */
+export function proSignedDownloadOptions(context, deps = {}) {
+    const { allowLoopback, loopbackHost } = resolveProDescriptorEndpoint(context.env);
+    return {
+        allowedHosts: deps.allowedHosts ??
+            (loopbackHost ? [...PRO_DOWNLOAD_HOSTS, loopbackHost] : PRO_DOWNLOAD_HOSTS),
+        ...(deps.fetch ? { fetch: deps.fetch } : {}),
+        signal: context.signal,
+        now: context.now().getTime(),
+        ...(allowLoopback ? { allowLoopback: true } : {}),
+        ...(deps.onProgress ? { onProgress: deps.onProgress } : {}),
+    };
+}
+export async function downloadProArtifact(context, auth, expected, deps = {}) {
+    const fetchFn = deps.fetch ?? fetch;
+    const descriptor = await fetchProDescriptor(context, auth, expected, { fetch: fetchFn });
+    if (deps.selection &&
+        deps.selection.config.downloadMode !== "full" &&
+        descriptor.resources &&
+        descriptor.channel !== "local-test") {
+        const selected = await downloadProSelected(context, auth, descriptor, deps.selection, deps);
+        if (selected)
+            return {
+                descriptor,
+                artifactBytes: new Uint8Array(),
+                ...selected,
+                metadataSha256: descriptor.metadata.sha256,
+            };
+    }
+    if (deps.selection?.config.downloadMode === "icons")
+        throw new CliError("VALIDATION_ERROR", "this release/backend does not support selected resources; set downloadMode=full or use a newer release");
+    context.ui.note(deps.selection?.config.downloadMode === "full"
+        ? "Download mode: full (explicitly configured)."
+        : "Release does not advertise selected downloads; auto uses the verified full archive. Set downloadMode=icons to require selected downloads.", context.signal);
+    const downloadOptions = proSignedDownloadOptions(context, deps);
+    let metadata;
+    let metadataBytes;
+    if (descriptor.metadata) {
+        metadataBytes = await downloadSignedArtifact(descriptor.metadata, downloadOptions);
+        metadata = extractProMetadata(metadataBytes, descriptor.catalogSha256, descriptor.version, expected.allowLocalTest === true);
+    }
+    else {
+        throw new CliError("VALIDATION_ERROR", "pro release descriptor is missing the metadata archive");
+    }
+    if (deps.selection) {
+        try {
+            const strict = validateConfigDocument(deps.selection.document, parseCatalog(JSON.parse(metadata.catalogJson)));
+            if (strict.kind !== "ok")
+                throw new CliError("VALIDATION_ERROR", strict.kind === "invalid" ? strict.message : `config state: ${strict.kind}`);
+        }
+        catch (error) {
+            if (error instanceof CliError)
+                throw error;
+            throw new CliError("VALIDATION_ERROR", `invalid fixed release catalog: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    const artifactBytes = await downloadSignedArtifact({
+        url: descriptor.url,
+        expiresAt: descriptor.expiresAt,
+        size: descriptor.size,
+        sha256: descriptor.sha256,
+    }, downloadOptions);
+    const extracted = extractTarGz(artifactBytes, {
+        maxEntries: ICON_ARCHIVE_MAX_ENTRIES,
+        maxExpandedBytes: ICON_ARCHIVE_MAX_EXPANDED_BYTES,
+    });
     if (extracted.errors.length > 0)
         throw new CliError("VALIDATION_ERROR", extracted.errors[0] ?? "invalid pro archive");
-    const catalog = extracted.files[descriptor.catalogFilename] ?? extracted.files[`./${descriptor.catalogFilename}`];
+    const catalog = extracted.files[descriptor.catalogFilename] ??
+        extracted.files[`./${descriptor.catalogFilename}`];
     if (!catalog || sha256Bytes(catalog) !== descriptor.catalogSha256)
         throw new CliError("VALIDATION_ERROR", "pro catalog SHA-256 mismatch");
-    return { descriptor, artifactBytes, catalogJson: decodeUtf8(catalog) };
+    return {
+        descriptor,
+        artifactBytes,
+        catalogJson: decodeUtf8(catalog),
+        manifestJson: metadata.manifestJson,
+        manualMd: metadata.manualMd,
+        metadataSha256: descriptor.metadata.sha256,
+        metadataBytes,
+    };
 }

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

@@ -1,9 +1,10 @@
-import { type TransactionalFs } from "../project/install.js";
-import type { AuthUseCaseDependencies } from "./auth.js";
+import { type TransactionalFs, type TransactionalFsWithCopy } from "../project/install.js";
+import { type AuthUseCaseDependencies } from "./auth.js";
 import type { CommandContext } from "./context.js";
 import type { Target } from "../commands/parser.js";
+type ProInstallFs = TransactionalFs & Partial<Pick<TransactionalFsWithCopy, "readFileSync" | "readdirSync" | "copyFileSync">>;
 export declare function runProInstallUseCase(context: CommandContext, deps: {
-    readonly fs: TransactionalFs;
+    readonly fs: ProInstallFs;
     readonly auth: AuthUseCaseDependencies;
     readonly fetch?: typeof fetch;
     readonly allowedHosts?: readonly string[];
@@ -15,10 +16,17 @@ export declare function runProInstallUseCase(context: CommandContext, deps: {
     readonly version: string;
     readonly descriptorSha256: string;
     readonly target?: Target;
+    /** A-1b: allow a declared local-test candidate (never true for production). */
+    readonly allowLocalTest?: boolean;
 }): Promise<{
     readonly projectRoot: string;
     readonly artifactVersion: string;
     readonly descriptorSha256: string;
     readonly catalogSha256: string;
     readonly artifactBytes: number;
+    readonly downloadMode: "icons" | "full";
+    readonly downloadNotes: readonly string[];
+    readonly networkBytes?: number;
+    readonly selectedFiles?: number;
 }>;
+export {};