@moewolf/moe-icons-cli 0.0.1 → 0.0.2

package/dist/cli.js

@@ -1,22 +1,36 @@
+import { safeMcpValue } from "./mcp/server.js";
+import { createProjectMcpServices } from "./mcp/services.js";
+import { assertDownloadSelection } from "./core/selected-resources.js";
 import { parseArgs, HELP_TEXT } from "./commands/parser.js";
 import { CliError, isCliError, jsonErrorBody } from "./errors/index.js";
 import { detectProject } from "./project/detect.js";
-import { readMoeiconsConfig } from "./project/config.js";
-import { mkdirSync, writeFileSync, readFileSync, existsSync, renameSync, rmSync, readdirSync, copyFileSync, } from "node:fs";
+import { readMoeiconsConfig, loadConfigDocument, validateConfigDocument, } from "./project/config.js";
+import { mkdirSync, writeFileSync, readFileSync, existsSync, renameSync, rmSync, readdirSync, copyFileSync, statfsSync, } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
-import { runInitUseCase } from "./core/init.js";
 import { runGenerateUseCase } from "./core/generate.js";
+import { recoverManagedReconcile, safeManagedPath } from "./project/install.js";
+import { withProjectLockSync } from "./project/project-lock.js";
 import { runInstallUseCase } from "./core/install.js";
-import { runWizardUseCase } from "./core/wizard.js";
+import { runWizardUseCase, loginRecoveryChoices } from "./core/wizard.js";
 import { createCommandUi } from "./ui/create-ui.js";
-import { CLI_VERSION, MOEICONS_BANNER, renderBannerText, renderNoticeBox } from "./ui/banner.js";
-import { runAccountUseCase, runLoginUseCase, runLogoutUseCase, runSessionStatusUseCase, } from "./core/auth.js";
+import { CLI_VERSION, MOEICONS_BANNER, renderNoticeBox, renderProjectNotice, renderWordmarkText, } from "./ui/banner.js";
+import { createTheme, isThemeEnabled } from "./ui/theme.js";
+import { renderHistoryBar } from "./tui/components.js";
+import { describeAuthEnvironment, runAccountUseCase, runLoginUseCase, runLogoutUseCase, runRemoteAccountUseCase, runSessionStatusUseCase, } from "./core/auth.js";
 import { formatLibraryVersionStatus, getLibraryVersionStatus } from "./core/manage.js";
 import { runCliUpdateCheck } from "./core/cli-update.js";
 import { fetchLibraryVersions } from "./core/version-service.js";
 import { runProInstallUseCase } from "./core/pro-install.js";
+import { resolveLocalTestContext } from "./core/local-test-env.js";
 import { runLibraryUpdateUseCase } from "./core/library-update.js";
+import { runMetadataSyncUseCase } from "./core/metadata-sync.js";
+import { runBootstrapUseCase } from "./core/bootstrap.js";
+import { fetchProDescriptor } from "./core/pro-download.js";
+import { proResourceState, runProPredownloadUseCase, runProResourceWarmupUseCase, } from "./core/pro-resources.js";
+import { formatBytes } from "./metadata/version.js";
+import { isLocalTestVersion } from "./core/release-descriptor.js";
+import { buildInitPlan, checkRequiresFix, collectSafeFixes, doctorJson, formatDoctorReport, formatPlannedDiffs, plannedDiffsJson, runDoctorApply, runDoctorDiagnose, } from "./core/doctor.js";
 function commandContext(runtime, flags) {
     const streams = runtime.readLine !== undefined && runtime.readKey !== undefined
         ? {
@@ -31,19 +45,64 @@ function commandContext(runtime, flags) {
             json: flags.json,
             yes: flags.yes,
             isTTY: runtime.isTTY(),
+            env: runtime.env,
             ...(streams ? { streams } : {}),
         }),
         cwd: runtime.cwd(),
         env: runtime.env,
-        signal: new AbortController().signal,
+        signal: runtime.signal ?? new AbortController().signal,
         now: () => new Date(),
     };
 }
+/**
+ * E2E-E3: allow a local candidate `X.Y.Z-test` to be installed by overriding
+ * the bundled catalog source version. Only honored when the process is pointed
+ * at a local release fixture (`MOEICONS_FREE_RELEASE_DIR`), never for the
+ * production GitHub/npm path.
+ */
+function localFixtureSourceVersion(env) {
+    const fixture = env.MOEICONS_FREE_RELEASE_DIR;
+    const override = env.MOEICONS_SOURCE_VERSION;
+    if (!fixture || !override)
+        return undefined;
+    if (!isLocalTestVersion(override)) {
+        throw new CliError("VALIDATION_ERROR", "MOEICONS_SOURCE_VERSION override is only allowed for local X.Y.Z-test candidates");
+    }
+    return override;
+}
+function freeDownloadDeps(runtime) {
+    return {
+        fetchFn: globalThis.fetch.bind(globalThis),
+        readFileSync: (path) => new Uint8Array(readFileSync(path)),
+        writeFileSync: (path, data) => writeFileSync(path, data),
+        mkdirSync: (path) => mkdirSync(path, { recursive: true }),
+        existsSync,
+        renameSync,
+        rmSync,
+        statfs: (dir) => {
+            try {
+                const stats = statfsSync(dir);
+                return { availableBytes: stats.bavail * stats.bsize };
+            }
+            catch {
+                return undefined;
+            }
+        },
+        ...(runtime.env.MOEICONS_FREE_RELEASE_DIR
+            ? { fixtureDir: runtime.env.MOEICONS_FREE_RELEASE_DIR }
+            : {}),
+        cacheDir: runtime.env.MOEICONS_CACHE_DIR ?? join(homedir(), ".moeicons", "cache"),
+        cliVersion: versionString(),
+    };
+}
 export { MOEICONS_BANNER };
 export const BANNER = MOEICONS_BANNER;
-/** Banner rendered as plain ASCII (fallback for narrow terminals). */
+/** Wordmark rendered for interactive wizard startup (notices come later). */
 export function renderBanner(runtime) {
-    runtime.stdout(renderBannerText());
+    runtime.stdout(`${renderWordmarkText({
+        columns: runtime.columns?.() ?? 80,
+        color: createTheme(isThemeEnabled(runtime.env, runtime.isTTY())).enabled,
+    })}\n`);
 }
 function argvRequestsJson(argv) {
     return argv.includes("--json");
@@ -53,6 +112,13 @@ function writeJson(runtime, value) {
 }
 function reportFailure(runtime, json, error) {
     if (isCliError(error)) {
+        if (error.code === "CANCELLED") {
+            if (json)
+                writeJson(runtime, jsonErrorBody(error.code, error.message));
+            else
+                runtime.stderr("Cancelled\n");
+            return 0;
+        }
         if (json)
             writeJson(runtime, jsonErrorBody(error.code, error.message));
         else
@@ -83,6 +149,31 @@ export async function main(argv, runtime) {
         return reportFailure(runtime, parsed.json, error);
     }
 }
+async function runBootstrap(runtime) {
+    const context = commandContext(runtime, { json: false, yes: false });
+    try {
+        const result = await runBootstrapUseCase(context, {
+            fs: {
+                existsSync,
+                readFileSync: (path) => readFileSync(path, "utf8"),
+                writeFileSync: (path, content) => writeFileSync(path, content),
+                mkdirSync: (path) => mkdirSync(path, { recursive: true }),
+            },
+            installFs: { mkdirSync, writeFileSync, existsSync, renameSync, rmSync },
+            free: freeDownloadDeps(runtime),
+            cliVersion: versionString(),
+        });
+        if (result.kind === "installed") {
+            runtime.stdout(`Installed moeicons Free v${result.version} with metadata into the current project.\n`);
+        }
+        else if (result.kind === "failed") {
+            runtime.stderr(`warning: automatic Free setup failed: ${result.message}\nRun: ${result.retry}\n`);
+        }
+    }
+    catch {
+        // Bootstrap must never block the wizard.
+    }
+}
 async function dispatchSync(command, runtime, json, yes, noTailwind, target) {
     switch (command.name) {
         case "version":
@@ -97,45 +188,254 @@ async function dispatchSync(command, runtime, json, yes, noTailwind, target) {
         case "wizard":
             return await runWizard(runtime, json, yes);
         case "install":
-            return await runInstall(command.group, runtime, json, noTailwind, undefined, undefined, command.target);
+            return await runInstall(command.group, runtime, json, noTailwind, localFixtureSourceVersion(runtime.env), undefined, command.target);
         case "login":
             return await runLogin(runtime, json, yes);
         case "logout":
-            return await runLogout(runtime, json);
+            return await runLogout(runtime, json, yes);
         case "account":
             return await runAccount(runtime, json);
         case "groups":
             throw new CliError("NOT_IMPLEMENTED", "groups is not implemented yet");
         case "generate":
             return await runGenerate(runtime, json, noTailwind, false, target, yes);
+        case "recover": {
+            const root = runtime.cwd();
+            safeManagedPath(root, ".moeicons");
+            const recovered = withProjectLockSync(root, "recover", () => recoverManagedReconcile(root, {
+                mkdirSync,
+                writeFileSync,
+                readFileSync,
+                existsSync,
+                renameSync,
+                rmSync,
+                readdirSync,
+                copyFileSync,
+            }));
+            if (json)
+                writeJson(runtime, { ok: true, recovered });
+            else
+                runtime.stdout(`Recovered ${recovered} interrupted transaction(s). Rerun the original command.\n`);
+            return 0;
+        }
         case "init":
-            return runInit(runtime, json, target);
+            return await runInit(runtime, json, yes, command.dryRun === true, target);
+        case "doctor":
+            return runDoctor(runtime, json, command.check === true, command.dryRun === true);
         case "mcp":
-            void runMcp(runtime);
+            await runMcp(runtime);
             return 0;
+        case "update":
+            return await runUpdate(runtime, json, yes, command.metadata === true);
     }
 }
 async function runLogin(runtime, json, yes) {
-    const session = await runLoginUseCase(commandContext(runtime, { json, yes }), {
+    const context = commandContext(runtime, { json, yes });
+    const environment = describeAuthEnvironment(context);
+    const session = await runLoginUseCase(context, {
         ...runtime.auth,
         fileFallbackAllowed: runtime.isTTY(),
     });
     if (json)
-        writeJson(runtime, { ok: true, account: session });
+        writeJson(runtime, { ok: true, environment, account: session });
     else
-        runtime.stdout(`Logged in as ${session.accountId}\n`);
+        runtime.stdout(`Environment: ${environment}\nLogged in as ${session.accountId}\n`);
+    if (!json && runtime.isTTY())
+        await offerProPredownload(runtime);
     return 0;
 }
+/**
+ * After a successful interactive login, offer to pre-download the full Pro
+ * code + metadata. Cancelling or a failed probe never logs the user out.
+ */
+async function offerProPredownload(runtime) {
+    const context = commandContext(runtime, { json: false, yes: false });
+    try {
+        const versions = await fetchLibraryVersions({
+            ...(runtime.auth?.fetch ? { fetch: runtime.auth.fetch } : {}),
+            signal: context.signal,
+            env: runtime.env,
+        });
+        if (!versions.pro) {
+            runtime.stdout("No Pro release is published yet.\n");
+            return;
+        }
+        const descriptor = await fetchProDescriptor(context, runtime.auth ?? {}, { version: versions.pro.version, descriptorSha256: versions.pro.descriptorSha256 }, runtime.auth?.fetch ? { fetch: runtime.auth.fetch } : {});
+        const sizes = `${formatBytes(descriptor.size)} code + ${descriptor.metadata ? formatBytes(descriptor.metadata.size) : "0 B"} metadata`;
+        runtime.stdout(`Pro ${versions.pro.version} available (${sizes}).\n`);
+        const accepted = await context.ui.confirm("Download Pro resources now? (code + metadata)", context.signal);
+        if (accepted !== true) {
+            runtime.stdout("Skipped Pro download; you can download it later from the home screen.\n");
+            return;
+        }
+        const progress = startResourceProgress(context, "Downloading Pro resources");
+        try {
+            const result = await runProPredownloadUseCase(context, runtime.auth ?? {}, {
+                ...(runtime.auth?.fetch ? { fetch: runtime.auth.fetch } : {}),
+                onProgress: ({ downloadedBytes, totalBytes }) => progress.bytes({ downloadedBytes, ...(totalBytes !== undefined ? { totalBytes } : {}) }),
+            });
+            const warmed = await warmProBitmapShards(runtime, result, runtime.auth?.fetch ? { fetch: runtime.auth.fetch } : {}, progress);
+            progress.stop("Pro resources downloaded");
+            runtime.stdout(`Cached Pro ${result.version} code + metadata.\n`);
+            if (warmed)
+                runtime.stdout(`${warmed}\n`);
+        }
+        catch (error) {
+            progress.stop("Pro download stopped");
+            runtime.stderr(`warning: Pro download failed (${error instanceof Error ? error.message : String(error)}). You can retry from the home screen.\n`);
+        }
+    }
+    catch {
+        // A failed probe must not make login fail.
+    }
+}
+/**
+ * W3-A: normalize the optional progress-bar surface. Falls back to the legacy
+ * line-oriented `progress` port for adapters that do not render a bar.
+ */
+function startResourceProgress(context, label) {
+    const bar = context.ui.progressBar?.(label, context.signal);
+    if (bar) {
+        return {
+            bytes: (event) => bar.update({
+                done: event.downloadedBytes,
+                ...(event.totalBytes !== undefined ? { total: event.totalBytes } : {}),
+                ...(event.detail !== undefined ? { detail: event.detail } : {}),
+            }),
+            phase: (detail) => bar.update({ detail }),
+            stop: (message) => bar.stop(message),
+        };
+    }
+    const legacy = context.ui.progress(label, context.signal);
+    return {
+        bytes: (event) => legacy.update?.(`Downloaded ${event.downloadedBytes} bytes${event.totalBytes ? ` of ${event.totalBytes}` : ""}${event.detail ? ` (${event.detail})` : ""}`),
+        phase: (detail) => legacy.update?.(detail),
+        stop: (message) => legacy.stop(message),
+    };
+}
+/**
+ * W2-A: best-effort warm-up of the default bitmap shard set after the Pro code
+ * and metadata are cached. Never fails the surrounding download.
+ */
+async function warmProBitmapShards(runtime, result, fetchDeps, progress) {
+    if (!result.metadataSha256)
+        return undefined;
+    try {
+        const warm = await runProResourceWarmupUseCase(commandContext(runtime, { json: false, yes: false }), runtime.auth ?? {}, {
+            version: result.version,
+            descriptorSha256: result.descriptorSha256,
+            metadataSha256: result.metadataSha256,
+            catalogSha256: result.catalogSha256,
+            ...fetchDeps,
+            onPlan: (plan) => progress.phase(`Default bitmap shards: ${plan.missing.length} to download, ${plan.reused} cached`),
+            onProgress: (event) => progress.phase(`Shard ${event.index}/${event.total} ${event.phase} — ${event.tuple.styleGroupId} ${event.tuple.imageSize.width}x${event.tuple.imageSize.height} ${event.tuple.format}`),
+        });
+        return `Warmed ${warm.shards} default bitmap shards (${warm.downloaded} downloaded, ${warm.reused} cached).`;
+    }
+    catch (error) {
+        runtime.stderr(`warning: default bitmap shard warm-up skipped (${error instanceof Error ? error.message : String(error)}).\n`);
+        return undefined;
+    }
+}
+/**
+ * Home-screen Pro resources flow: show the current cache state and drive the
+ * matching action (download / update / repair / verify). Requires auth.
+ */
+async function runProResources(runtime, yes) {
+    const context = commandContext(runtime, { json: false, yes });
+    const fetchDeps = runtime.auth?.fetch ? { fetch: runtime.auth.fetch } : {};
+    const state = await proResourceState(context, runtime.auth ?? {}, fetchDeps);
+    if (state.kind === "unavailable") {
+        runtime.stdout(`Pro resources unavailable: ${state.reason}\n`);
+        return 0;
+    }
+    let action = "";
+    if (state.kind === "current") {
+        runtime.stdout(`Pro resources are up to date (v${state.version}).\n`);
+        return 0;
+    }
+    if (state.kind === "not-cached") {
+        runtime.stdout(`Pro ${state.version}: ${formatBytes(state.codeBytes)} code + ${formatBytes(state.metadataBytes)} metadata.\n`);
+        action = "Download";
+    }
+    else if (state.kind === "outdated") {
+        runtime.stdout(`Pro ${state.version} → ${state.latestVersion}: ${formatBytes(state.codeBytes)} code + ${formatBytes(state.metadataBytes)} metadata.\n`);
+        action = "Update";
+    }
+    else {
+        runtime.stdout(`Pro ${state.version} cache is corrupt; re-downloading.\n`);
+        action = "Repair";
+    }
+    const confirmed = await context.ui.confirm(`${action} Pro resources now? (code + metadata)`, context.signal);
+    if (confirmed !== true) {
+        runtime.stdout("Cancelled; Pro resources were not downloaded.\n");
+        return 0;
+    }
+    const progress = startResourceProgress(context, "Downloading Pro resources");
+    try {
+        const result = await runProPredownloadUseCase(context, runtime.auth ?? {}, {
+            ...fetchDeps,
+            force: state.kind === "corrupt",
+            onProgress: ({ downloadedBytes, totalBytes }) => progress.bytes({ downloadedBytes, ...(totalBytes !== undefined ? { totalBytes } : {}) }),
+        });
+        const warmed = await warmProBitmapShards(runtime, result, fetchDeps, progress);
+        progress.stop("Pro resources downloaded");
+        runtime.stdout(`Cached Pro ${result.version} code + metadata.\n`);
+        if (warmed)
+            runtime.stdout(`${warmed}\n`);
+        return 0;
+    }
+    catch (error) {
+        progress.stop("Pro download stopped");
+        if (error instanceof CliError && (error.code === "FORBIDDEN" || error.code === "AUTH_ERROR")) {
+            throw error;
+        }
+        runtime.stderr(`warning: Pro download failed (${error instanceof Error ? error.message : String(error)}). Retry from this menu.\n`);
+        return 0;
+    }
+}
 async function runAccount(runtime, json) {
-    const session = await runAccountUseCase(commandContext(runtime, { json, yes: false }), runtime.auth);
+    const context = commandContext(runtime, { json, yes: false });
+    const environment = describeAuthEnvironment(context);
+    const session = await runAccountUseCase(context, runtime.auth);
+    // H6/account: never silently report success when the Worker entitlement
+    // lookup failed. JSON/automation fails non-zero; interactive mode says so.
+    let remote;
+    let remoteError;
+    try {
+        remote = await runRemoteAccountUseCase(commandContext(runtime, { json, yes: false }), {
+            ...runtime.auth,
+            fetch: runtime.auth?.fetch ?? globalThis.fetch.bind(globalThis),
+        });
+    }
+    catch (error) {
+        remoteError = error;
+    }
+    if (json && remoteError)
+        throw remoteError;
+    const account = { ...session, ...(remote ?? {}) };
     if (json)
-        writeJson(runtime, { ok: true, account: session });
-    else
-        runtime.stdout(`Account: ${session.accountId}\nSession expires: ${new Date(session.expiresAt).toISOString()}\n`);
+        writeJson(runtime, { ok: true, environment, account });
+    else {
+        runtime.stdout(`Environment: ${environment}\nAccount: ${account.accountId}\nSession expires: ${new Date(account.expiresAt).toISOString()}\n`);
+        if (remote)
+            runtime.stdout(`Tier: ${account.tier}\nEntitlement: ${account.entitlementStatus}\n`);
+        else
+            runtime.stdout("Remote account: unavailable\n");
+    }
     return 0;
 }
-async function runLogout(runtime, json) {
-    const result = await runLogoutUseCase(commandContext(runtime, { json, yes: false }), runtime.auth);
+async function runLogout(runtime, json, yes) {
+    const context = commandContext(runtime, { json, yes });
+    // H3: interactive logout is explicit; declining leaves credentials intact.
+    if (!json && !yes && runtime.isTTY()) {
+        const confirmed = await context.ui.confirm("Log out and revoke the current session?", context.signal);
+        if (confirmed !== true) {
+            runtime.stdout("Cancelled; you are still logged in.\n");
+            return 0;
+        }
+    }
+    const result = await runLogoutUseCase(context, runtime.auth);
     if (json)
         writeJson(runtime, { ok: true, ...result });
     else
@@ -144,42 +444,126 @@ async function runLogout(runtime, json) {
             : "Logged out locally; remote revocation was not confirmed.\n");
     return 0;
 }
-/** Create moeicons.config.jsonc if absent (never overwrites an existing config). */
-function runInit(runtime, json, target) {
-    const result = runInitUseCase(commandContext(runtime, { json, yes: false }), { mkdirSync, writeFileSync, existsSync, renameSync, rmSync }, target);
-    if (!result.ok && result.reason === "exists") {
+/**
+ * Four-anchor init (E2E-B5): diagnose → plan → confirm/--yes → transactional apply.
+ * `--dry-run` never writes. Non-TTY / `--json` requires `--yes` to write.
+ */
+async function runInit(runtime, json, yes, dryRun = false, target) {
+    const { outcome } = buildInitPlan(runtime.cwd(), target);
+    const { report } = outcome;
+    const fixes = collectSafeFixes(outcome);
+    const manifest = report.anchors.find((a) => a.kind === "manifest");
+    if (!manifest || manifest.status === "missing" || manifest.status === "invalid") {
+        throw new CliError("VALIDATION_ERROR", "no project found");
+    }
+    if (dryRun) {
+        if (json) {
+            writeJson(runtime, {
+                ...doctorJson(report),
+                mode: "dry-run",
+                diffs: plannedDiffsJson(fixes),
+            });
+        }
+        else {
+            runtime.stdout(`${formatDoctorReport(report)}\n`);
+            const diffs = formatPlannedDiffs(fixes);
+            if (diffs)
+                runtime.stdout(`${diffs}\n`);
+        }
+        return 0;
+    }
+    if (fixes.length === 0) {
+        if (report.anchors.some((anchor) => anchor.status === "ambiguous"))
+            throw new CliError("VALIDATION_ERROR", "select --target before initializing this project");
         if (json)
-            writeJson(runtime, { ok: true, alreadyExisted: true });
+            writeJson(runtime, { ok: true, alreadyConfigured: true, ...doctorJson(report) });
         else
-            runtime.stdout("moeicons.config.jsonc already exists; not overwritten.\n");
+            runtime.stdout("already configured\n");
         return 0;
     }
-    if (!result.ok) {
-        throw new CliError("VALIDATION_ERROR", result.reason === "no-project" ? "no project found" : "init failed");
+    if (!json) {
+        runtime.stdout(`${formatDoctorReport(report)}\n`);
+        const diffs = formatPlannedDiffs(fixes);
+        if (diffs)
+            runtime.stdout(`${diffs}\n`);
+    }
+    const context = commandContext(runtime, { json, yes });
+    const confirmed = await context.ui.confirm(`Apply ${fixes.length} planned change(s)?`, context.signal);
+    if (confirmed !== true) {
+        if (json)
+            writeJson(runtime, { ok: true, cancelled: true });
+        else
+            runtime.stdout("Cancelled; no files written.\n");
+        return 0;
+    }
+    const result = runDoctorApply(runtime.cwd(), fixes);
+    if (result.ok === false) {
+        throw new CliError("UNEXPECTED", result.message);
+    }
+    if (result.alreadyConfigured) {
+        if (json)
+            writeJson(runtime, { ok: true, alreadyConfigured: true, written: [] });
+        else
+            runtime.stdout("already configured\n");
+        return 0;
     }
     if (json)
-        writeJson(runtime, { ok: true, created: result.created });
+        writeJson(runtime, { ok: true, written: result.written ?? [] });
     else
-        runtime.stdout(`Created ${result.created}\n`);
+        runtime.stdout(`Applied ${(result.written ?? []).join(", ")}\n`);
     return 0;
 }
+/** Read-only four-anchor diagnosis command (`doctor`). */
+function runDoctor(runtime, json, check, dryRun) {
+    const { report } = runDoctorDiagnose(runtime.cwd());
+    void dryRun; // doctor is always read-only; --dry-run is accepted for parity
+    if (json)
+        writeJson(runtime, doctorJson(report));
+    else
+        runtime.stdout(formatDoctorReport(report));
+    return check ? (checkRequiresFix(report) ? 1 : 0) : 0;
+}
 /** Start the MCP stdio server; protocol data to stdout, logs to stderr. */
+/**
+ * AUD-CL-01: the MCP surface exposes no single style-group install. It fails
+ * closed with guidance rather than reporting a fake success.
+ */
+export function createMcpServices(runtime) {
+    return createProjectMcpServices(runtime, async (argv) => {
+        let output = "";
+        const status = await main(argv, { ...runtime, isTTY: () => false, stdout: (text) => { output += text; }, stderr: (text) => runtime.stderr(String(safeMcpValue(text)).split(runtime.cwd()).join(".")) });
+        try {
+            return JSON.parse(output);
+        }
+        catch {
+            return { ok: false, code: "COMMAND_FAILED", message: `command returned ${status} without a JSON result` };
+        }
+    });
+}
 async function runMcp(runtime) {
     const { runMcpStdio } = await import("./mcp/server.js");
+    if (runtime.mcpLines) {
+        await runMcpStdio({ services: createMcpServices(runtime), projectRoot: runtime.cwd(), stdout: runtime.stdout, stderr: runtime.stderr, lines: runtime.mcpLines, ...(runtime.signal ? { signal: runtime.signal } : {}) });
+        return;
+    }
     const readline = await import("node:readline");
-    const services = {
-        listIconGroups: () => Promise.resolve([
-            { id: "free", displayName: "Free icons" },
-            { id: "pro", displayName: "Pro icons" },
-        ]),
-        getAccount: () => Promise.resolve(undefined),
-        installIconGroup: (args) => {
-            runtime.stderr(`installing ${args.groupId} into ${args.projectPath} (stub)\n`);
-            return Promise.resolve({ ok: true, message: `installed ${args.groupId}` });
-        },
-    };
+    const controller = new AbortController();
+    const services = createMcpServices({ ...runtime, signal: controller.signal });
     const rl = readline.createInterface({ input: process.stdin });
-    await runMcpStdio({ services, stdout: runtime.stdout, stderr: runtime.stderr, lines: rl });
+    const stop = () => { controller.abort(); rl.close(); };
+    const eof = () => controller.abort();
+    process.once("SIGINT", stop);
+    process.once("SIGTERM", stop);
+    rl.once("close", eof);
+    try {
+        await runMcpStdio({ services, projectRoot: runtime.cwd(), stdout: runtime.stdout, stderr: runtime.stderr, lines: rl, signal: controller.signal });
+    }
+    finally {
+        process.removeListener("SIGINT", stop);
+        process.removeListener("SIGTERM", stop);
+        rl.removeListener("close", eof);
+        rl.close();
+    }
 }
 function versionString() {
     return CLI_VERSION;
@@ -197,7 +581,15 @@ function renderCliUpdateNotice(update) {
 }
 /** Guided flow: Free / Pro / Login, with project-root confirmation before write. */
 async function runWizard(runtime, json, yes) {
-    if (!json && runtime.isTTY()) {
+    if (json) {
+        const context = commandContext(runtime, { json, yes });
+        const result = await runWizardUseCase(context, { json: true });
+        if (result.ok && result.action === "json-hint") {
+            writeJson(runtime, { ok: true, message: result.message });
+        }
+        return 0;
+    }
+    if (runtime.isTTY()) {
         renderBanner(runtime);
         runtime.stdout(`CLI ${versionString()}\n`);
         try {
@@ -212,14 +604,15 @@ async function runWizard(runtime, json, yes) {
             runtime.stdout(`${renderCliUpdateNotice(update)}\n`);
         }
         catch {
-            runtime.stdout(`${renderNoticeBox(["Moeicons CLI version status", `Current ${versionString()} / Latest unavailable / Update: unavailable`])}\n`);
+            runtime.stdout(`${renderNoticeBox([
+                "Moeicons CLI version status",
+                `Current ${versionString()} / Latest unavailable / Update: unavailable`,
+            ])}\n`);
         }
+        runtime.stdout(`${renderProjectNotice(runtime.columns?.() ?? 80)}\n`);
+        if (runtime.readLine === undefined)
+            await runBootstrap(runtime);
     }
-    const context = commandContext(runtime, { json, yes });
-    const session = await runSessionStatusUseCase(context, runtime.auth).catch((error) => ({
-        kind: "unknown",
-        reason: error instanceof Error ? error.message : "session status unavailable",
-    }));
     const getStatus = async () => {
         const project = detectProject(runtime.cwd());
         if (!project)
@@ -229,70 +622,180 @@ async function runWizard(runtime, json, yes) {
             return `Current: invalid / Latest: unavailable / Status: config ${config.kind}`;
         return formatLibraryVersionStatus(await getLibraryVersionStatus(project.root, config.config.tier));
     };
-    const result = await runWizardUseCase(context, {
-        json,
-        session: session.kind,
-        getLibraryStatus: getStatus,
-    });
-    if (result.ok && result.action === "json-hint") {
-        writeJson(runtime, { ok: true, message: result.message });
-        return 0;
-    }
-    if (!result.ok) {
-        throw new CliError("CANCELLED", "cancelled");
-    }
-    if (result.action === "install") {
-        const project = detectProject(runtime.cwd());
-        if (project)
-            runtime.stdout(`Project root: ${project.root}\n`);
-        return await runInstall(result.group, runtime, false, false, undefined, undefined, result.target);
-    }
-    if (result.action === "settings") {
-        if (result.flow === "logout")
-            return runLogout(runtime, false);
-        const update = await runCliUpdateCheck({
-            currentVersion: versionString(),
-            cwd: runtime.cwd(),
-            env: runtime.env,
-            fs: { existsSync, readFileSync: (path) => readFileSync(path, "utf8") },
-            signal: context.signal,
-            timeoutMs: 1_000,
-            ...(runtime.fetchVersions ? { fetchVersions: runtime.fetchVersions } : {}),
-        }).catch(() => undefined);
-        if (!update) {
-            runtime.stdout(`${renderNoticeBox(["Moeicons CLI version status", `Current ${versionString()} / Latest unavailable / Update: unavailable`])}\n`);
+    // W3-E2: single-line preview of the most recent task, colour-coded by state.
+    const theme = createTheme(isThemeEnabled(runtime.env, runtime.isTTY()));
+    let lastTask;
+    // Single-level loop: never recurse runWizard; banner/bootstrap once per process.
+    for (;;) {
+        const context = commandContext(runtime, { json: false, yes });
+        const session = await runSessionStatusUseCase(context, runtime.auth).catch((error) => ({
+            kind: "unknown",
+            reason: error instanceof Error ? error.message : "session status unavailable",
+        }));
+        const historyLine = renderHistoryBar(lastTask, theme);
+        const result = await runWizardUseCase(context, {
+            json: false,
+            session: session.kind,
+            ...(historyLine ? { historyLine } : {}),
+            getLibraryStatus: getStatus,
+            getProResourceLabel: async () => {
+                if (session.kind !== "authenticated")
+                    return undefined;
+                const state = await proResourceState(context, runtime.auth ?? {}, {
+                    ...(runtime.auth?.fetch ? { fetch: runtime.auth.fetch } : {}),
+                }).catch(() => undefined);
+                if (!state || state.kind === "unavailable")
+                    return undefined;
+                if (state.kind === "not-cached")
+                    return "Download Pro resources";
+                if (state.kind === "outdated")
+                    return `Update Pro resources (${state.version} → ${state.latestVersion})`;
+                if (state.kind === "corrupt")
+                    return "Repair Pro resources";
+                return "Pro resources are up to date";
+            },
+        });
+        if (!result.ok) {
+            // Select/confirm cancel frames already render "■ Cancelled"; do not duplicate.
             return 0;
         }
-        if (update.status === "update")
-            runtime.stdout(`CLI ${update.currentVersion} → ${update.latestVersion}\nRun: ${update.instruction}\n`);
-        else if (update.status === "current")
-            runtime.stdout(`CLI ${update.currentVersion} is up to date.\n`);
-        else
-            runtime.stdout(`Unable to find a CLI release in the current channel.\n`);
+        if (result.action === "exit") {
+            if (result.via === "menu")
+                runtime.stdout("Exited\n");
+            return 0;
+        }
+        if (result.action === "back")
+            continue;
+        if (result.action === "pro-resources") {
+            const code = await runProResources(runtime, yes);
+            lastTask = {
+                label: "Pro resources",
+                state: code === 0 ? "success" : "failure",
+            };
+            continue;
+        }
+        if (result.action === "install") {
+            const project = detectProject(runtime.cwd());
+            if (project)
+                runtime.stdout(`Project root: ${project.root}\n`);
+            // W3-E1: never leave the user stuck at the end of a task; return to the
+            // home menu (with the history bar) instead of exiting.
+            const code = await runInstall(result.group, runtime, false, false, undefined, undefined, result.target);
+            lastTask = {
+                label: `Install ${result.group} (${result.target})`,
+                state: code === 0 ? "success" : "failure",
+            };
+            continue;
+        }
+        if (result.action === "settings") {
+            if (result.flow === "logout") {
+                await runLogout(runtime, false, true);
+                continue;
+            }
+            const update = await runCliUpdateCheck({
+                currentVersion: versionString(),
+                cwd: runtime.cwd(),
+                env: runtime.env,
+                fs: { existsSync, readFileSync: (path) => readFileSync(path, "utf8") },
+                signal: context.signal,
+                timeoutMs: 1_000,
+                ...(runtime.fetchVersions ? { fetchVersions: runtime.fetchVersions } : {}),
+            }).catch(() => undefined);
+            if (!update) {
+                runtime.stdout(`${renderNoticeBox([
+                    "Moeicons CLI version status",
+                    `Current ${versionString()} / Latest unavailable / Update: unavailable`,
+                ])}\n`);
+            }
+            else if (update.status === "update") {
+                runtime.stdout(`CLI ${update.currentVersion} → ${update.latestVersion}\nRun: ${update.instruction}\n`);
+            }
+            else if (update.status === "current") {
+                runtime.stdout(`CLI ${update.currentVersion} is up to date.\n`);
+            }
+            else {
+                runtime.stdout(`Unable to find a CLI release in the current channel.\n`);
+            }
+            continue;
+        }
+        if (result.action === "manage") {
+            if (result.flow === "reload") {
+                const code = await runGenerate(runtime, false, false, true, undefined, yes);
+                lastTask = { label: "Update project resources", state: code === 0 ? "success" : "failure" };
+                continue;
+            }
+            const project = detectProject(runtime.cwd());
+            if (!project)
+                throw new CliError("VALIDATION_ERROR", "no project found");
+            const config = readMoeiconsConfig(project.root);
+            if (config.kind !== "ok")
+                throw new CliError("VALIDATION_ERROR", `config ${config.kind}`);
+            assertDownloadSelection(config.config);
+            const status = await getLibraryVersionStatus(project.root, config.config.tier);
+            runtime.stdout(`${formatLibraryVersionStatus(status)}\n`);
+            if (status.kind === "update") {
+                const code = await runLibraryUpdate(runtime, status.metadata.tier, status.latestVersion, status.latestDescriptorSha256);
+                lastTask = { label: "Update icon library", state: code === 0 ? "success" : "failure" };
+            }
+            else {
+                lastTask = { label: "Update icon library", state: "success", detail: "already current" };
+            }
+            continue;
+        }
+        if (result.action === "pending" && result.flow === "login") {
+            const loginOutcome = await runWizardLogin(runtime, yes);
+            if (loginOutcome === "exit")
+                return 0;
+            lastTask = { label: "Login", state: loginOutcome === "home" ? "success" : "failure" };
+            continue;
+        }
         return 0;
     }
-    if (result.action === "manage") {
-        if (result.flow === "reload")
-            return await runGenerate(runtime, false, false, true, undefined, yes);
-        const project = detectProject(runtime.cwd());
-        if (!project)
-            throw new CliError("VALIDATION_ERROR", "no project found");
-        const config = readMoeiconsConfig(project.root);
-        if (config.kind !== "ok")
-            throw new CliError("VALIDATION_ERROR", `config ${config.kind}`);
-        const status = await getLibraryVersionStatus(project.root, config.config.tier);
-        runtime.stdout(`${formatLibraryVersionStatus(status)}\n`);
-        if (status.kind !== "update")
-            return 0;
-        return runLibraryUpdate(runtime, status.metadata.tier, status.latestVersion, status.latestDescriptorSha256);
+}
+/**
+ * Wizard-local login with Retry/Back. Explicit `moeicons login` still uses runLogin.
+ * Returns "home" to resume the wizard loop, or "exit" on cancel/Ctrl+C.
+ */
+async function runWizardLogin(runtime, yes) {
+    for (;;) {
+        try {
+            const code = await runLogin(runtime, false, yes);
+            if (code !== 0) {
+                // runLogin only returns non-zero via thrown errors normally; keep home on soft failure.
+                return "home";
+            }
+            return "home";
+        }
+        catch (error) {
+            if (isCliError(error) && error.code === "CANCELLED") {
+                runtime.stderr("Cancelled\n");
+                return "exit";
+            }
+            const message = isCliError(error)
+                ? error.message
+                : error instanceof Error
+                    ? error.message
+                    : String(error);
+            runtime.stderr(`Login failed: ${message}\n`);
+            const context = commandContext(runtime, { json: false, yes });
+            const choice = await context.ui.select("Login", loginRecoveryChoices(), context.signal);
+            if (choice === undefined) {
+                // Select cancel frame already rendered "■ Cancelled"; do not duplicate.
+                return "exit";
+            }
+            if (choice === "back")
+                return "home";
+            // retry → loop with a fresh session
+        }
     }
-    if (result.flow === "login")
-        return runLogin(runtime, false, yes);
-    return 0;
 }
-async function runLibraryUpdate(runtime, tier, version, descriptorSha256) {
-    const context = commandContext(runtime, { json: false, yes: false });
-    const progress = context.ui.progress("Downloading icon library update", context.signal);
+async function runLibraryUpdate(runtime, tier, version, descriptorSha256, json = false) {
+    const context = commandContext(runtime, { json, yes: false });
+    // W3-A: a single progress surface. `task` is deliberately NOT used here: the
+    // clack adapter implements both with `p.spinner()`, so stacking them would
+    // drive two concurrent spinners over stdout. The bar's stop message already
+    // carries the success/failure status.
+    const progress = startResourceProgress(context, "Downloading icon library update");
     try {
         const result = await runLibraryUpdateUseCase(context, {
             fs: {
@@ -305,24 +808,20 @@ async function runLibraryUpdate(runtime, tier, version, descriptorSha256) {
                 readdirSync,
                 copyFileSync,
             },
-            free: {
-                fetchFn: globalThis.fetch.bind(globalThis),
-                readFileSync: (path) => new Uint8Array(readFileSync(path)),
-                writeFileSync: (path, data) => writeFileSync(path, data),
-                mkdirSync: (path) => mkdirSync(path, { recursive: true }),
-                existsSync,
-                ...(runtime.env.MOEICONS_FREE_RELEASE_DIR
-                    ? { fixtureDir: runtime.env.MOEICONS_FREE_RELEASE_DIR }
-                    : {}),
-                cacheDir: runtime.env.MOEICONS_CACHE_DIR ?? join(homedir(), ".moeicons", "cache"),
-                cliVersion: versionString(),
-            },
+            free: freeDownloadDeps(runtime),
             auth: runtime.auth ?? {},
             fetch: runtime.auth?.fetch ?? globalThis.fetch.bind(globalThis),
-            onProgress: ({ downloadedBytes, totalBytes }) => progress.update?.(`Downloaded ${downloadedBytes} bytes${totalBytes ? ` of ${totalBytes}` : ""}`),
+            onProgress: ({ downloadedBytes, totalBytes }) => progress.bytes({ downloadedBytes, ...(totalBytes !== undefined ? { totalBytes } : {}) }),
         }, { tier, version, descriptorSha256 });
         progress.stop("Icon library update complete");
-        runtime.stdout(`Updated ${tier} artifact to ${result.artifactVersion}; reconciled ${result.files.length} generated files.\n`);
+        if (json)
+            writeJson(runtime, { ok: true, ...result });
+        else {
+            runtime.stdout(`Updated ${tier} artifact to ${result.artifactVersion}; reconciled ${result.files.length} generated files.\n`);
+            runtime.stdout(`Download mode: ${result.downloadMode}${result.selectedFiles !== undefined ? `; ${result.selectedFiles} resource files; ${result.networkBytes} resource bytes received` : ""}.\n`);
+            for (const note of result.downloadNotes)
+                runtime.stdout(`${note}\n`);
+        }
         return 0;
     }
     catch (error) {
@@ -330,15 +829,104 @@ async function runLibraryUpdate(runtime, tier, version, descriptorSha256) {
         throw error;
     }
 }
+/**
+ * `update` command: `update metadata` syncs only the small metadata archive for
+ * the installed version; `update` performs a full code + metadata update.
+ */
+async function runUpdate(runtime, json, yes, metadataOnly) {
+    const context = commandContext(runtime, { json, yes });
+    if (metadataOnly) {
+        try {
+            const result = await runMetadataSyncUseCase(context, {
+                fs: {
+                    mkdirSync,
+                    writeFileSync,
+                    readFileSync,
+                    existsSync,
+                    renameSync,
+                    rmSync,
+                    readdirSync,
+                    copyFileSync,
+                },
+                free: freeDownloadDeps(runtime),
+                auth: runtime.auth ?? {},
+                ...(runtime.auth?.fetch ? { fetch: runtime.auth.fetch } : {}),
+            }, {});
+            if (json)
+                writeJson(runtime, { ok: true, ...result });
+            else
+                runtime.stdout(`Synced ${result.tier} metadata ${result.artifactVersion} into ${result.projectRoot}.\n`);
+            return 0;
+        }
+        catch (error) {
+            if (json)
+                return reportFailure(runtime, true, error);
+            throw error;
+        }
+    }
+    const project = detectProject(runtime.cwd());
+    if (!project)
+        throw new CliError("VALIDATION_ERROR", "no project found; run install first");
+    const config = validateConfigDocument(loadConfigDocument(project.root), undefined, {
+        lenientCatalog: true,
+    });
+    if (config.kind !== "ok")
+        throw new CliError("VALIDATION_ERROR", config.kind === "invalid" ? config.message : `config ${config.kind}; run moeicons init`);
+    assertDownloadSelection(config.config);
+    const { allowLocalTest } = resolveLocalTestContext(runtime.env);
+    const status = await getLibraryVersionStatus(project.root, config.config.tier, {
+        fetchVersions: () => fetchLibraryVersions({
+            signal: context.signal,
+            env: runtime.env,
+            allowLocalTest,
+            ...(runtime.auth?.fetch ? { fetch: runtime.auth.fetch } : {}),
+        }),
+    });
+    if (context.signal?.aborted)
+        throw new CliError("CANCELLED", "update cancelled");
+    if (status.kind === "check-failed")
+        throw new CliError("NETWORK_ERROR", status.message);
+    if (status.kind === "installation-invalid")
+        throw new CliError("VALIDATION_ERROR", status.message);
+    if (status.kind === "current" &&
+        status.latestDescriptorSha256 !== status.metadata.descriptorSha256)
+        throw new CliError("VALIDATION_ERROR", "published identity changed for the installed version; refusing to replace the pinned release");
+    if (status.kind !== "update" && status.kind !== "current") {
+        if (json)
+            writeJson(runtime, { ok: true, status: status.kind });
+        else
+            runtime.stdout(`${formatLibraryVersionStatus(status)}\n`);
+        return 0;
+    }
+    return runLibraryUpdate(runtime, status.metadata.tier, status.latestVersion, status.latestDescriptorSha256, json);
+}
 /** Free install orchestration: download/verify then map to JSON/human output. */
 async function runInstall(group, runtime, json, noTailwind, sourceVersion, expectedDescriptorSha256, target) {
     const context = commandContext(runtime, { json, yes: false });
+    const project = detectProject(runtime.cwd());
+    if (!project)
+        throw new CliError("VALIDATION_ERROR", "no package.json found in the current directory or parents; run inside a project");
+    const bootstrap = validateConfigDocument(loadConfigDocument(project.root), undefined, {
+        lenientCatalog: true,
+    });
+    if (bootstrap.kind === "invalid")
+        throw new CliError("VALIDATION_ERROR", bootstrap.message);
+    if (bootstrap.kind === "ok")
+        assertDownloadSelection(bootstrap.config);
+    const requestedTier = group === "pro" || group === "ent" ? "pro" : "free";
+    if (bootstrap.kind === "ok" && bootstrap.config.tier !== requestedTier)
+        throw new CliError("VALIDATION_ERROR", `config.tier=${bootstrap.config.tier} conflicts with install ${requestedTier}; run moeicons install ${bootstrap.config.tier} or edit config.tier`);
+    if (bootstrap.kind === "ok" && target && bootstrap.config.target !== target)
+        throw new CliError("VALIDATION_ERROR", `config.target=${bootstrap.config.target} conflicts with --target=${target}; edit config.target before downloading`);
     const progress = context.ui.progress("Downloading icon library", context.signal);
     if (group === "pro" || group === "ent") {
+        const { allowLocalTest } = resolveLocalTestContext(runtime.env);
         const identity = sourceVersion && expectedDescriptorSha256
             ? { version: sourceVersion, descriptorSha256: expectedDescriptorSha256 }
             : await fetchLibraryVersions({
                 signal: context.signal,
+                env: runtime.env,
+                allowLocalTest,
                 ...(runtime.auth?.fetch ? { fetch: runtime.auth.fetch } : {}),
             }).then((versions) => {
                 if (!versions.pro)
@@ -350,7 +938,16 @@ async function runInstall(group, runtime, json, noTailwind, sourceVersion, expec
             });
         try {
             const result = await runProInstallUseCase(context, {
-                fs: { mkdirSync, writeFileSync, existsSync, renameSync, rmSync },
+                fs: {
+                    mkdirSync,
+                    writeFileSync,
+                    existsSync,
+                    renameSync,
+                    rmSync,
+                    readFileSync,
+                    readdirSync,
+                    copyFileSync,
+                },
                 auth: runtime.auth ?? {},
                 fetch: runtime.auth?.fetch ?? globalThis.fetch.bind(globalThis),
                 onProgress: ({ downloadedBytes, totalBytes }) => {
@@ -359,12 +956,20 @@ async function runInstall(group, runtime, json, noTailwind, sourceVersion, expec
                         : "";
                     progress.update?.(`Downloaded ${downloadedBytes} bytes${totalBytes ? ` of ${totalBytes}` : ""}${percent}`);
                 },
-            }, { ...identity, ...(target ? { target } : {}) });
+            }, {
+                ...identity,
+                ...(allowLocalTest ? { allowLocalTest: true } : {}),
+                ...(target ? { target } : {}),
+            });
             progress.stop("Icon library download complete");
             if (json)
                 writeJson(runtime, { ok: true, group: "pro", ...result });
-            else
+            else {
                 runtime.stdout(`Installed pro artifact ${result.artifactVersion} into ${result.projectRoot}.\n`);
+                runtime.stdout(`Download mode: ${result.downloadMode}${result.selectedFiles !== undefined ? `; ${result.selectedFiles} resource files; ${result.networkBytes} resource bytes received` : ""}.\n`);
+                for (const note of result.downloadNotes)
+                    runtime.stdout(`${note}\n`);
+            }
             return 0;
         }
         catch (error) {
@@ -375,16 +980,7 @@ async function runInstall(group, runtime, json, noTailwind, sourceVersion, expec
     const result = await runInstallUseCase(context, {
         fs: { mkdirSync, writeFileSync, existsSync, renameSync, rmSync },
         download: {
-            fetchFn: globalThis.fetch.bind(globalThis),
-            readFileSync: (path) => new Uint8Array(readFileSync(path)),
-            writeFileSync: (path, data) => writeFileSync(path, data),
-            mkdirSync: (path) => mkdirSync(path, { recursive: true }),
-            existsSync,
-            ...(runtime.env.MOEICONS_FREE_RELEASE_DIR
-                ? { fixtureDir: runtime.env.MOEICONS_FREE_RELEASE_DIR }
-                : {}),
-            cacheDir: runtime.env.MOEICONS_CACHE_DIR ?? join(homedir(), ".moeicons", "cache"),
-            cliVersion: versionString(),
+            ...freeDownloadDeps(runtime),
             onProgress: ({ downloadedBytes, totalBytes }) => {
                 const percent = totalBytes
                     ? ` (${Math.min(100, Math.floor((downloadedBytes / totalBytes) * 100))}%)`
@@ -414,6 +1010,9 @@ async function runInstall(group, runtime, json, noTailwind, sourceVersion, expec
     if (!result.ok && result.reason === "not-found") {
         throw new CliError("NOT_FOUND", result.message);
     }
+    if (!result.ok && result.reason === "disk-full") {
+        throw new CliError("DISK_FULL", result.message);
+    }
     if (!result.ok && result.reason === "validation") {
         throw new CliError("VALIDATION_ERROR", result.message);
     }
@@ -433,7 +1032,12 @@ async function runInstall(group, runtime, json, noTailwind, sourceVersion, expec
             artifactVersion: result.artifactVersion,
             descriptorSha256: result.descriptorSha256,
             catalogSha256: result.catalogSha256,
+            metadataSha256: result.metadataSha256,
             cacheHit: result.cacheHit,
+            downloadMode: result.downloadMode,
+            downloadNotes: result.downloadNotes,
+            networkBytes: result.networkBytes,
+            selectedFiles: result.selectedFiles,
         });
     }
     else {
@@ -441,6 +1045,9 @@ async function runInstall(group, runtime, json, noTailwind, sourceVersion, expec
         runtime.stdout(`Group: ${result.group}\n`);
         runtime.stdout(`Artifact: ${result.artifactVersion}\n`);
         runtime.stdout(`Config state: ${result.config}\n`);
+        runtime.stdout(`Download mode: ${result.downloadMode}${result.selectedFiles !== undefined ? `; ${result.selectedFiles} resource files; ${result.networkBytes} resource bytes received` : ""}.\n`);
+        for (const note of result.downloadNotes ?? [])
+            runtime.stdout(`${note}\n`);
         runtime.stdout(`Installed free artifact metadata to .moeicons (cacheHit=${String(result.cacheHit)}).\n`);
     }
     return 0;
@@ -448,24 +1055,42 @@ async function runInstall(group, runtime, json, noTailwind, sourceVersion, expec
 function generateFailureCode(reason) {
     if (reason === "cancelled")
         return "CANCELLED";
-    if (reason === "validation" || reason === "no-project" || reason.startsWith("config state:")) {
+    if (reason === "validation" ||
+        reason === "no-project" ||
+        reason.startsWith("config state:") ||
+        reason.startsWith("installed artifact targets") ||
+        reason.startsWith("generate requires an installed")) {
         return "VALIDATION_ERROR";
     }
     return "UNEXPECTED";
 }
 /** Generate proxy components from config. */
 async function runGenerate(runtime, json, noTailwind, reconcileInstalled = false, target, yes = false) {
-    const result = await runGenerateUseCase(commandContext(runtime, { json, yes }), {
-        mkdirSync,
-        writeFileSync,
-        readFileSync,
-        existsSync,
-        renameSync,
-        rmSync,
-        readdirSync,
-        copyFileSync,
-    }, { noTailwind, reconcileInstalled, ...(target ? { target } : {}) });
+    const context = commandContext(runtime, { json, yes });
+    // W3-C: generation has no byte progress, so the strict task status covers it.
+    const task = !json && runtime.readLine === undefined
+        ? context.ui.task?.("Generating icon components", context.signal)
+        : undefined;
+    let result;
+    try {
+        // W3-C: generation has no byte progress, so its status is the task handle.
+        result = await runGenerateUseCase(context, {
+            mkdirSync,
+            writeFileSync,
+            readFileSync,
+            existsSync,
+            renameSync,
+            rmSync,
+            readdirSync,
+            copyFileSync,
+        }, { noTailwind, reconcileInstalled, ...(target ? { target } : {}) });
+    }
+    catch (error) {
+        task?.fail(error instanceof Error ? error.message : String(error));
+        throw error;
+    }
     if (!result.ok) {
+        task?.fail(result.reason);
         if (result.code === "TAILWIND_VERSION_UNSUPPORTED") {
             if (json)
                 writeJson(runtime, jsonErrorBody("TAILWIND_VERSION_UNSUPPORTED", result.reason));
@@ -497,6 +1122,7 @@ async function runGenerate(runtime, json, noTailwind, reconcileInstalled = false
             ...(result.warnings ? { warnings: result.warnings } : {}),
         });
     else {
+        task?.succeed(`Generated ${result.files.length} files`);
         runtime.stdout(`Generated ${result.files.length} files.\n`);
         if (result.warnings) {
             for (const warning of result.warnings)