@nucleoicons/skills 0.1.3 → 0.1.5

package/README.md

@@ -25,9 +25,9 @@ npx @nucleoicons/skills setup --target react --tools cursor
 npx @nucleoicons/skills setup --target vanilla --tools cursor,claude
 ```
 
-Setup installs the package under your user home (`~/.nucleo/skills`) and configures the editors you choose.
+Setup installs the package under your user home (`~/.nucleo/skills`) and configures the editors you choose (skills + MCP, no manual config step).
 
-After setup, follow any MCP steps printed in the terminal, reload MCP in your editor, then ask something like:
+Reload MCP in your editor, then ask something like:
 
 ```text
 What Nucleo icon families do I have?
@@ -47,8 +47,8 @@ After updating, reload MCP in your editor again.
 
 ## Editors
 
-| Tool        | `--tools` value |
-| ----------- | --------------- |
-| Cursor      | `cursor`        |
-| Claude Code | `claude`        |
-| Codex       | `codex`         |
+| Tool        | `--tools` value | Auto-configured |
+| ----------- | --------------- | --------------- |
+| Cursor      | `cursor`        | `~/.cursor/mcp.json` + `~/.cursor/skills/` |
+| Claude Code | `claude`        | `~/.claude.json` + `~/.claude/skills/` |
+| Codex       | `codex`         | `~/.codex/config.toml` + `~/.agents/skills/` |

package/dist/adapters/agents.d.ts

@@ -1,17 +1,25 @@
 import { type AgentTool } from "../config.js";
+/** Remove an existing `[mcp_servers.<name>]` table (+ nested tables), then append `block`. */
+export declare function upsertTomlMcpServer(toml: string, serverName: string, block: string): string;
 /** Merge nucleo-icons into ~/.cursor/mcp.json and copy skills to ~/.cursor/skills */
 export declare function configureCursor(root?: string): Promise<{
     mcpPath: string;
+    skillsPath: string;
     skills: string[];
 }>;
-/** Copy skills to ~/.claude/skills and print MCP snippet (Claude uses `claude mcp add` or config file) */
+/**
+ * Copy skills to ~/.claude/skills and merge MCP into ~/.claude.json
+ * (user-scope mcpServers — same file `claude mcp add --scope user` writes).
+ */
 export declare function configureClaude(root?: string): Promise<{
+    mcpPath: string;
+    skillsPath: string;
     skills: string[];
-    hint: string;
 }>;
-/** Copy skills to ~/.agents/skills and print Codex config.toml snippet */
+/** Copy skills to ~/.agents/skills and merge MCP into ~/.codex/config.toml */
 export declare function configureCodex(root?: string): Promise<{
+    mcpPath: string;
+    skillsPath: string;
     skills: string[];
-    hint: string;
 }>;
 export declare function configureTool(tool: AgentTool, root?: string): Promise<void>;

package/dist/adapters/agents.js

@@ -4,6 +4,7 @@ import { homedir } from "node:os";
 import { join } from "node:path";
 import { installRoot } from "../config.js";
 import { mcpEntryPath, skillsSourceDir } from "../install.js";
+const MCP_SERVER_NAME = "nucleo-icons";
 async function readJsonFile(path, fallback) {
     if (!existsSync(path)) {
         return fallback;
@@ -40,60 +41,101 @@ function nucleoMcpServerConfig(root = installRoot()) {
         },
     };
 }
+function escapeTomlString(value) {
+    return value.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+}
+/** Remove an existing `[mcp_servers.<name>]` table (+ nested tables), then append `block`. */
+export function upsertTomlMcpServer(toml, serverName, block) {
+    const prefix = `mcp_servers.${serverName}`;
+    const lines = toml.length > 0 ? toml.split(/\r?\n/) : [];
+    const kept = [];
+    let skipping = false;
+    for (const line of lines) {
+        const header = line.match(/^\[([^\]]+)\]\s*$/);
+        if (header) {
+            const name = header[1];
+            skipping = name === prefix || name.startsWith(`${prefix}.`);
+        }
+        if (!skipping) {
+            kept.push(line);
+        }
+    }
+    let result = kept.join("\n").replace(/\n{3,}/g, "\n\n").trimEnd();
+    if (result.length > 0) {
+        result += "\n\n";
+    }
+    return `${result}${block.trimEnd()}\n`;
+}
+function nucleoCodexTomlBlock(root = installRoot()) {
+    const entry = escapeTomlString(mcpEntryPath(root));
+    const skillsRoot = escapeTomlString(root);
+    return [
+        `[mcp_servers.${MCP_SERVER_NAME}]`,
+        'command = "node"',
+        `args = ["${entry}"]`,
+        "",
+        `[mcp_servers.${MCP_SERVER_NAME}.env]`,
+        `NUCLEO_SKILLS_ROOT = "${skillsRoot}"`,
+    ].join("\n");
+}
 /** Merge nucleo-icons into ~/.cursor/mcp.json and copy skills to ~/.cursor/skills */
 export async function configureCursor(root = installRoot()) {
     const cursorDir = join(homedir(), ".cursor");
     const mcpPath = join(cursorDir, "mcp.json");
+    const skillsPath = join(cursorDir, "skills");
     await mkdir(cursorDir, { recursive: true });
     const mcp = await readJsonFile(mcpPath, { mcpServers: {} });
     mcp.mcpServers = mcp.mcpServers ?? {};
-    mcp.mcpServers["nucleo-icons"] = nucleoMcpServerConfig(root);
+    mcp.mcpServers[MCP_SERVER_NAME] = nucleoMcpServerConfig(root);
     await writeFile(mcpPath, `${JSON.stringify(mcp, null, 2)}\n`, "utf8");
-    const skills = await copySkillFolders(join(cursorDir, "skills"), root);
-    return { mcpPath, skills };
+    const skills = await copySkillFolders(skillsPath, root);
+    return { mcpPath, skillsPath, skills };
 }
-/** Copy skills to ~/.claude/skills and print MCP snippet (Claude uses `claude mcp add` or config file) */
+/**
+ * Copy skills to ~/.claude/skills and merge MCP into ~/.claude.json
+ * (user-scope mcpServers — same file `claude mcp add --scope user` writes).
+ */
 export async function configureClaude(root = installRoot()) {
     const claudeDir = join(homedir(), ".claude");
-    const skills = await copySkillFolders(join(claudeDir, "skills"), root);
-    const hint = [
-        "Add the MCP server with:",
-        "",
-        `  claude mcp add --scope user --transport stdio nucleo-icons \\`,
-        `    --env NUCLEO_SKILLS_ROOT=${root} \\`,
-        `    -- node ${mcpEntryPath(root)}`,
-        "",
-        "Or merge the same command/args/env into your Claude MCP config.",
-    ].join("\n");
-    return { skills, hint };
+    const mcpPath = join(homedir(), ".claude.json");
+    const skillsPath = join(claudeDir, "skills");
+    await mkdir(claudeDir, { recursive: true });
+    const config = await readJsonFile(mcpPath, {});
+    config.mcpServers = config.mcpServers ?? {};
+    config.mcpServers[MCP_SERVER_NAME] = {
+        type: "stdio",
+        ...nucleoMcpServerConfig(root),
+    };
+    await writeFile(mcpPath, `${JSON.stringify(config, null, 2)}\n`, "utf8");
+    const skills = await copySkillFolders(skillsPath, root);
+    return { mcpPath, skillsPath, skills };
 }
-/** Copy skills to ~/.agents/skills and print Codex config.toml snippet */
+/** Copy skills to ~/.agents/skills and merge MCP into ~/.codex/config.toml */
 export async function configureCodex(root = installRoot()) {
-    const skills = await copySkillFolders(join(homedir(), ".agents", "skills"), root);
-    const hint = [
-        "Add to ~/.codex/config.toml:",
-        "",
-        "[mcp_servers.nucleo-icons]",
-        'command = "node"',
-        `args = ["${mcpEntryPath(root)}"]`,
-        `env = { NUCLEO_SKILLS_ROOT = "${root}" }`,
-    ].join("\n");
-    return { skills, hint };
+    const codexDir = join(homedir(), ".codex");
+    const mcpPath = join(codexDir, "config.toml");
+    const skillsPath = join(homedir(), ".agents", "skills");
+    await mkdir(codexDir, { recursive: true });
+    const existing = existsSync(mcpPath) ? await readFile(mcpPath, "utf8") : "";
+    const next = upsertTomlMcpServer(existing, MCP_SERVER_NAME, nucleoCodexTomlBlock(root));
+    await writeFile(mcpPath, next, "utf8");
+    const skills = await copySkillFolders(skillsPath, root);
+    return { mcpPath, skillsPath, skills };
 }
 export async function configureTool(tool, root = installRoot()) {
     if (tool === "cursor") {
         const result = await configureCursor(root);
         console.log(`  Cursor MCP → ${result.mcpPath}`);
-        console.log(`  Cursor skills → ~/.cursor/skills/ (${result.skills.join(", ")})`);
+        console.log(`  Cursor skills → ${result.skillsPath} (${result.skills.join(", ")})`);
         return;
     }
     if (tool === "claude") {
         const result = await configureClaude(root);
-        console.log(`  Claude skills → ~/.claude/skills/ (${result.skills.join(", ")})`);
-        console.log(result.hint);
+        console.log(`  Claude MCP → ${result.mcpPath}`);
+        console.log(`  Claude skills → ${result.skillsPath} (${result.skills.join(", ")})`);
         return;
     }
     const result = await configureCodex(root);
-    console.log(`  Codex skills → ~/.agents/skills/ (${result.skills.join(", ")})`);
-    console.log(result.hint);
+    console.log(`  Codex MCP → ${result.mcpPath}`);
+    console.log(`  Codex skills → ${result.skillsPath} (${result.skills.join(", ")})`);
 }

package/dist/api.d.ts

@@ -32,6 +32,10 @@ export interface SkillsReleaseData {
     files: SkillsReleaseFile[];
     message?: string;
 }
+export interface DownloadProgress {
+    transferred: number;
+    total: number | null;
+}
 /**
  * POST /skills/login
  * Body: { email, password }
@@ -43,5 +47,10 @@ export declare function skillsLogin(email: string, password: string): Promise<Sk
  * Response: { data: { version, families, files, downloadReady } }
  */
 export declare function fetchSkillsRelease(token: string, target: PackageTarget): Promise<SkillsReleaseData>;
-/** Download a remote file (signed R2 URL) to disk. */
-export declare function downloadUrlToFile(url: string, destPath: string): Promise<void>;
+declare function formatBytes(bytes: number): string;
+/** Download a remote file (signed R2 URL) to disk, with optional progress. */
+export declare function downloadUrlToFile(url: string, destPath: string, onProgress?: (progress: DownloadProgress) => void): Promise<{
+    bytes: number;
+    total: number | null;
+}>;
+export { formatBytes };

package/dist/api.js

@@ -1,6 +1,7 @@
 import { createWriteStream } from "node:fs";
 import { mkdir } from "node:fs/promises";
 import { dirname } from "node:path";
+import { Transform } from "node:stream";
 import { pipeline } from "node:stream/promises";
 import { Readable } from "node:stream";
 import { getApiBaseUrl } from "./config.js";
@@ -84,18 +85,58 @@ export async function fetchSkillsRelease(token, target) {
     }
     return json.data;
 }
-/** Download a remote file (signed R2 URL) to disk. */
-export async function downloadUrlToFile(url, destPath) {
-    const res = await fetch(url);
+function formatBytes(bytes) {
+    if (bytes < 1024) {
+        return `${bytes} B`;
+    }
+    if (bytes < 1024 * 1024) {
+        return `${(bytes / 1024).toFixed(1)} KB`;
+    }
+    return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+/** Download a remote file (signed R2 URL) to disk, with optional progress. */
+export async function downloadUrlToFile(url, destPath, onProgress) {
+    let res;
+    try {
+        res = await fetch(url);
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        throw new ApiError(`Download failed (network): ${detail}`);
+    }
     if (!res.ok) {
-        throw new ApiError(`Download failed (${res.status}) for ${url}`, res.status);
+        throw new ApiError(`Download failed (${res.status}). The link may have expired — run setup again.`, res.status);
     }
     if (!res.body) {
         throw new ApiError("Download failed: empty response body.");
     }
+    const totalHeader = res.headers.get("content-length");
+    const total = totalHeader ? Number(totalHeader) : null;
+    let transferred = 0;
+    let lastLogged = 0;
     await mkdir(dirname(destPath), { recursive: true });
     const fileStream = createWriteStream(destPath);
-    // Node fetch body → Web ReadableStream; convert for pipeline
-    const nodeReadable = Readable.fromWeb(res.body);
-    await pipeline(nodeReadable, fileStream);
+    const progressTap = new Transform({
+        transform(chunk, _encoding, callback) {
+            transferred += chunk.length;
+            if (onProgress) {
+                onProgress({ transferred, total: Number.isFinite(total) ? total : null });
+            }
+            // Throttle console-friendly updates to ~every 2MB
+            if (transferred - lastLogged >= 2 * 1024 * 1024 || transferred === total) {
+                lastLogged = transferred;
+            }
+            callback(null, chunk);
+        },
+    });
+    try {
+        const nodeReadable = Readable.fromWeb(res.body);
+        await pipeline(nodeReadable, progressTap, fileStream);
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        throw new ApiError(`Download interrupted after ${formatBytes(transferred)}${total ? ` of ${formatBytes(total)}` : ""}: ${detail}`);
+    }
+    return { bytes: transferred, total: Number.isFinite(total) ? total : null };
 }
+export { formatBytes };

package/dist/index.js

@@ -23,11 +23,32 @@ function parseTools(value) {
         .map((t) => t.trim().toLowerCase())
         .filter(Boolean);
 }
+let verbose = false;
+function printError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(`\nError: ${message}`);
+    if (verbose && error instanceof Error && error.stack) {
+        console.error(error.stack);
+    }
+    console.error("");
+}
+process.on("unhandledRejection", (reason) => {
+    printError(reason);
+    process.exit(1);
+});
+process.on("uncaughtException", (error) => {
+    printError(error);
+    process.exit(1);
+});
 const program = new Command();
 program
     .name("nucleo-skills")
     .description("Install and update Nucleo Pro MCP + icon skills")
-    .version(packageVersion());
+    .version(packageVersion())
+    .option("-v, --verbose", "Show full error details")
+    .hook("preAction", (thisCommand) => {
+    verbose = Boolean(thisCommand.opts().verbose);
+});
 program
     .command("setup")
     .description("Sign in, download your licensed package, configure your editor")
@@ -52,7 +73,7 @@ program
         });
     }
     catch (error) {
-        console.error(`\nError: ${error instanceof Error ? error.message : String(error)}\n`);
+        printError(error);
         process.exitCode = 1;
     }
 });
@@ -73,7 +94,7 @@ program
         });
     }
     catch (error) {
-        console.error(`\nError: ${error instanceof Error ? error.message : String(error)}\n`);
+        printError(error);
         process.exitCode = 1;
     }
 });
@@ -85,7 +106,7 @@ program
         await runStatus();
     }
     catch (error) {
-        console.error(`\nError: ${error instanceof Error ? error.message : String(error)}\n`);
+        printError(error);
         process.exitCode = 1;
     }
 });
@@ -97,7 +118,7 @@ program
         await runLogout();
     }
     catch (error) {
-        console.error(`\nError: ${error instanceof Error ? error.message : String(error)}\n`);
+        printError(error);
         process.exitCode = 1;
     }
 });

package/dist/install.d.ts

@@ -4,6 +4,8 @@ export declare function readInstallManifest(root?: string): Promise<InstallManif
 export declare function cleanInstallRoot(root?: string): Promise<void>;
 /**
  * Download all release files (signed URLs) and merge into the install root.
+ * Downloads complete first, then the install folder is replaced — so a failed
+ * download does not wipe a previous working install.
  */
 export declare function installFromRelease(release: SkillsReleaseData, target: PackageTarget, root?: string): Promise<void>;
 /**

package/dist/install.js

@@ -1,10 +1,10 @@
 import { existsSync } from "node:fs";
-import { cp, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { cp, mkdir, readdir, readFile, rm, stat, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 import extract from "extract-zip";
-import { downloadUrlToFile } from "./api.js";
+import { downloadUrlToFile, formatBytes } from "./api.js";
 import { installRoot, nucleoHomeDir } from "./config.js";
 const execFileAsync = promisify(execFile);
 export async function readInstallManifest(root = installRoot()) {
@@ -23,43 +23,116 @@ export async function cleanInstallRoot(root = installRoot()) {
     await rm(root, { recursive: true, force: true });
     await mkdir(root, { recursive: true });
 }
-/** Extract one zip into dest, merging (does not wipe dest first). */
+async function canRunUnzip() {
+    try {
+        await execFileAsync("unzip", ["-v"], { timeout: 5_000 });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Extract one zip into dest (merge). Prefer system `unzip` — extract-zip + a
+ * full-tree cp of ~40k files is slow and has been hanging/exiting mid-install.
+ */
 async function extractZipMerge(zipPath, dest) {
-    const tmp = join(nucleoHomeDir(), `.extract-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`);
-    await rm(tmp, { recursive: true, force: true });
-    await mkdir(tmp, { recursive: true });
+    await mkdir(dest, { recursive: true });
+    const heartbeat = setInterval(() => {
+        process.stdout.write(".");
+    }, 2_000);
     try {
-        await extract(zipPath, { dir: tmp });
-        await mkdir(dest, { recursive: true });
-        await cp(tmp, dest, { recursive: true });
+        if (await canRunUnzip()) {
+            // -o overwrite, -q quiet (we print our own progress)
+            await execFileAsync("unzip", ["-o", "-q", zipPath, "-d", dest], {
+                maxBuffer: 16 * 1024 * 1024,
+            });
+        }
+        else {
+            // Fallback: extract directly into dest (no tmp + cp)
+            await extract(zipPath, { dir: dest });
+        }
     }
     finally {
-        await rm(tmp, { recursive: true, force: true });
+        clearInterval(heartbeat);
+        process.stdout.write("\n");
+    }
+}
+/** Fail loudly if extract left an empty/incomplete install. */
+async function assertInstallLooksComplete(root) {
+    const required = ["mcp", "skills"];
+    const missing = required.filter((name) => !existsSync(join(root, name)));
+    if (missing.length > 0) {
+        const listing = existsSync(root) ? (await readdir(root)).join(", ") || "(empty)" : "(missing)";
+        throw new Error(`Install looks incomplete at ${root}. Missing: ${missing.join(", ")}. ` +
+            `Contents: ${listing}`);
     }
 }
 /**
  * Download all release files (signed URLs) and merge into the install root.
+ * Downloads complete first, then the install folder is replaced — so a failed
+ * download does not wipe a previous working install.
  */
 export async function installFromRelease(release, target, root = installRoot()) {
     if (!release.downloadReady) {
         throw new Error(release.message ||
-            "Downloads are not ready on the server yet (R2 not configured or urls missing).");
+            "Downloads are not ready on the server yet. Please try again later.");
     }
     const missingUrl = release.files.filter((f) => !f.url);
     if (missingUrl.length > 0) {
         throw new Error(`Release files missing download urls: ${missingUrl.map((f) => f.id).join(", ")}`);
     }
-    await cleanInstallRoot(root);
     const downloadsDir = join(nucleoHomeDir(), "downloads");
     await mkdir(downloadsDir, { recursive: true });
+    const downloaded = [];
     try {
+        // 1) Download everything first (keeps existing install intact on failure)
         for (const file of release.files) {
             const zipPath = join(downloadsDir, `${file.id}-${release.version}.zip`);
-            console.log(`  ↓ ${file.id}`);
-            await downloadUrlToFile(file.url, zipPath);
-            await extractZipMerge(zipPath, root);
-            await rm(zipPath, { force: true }).catch(() => undefined);
+            process.stdout.write(`  ↓ ${file.id}`);
+            let lastLine = "";
+            try {
+                const result = await downloadUrlToFile(file.url, zipPath, ({ transferred, total }) => {
+                    const label = total
+                        ? `  ↓ ${file.id}  ${formatBytes(transferred)} / ${formatBytes(total)}`
+                        : `  ↓ ${file.id}  ${formatBytes(transferred)}`;
+                    // overwrite current line
+                    process.stdout.write(`\r${label}${" ".repeat(Math.max(0, lastLine.length - label.length))}`);
+                    lastLine = label;
+                });
+                const sizeLabel = result.total
+                    ? `${formatBytes(result.bytes)} / ${formatBytes(result.total)}`
+                    : formatBytes(result.bytes);
+                process.stdout.write(`\r  ↓ ${file.id}  ${sizeLabel}  ✓\n`);
+            }
+            catch (error) {
+                process.stdout.write("\n");
+                throw error;
+            }
+            const info = await stat(zipPath);
+            if (info.size <= 0) {
+                throw new Error(`Downloaded file is empty: ${file.id}`);
+            }
+            downloaded.push({ id: file.id, zipPath });
+        }
+        // 2) Only now replace the install root
+        console.log("  Extracting…");
+        await cleanInstallRoot(root);
+        for (const file of downloaded) {
+            const zipInfo = await stat(file.zipPath);
+            process.stdout.write(`  ▸ ${file.id} (${formatBytes(zipInfo.size)}) `);
+            try {
+                await extractZipMerge(file.zipPath, root);
+                console.log(`  ✓ ${file.id}`);
+            }
+            catch (error) {
+                const detail = error instanceof Error ? error.message : String(error);
+                throw new Error(`Failed extracting ${file.id} (${formatBytes(zipInfo.size)}). ${detail}\n` +
+                    `If this keeps happening, free disk space or try again with:\n` +
+                    `  NODE_OPTIONS=--max-old-space-size=8192 npx @nucleoicons/skills setup …`);
+            }
         }
+        await assertInstallLooksComplete(root);
     }
     finally {
         await rm(downloadsDir, { recursive: true, force: true }).catch(() => undefined);
@@ -116,11 +189,19 @@ export async function buildMcp(root = installRoot()) {
     }
     const distEntry = join(mcpDir, "dist", "index.js");
     const hasDist = existsSync(distEntry);
-    await execFileAsync("npm", ["install", "--omit=dev"], {
-        cwd: mcpDir,
-        env: process.env,
-    });
+    console.log("  npm install (mcp)…");
+    try {
+        await execFileAsync("npm", ["install", "--omit=dev"], {
+            cwd: mcpDir,
+            env: process.env,
+        });
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        throw new Error(`MCP dependency install failed: ${detail}`);
+    }
     if (!hasDist || existsSync(join(mcpDir, "src"))) {
+        console.log("  npm run build (mcp)…");
         try {
             await execFileAsync("npm", ["run", "build"], {
                 cwd: mcpDir,
@@ -129,7 +210,8 @@ export async function buildMcp(root = installRoot()) {
         }
         catch (error) {
             if (!existsSync(distEntry)) {
-                throw error;
+                const detail = error instanceof Error ? error.message : String(error);
+                throw new Error(`MCP build failed: ${detail}`);
             }
         }
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nucleoicons/skills",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "CLI to install and update Nucleo Pro MCP + icon skills",
   "type": "module",
   "bin": {