@moewolf/moe-icons-cli 0.0.1

package/dist/core/install.d.ts

@@ -0,0 +1,67 @@
+import { type TransactionalFs } from "../project/install.js";
+import type { CommandContext } from "./context.js";
+import type { PackageManager } from "../project/detect.js";
+import { type FreeDownloadIo } from "./free-download.js";
+import type { Target } from "../commands/parser.js";
+export type InstallResult = {
+    readonly ok: true;
+    readonly projectRoot: string;
+    readonly packageManager: PackageManager;
+    readonly group: "free";
+    readonly target: Target;
+    readonly artifactBytes: number;
+    readonly planItems: number;
+    readonly config: string;
+    readonly artifactVersion: string;
+    readonly descriptorSha256: string;
+    readonly catalogSha256: string;
+    readonly cacheHit: boolean;
+} | {
+    readonly ok: false;
+    readonly reason: "no-project";
+} | {
+    readonly ok: false;
+    readonly reason: "cancelled";
+    readonly message: string;
+} | {
+    readonly ok: false;
+    readonly reason: "checksum-mismatch";
+    readonly message: string;
+} | {
+    readonly ok: false;
+    readonly reason: "network";
+    readonly message: string;
+} | {
+    readonly ok: false;
+    readonly reason: "not-found";
+    readonly message: string;
+} | {
+    readonly ok: false;
+    readonly reason: "offline-no-cache";
+    readonly message: string;
+} | {
+    readonly ok: false;
+    readonly reason: "validation";
+    readonly message: string;
+} | {
+    readonly ok: false;
+    readonly reason: "write-failed";
+    readonly message: string;
+};
+export interface InstallUseCaseDeps {
+    readonly fs: TransactionalFs;
+    readonly download: Omit<FreeDownloadIo, "signal">;
+}
+/**
+ * Free install: resolve the catalog sourceVersion tag, download/verify the
+ * GitHub Release (or a local release fixture), verify the selected target's
+ * descriptor subtree, then transactionally write managed metadata plus the
+ * selected target subtree. Pro installs route through the authenticated
+ * `runProInstallUseCase`; this use case rejects them explicitly.
+ */
+export declare function runInstallUseCase(context: CommandContext, deps: InstallUseCaseDeps, options: {
+    readonly group?: string;
+    readonly target?: Target;
+    readonly sourceVersion?: string;
+    readonly expectedDescriptorSha256?: string;
+}): Promise<InstallResult>;

package/dist/core/install.js

@@ -0,0 +1,117 @@
+import { createInstallPlan, executeInstallPlan } from "../project/install.js";
+import { detectProject } from "../project/detect.js";
+import { readMoeiconsConfig } from "../project/config.js";
+import { bundledSourceVersion, downloadFreeRelease } from "./free-download.js";
+import { serializeInstallMetadata, sha256Bytes } from "../project/install-metadata.js";
+import { withProjectLock } from "../project/project-lock.js";
+import { selectTargetSubtree } from "./target-subtree.js";
+function normalizeGroup(group) {
+    if (group === undefined || group === "free")
+        return "free";
+    if (group === "ent")
+        return "pro";
+    return group === "pro" ? "pro" : "free";
+}
+/**
+ * Free install: resolve the catalog sourceVersion tag, download/verify the
+ * GitHub Release (or a local release fixture), verify the selected target's
+ * descriptor subtree, then transactionally write managed metadata plus the
+ * selected target subtree. Pro installs route through the authenticated
+ * `runProInstallUseCase`; this use case rejects them explicitly.
+ */
+export async function runInstallUseCase(context, deps, options) {
+    const project = detectProject(context.cwd);
+    if (!project)
+        return { ok: false, reason: "no-project" };
+    const groupArg = options.group;
+    if (groupArg !== undefined && groupArg !== "free" && groupArg !== "pro" && groupArg !== "ent") {
+        return { ok: false, reason: "validation", message: `unknown install group: ${groupArg}` };
+    }
+    const group = normalizeGroup(groupArg);
+    if (group === "pro") {
+        return {
+            ok: false,
+            reason: "validation",
+            message: "pro install requires the authenticated pro flow",
+        };
+    }
+    const config = readMoeiconsConfig(project.root);
+    if (config.kind === "invalid" || config.kind === "unsupported") {
+        return {
+            ok: false,
+            reason: "validation",
+            message: config.kind === "invalid" ? config.message : `unsupported config schema version ${config.version}`,
+        };
+    }
+    const target = options.target ?? (config.kind === "ok" ? config.config.target : "react");
+    const downloaded = await downloadFreeRelease({ ...deps.download, signal: context.signal }, options.sourceVersion ?? bundledSourceVersion());
+    if (!downloaded.ok) {
+        return downloaded.reason === "cancelled"
+            ? { ok: false, reason: "cancelled", message: downloaded.message }
+            : downloaded;
+    }
+    if ((options.sourceVersion && downloaded.descriptor.fullVersion !== options.sourceVersion) ||
+        (options.expectedDescriptorSha256 &&
+            downloaded.descriptorSha256 !== options.expectedDescriptorSha256)) {
+        return {
+            ok: false,
+            reason: "validation",
+            message: "downloaded release identity changed after version check; retry the update",
+        };
+    }
+    const subtree = selectTargetSubtree(downloaded.artifactBytes, downloaded.descriptor.free, target);
+    if (!subtree.ok) {
+        return subtree.reason === "checksum-mismatch"
+            ? { ok: false, reason: "checksum-mismatch", message: subtree.message }
+            : { ok: false, reason: "validation", message: subtree.message };
+    }
+    const catalogJson = downloaded.catalogJson;
+    const files = {
+        ".moeicons/catalog.json": catalogJson,
+        "src/moeicons/types.ts": `export type { ReactIconProps } from "moe-icons";\n`,
+        "src/moeicons/.moeicons-free.marker": "free\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.fullVersion,
+        tier: "free",
+        target,
+        descriptorSha256: downloaded.descriptorSha256,
+        catalogSha256: downloaded.descriptor.catalog.sha256,
+        artifactSha256: downloaded.descriptor.free.sha256,
+        installedAt: context.now().toISOString(),
+        managedFiles,
+        targetSha256: subtree.sha256,
+        targetFileCount: subtree.fileCount,
+        targetByteCount: subtree.byteCount,
+    });
+    const plan = createInstallPlan(project.root, files);
+    try {
+        await withProjectLock(project.root, "install", () => executeInstallPlan(plan, deps.fs));
+    }
+    catch (error) {
+        return {
+            ok: false,
+            reason: "write-failed",
+            message: error instanceof Error ? error.message : String(error),
+        };
+    }
+    return {
+        ok: true,
+        projectRoot: project.root,
+        packageManager: project.packageManager,
+        group: "free",
+        target,
+        artifactBytes: downloaded.artifactBytes.byteLength,
+        planItems: plan.items.length,
+        config: config.kind,
+        artifactVersion: downloaded.descriptor.fullVersion,
+        descriptorSha256: downloaded.descriptorSha256,
+        catalogSha256: downloaded.descriptor.catalog.sha256,
+        cacheHit: downloaded.cacheHit,
+    };
+}

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

@@ -0,0 +1,24 @@
+import { type TransactionalFsWithCopy } from "../project/install.js";
+import type { AuthUseCaseDependencies } from "./auth.js";
+import type { CommandContext } from "./context.js";
+import { type FreeDownloadIo } from "./free-download.js";
+export interface LibraryUpdateDeps {
+    readonly fs: TransactionalFsWithCopy;
+    readonly free: Omit<FreeDownloadIo, "signal">;
+    readonly auth: AuthUseCaseDependencies;
+    readonly fetch?: typeof fetch;
+    readonly allowedProHosts?: readonly string[];
+    readonly onProgress?: (event: {
+        readonly downloadedBytes: number;
+        readonly totalBytes?: number;
+    }) => void;
+}
+export declare function runLibraryUpdateUseCase(context: CommandContext, deps: LibraryUpdateDeps, expected: {
+    readonly tier: "free" | "pro";
+    readonly version: string;
+    readonly descriptorSha256: string;
+}): Promise<{
+    readonly projectRoot: string;
+    readonly artifactVersion: string;
+    readonly files: readonly string[];
+}>;

package/dist/core/library-update.js

@@ -0,0 +1,161 @@
+import { join, relative, resolve } from "node:path";
+import { homedir } from "node:os";
+import { parseCatalog } from "../catalog/catalog.js";
+import { CliError } from "../errors/index.js";
+import { planGeneratedFiles } from "../generator/generate.js";
+import { readMoeiconsConfig } from "../project/config.js";
+import { detectProject } from "../project/detect.js";
+import { executeManagedReconcile } from "../project/install.js";
+import { parseInstallMetadata, serializeInstallMetadata, sha256Bytes, } from "../project/install-metadata.js";
+import { withProjectLock } from "../project/project-lock.js";
+import { ensureClassMergeDependencies, planTailwindIntegration } from "../project/tailwind.js";
+import { extractTarGz } from "../project/tar-gz.js";
+import { artifactCachePath, downloadFreeRelease } from "./free-download.js";
+import { downloadProArtifact } from "./pro-download.js";
+import { selectTargetSubtree } from "./target-subtree.js";
+export async function runLibraryUpdateUseCase(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");
+    let catalogJson;
+    let archiveBytes;
+    let artifactSha256;
+    let catalogSha256;
+    let tierSource;
+    if (expected.tier === "free") {
+        const downloaded = await downloadFreeRelease({
+            ...deps.free,
+            signal: context.signal,
+            ...(deps.onProgress ? { onProgress: deps.onProgress } : {}),
+        }, expected.version);
+        if (!downloaded.ok)
+            throw new CliError(downloaded.reason === "cancelled" ? "CANCELLED" : "VALIDATION_ERROR", downloaded.message);
+        if (downloaded.descriptorSha256 !== expected.descriptorSha256 ||
+            downloaded.descriptor.fullVersion !== expected.version) {
+            throw new CliError("VALIDATION_ERROR", "downloaded release identity changed after version check; retry the update");
+        }
+        catalogJson = downloaded.catalogJson;
+        archiveBytes = downloaded.artifactBytes;
+        artifactSha256 = downloaded.descriptor.free.sha256;
+        catalogSha256 = downloaded.descriptor.catalog.sha256;
+        tierSource = downloaded.descriptor.free;
+    }
+    else {
+        const downloaded = await downloadProArtifact(context, deps.auth, expected, {
+            ...(deps.fetch ? { fetch: deps.fetch } : {}),
+            ...(deps.allowedProHosts ? { allowedHosts: deps.allowedProHosts } : {}),
+            ...(deps.onProgress ? { onProgress: deps.onProgress } : {}),
+        });
+        catalogJson = downloaded.catalogJson;
+        archiveBytes = downloaded.artifactBytes;
+        artifactSha256 = downloaded.descriptor.sha256;
+        catalogSha256 = downloaded.descriptor.catalogSha256;
+        tierSource = downloaded.descriptor;
+        const cacheDir = context.env.MOEICONS_CACHE_DIR ?? join(homedir(), ".moeicons", "cache");
+        const cached = artifactCachePath(cacheDir, downloaded.descriptor.version, downloaded.descriptor.sha256);
+        if (!deps.fs.existsSync(cached)) {
+            deps.fs.mkdirSync(join(cached, ".."), { recursive: true });
+            deps.fs.writeFileSync(cached, downloaded.artifactBytes);
+        }
+    }
+    let candidateCatalog;
+    try {
+        candidateCatalog = parseCatalog(JSON.parse(catalogJson));
+    }
+    catch (error) {
+        throw new CliError("VALIDATION_ERROR", error instanceof Error ? error.message : String(error));
+    }
+    if (candidateCatalog.sourceVersion !== expected.version ||
+        sha256Bytes(catalogJson) !== catalogSha256) {
+        throw new CliError("VALIDATION_ERROR", "candidate catalog identity does not match the selected release");
+    }
+    const loaded = readMoeiconsConfig(project.root, candidateCatalog);
+    if (loaded.kind !== "ok" || loaded.config.tier !== expected.tier)
+        throw new CliError("VALIDATION_ERROR", `config is invalid for the ${expected.tier} candidate`);
+    const unpacked = extractTarGz(archiveBytes, {
+        maxEntries: 20_000,
+        maxExpandedBytes: 64 * 1024 * 1024,
+    });
+    if (unpacked.errors.length)
+        throw new CliError("VALIDATION_ERROR", unpacked.errors[0] ?? "invalid artifact");
+    const target = loaded.config.target;
+    const subtree = selectTargetSubtree(archiveBytes, tierSource, target);
+    if (!subtree.ok)
+        throw new CliError("VALIDATION_ERROR", subtree.message);
+    const generated = planGeneratedFiles(loaded.config, loaded.config.outputDir, {
+        archiveFiles: unpacked.files,
+        catalog: candidateCatalog,
+    });
+    if (!generated.ok)
+        throw new CliError("VALIDATION_ERROR", generated.errors.join("; "));
+    const writes = {
+        ".moeicons/catalog.json": catalogJson,
+        [`${loaded.config.outputDir.replace(/\\/g, "/").replace(/\/$/, "")}/.moeicons-${expected.tier}.marker`]: `${expected.tier}\n`,
+    };
+    for (const file of generated.files)
+        writes[file.path.replace(/\\/g, "/")] = file.content;
+    for (const [rel, bytes] of Object.entries(subtree.files)) {
+        writes[`.moeicons/artifact/${target}/${rel}`] = bytes;
+    }
+    const tailwindPlan = planTailwindIntegration(project.root, loaded.config.outputDir, {
+        noTailwind: false,
+        target,
+    });
+    for (const side of tailwindPlan.files) {
+        const rel = relative(project.root, resolve(side.path)).replace(/\\/g, "/");
+        if (!rel || rel === ".." || rel.startsWith("../"))
+            throw new CliError("VALIDATION_ERROR", `side file escapes project: ${side.path}`);
+        writes[rel] = side.content;
+    }
+    const pkgPath = join(project.root, "package.json");
+    if (deps.fs.existsSync(pkgPath)) {
+        const dependencyPlan = target === "react" || target === "vue"
+            ? ensureClassMergeDependencies(deps.fs.readFileSync(pkgPath, "utf8"))
+            : { nextSource: deps.fs.readFileSync(pkgPath, "utf8"), changed: false, notes: [] };
+        if (dependencyPlan.changed)
+            writes["package.json"] = dependencyPlan.nextSource;
+    }
+    const sidePaths = new Set([
+        "package.json",
+        ...tailwindPlan.files.map((file) => relative(project.root, resolve(file.path)).replace(/\\/g, "/")),
+    ]);
+    const managedFiles = Object.fromEntries(Object.entries(writes)
+        .filter(([path]) => !sidePaths.has(path))
+        .map(([path, content]) => [path, sha256Bytes(content)]));
+    const nextMetadata = {
+        schemaVersion: 1,
+        artifactVersion: expected.version,
+        tier: expected.tier,
+        target,
+        descriptorSha256: expected.descriptorSha256,
+        artifactSha256,
+        catalogSha256,
+        installedAt: context.now().toISOString(),
+        managedFiles,
+        targetSha256: subtree.sha256,
+        targetFileCount: subtree.fileCount,
+        targetByteCount: subtree.byteCount,
+    };
+    writes[".moeicons/install-metadata.json"] = serializeInstallMetadata(nextMetadata);
+    await withProjectLock(project.root, "update", () => {
+        const metadataPath = join(project.root, ".moeicons", "install-metadata.json");
+        if (!deps.fs.existsSync(metadataPath))
+            throw new CliError("VALIDATION_ERROR", "managed install metadata is missing");
+        const old = parseInstallMetadata(deps.fs.readFileSync(metadataPath, "utf8"));
+        if (!old || old.tier !== expected.tier)
+            throw new CliError("VALIDATION_ERROR", "managed install metadata is invalid");
+        for (const [path, hash] of Object.entries(old.managedFiles)) {
+            const absolute = join(project.root, path);
+            if (!deps.fs.existsSync(absolute) ||
+                sha256Bytes(deps.fs.readFileSync(absolute)) !== hash) {
+                throw new CliError("VALIDATION_ERROR", `managed file was modified or removed: ${path}`);
+            }
+        }
+        executeManagedReconcile(project.root, writes, Object.keys(old.managedFiles).filter((path) => !(path in managedFiles)), deps.fs);
+    });
+    return {
+        projectRoot: project.root,
+        artifactVersion: expected.version,
+        files: generated.files.map((file) => file.path),
+    };
+}

package/dist/core/manage.d.ts

@@ -0,0 +1,24 @@
+import { readInstalledResourceState, type InstallMetadata } from "../project/install-metadata.js";
+import { type PublicLibraryVersions } from "./version-service.js";
+export type LibraryVersionStatus = {
+    readonly kind: "installation-invalid";
+    readonly message: string;
+} | {
+    readonly kind: "check-failed";
+    readonly metadata: InstallMetadata;
+    readonly message: string;
+} | {
+    readonly kind: "unavailable";
+    readonly metadata: InstallMetadata;
+    readonly message: string;
+} | {
+    readonly kind: "current" | "update" | "channel-mismatch" | "remote-older";
+    readonly metadata: InstallMetadata;
+    readonly latestVersion: string;
+    readonly latestDescriptorSha256: string;
+};
+export declare function getLibraryVersionStatus(projectRoot: string, configTier: "free" | "pro", deps?: {
+    readonly readState?: typeof readInstalledResourceState;
+    readonly fetchVersions?: () => Promise<PublicLibraryVersions>;
+}): Promise<LibraryVersionStatus>;
+export declare function formatLibraryVersionStatus(status: LibraryVersionStatus): string;

package/dist/core/manage.js

@@ -0,0 +1,38 @@
+import { readInstalledResourceState } from "../project/install-metadata.js";
+import { decideUpdate } from "./update-policy.js";
+import { fetchLibraryVersions } from "./version-service.js";
+export async function getLibraryVersionStatus(projectRoot, configTier, deps = {}) {
+    const installed = (deps.readState ?? readInstalledResourceState)(projectRoot, configTier);
+    if (installed.kind !== "ok")
+        return { kind: "installation-invalid", message: installed.message };
+    let versions;
+    try {
+        versions = await (deps.fetchVersions ?? (() => fetchLibraryVersions()))();
+    }
+    catch (error) {
+        return { kind: "check-failed", metadata: installed.metadata, message: error instanceof Error ? error.message : "version check failed" };
+    }
+    const remote = versions[installed.metadata.tier];
+    if (!remote)
+        return { kind: "unavailable", metadata: installed.metadata, message: `no ${installed.metadata.tier} release is published` };
+    const decision = decideUpdate({
+        installedTier: installed.metadata.tier, remoteTier: installed.metadata.tier,
+        installedVersion: installed.metadata.artifactVersion, remoteVersion: remote.version,
+    });
+    const identity = { metadata: installed.metadata, latestVersion: remote.version, latestDescriptorSha256: remote.descriptorSha256 };
+    if (decision.kind === "current")
+        return { kind: "current", ...identity };
+    if (decision.kind === "update")
+        return { kind: "update", ...identity };
+    if (decision.reason === "channel-mismatch")
+        return { kind: "channel-mismatch", ...identity };
+    return { kind: "remote-older", ...identity };
+}
+export function formatLibraryVersionStatus(status) {
+    if (status.kind === "installation-invalid")
+        return `Current: invalid / Latest: unavailable / Status: installation invalid (${status.message})`;
+    if (status.kind === "check-failed" || status.kind === "unavailable")
+        return `Current: ${status.metadata.artifactVersion} / Latest: unavailable / Status: ${status.message}`;
+    const label = status.kind === "current" ? "up to date" : status.kind === "update" ? "update available" : status.kind === "channel-mismatch" ? "prerelease channel differs" : "remote version is older";
+    return `Current: ${status.metadata.artifactVersion} / Latest: ${status.latestVersion} / Status: ${label}`;
+}

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

@@ -0,0 +1,29 @@
+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"];
+export interface ProArtifactDescriptor extends SignedArtifactDescriptor {
+    readonly tier: "pro";
+    readonly version: string;
+    readonly descriptorSha256: string;
+    readonly catalogFilename: "catalog.json";
+    readonly catalogSha256: string;
+    /** Optional per-target subtree metadata; verified when the API provides it. */
+    readonly targetMetadata?: Readonly<Partial<Record<ReleaseTarget, ReleaseTargetMetadata>>>;
+}
+export declare function downloadProArtifact(context: CommandContext, auth: AuthUseCaseDependencies, expected: {
+    version: string;
+    descriptorSha256: string;
+}, deps?: {
+    readonly fetch?: typeof fetch;
+    readonly allowedHosts?: readonly string[];
+    readonly onProgress?: (event: {
+        readonly downloadedBytes: number;
+        readonly totalBytes?: number;
+    }) => void;
+}): Promise<{
+    readonly descriptor: ProArtifactDescriptor;
+    readonly artifactBytes: Uint8Array;
+    readonly catalogJson: string;
+}>;

package/dist/core/pro-download.js

@@ -0,0 +1,112 @@
+import { CliError } from "../errors/index.js";
+import { extractTarGz, decodeUtf8 } from "../project/tar-gz.js";
+import { sha256Bytes } from "../project/install-metadata.js";
+import { downloadSignedArtifact } from "./signed-artifact.js";
+import { runAccessTokenUseCase } from "./auth.js";
+const ENDPOINT = "https://api.moeicons.com/v1/icon-library/pro/artifact-descriptor";
+export const PRO_DOWNLOAD_HOSTS = ["06898acc14d0b9633f259fe20145fd49.r2.cloudflarestorage.com"];
+const SHA = /^[a-f0-9]{64}$/;
+const VERSION = /^\d+\.\d+\.\d+(?:-(?:alpha|beta))?$/;
+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") {
+            return undefined;
+        }
+        if (typeof entry !== "object" || entry === null || Array.isArray(entry))
+            return undefined;
+        const item = entry;
+        if (typeof item.path !== "string" || /(^|[\\/])\.\.([\\/]|$)/.test(item.path))
+            return undefined;
+        if (typeof item.sha256 !== "string" || !SHA.test(item.sha256))
+            return undefined;
+        if (typeof item.fileCount !== "number" || !Number.isSafeInteger(item.fileCount))
+            return undefined;
+        if (typeof item.byteCount !== "number" || !Number.isSafeInteger(item.byteCount))
+            return undefined;
+        result[key] = {
+            path: item.path,
+            sha256: item.sha256,
+            fileCount: item.fileCount,
+            byteCount: item.byteCount,
+        };
+    }
+    return result;
+}
+function parse(value, expected) {
+    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)) {
+        throw new CliError("VALIDATION_ERROR", "invalid or changed pro artifact descriptor");
+    }
+    const targetMetadata = item.targetMetadata !== undefined ? parseTargetMetadata(item.targetMetadata) : undefined;
+    return {
+        ...item,
+        ...(targetMetadata ? { targetMetadata } : {}),
+    };
+}
+async function requestDescriptor(token, expected, deps) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), 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(ENDPOINT, {
+            method: "POST", redirect: "error", signal: controller.signal,
+            headers: { authorization: `Bearer ${token}`, accept: "application/json", "content-type": "application/json" },
+            body: JSON.stringify(expected),
+        });
+        if (!response.ok)
+            return { status: response.status };
+        return { status: response.status, value: parse(await response.json(), expected) };
+    }
+    catch (error) {
+        if (error instanceof CliError)
+            throw error;
+        throw new CliError(deps.signal.aborted ? "CANCELLED" : "NETWORK_ERROR", deps.signal.aborted ? "pro download cancelled" : "pro descriptor request failed");
+    }
+    finally {
+        clearTimeout(timer);
+        deps.signal.removeEventListener("abort", abort);
+    }
+}
+export async function downloadProArtifact(context, auth, expected, deps = {}) {
+    const fetchFn = deps.fetch ?? fetch;
+    let token = await runAccessTokenUseCase(context, auth);
+    let response = await requestDescriptor(token, expected, { fetch: fetchFn, signal: context.signal });
+    if (response.status === 401) {
+        token = await runAccessTokenUseCase(context, auth, true);
+        response = await requestDescriptor(token, expected, { fetch: fetchFn, signal: context.signal });
+    }
+    token = "";
+    if (response.status === 401)
+        throw new CliError("AUTH_ERROR", "pro download authentication failed after one refresh");
+    if (response.status === 403)
+        throw new CliError("FORBIDDEN", "active pro entitlement required");
+    if (response.status === 404)
+        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 });
+    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}`];
+    if (!catalog || sha256Bytes(catalog) !== descriptor.catalogSha256)
+        throw new CliError("VALIDATION_ERROR", "pro catalog SHA-256 mismatch");
+    return { descriptor, artifactBytes, catalogJson: decodeUtf8(catalog) };
+}

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

@@ -0,0 +1,24 @@
+import { type TransactionalFs } from "../project/install.js";
+import type { AuthUseCaseDependencies } from "./auth.js";
+import type { CommandContext } from "./context.js";
+import type { Target } from "../commands/parser.js";
+export declare function runProInstallUseCase(context: CommandContext, deps: {
+    readonly fs: TransactionalFs;
+    readonly auth: AuthUseCaseDependencies;
+    readonly fetch?: typeof fetch;
+    readonly allowedHosts?: readonly string[];
+    readonly onProgress?: (event: {
+        readonly downloadedBytes: number;
+        readonly totalBytes?: number;
+    }) => void;
+}, expected: {
+    readonly version: string;
+    readonly descriptorSha256: string;
+    readonly target?: Target;
+}): Promise<{
+    readonly projectRoot: string;
+    readonly artifactVersion: string;
+    readonly descriptorSha256: string;
+    readonly catalogSha256: string;
+    readonly artifactBytes: number;
+}>;