@moewolf/moe-icons-cli 0.0.1 → 0.0.3

package/dist/mcp/server.js

@@ -1,176 +1,98 @@
-/**
- * Minimal MCP (Model Context Protocol) stdio server. Registers only v1 tools:
- * list_icon_groups, get_account, install_icon_group. Protocol data goes only
- * to stdout; logs go to stderr. Graceful shutdown on SIGINT/SIGTERM.
- */
+/** Local, newline-delimited MCP transport. Business failures are tool results. */
 import { CLI_VERSION } from "../ui/banner.js";
-function validateArgs(method, params, required) {
-    if (!params) {
-        return undefined;
-    }
-    for (const key of required) {
-        if (typeof params[key] !== "string" || params[key].length === 0) {
-            return undefined;
-        }
-    }
-    const out = {};
-    for (const key of required) {
-        out[key] = String(params[key]);
-    }
-    return out;
+export class McpArgumentError extends Error {
 }
-/**
- * Create an MCP server bound to injected streams. Returns a dispatcher that
- * handles one decoded JSON-RPC message.
- */
+export const isRecord = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+export function safeMcpValue(value, projectRoot) {
+    if (typeof value === "string")
+        return (projectRoot ? value.split(projectRoot).join(".") : value).replace(/https?:\/\/[^\s"<>]+\?[^\s"<>]+/g, "[redacted URL]").replace(/(?:\/Users\/|\/home\/)[^/\s]+/g, "[home]");
+    if (Array.isArray(value))
+        return value.map((entry) => safeMcpValue(entry, projectRoot));
+    if (!isRecord(value))
+        return value;
+    return Object.fromEntries(Object.entries(value).filter(([key]) => !/(token|secret|authorization|signedurl|verifier)/i.test(key)).map(([key, entry]) => [key, safeMcpValue(entry, projectRoot)]));
+}
+const objectSchema = (properties = {}, required = []) => ({ type: "object", properties, required, additionalProperties: false });
+const legacyTools = [
+    { name: "list_icon_groups", description: "List available style groups and catalog identity", inputSchema: objectSchema() },
+    { name: "get_account", description: "Read the current account and entitlement without credentials", inputSchema: objectSchema() },
+    { name: "install_icon_group", description: "Deprecated: use configuration and install instead", inputSchema: objectSchema({ groupId: { type: "string" }, projectPath: { type: "string" } }, ["groupId", "projectPath"]) },
+];
 export function createMcpServer(deps) {
-    const handle = async (message) => {
-        if (message.jsonrpc !== "2.0") {
-            return { jsonrpc: "2.0", id: message.id, error: { code: -32600, message: "invalid request" } };
+    const tools = deps.services.tools ?? legacyTools;
+    const handle = async (value) => {
+        const id = isRecord(value) && (typeof value.id === "string" || typeof value.id === "number") ? value.id : null;
+        const error = (code, message) => ({ jsonrpc: "2.0", id, error: { code, message } });
+        if (!isRecord(value) || value.jsonrpc !== "2.0" || typeof value.method !== "string" || (value.id !== undefined && id === null))
+            return error(-32600, "invalid request");
+        if (value.id === undefined)
+            return undefined; // Never respond to notifications.
+        if (value.params !== undefined && !isRecord(value.params))
+            return error(-32602, "params must be an object");
+        const params = value.params ?? {};
+        if (value.method === "initialize") {
+            const requested = params.protocolVersion;
+            const supported = ["2024-11-05", "2025-03-26", "2025-06-18"];
+            const protocolVersion = typeof requested === "string" && supported.includes(requested) ? requested : "2024-11-05";
+            return { jsonrpc: "2.0", id, result: { protocolVersion, capabilities: { tools: {} }, serverInfo: { name: "moeicons", version: CLI_VERSION } } };
         }
-        switch (message.method) {
-            case "initialize":
-                return {
-                    jsonrpc: "2.0",
-                    id: message.id,
-                    result: {
-                        protocolVersion: "2024-11-05",
-                        capabilities: { tools: {} },
-                        serverInfo: { name: "moeicons", version: CLI_VERSION },
-                    },
-                };
-            case "tools/list":
-                return {
-                    jsonrpc: "2.0",
-                    id: message.id,
-                    result: {
-                        tools: [
-                            {
-                                name: "list_icon_groups",
-                                description: "List available icon groups",
-                                inputSchema: { type: "object", properties: {} },
-                            },
-                            {
-                                name: "get_account",
-                                description: "Get the current account/tier",
-                                inputSchema: { type: "object", properties: {} },
-                            },
-                            {
-                                name: "install_icon_group",
-                                description: "Install an icon group into a project",
-                                inputSchema: {
-                                    type: "object",
-                                    properties: {
-                                        groupId: { type: "string" },
-                                        projectPath: { type: "string" },
-                                    },
-                                    required: ["groupId", "projectPath"],
-                                },
-                            },
-                        ],
-                    },
-                };
-            case "tools/call": {
-                const toolName = message.params?.name;
-                const args = message.params?.arguments ?? {};
-                try {
-                    if (toolName === "list_icon_groups") {
-                        const groups = await deps.services.listIconGroups();
-                        return {
-                            jsonrpc: "2.0",
-                            id: message.id,
-                            result: { content: [{ type: "text", text: JSON.stringify(groups) }] },
-                        };
-                    }
-                    if (toolName === "get_account") {
-                        const account = await deps.services.getAccount();
-                        return {
-                            jsonrpc: "2.0",
-                            id: message.id,
-                            result: {
-                                content: [
-                                    { type: "text", text: account ? JSON.stringify(account) : "not logged in" },
-                                ],
-                            },
-                        };
-                    }
-                    if (toolName === "install_icon_group") {
-                        const validated = validateArgs(toolName, args, ["groupId", "projectPath"]);
-                        if (!validated) {
-                            return {
-                                jsonrpc: "2.0",
-                                id: message.id,
-                                error: { code: -32602, message: "groupId and projectPath are required strings" },
-                            };
-                        }
-                        const projectPath = validated["projectPath"];
-                        const groupId = validated["groupId"];
-                        if (!projectPath || !groupId) {
-                            return {
-                                jsonrpc: "2.0",
-                                id: message.id,
-                                error: { code: -32602, message: "groupId and projectPath are required strings" },
-                            };
-                        }
-                        if (projectPath.split(/[\\/]/).includes("..")) {
-                            return {
-                                jsonrpc: "2.0",
-                                id: message.id,
-                                error: { code: -32602, message: "projectPath must not contain path traversal" },
-                            };
-                        }
-                        const result = await deps.services.installIconGroup({
-                            groupId,
-                            projectPath,
-                        });
-                        return {
-                            jsonrpc: "2.0",
-                            id: message.id,
-                            result: { content: [{ type: "text", text: JSON.stringify(result) }] },
-                        };
-                    }
-                    return {
-                        jsonrpc: "2.0",
-                        id: message.id,
-                        error: { code: -32601, message: `unknown tool: ${String(toolName)}` },
-                    };
-                }
-                catch (error) {
-                    deps.stderr(`mcp tool error: ${String(error)}\n`);
-                    return {
-                        jsonrpc: "2.0",
-                        id: message.id,
-                        error: { code: -32000, message: String(error) },
-                    };
-                }
+        if (value.method === "ping")
+            return { jsonrpc: "2.0", id, result: {} };
+        if (value.method === "tools/list")
+            return { jsonrpc: "2.0", id, result: { tools } };
+        if (value.method !== "tools/call")
+            return error(-32601, `method not found: ${value.method}`);
+        const name = params.name;
+        if (typeof name !== "string" || !tools.some((tool) => tool.name === name))
+            return error(-32601, "unknown tool");
+        if (params.arguments !== undefined && !isRecord(params.arguments))
+            return error(-32602, "arguments must be an object");
+        const args = params.arguments ?? {};
+        try {
+            let result;
+            if (deps.services.callTool)
+                result = await deps.services.callTool(name, args);
+            else if (name === "list_icon_groups")
+                result = await deps.services.listIconGroups();
+            else if (name === "get_account")
+                result = await deps.services.getAccount() ?? "not logged in";
+            else {
+                if (typeof args.groupId !== "string" || !args.groupId || typeof args.projectPath !== "string" || !args.projectPath)
+                    throw new McpArgumentError("groupId and projectPath are required strings");
+                if (args.projectPath.split(/[\\/]/).includes(".."))
+                    throw new McpArgumentError("projectPath must not contain path traversal");
+                result = await deps.services.installIconGroup({ groupId: args.groupId, projectPath: args.projectPath });
             }
-            default:
-                return { jsonrpc: "2.0", id: message.id, error: { code: -32601, message: `method not found: ${message.method}` } };
+            const safe = safeMcpValue(result, deps.projectRoot);
+            return { jsonrpc: "2.0", id, result: { content: [{ type: "text", text: typeof safe === "string" ? safe : JSON.stringify(safe) }], ...(isRecord(result) && result.ok === false ? { isError: true } : {}) } };
+        }
+        catch (cause) {
+            if (cause instanceof McpArgumentError)
+                return error(-32602, cause.message);
+            const message = String(safeMcpValue(cause instanceof Error ? cause.message : String(cause), deps.projectRoot));
+            deps.stderr(`mcp tool error: ${message}\n`);
+            return { jsonrpc: "2.0", id, result: { isError: true, content: [{ type: "text", text: JSON.stringify({ ok: false, code: isRecord(cause) && typeof cause.code === "string" ? cause.code : "TOOL_ERROR", message }) }] } };
         }
     };
     return { handle };
 }
-/**
- * Read JSON-RPC messages from an async iterable of lines and write responses to
- * stdout. Used by the stdio transport.
- */
 export async function runMcpStdio(deps) {
     const server = createMcpServer(deps);
     for await (const line of deps.lines) {
-        const trimmed = line.trim();
-        if (!trimmed)
+        if (deps.signal?.aborted)
+            break;
+        if (!line.trim())
             continue;
         let message;
         try {
-            message = JSON.parse(trimmed);
+            message = JSON.parse(line);
         }
         catch {
             deps.stdout(JSON.stringify({ jsonrpc: "2.0", id: null, error: { code: -32700, message: "parse error" } }) + "\n");
             continue;
         }
         const response = await server.handle(message);
-        if (response) {
+        if (response)
             deps.stdout(JSON.stringify(response) + "\n");
-        }
     }
 }

package/dist/mcp/services.d.ts

@@ -0,0 +1,4 @@
+import type { CliRuntime } from "../cli.js";
+import { type McpTool, type McpServices } from "./server.js";
+export declare const projectTools: readonly [McpTool, McpTool, McpTool, McpTool, McpTool, McpTool, McpTool, McpTool, McpTool, McpTool, McpTool];
+export declare function createProjectMcpServices(runtime: CliRuntime, execute: (argv: readonly string[]) => Promise<unknown>): McpServices;

package/dist/mcp/services.js

@@ -0,0 +1,230 @@
+import { existsSync, readFileSync, realpathSync } from "node:fs";
+import { relative, resolve, basename } from "node:path";
+import { applyEdits, modify, parse } from "jsonc-parser";
+import { catalog } from "../catalog/catalog.js";
+import { loadInstalledCatalogState } from "../core/generate.js";
+import { buildInitPlan, collectSafeFixes, doctorJson, runDoctorApply, runDoctorDiagnose } from "../core/doctor.js";
+import { findConfigFile, loadConfigDocument, validateConfigDocument } from "../project/config.js";
+import { safeManagedPath } from "../project/install.js";
+import { sha256Bytes } from "../project/install-metadata.js";
+import { allowLocalTestFromEnv } from "../core/local-test-env.js";
+import { toProxyName } from "../core/icon-names.js";
+import { McpArgumentError, isRecord } from "./server.js";
+const string = { type: "string" };
+const strings = { type: "array", items: string, uniqueItems: true };
+const boolean = { type: "boolean" };
+const targetSchema = { type: "string", enum: ["vue", "react", "vanilla", "assets"] };
+const tool = (name, description, properties = {}, required = []) => ({ name, description, inputSchema: { type: "object", properties: { projectPath: string, ...properties }, required, additionalProperties: false } });
+export const projectTools = [
+    tool("list_icon_groups", "Read style groups from verified installed catalog, or identify bundled fallback"),
+    tool("get_account", "Read account/entitlement. Login outside MCP with moeicons login"),
+    tool("get_project_config", "Read normalized configuration, hash for update_config, and integration diagnosis"),
+    tool("find_icons", "Search icon IDs available in every requested style group", { query: string, styleGroups: strings, limit: { type: "integer", minimum: 1, maximum: 100 }, cursor: string }),
+    tool("get_usage_guide", "Read generated-component integration rules", { target: targetSchema }),
+    tool("init_config", "Initialize configuration and safe integration fixes. Explicit target resolves mixed frameworks", { target: targetSchema, integration: { type: "object", properties: { adapter: string, entry: string, style: string }, additionalProperties: false }, dryRun: boolean }),
+    tool("update_config", "Patch JSONC without overwriting unrelated settings. Reinstall then generate after changing icons", { expectedHash: { type: "string", pattern: "^[a-f0-9]{64}$" }, patch: { type: "object", properties: { tier: { enum: ["free", "pro"] }, target: targetSchema, outputDir: string, defaultTheme: string, downloadMode: { enum: ["auto", "icons", "full"] }, missingIconPolicy: { enum: ["error", "fallback"] }, integration: { type: "object" }, themes: { type: "object", properties: { upsert: { type: "object" }, remove: strings }, additionalProperties: false }, icons: { type: "object", properties: { add: strings, remove: strings }, additionalProperties: false }, themeIcons: { type: "object" } }, additionalProperties: false }, dryRun: boolean }, ["expectedHash", "patch"]),
+    tool("install", "Download and verify configured resources from Free/Pro release", { tier: { type: "string", enum: ["free", "pro"] } }, ["tier"]),
+    tool("update", "Update resource release and reconcile config (not CLI self-update)"),
+    tool("generate", "Generate code using installed verified resources; does not implicitly download"),
+    tool("install_icon_group", "Deprecated. Configure style groups then call install", { groupId: string }, ["groupId", "projectPath"]),
+];
+function keys(value, allowed) {
+    if (Object.keys(value).some((key) => !allowed.includes(key)))
+        throw new McpArgumentError("unknown argument field");
+}
+function list(value) {
+    if (value === undefined)
+        return [];
+    if (!Array.isArray(value) || value.some((x) => typeof x !== "string" || !x) || new Set(value).size !== value.length)
+        throw new McpArgumentError("expected unique string array");
+    return value;
+}
+function changes(value) {
+    if (!isRecord(value))
+        throw new McpArgumentError("icon changes must be an object");
+    keys(value, ["add", "remove"]);
+    const add = list(value.add), remove = list(value.remove);
+    if ([...add, ...remove].some((id) => !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(id)))
+        throw new McpArgumentError("icon IDs must be lowercase kebab-case");
+    if (add.some((x) => remove.includes(x)))
+        throw new McpArgumentError("cannot add and remove the same icon");
+    return { add, remove };
+}
+const fail = (code, message) => ({ ok: false, code, message });
+export function createProjectMcpServices(runtime, execute) {
+    const root = () => realpathSync(runtime.cwd());
+    function source() {
+        const state = loadInstalledCatalogState(root(), { readFileSync, existsSync }, { allowLocalTest: allowLocalTestFromEnv(runtime.env) });
+        if (state.status === "invalid")
+            throw new Error(state.message);
+        return { catalog: state.status === "ok" ? state.catalog : catalog, source: state.status === "ok" ? "installed" : "bundled" };
+    }
+    function loaded() {
+        const path = findConfigFile(root());
+        if (!path)
+            throw new Error("configuration missing; call init_config first");
+        safeManagedPath(root(), relative(root(), path));
+        const state = source();
+        const config = validateConfigDocument(loadConfigDocument(root()), state.catalog, { lenientCatalog: state.source === "bundled" });
+        if (config.kind !== "ok")
+            throw new Error(config.kind === "invalid" ? config.message : `configuration ${config.kind}`);
+        safeManagedPath(root(), config.config.outputDir);
+        return { ...state, path, config: config.config, raw: readFileSync(path, "utf8") };
+    }
+    const installIconGroup = () => Promise.resolve({ ok: false, message: 'single style-group install is not supported — run "moeicons install free" or "moeicons install pro"' });
+    const callTool = async (name, args) => {
+        if (["init_config", "update_config", "install", "update", "generate"].includes(name) && !existsSync(resolve(root(), "package.json")))
+            throw new Error("bind MCP cwd to the project root containing package.json");
+        const def = projectTools.find((entry) => entry.name === name);
+        if (!def)
+            throw new McpArgumentError("unknown tool");
+        keys(args, Object.keys(def.inputSchema.properties));
+        if (args.projectPath !== undefined && (typeof args.projectPath !== "string" || realpathSync(resolve(root(), args.projectPath)) !== root()))
+            throw new McpArgumentError("projectPath must resolve to the bound project root");
+        for (const key of ["dryRun"])
+            if (args[key] !== undefined && typeof args[key] !== "boolean")
+                throw new McpArgumentError(`${key} must be boolean`);
+        if (args.target !== undefined && !["react", "vue", "vanilla", "assets"].includes(String(args.target)))
+            throw new McpArgumentError("invalid target");
+        if (name === "install_icon_group") {
+            if (typeof args.groupId !== "string" || typeof args.projectPath !== "string")
+                throw new McpArgumentError("groupId and projectPath are required strings");
+            return installIconGroup();
+        }
+        if (name === "list_icon_groups") {
+            const s = source();
+            return { ok: true, source: s.source, catalogVersion: s.catalog.catalogVersion, sourceVersion: s.catalog.sourceVersion, groups: s.catalog.styleGroups };
+        }
+        if (name === "get_account") {
+            const result = await execute(["account", "--json"]);
+            if (!isRecord(result) || result.ok === false)
+                return result;
+            const account = isRecord(result.account) ? result.account : {};
+            return { ok: true, environment: result.environment, account: Object.fromEntries(["accountId", "tier", "entitlementStatus", "expiresAt"].filter((key) => account[key] !== undefined).map((key) => [key, account[key]])) };
+        }
+        if (name === "get_project_config") {
+            const s = loaded();
+            return { ok: true, path: basename(s.path), config: s.config, hash: sha256Bytes(s.raw), availability: s.source === "installed" ? "verified" : "unverified", doctor: doctorJson(runDoctorDiagnose(root(), s.catalog).report) };
+        }
+        if (name === "find_icons") {
+            if (args.query !== undefined && typeof args.query !== "string")
+                throw new McpArgumentError("query must be a string");
+            const groups = list(args.styleGroups), s = source();
+            if (groups.some((id) => !s.catalog.styleGroups.some((g) => g.id === id)))
+                return fail("UNAVAILABLE_GROUP", "requested style group is absent from this catalog");
+            const limit = args.limit ?? 30;
+            const cursor = args.cursor ?? "0";
+            if (typeof limit !== "number" || !Number.isInteger(limit) || limit < 1 || limit > 100 || typeof cursor !== "string" || !/^\d+$/.test(cursor) || !Number.isSafeInteger(Number(cursor)))
+                throw new McpArgumentError("invalid limit/cursor");
+            const query = String(args.query ?? "").toLowerCase();
+            const items = s.catalog.icons.filter((icon) => groups.every((id) => icon.availableIn.includes(id)) && `${icon.id} ${icon.label} ${(icon.keywords ?? []).join(" ")}`.toLowerCase().includes(query));
+            const offset = Number(cursor);
+            return { ok: true, source: s.source, catalogVersion: s.catalog.catalogVersion, items: items.slice(offset, offset + limit).map((icon) => ({ id: icon.id, exportName: toProxyName(icon.id), availableIn: icon.availableIn })), nextCursor: offset + limit < items.length ? String(offset + limit) : null };
+        }
+        if (name === "get_usage_guide")
+            return { ok: true, target: args.target ?? "vue", guide: "Run init_config, read config/hash, find icons, update_config, install, then generate. Changing selections requires reinstall/update before generation. Install the generated runtime dependencies clsx and tailwind-merge (use a Tailwind-compatible version), as documented in the manual. Never edit generated files. Import named icon proxies from the generated index. Vue: wrap the application including navigation/footer in MoeiconsProvider and bind theme to an exact configured key; import components explicitly. React: wrap with MoeiconsProvider. Vanilla: use createMoeiconsRuntime and generated create functions. Assets: consume the generated assets. Inspect index.ts and installed MANUAL for exact exports. Decorative icons: aria-hidden and empty alt; icon-only controls need an accessible label. Never embed CLI credentials in browser code.", manual: existsSync(resolve(root(), ".moeicons/MANUAL.md")) ? ".moeicons/MANUAL.md" : null };
+        if (name === "init_config") {
+            let confirmed;
+            if (args.integration !== undefined) {
+                if (!isRecord(args.integration))
+                    throw new McpArgumentError("integration must be an object");
+                keys(args.integration, ["adapter", "entry", "style"]);
+                for (const [key, value] of Object.entries(args.integration)) {
+                    if (typeof value !== "string" || !value)
+                        throw new McpArgumentError("integration fields must be strings");
+                    if (key !== "adapter")
+                        safeManagedPath(root(), value);
+                    else if (!["vite-vue", "vite-react", "next-app", "next-pages", "nuxt", "vanilla", "assets-only"].includes(value))
+                        throw new McpArgumentError("invalid adapter");
+                }
+                confirmed = args.integration;
+            }
+            if (args.target && confirmed?.adapter) {
+                const adapterTarget = confirmed.adapter === "vite-vue" || confirmed.adapter === "nuxt" ? "vue" : confirmed.adapter === "vanilla" ? "vanilla" : confirmed.adapter === "assets-only" ? "assets" : "react";
+                if (args.target !== adapterTarget)
+                    throw new McpArgumentError("target and integration.adapter disagree");
+            }
+            const { outcome } = buildInitPlan(root(), args.target, confirmed, source().catalog);
+            if (outcome.report.anchors.some((anchor) => anchor.status === "ambiguous" || anchor.kind === "manifest" && anchor.status !== "ok"))
+                return fail("AMBIGUOUS_PROJECT", "select target/integration before initialization");
+            const fixes = collectSafeFixes(outcome);
+            if (args.dryRun)
+                return { ok: true, diffs: fixes, doctor: doctorJson(outcome.report) };
+            return runDoctorApply(root(), fixes);
+        }
+        if (name === "update_config") {
+            if (typeof args.expectedHash !== "string" || !/^[a-f0-9]{64}$/.test(args.expectedHash) || !isRecord(args.patch))
+                throw new McpArgumentError("expectedHash and patch are required");
+            const s = loaded();
+            if (sha256Bytes(s.raw) !== args.expectedHash)
+                return fail("CONFIG_CHANGED", "configuration changed; read it again before retrying");
+            const patch = args.patch;
+            keys(patch, ["tier", "target", "outputDir", "defaultTheme", "downloadMode", "missingIconPolicy", "integration", "themes", "icons", "themeIcons"]);
+            let text = s.raw;
+            const set = (path, value) => { text = applyEdits(text, modify(text, path, value, { formattingOptions: { insertSpaces: true, tabSize: 2 } })); };
+            for (const [key, value] of Object.entries(patch))
+                if (!["themes", "icons", "themeIcons"].includes(key))
+                    set([key], value);
+            if (patch.integration !== undefined)
+                set(["schemaVersion"], 3);
+            if (patch.themes !== undefined) {
+                if (!isRecord(patch.themes))
+                    throw new McpArgumentError("themes must be an object");
+                keys(patch.themes, ["upsert", "remove"]);
+                const remove = list(patch.themes.remove), upsert = patch.themes.upsert ?? {};
+                if (!isRecord(upsert) || remove.some((id) => id in upsert))
+                    throw new McpArgumentError("invalid theme changes");
+                for (const key of remove)
+                    set(["themes", key], undefined);
+                for (const [key, value] of Object.entries(upsert))
+                    set(["themes", key], value);
+            }
+            if (patch.icons !== undefined) {
+                const delta = changes(patch.icons), doc = parse(text);
+                if (Array.isArray(doc.icons))
+                    set(["icons"], [...new Set([...list(doc.icons).filter((id) => !delta.remove.includes(id)), ...delta.add])]);
+                else if (isRecord(doc.icons)) {
+                    for (const [prefix, ids] of Object.entries(doc.icons))
+                        set(["icons", prefix], list(ids).filter((id) => !delta.remove.includes(id)));
+                    for (const id of delta.add) {
+                        const prefix = s.catalog.icons.find((icon) => icon.id === id)?.prefix ?? id.split("-")[0];
+                        const current = parse(text);
+                        set(["icons", prefix], [...new Set([...list(current.icons[prefix]), id])]);
+                    }
+                }
+                else
+                    throw new McpArgumentError("unsupported icons structure");
+            }
+            if (patch.themeIcons !== undefined) {
+                if (!isRecord(patch.themeIcons))
+                    throw new McpArgumentError("themeIcons must be an object");
+                for (const [key, value] of Object.entries(patch.themeIcons)) {
+                    const doc = parse(text);
+                    if (!doc.themes[key])
+                        throw new McpArgumentError("unknown theme");
+                    const delta = changes(value);
+                    set(["themes", key, "icons"], [...new Set([...list(doc.themes[key].icons).filter((id) => !delta.remove.includes(id)), ...delta.add])]);
+                }
+            }
+            const validated = validateConfigDocument({ kind: "ok", value: parse(text), version: s.config.schemaVersion === 3 || patch.integration ? 3 : 2 }, s.catalog, { lenientCatalog: s.source === "bundled" });
+            if (validated.kind !== "ok")
+                return fail("INVALID_CONFIG", validated.kind === "invalid" ? validated.message : validated.kind);
+            safeManagedPath(root(), validated.config.outputDir);
+            const diffs = [{ kind: "replace", path: basename(s.path), before: s.raw, after: text }];
+            if (args.dryRun)
+                return { ok: true, diffs, requiresInstall: true, requiresGenerate: true };
+            const applied = runDoctorApply(root(), diffs);
+            return { ...applied, hash: sha256Bytes(text), availability: s.source === "installed" ? "verified" : "unverified", requiresInstall: true, requiresGenerate: true };
+        }
+        const s = loaded();
+        if (name === "install") {
+            if (args.tier !== "free" && args.tier !== "pro")
+                throw new McpArgumentError("tier must be free or pro");
+            if (args.tier !== s.config.tier)
+                return fail("TIER_MISMATCH", "install tier must match configuration");
+            return execute(["install", args.tier, "--yes", "--json"]);
+        }
+        return execute([name, "--yes", "--json"]);
+    };
+    return { tools: projectTools, callTool, listIconGroups: () => callTool("list_icon_groups", {}), getAccount: () => callTool("get_account", {}), installIconGroup };
+}

package/dist/metadata/archive.d.ts

@@ -0,0 +1,38 @@
+import { type MetadataFileDigest } from "./manifest.js";
+export declare const METADATA_ARCHIVE_ENTRIES: readonly ["MANUAL.md", "catalog.json", "manifest.json"];
+export interface MetadataArchiveFiles {
+    readonly manifestJson: string;
+    readonly manualMd: string;
+    readonly catalogJson: string;
+}
+export type MetadataArchiveVerification = {
+    readonly expectedCatalogSha: string;
+    readonly expectedTier: "free" | "pro";
+    readonly expectedVersion: string;
+    /** Free path: the release descriptor provides per-file size + sha256. */
+    readonly perFileDigests: Readonly<Record<(typeof METADATA_ARCHIVE_ENTRIES)[number], MetadataFileDigest>>;
+    /** ICON-E2E-0907 / E2E-E2: local-test manifests only. */
+    readonly allowLocalTest?: boolean;
+} | {
+    readonly expectedCatalogSha: string;
+    readonly expectedTier: "free" | "pro";
+    readonly expectedVersion: string;
+    /** Pro path: the signed whole-archive sha256 was already verified. */
+    readonly perFileDigests?: undefined;
+    readonly allowLocalTest?: boolean;
+};
+export type MetadataArchiveResult = {
+    readonly kind: "ok";
+    readonly value: MetadataArchiveFiles;
+} | {
+    readonly kind: "error";
+    readonly reason: "validation" | "checksum-mismatch";
+    readonly message: string;
+};
+/**
+ * Single implementation for unpacking + verifying a tier metadata archive.
+ * Free/Pro share the whole flow; they only differ in whether per-file digests
+ * are available (free descriptor) or the whole archive was already verified by
+ * its signed sha256 (pro).
+ */
+export declare function extractAndVerifyMetadataArchive(bytes: Uint8Array, verification: MetadataArchiveVerification, maxExpandedBytes?: number): MetadataArchiveResult;

package/dist/metadata/archive.js

@@ -0,0 +1,94 @@
+import { createHash } from "node:crypto";
+import { extractTarGz, decodeUtf8 } from "../project/tar-gz.js";
+import { parseMetadataManifest } from "./manifest.js";
+export const METADATA_ARCHIVE_ENTRIES = ["MANUAL.md", "catalog.json", "manifest.json"];
+/** Exact archive layout the contract requires: nothing more, nothing less. */
+const ALLOWED_ENTRIES = new Set(METADATA_ARCHIVE_ENTRIES.map((name) => `metadata/${name}`));
+function sha256Hex(bytes) {
+    return createHash("sha256").update(bytes).digest("hex");
+}
+function sha256HexOfString(value) {
+    return createHash("sha256").update(value).digest("hex");
+}
+/**
+ * Single implementation for unpacking + verifying a tier metadata archive.
+ * Free/Pro share the whole flow; they only differ in whether per-file digests
+ * are available (free descriptor) or the whole archive was already verified by
+ * its signed sha256 (pro).
+ */
+export function extractAndVerifyMetadataArchive(bytes, verification, maxExpandedBytes = 8 * 1024 * 1024) {
+    const unpacked = extractTarGz(bytes, { maxEntries: 20_000, maxExpandedBytes });
+    if (unpacked.errors.length > 0) {
+        return { kind: "error", reason: "validation", message: unpacked.errors[0] ?? "metadata archive extract failed" };
+    }
+    // Strict whitelist: the archive must contain exactly the three frozen entries.
+    const actual = new Set(Object.keys(unpacked.files));
+    if (actual.size !== ALLOWED_ENTRIES.size || [...actual].some((name) => !ALLOWED_ENTRIES.has(name))) {
+        const extra = [...actual].filter((name) => !ALLOWED_ENTRIES.has(name));
+        const missing = [...ALLOWED_ENTRIES].filter((name) => !actual.has(name));
+        return {
+            kind: "error",
+            reason: "validation",
+            message: `metadata archive must contain exactly the frozen files${extra.length ? `; unexpected: ${extra.join(", ")}` : ""}${missing.length ? `; missing: ${missing.join(", ")}` : ""}`,
+        };
+    }
+    let manifestJson = "";
+    let manualMd = "";
+    let catalogJson = "";
+    for (const name of METADATA_ARCHIVE_ENTRIES) {
+        const raw = unpacked.files[`metadata/${name}`];
+        const digest = verification.perFileDigests?.[name];
+        if (digest && (sha256Hex(raw) !== digest.sha256 || raw.byteLength !== digest.size)) {
+            return {
+                kind: "error",
+                reason: "checksum-mismatch",
+                message: `metadata/${name} digest mismatch: expected ${digest.sha256}, got ${sha256Hex(raw)}`,
+            };
+        }
+        const text = decodeUtf8(raw);
+        if (name === "MANUAL.md")
+            manualMd = text;
+        else if (name === "catalog.json")
+            catalogJson = text;
+        else
+            manifestJson = text;
+    }
+    if (sha256HexOfString(catalogJson) !== verification.expectedCatalogSha) {
+        return {
+            kind: "error",
+            reason: "checksum-mismatch",
+            message: "metadata catalog.json does not match the code archive catalog",
+        };
+    }
+    let manifest;
+    try {
+        manifest = parseMetadataManifest(manifestJson, {
+            allowLocalTest: verification.allowLocalTest === true,
+        });
+    }
+    catch (error) {
+        return { kind: "error", reason: "validation", message: error instanceof Error ? error.message : String(error) };
+    }
+    if (manifest.tier !== verification.expectedTier) {
+        return {
+            kind: "error",
+            reason: "validation",
+            message: `manifest tier ${manifest.tier} does not match ${verification.expectedTier}`,
+        };
+    }
+    if (manifest.libraryVersion !== verification.expectedVersion) {
+        return {
+            kind: "error",
+            reason: "validation",
+            message: `manifest libraryVersion ${manifest.libraryVersion} does not match release ${verification.expectedVersion}`,
+        };
+    }
+    if (manifest.files["catalog.json"].sha256 !== verification.expectedCatalogSha) {
+        return {
+            kind: "error",
+            reason: "checksum-mismatch",
+            message: "manifest catalog digest does not match the code archive catalog",
+        };
+    }
+    return { kind: "ok", value: { manifestJson, manualMd, catalogJson } };
+}