@moewolf/moe-icons-cli 0.0.1

package/dist/commands/parser.js

@@ -0,0 +1,146 @@
+import { Command as Commander, CommanderError } from "commander";
+import { CliError } from "../errors/index.js";
+const SIMPLE_COMMANDS = [
+    "login",
+    "logout",
+    "account",
+    "groups",
+    "generate",
+    "init",
+    "mcp",
+    "help",
+];
+function addSharedOptions(command) {
+    return command
+        .allowUnknownOption(true)
+        .allowExcessArguments(true)
+        .helpOption(false)
+        .option("-h, --help")
+        .option("-v, --showVersion")
+        .option("--version")
+        .option("--json")
+        .option("--yes")
+        .option("--no-tailwind")
+        .option("--pro")
+        .option("--ent");
+}
+function createProgram(onSelect) {
+    const program = addSharedOptions(new Commander());
+    program
+        .name("moeicons")
+        .exitOverride()
+        .addHelpCommand(false)
+        .showHelpAfterError(false)
+        .enablePositionalOptions()
+        .configureOutput({
+        writeOut: () => undefined,
+        writeErr: () => undefined,
+    })
+        .action(() => {
+        onSelect({ name: "wizard" });
+    });
+    addSharedOptions(program.command("install").argument("[group]")).action((group) => {
+        onSelect(group ? { name: "install", group } : { name: "install" });
+    });
+    for (const name of SIMPLE_COMMANDS) {
+        addSharedOptions(program.command(name)).action(() => {
+            onSelect({ name });
+        });
+    }
+    return program;
+}
+function toCliError(error) {
+    if (error instanceof CommanderError && error.code === "commander.unknownCommand") {
+        const match = /unknown command ['`]?([^'`\s]+)/.exec(error.message);
+        throw new CliError("VALIDATION_ERROR", `unknown command: ${match?.[1] ?? "unknown"}`);
+    }
+    if (error instanceof CommanderError &&
+        (error.code === "commander.help" || error.code === "commander.helpDisplayed")) {
+        throw new CliError("VALIDATION_ERROR", error.message);
+    }
+    throw error;
+}
+const KNOWN_COMMANDS = new Set(["install", ...SIMPLE_COMMANDS]);
+/**
+ * Parse argv into a Command via Commander. Never calls `process.exit()`.
+ * `moeicons --pro` / `--ent` legacy aliases map to install for the compatibility window.
+ */
+export function parseArgs(argv) {
+    const json = argv.includes("--json");
+    const yes = argv.includes("--yes");
+    const noTailwind = argv.includes("--no-tailwind");
+    const version = argv.includes("--version") || argv.includes("-v");
+    const help = argv.includes("--help") || argv.includes("-h");
+    const pro = argv.includes("--pro");
+    const ent = argv.includes("--ent");
+    const targetIndex = argv.indexOf("--target");
+    const targetValue = targetIndex >= 0 ? argv[targetIndex + 1] : undefined;
+    if (targetIndex >= 0 && !["react", "vue", "vanilla", "assets"].includes(targetValue ?? "")) {
+        throw new CliError("VALIDATION_ERROR", `unknown target: ${targetValue ?? ""}`);
+    }
+    const target = targetValue;
+    const withTarget = (command) => target ? { ...command, target } : command;
+    // Preserve previous flag precedence: version/help/legacy aliases beat subcommands.
+    if (version)
+        return { command: { name: "version" }, json, yes, noTailwind, ...(target ? { target } : {}) };
+    if (help)
+        return { command: { name: "help" }, json, yes, noTailwind, ...(target ? { target } : {}) };
+    if (pro)
+        return {
+            command: withTarget({ name: "install", group: "pro" }),
+            json,
+            yes,
+            noTailwind,
+            ...(target ? { target } : {}),
+        };
+    if (ent)
+        return {
+            command: withTarget({ name: "install", group: "ent" }),
+            json,
+            yes,
+            noTailwind,
+            ...(target ? { target } : {}),
+        };
+    const positional = argv.filter((arg) => !arg.startsWith("-"));
+    const first = positional[0];
+    if (first !== undefined && !KNOWN_COMMANDS.has(first)) {
+        throw new CliError("VALIDATION_ERROR", `unknown command: ${first}`);
+    }
+    let selected;
+    try {
+        createProgram((command) => {
+            selected = withTarget(command);
+        }).parse([...argv], { from: "user" });
+    }
+    catch (error) {
+        toCliError(error);
+    }
+    return {
+        command: selected ?? { name: "wizard" },
+        json,
+        yes,
+        noTailwind,
+        ...(target ? { target } : {}),
+    };
+}
+export const HELP_TEXT = `moeicons — Moeicons icon library CLI
+
+Usage:
+  moeicons                      interactive guided flow (free / pro / login)
+  moeicons install [group]      install an icon group
+  moeicons login                browser login (PKCE)
+  moeicons logout               clear local session
+  moeicons account              show account/tier info
+  moeicons groups               list available icon groups
+  moeicons generate             generate React/Vue proxy components
+  moeicons init                 create moeicons.config.json
+  moeicons mcp                  start the MCP stdio server
+  moeicons --version            show version
+  moeicons --help               show help
+
+Options:
+  --json         machine-readable JSON output
+  --yes          skip confirmations in noninteractive mode
+  --target       output target: react, vue, vanilla, or assets
+  --no-tailwind  skip Tailwind config auto-integration
+`;

package/dist/core/auth.d.ts

@@ -0,0 +1,32 @@
+import { type DeviceLoginDependencies } from "../auth/device-login.js";
+import { redactSession, type TokenStore } from "../auth/token-store.js";
+import type { CommandContext } from "./context.js";
+export interface AuthUseCaseDependencies {
+    readonly tokenStore?: TokenStore;
+    readonly systemTokenStore?: () => TokenStore | undefined;
+    readonly fileTokenStore?: (rootDir?: string) => TokenStore;
+    readonly request?: DeviceLoginDependencies["request"];
+    readonly openBrowser?: (url: string) => Promise<void>;
+    readonly sleep?: (milliseconds: number, signal?: AbortSignal) => Promise<void>;
+    readonly fetch?: typeof fetch;
+    readonly fileFallbackAllowed?: boolean;
+}
+export type SessionStatus = {
+    readonly kind: "authenticated";
+    readonly account: ReturnType<typeof redactSession>;
+} | {
+    readonly kind: "signed-out";
+    readonly reason?: string;
+} | {
+    readonly kind: "unknown";
+    readonly reason: string;
+};
+/** Probe existing credentials without prompting for or creating fallback storage. */
+export declare function runSessionStatusUseCase(context: CommandContext, deps?: AuthUseCaseDependencies): Promise<SessionStatus>;
+export declare function runLoginUseCase(context: CommandContext, deps?: AuthUseCaseDependencies): Promise<ReturnType<typeof redactSession>>;
+/** Internal authenticated transport credential; adapters must never render it. */
+export declare function runAccessTokenUseCase(context: CommandContext, deps?: AuthUseCaseDependencies, forceRefresh?: boolean): Promise<string>;
+export declare function runAccountUseCase(context: CommandContext, deps?: AuthUseCaseDependencies): Promise<ReturnType<typeof redactSession>>;
+export declare function runLogoutUseCase(context: CommandContext, deps?: AuthUseCaseDependencies): Promise<{
+    revoked: boolean;
+}>;

package/dist/core/auth.js

@@ -0,0 +1,131 @@
+import { loginWithDeviceSession, refreshAuth0Session } from "../auth/device-login.js";
+import { createFileTokenStore, createSystemTokenStore, redactSession } from "../auth/token-store.js";
+import { openBrowser } from "../auth/open-browser.js";
+import { requestJson } from "../api/client.js";
+import { CliError } from "../errors/index.js";
+const API_BASE_URL = "https://api.moeicons.com";
+const WEBSITE_ORIGIN = "https://moeicons.com";
+function existingStore(context, deps) {
+    return deps.tokenStore ?? (context.env.MOEICONS_DISABLE_SYSTEM_KEYCHAIN === "1" ? undefined : (deps.systemTokenStore ?? createSystemTokenStore)()) ??
+        (context.env.MOEICONS_TOKEN_STORE_DIR ? (deps.fileTokenStore ?? ((rootDir) => createFileTokenStore(rootDir ? { rootDir } : {})))(context.env.MOEICONS_TOKEN_STORE_DIR) : undefined);
+}
+/** Probe existing credentials without prompting for or creating fallback storage. */
+export async function runSessionStatusUseCase(context, deps = {}) {
+    const store = existingStore(context, deps);
+    if (!store)
+        return { kind: "signed-out" };
+    const session = store.getActive();
+    if (!session)
+        return { kind: "signed-out" };
+    if (session.expiresAt > context.now().getTime())
+        return { kind: "authenticated", account: redactSession(session) };
+    const config = auth0Config(context);
+    if (!config.auth0Issuer || !config.auth0ClientId)
+        return { kind: "signed-out", reason: "stored session is expired" };
+    try {
+        const refreshed = await refreshAuth0Session(config, session, { fetch: deps.fetch ?? fetch, tokenStore: store, now: () => context.now().getTime(), signal: context.signal });
+        return { kind: "authenticated", account: redactSession(refreshed) };
+    }
+    catch (error) {
+        if (!(error instanceof CliError) || error.code === "NETWORK_ERROR" || error.code === "CANCELLED") {
+            return { kind: "unknown", reason: error instanceof Error ? error.message : "session validation unavailable" };
+        }
+        return { kind: "signed-out", reason: error.message };
+    }
+}
+async function selectStore(context, deps) {
+    if (deps.tokenStore)
+        return deps.tokenStore;
+    const system = context.env.MOEICONS_DISABLE_SYSTEM_KEYCHAIN === "1" ? undefined : (deps.systemTokenStore ?? createSystemTokenStore)();
+    if (system)
+        return system;
+    if (context.env.MOEICONS_DISABLE_SYSTEM_KEYCHAIN === "1" && context.env.MOEICONS_TOKEN_STORE_DIR) {
+        return (deps.fileTokenStore ?? ((rootDir) => createFileTokenStore(rootDir ? { rootDir } : {})))(context.env.MOEICONS_TOKEN_STORE_DIR);
+    }
+    if (deps.fileFallbackAllowed === false)
+        throw new CliError("AUTH_ERROR", "system credential storage is unavailable; non-interactive file fallback is disabled");
+    if (!context.ui.confirm)
+        throw new CliError("AUTH_ERROR", "system credential storage is unavailable");
+    const accepted = await context.ui.confirm("System credential storage is unavailable. Use a local file protected with mode 0600?", context.signal);
+    if (accepted === undefined)
+        throw new CliError("CANCELLED", "login cancelled");
+    if (!accepted)
+        throw new CliError("AUTH_ERROR", "login requires secure credential storage");
+    return (deps.fileTokenStore ?? ((rootDir) => createFileTokenStore(rootDir ? { rootDir } : {})))(context.env.MOEICONS_TOKEN_STORE_DIR);
+}
+function auth0Config(context) {
+    return {
+        apiBaseUrl: API_BASE_URL,
+        websiteOrigin: WEBSITE_ORIGIN,
+        auth0Issuer: context.env.MOEICONS_AUTH0_ISSUER ?? "",
+        auth0ClientId: context.env.MOEICONS_AUTH0_CLIENT_ID ?? "",
+    };
+}
+export async function runLoginUseCase(context, deps = {}) {
+    const tokenStore = await selectStore(context, deps);
+    const request = deps.request ?? ((path, options) => requestJson({ baseUrl: API_BASE_URL }, path, { ...options, retries: options.method === "GET" ? 3 : 0 }));
+    const session = await loginWithDeviceSession(auth0Config(context), {
+        request,
+        openBrowser: deps.openBrowser ?? openBrowser,
+        sleep: deps.sleep ?? ((milliseconds, signal) => new Promise((resolve, reject) => {
+            const timer = setTimeout(resolve, milliseconds);
+            signal?.addEventListener("abort", () => { clearTimeout(timer); reject(new CliError("CANCELLED", "login cancelled")); }, { once: true });
+        })),
+        tokenStore,
+        now: () => context.now().getTime(),
+    }, context.signal);
+    return redactSession(session);
+}
+async function activeSession(context, deps) {
+    const store = await selectStore(context, deps);
+    const session = store.getActive();
+    if (!session)
+        throw new CliError("AUTH_ERROR", "not logged in");
+    if (session.expiresAt > context.now().getTime())
+        return { store, session };
+    const config = auth0Config(context);
+    if (!config.auth0Issuer || !config.auth0ClientId)
+        throw new CliError("AUTH_ERROR", "session expired and Auth0 refresh configuration is unavailable");
+    const refreshed = await refreshAuth0Session(config, session, { fetch: deps.fetch ?? fetch, tokenStore: store, now: () => context.now().getTime(), signal: context.signal });
+    return { store, session: refreshed };
+}
+/** Internal authenticated transport credential; adapters must never render it. */
+export async function runAccessTokenUseCase(context, deps = {}, forceRefresh = false) {
+    if (!forceRefresh)
+        return (await activeSession(context, deps)).session.accessToken;
+    const store = await selectStore(context, deps);
+    const session = store.getActive();
+    if (!session)
+        throw new CliError("AUTH_ERROR", "not logged in");
+    const config = auth0Config(context);
+    if (!config.auth0Issuer || !config.auth0ClientId)
+        throw new CliError("AUTH_ERROR", "Auth0 refresh configuration is unavailable");
+    return (await refreshAuth0Session(config, session, { fetch: deps.fetch ?? fetch, tokenStore: store, now: () => context.now().getTime(), signal: context.signal })).accessToken;
+}
+export async function runAccountUseCase(context, deps = {}) {
+    return redactSession((await activeSession(context, deps)).session);
+}
+export async function runLogoutUseCase(context, deps = {}) {
+    const store = existingStore(context, deps);
+    if (!store)
+        return { revoked: true };
+    const session = store.getActive();
+    if (!session)
+        return { revoked: true };
+    let revoked = false;
+    const config = auth0Config(context);
+    if (config.auth0Issuer && config.auth0ClientId) {
+        try {
+            const response = await (deps.fetch ?? fetch)(`${config.auth0Issuer.replace(/\/$/, "")}/oauth/revoke`, {
+                method: "POST", headers: { "content-type": "application/json" },
+                body: JSON.stringify({ client_id: config.auth0ClientId, token: session.refreshToken }), signal: context.signal,
+            });
+            revoked = response.ok;
+        }
+        catch {
+            revoked = false;
+        }
+    }
+    store.clear();
+    return { revoked };
+}

package/dist/core/bitmap-assets.d.ts

@@ -0,0 +1,29 @@
+import { type ResourceVariant } from "./resource-variant.js";
+export interface SelectedBitmapAsset {
+    /** POSIX path relative to outputDir, e.g. assets/moe-cute-3d-webp-256/ui-search.webp */
+    readonly destRel: string;
+    readonly bytes: Uint8Array;
+    readonly resourceVariantId: string;
+    readonly iconId: string;
+}
+/**
+ * Identify a bitmap file inside a free/pro archive by parsing a directory
+ * segment as resourceVariantId (G2, from the right). Never scans for a mid-path `-3d`.
+ */
+export declare function matchArchiveBitmapFile(archivePath: string): {
+    readonly variant: ResourceVariant;
+    readonly iconId: string;
+} | undefined;
+export type SelectBitmapAssetsResult = {
+    readonly ok: true;
+    readonly assets: readonly SelectedBitmapAsset[];
+    readonly skipped: readonly string[];
+} | {
+    readonly ok: false;
+    readonly errors: readonly string[];
+};
+/**
+ * Keep only archive files that belong to the requested variants and selected
+ * icons. Other sizes/formats stay in the tarball/cache and are not written.
+ */
+export declare function selectBitmapVariantAssets(archiveFiles: Readonly<Record<string, Uint8Array>>, variants: readonly ResourceVariant[], iconIds: readonly string[]): SelectBitmapAssetsResult;

package/dist/core/bitmap-assets.js

@@ -0,0 +1,77 @@
+import { parseResourceVariantId, assetRelativePath } from "./resource-variant.js";
+function normalizeArchivePath(rel) {
+    return rel.replace(/\\/g, "/").replace(/^\.\//, "");
+}
+/**
+ * Identify a bitmap file inside a free/pro archive by parsing a directory
+ * segment as resourceVariantId (G2, from the right). Never scans for a mid-path `-3d`.
+ */
+export function matchArchiveBitmapFile(archivePath) {
+    const cleaned = normalizeArchivePath(archivePath);
+    const parts = cleaned.split("/").filter(Boolean);
+    if (parts.length < 2)
+        return undefined;
+    const file = parts[parts.length - 1] ?? "";
+    const dot = file.lastIndexOf(".");
+    if (dot <= 0)
+        return undefined;
+    const format = file.slice(dot + 1);
+    const iconId = file.slice(0, dot);
+    if (!iconId || iconId.includes(".."))
+        return undefined;
+    for (let i = 0; i < parts.length - 1; i += 1) {
+        const segment = parts[i] ?? "";
+        try {
+            const variant = parseResourceVariantId(segment);
+            if (variant.format !== format)
+                continue;
+            return { variant, iconId };
+        }
+        catch {
+            continue;
+        }
+    }
+    return undefined;
+}
+/**
+ * Keep only archive files that belong to the requested variants and selected
+ * icons. Other sizes/formats stay in the tarball/cache and are not written.
+ */
+export function selectBitmapVariantAssets(archiveFiles, variants, iconIds) {
+    const wanted = new Map(variants.map((variant) => [variant.resourceVariantId, variant]));
+    const iconSet = new Set(iconIds);
+    const skipped = [];
+    const chosen = new Map();
+    for (const [archivePath, bytes] of Object.entries(archiveFiles)) {
+        const matched = matchArchiveBitmapFile(archivePath);
+        if (!matched)
+            continue;
+        if (!wanted.has(matched.variant.resourceVariantId)) {
+            skipped.push(archivePath);
+            continue;
+        }
+        if (!iconSet.has(matched.iconId)) {
+            skipped.push(archivePath);
+            continue;
+        }
+        const destRel = assetRelativePath(matched.variant.resourceVariantId, matched.iconId, matched.variant.format);
+        chosen.set(destRel, {
+            destRel,
+            bytes,
+            resourceVariantId: matched.variant.resourceVariantId,
+            iconId: matched.iconId,
+        });
+    }
+    const errors = [];
+    for (const variant of variants) {
+        for (const iconId of iconIds) {
+            const destRel = assetRelativePath(variant.resourceVariantId, iconId, variant.format);
+            if (!chosen.has(destRel)) {
+                errors.push(`bitmap asset missing for icon "${iconId}" variant "${variant.resourceVariantId}"`);
+            }
+        }
+    }
+    if (errors.length > 0)
+        return { ok: false, errors };
+    return { ok: true, assets: [...chosen.values()], skipped };
+}

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

@@ -0,0 +1,43 @@
+export type InstallSource = {
+    readonly kind: "local";
+    readonly manager: "npm" | "pnpm" | "yarn";
+} | {
+    readonly kind: "global";
+    readonly manager: "npm" | "pnpm" | "yarn";
+} | {
+    readonly kind: "npx";
+} | {
+    readonly kind: "unknown";
+};
+export declare function detectInstallSource(input: {
+    env: Readonly<Record<string, string | undefined>>;
+    localManager?: "npm" | "pnpm" | "yarn";
+    localDependency?: boolean;
+}): InstallSource;
+export declare function fixedUpdateInstruction(source: InstallSource, version: string): string;
+export declare function planCliUpdate(currentVersion: string, versions: readonly string[], source: InstallSource): {
+    readonly status: "current" | "update" | "unavailable";
+    readonly currentVersion: string;
+    readonly latestVersion?: string;
+    readonly instruction?: string;
+};
+export interface CliUpdateFileSystem {
+    readonly existsSync: (path: string) => boolean;
+    readonly readFileSync: (path: string, encoding: "utf8") => string;
+}
+export declare function detectLocalInstall(cwd: string, fs: CliUpdateFileSystem): {
+    readonly localDependency: boolean;
+    readonly localManager?: "npm" | "pnpm" | "yarn";
+};
+/** Read-only update check. This module intentionally has no subprocess API. */
+export declare function runCliUpdateCheck(input: {
+    readonly currentVersion: string;
+    readonly cwd: string;
+    readonly env: Readonly<Record<string, string | undefined>>;
+    readonly fs: CliUpdateFileSystem;
+    readonly signal?: AbortSignal;
+    readonly timeoutMs?: number;
+    readonly fetchVersions?: () => Promise<readonly string[]>;
+}): Promise<ReturnType<typeof planCliUpdate> & {
+    readonly source: InstallSource;
+}>;

package/dist/core/cli-update.js

@@ -0,0 +1,71 @@
+import { fetchMoeiconsVersionsCached, latestInChannel } from "./version-service.js";
+import { decideUpdate } from "./update-policy.js";
+const CLI_PACKAGE = "@moewolf/moe-icons-cli";
+export function detectInstallSource(input) {
+    if (input.localDependency && input.localManager)
+        return { kind: "local", manager: input.localManager };
+    const agent = input.env.npm_config_user_agent ?? "";
+    const manager = agent.startsWith("pnpm/") ? "pnpm" : agent.startsWith("yarn/") ? "yarn" : "npm";
+    if (input.env.npm_command === "exec" || input.env.npm_lifecycle_event === "npx")
+        return { kind: "npx" };
+    if (input.env.npm_config_global === "true")
+        return { kind: "global", manager };
+    return { kind: "unknown" };
+}
+export function fixedUpdateInstruction(source, version) {
+    const spec = `${CLI_PACKAGE}@${version}`;
+    if (source.kind === "npx")
+        return `npx --yes ${spec}`;
+    if (source.kind === "unknown")
+        return `See https://moeicons.com/docs/cli-update for ${spec}`;
+    if (source.kind === "local") {
+        if (source.manager === "npm")
+            return `npm install --save-exact ${spec}`;
+        if (source.manager === "pnpm")
+            return `pnpm add --save-exact ${spec}`;
+        return `yarn add --exact ${spec}`;
+    }
+    if (source.manager === "npm")
+        return `npm install --global ${spec}`;
+    if (source.manager === "pnpm")
+        return `pnpm add --global --save-exact ${spec}`;
+    return `yarn global add --exact ${spec}`;
+}
+export function planCliUpdate(currentVersion, versions, source) {
+    const latest = latestInChannel(currentVersion, versions);
+    if (!latest)
+        return { status: "unavailable", currentVersion };
+    const decision = decideUpdate({ installedTier: "free", remoteTier: "free", installedVersion: currentVersion, remoteVersion: latest });
+    if (decision.kind !== "update")
+        return { status: "current", currentVersion, latestVersion: latest };
+    return { status: "update", currentVersion, latestVersion: latest, instruction: fixedUpdateInstruction(source, latest) };
+}
+export function detectLocalInstall(cwd, fs) {
+    let parsed = {};
+    try {
+        parsed = JSON.parse(fs.readFileSync(`${cwd}/package.json`, "utf8"));
+    }
+    catch {
+        return { localDependency: false };
+    }
+    const localDependency = typeof parsed.dependencies?.[CLI_PACKAGE] === "string" || typeof parsed.devDependencies?.[CLI_PACKAGE] === "string";
+    if (!localDependency)
+        return { localDependency: false };
+    if (fs.existsSync(`${cwd}/pnpm-lock.yaml`))
+        return { localDependency, localManager: "pnpm" };
+    if (fs.existsSync(`${cwd}/yarn.lock`))
+        return { localDependency, localManager: "yarn" };
+    if (fs.existsSync(`${cwd}/package-lock.json`))
+        return { localDependency, localManager: "npm" };
+    return { localDependency };
+}
+/** Read-only update check. This module intentionally has no subprocess API. */
+export async function runCliUpdateCheck(input) {
+    const local = detectLocalInstall(input.cwd, input.fs);
+    const source = detectInstallSource({ env: input.env, ...local });
+    const versions = await (input.fetchVersions ?? (() => fetchMoeiconsVersionsCached({
+        ...(input.signal ? { signal: input.signal } : {}),
+        ...(input.timeoutMs === undefined ? {} : { timeoutMs: input.timeoutMs }),
+    })))();
+    return { ...planCliUpdate(input.currentVersion, versions, source), source };
+}

package/dist/core/context.d.ts

@@ -0,0 +1,22 @@
+export interface UiChoice {
+    readonly value: string;
+    readonly label: string;
+}
+export interface CommandUi {
+    readonly select: (message: string, choices: readonly UiChoice[], signal: AbortSignal) => Promise<string | undefined>;
+    readonly confirm: (message: string, signal: AbortSignal) => Promise<boolean | undefined>;
+    readonly text: (message: string, signal: AbortSignal) => Promise<string | undefined>;
+    readonly note: (message: string, signal: AbortSignal) => void;
+    readonly progress: (message: string, signal: AbortSignal) => {
+        readonly update?: (message: string) => void;
+        readonly stop: (message?: string) => void;
+    };
+}
+/** Dependencies shared by command use cases; it deliberately contains no Node globals. */
+export interface CommandContext {
+    readonly ui: CommandUi;
+    readonly cwd: string;
+    readonly env: Readonly<Record<string, string | undefined>>;
+    readonly signal: AbortSignal;
+    readonly now: () => Date;
+}

package/dist/core/context.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,66 @@
+import { type DownloadLimits } from "../project/install.js";
+import { type ReleaseDescriptor } from "./release-descriptor.js";
+export declare const DESCRIPTOR_MAX_BYTES: number;
+export declare const ARTIFACT_MAX_BYTES: number;
+export declare const DOWNLOAD_TIMEOUT_MS = 30000;
+export declare const MAX_REDIRECTS = 5;
+export declare const DESCRIPTOR_NAME = "release-descriptor.json";
+export declare const DESCRIPTOR_SHA_NAME = "release-descriptor.json.sha256";
+export type FreeDownloadFailure = {
+    readonly ok: false;
+    readonly reason: "network";
+    readonly message: string;
+} | {
+    readonly ok: false;
+    readonly reason: "not-found";
+    readonly message: string;
+} | {
+    readonly ok: false;
+    readonly reason: "validation";
+    readonly message: string;
+} | {
+    readonly ok: false;
+    readonly reason: "checksum-mismatch";
+    readonly message: string;
+} | {
+    readonly ok: false;
+    readonly reason: "offline-no-cache";
+    readonly message: string;
+} | {
+    readonly ok: false;
+    readonly reason: "cancelled";
+    readonly message: string;
+};
+export type FreeDownloadSuccess = {
+    readonly ok: true;
+    readonly descriptor: ReleaseDescriptor;
+    readonly descriptorSha256: string;
+    readonly artifactBytes: Uint8Array;
+    readonly catalogJson: string;
+    readonly cacheHit: boolean;
+    readonly tag: string;
+};
+export type FreeDownloadResult = FreeDownloadSuccess | FreeDownloadFailure;
+export interface FreeDownloadIo {
+    readonly fetchFn: typeof fetch;
+    readonly readFileSync: (path: string) => Uint8Array;
+    readonly writeFileSync: (path: string, data: Uint8Array) => void;
+    readonly mkdirSync: (path: string) => void;
+    readonly existsSync: (path: string) => boolean;
+    readonly fixtureDir?: string;
+    /** Test-only loopback HTTP fixture root; production callers leave unset. */
+    readonly fixtureBaseUrl?: string;
+    readonly timeoutMs?: number;
+    readonly cacheDir: string;
+    readonly cliVersion: string;
+    readonly signal: AbortSignal;
+    readonly onProgress?: DownloadLimits["onProgress"];
+}
+export declare function artifactCachePath(cacheDir: string, fullVersion: string, sha256: string): string;
+/**
+ * Fetch descriptor sidecar → verify descriptor → download free.filename from
+ * the descriptor (never guessed) → verify archive + nested catalog checksums.
+ * Local `fixtureDir` stands in for a GitHub Release directory.
+ */
+export declare function downloadFreeRelease(io: FreeDownloadIo, sourceVersion: string): Promise<FreeDownloadResult>;
+export declare function bundledSourceVersion(): string;