@nucleoicons/skills 0.1.0

package/README.md

@@ -0,0 +1,51 @@
+# @nucleoicons/skills
+
+CLI to install and update **Nucleo** MCP + icon skills on your machine.
+
+Requires **Node.js 20+**.
+
+## Install
+
+```bash
+npx @nucleoicons/skills setup --target react --tools cursor
+```
+
+**Required for setup:** `--target` (`react` or `vanilla`) and `--tools` (e.g. `cursor`, or `cursor,claude`).
+
+```bash
+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.
+
+After setup, follow any MCP steps printed in the terminal, reload MCP in your editor, then ask:
+
+> What Nucleo icon families do I have?
+
+## Update
+
+```bash
+npx @nucleoicons/skills update
+```
+
+```bash
+npx @nucleoicons/skills update --check   # only report whether an update is available
+```
+
+After updating, reload MCP in your editor again.
+
+## Other commands
+
+```bash
+npx @nucleoicons/skills status   # install path, version, sign-in
+npx @nucleoicons/skills logout   # remove saved credentials
+```
+
+## Editors
+
+| Tool            | What setup does                                                    |
+| --------------- | ------------------------------------------------------------------ |
+| **Cursor**      | Writes `~/.cursor/mcp.json` + copies skills to `~/.cursor/skills/` |
+| **Claude Code** | Copies skills; prints `claude mcp add …` command                   |
+| **Codex**       | Copies skills to `~/.agents/skills/`; prints `config.toml` snippet |

package/dist/adapters/agents.d.ts

@@ -0,0 +1,17 @@
+import { type AgentTool } from "../config.js";
+/** Merge nucleo-icons into ~/.cursor/mcp.json and copy skills to ~/.cursor/skills */
+export declare function configureCursor(root?: string): Promise<{
+    mcpPath: string;
+    skills: string[];
+}>;
+/** Copy skills to ~/.claude/skills and print MCP snippet (Claude uses `claude mcp add` or config file) */
+export declare function configureClaude(root?: string): Promise<{
+    skills: string[];
+    hint: string;
+}>;
+/** Copy skills to ~/.agents/skills and print Codex config.toml snippet */
+export declare function configureCodex(root?: string): Promise<{
+    skills: string[];
+    hint: string;
+}>;
+export declare function configureTool(tool: AgentTool, root?: string): Promise<void>;

package/dist/adapters/agents.js

@@ -0,0 +1,99 @@
+import { existsSync } from "node:fs";
+import { cp, mkdir, readFile, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { installRoot } from "../config.js";
+import { mcpEntryPath, skillsSourceDir } from "../install.js";
+async function readJsonFile(path, fallback) {
+    if (!existsSync(path)) {
+        return fallback;
+    }
+    try {
+        return JSON.parse(await readFile(path, "utf8"));
+    }
+    catch {
+        return fallback;
+    }
+}
+async function copySkillFolders(destSkillsRoot, root = installRoot()) {
+    const source = skillsSourceDir(root);
+    if (!existsSync(source)) {
+        throw new Error(`No skills/ folder in install at ${source}`);
+    }
+    const { readdir } = await import("node:fs/promises");
+    const entries = await readdir(source, { withFileTypes: true });
+    const skillDirs = entries.filter((e) => e.isDirectory()).map((e) => e.name);
+    await mkdir(destSkillsRoot, { recursive: true });
+    for (const name of skillDirs) {
+        const from = join(source, name);
+        const to = join(destSkillsRoot, name);
+        await cp(from, to, { recursive: true });
+    }
+    return skillDirs;
+}
+function nucleoMcpServerConfig(root = installRoot()) {
+    return {
+        command: "node",
+        args: [mcpEntryPath(root)],
+        env: {
+            NUCLEO_SKILLS_ROOT: root,
+        },
+    };
+}
+/** 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");
+    await mkdir(cursorDir, { recursive: true });
+    const mcp = await readJsonFile(mcpPath, { mcpServers: {} });
+    mcp.mcpServers = mcp.mcpServers ?? {};
+    mcp.mcpServers["nucleo-icons"] = nucleoMcpServerConfig(root);
+    await writeFile(mcpPath, `${JSON.stringify(mcp, null, 2)}\n`, "utf8");
+    const skills = await copySkillFolders(join(cursorDir, "skills"), root);
+    return { mcpPath, skills };
+}
+/** Copy skills to ~/.claude/skills and print MCP snippet (Claude uses `claude mcp add` or config file) */
+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 };
+}
+/** Copy skills to ~/.agents/skills and print Codex config.toml snippet */
+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 };
+}
+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(", ")})`);
+        return;
+    }
+    if (tool === "claude") {
+        const result = await configureClaude(root);
+        console.log(`  Claude skills → ~/.claude/skills/ (${result.skills.join(", ")})`);
+        console.log(result.hint);
+        return;
+    }
+    const result = await configureCodex(root);
+    console.log(`  Codex skills → ~/.agents/skills/ (${result.skills.join(", ")})`);
+    console.log(result.hint);
+}

package/dist/api.d.ts

@@ -0,0 +1,47 @@
+import { type PackageTarget } from "./config.js";
+export declare class ApiError extends Error {
+    readonly status?: number | undefined;
+    readonly body?: string | undefined;
+    constructor(message: string, status?: number | undefined, body?: string | undefined);
+}
+/** POST /skills/login → data */
+export interface SkillsLoginData {
+    id: number | string;
+    token: string;
+    email: string;
+    families: string[];
+    nucleo_icons_core?: number;
+    nucleo_icons_ui?: number;
+    nucleo_icons_axis?: number;
+    nucleo_icons_micro?: number;
+    nucleo_icons_sharp?: number;
+    nucleo_icons_pixel?: number;
+}
+export interface SkillsReleaseFile {
+    id: string;
+    key: string;
+    url: string | null;
+    expiresAt: string | null;
+}
+/** GET /skills/release → data */
+export interface SkillsReleaseData {
+    version: string;
+    target: PackageTarget | string;
+    families: string[];
+    downloadReady: boolean;
+    files: SkillsReleaseFile[];
+    message?: string;
+}
+/**
+ * POST /skills/login
+ * Body: { email, password }
+ * Response: { data: { token, email, families, ... } }
+ */
+export declare function skillsLogin(email: string, password: string): Promise<SkillsLoginData>;
+/**
+ * GET /skills/release?token=…&target=react|vanilla
+ * 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>;

package/dist/api.js

@@ -0,0 +1,101 @@
+import { createWriteStream } from "node:fs";
+import { mkdir } from "node:fs/promises";
+import { dirname } from "node:path";
+import { pipeline } from "node:stream/promises";
+import { Readable } from "node:stream";
+import { getApiBaseUrl } from "./config.js";
+export class ApiError extends Error {
+    status;
+    body;
+    constructor(message, status, body) {
+        super(message);
+        this.status = status;
+        this.body = body;
+        this.name = "ApiError";
+    }
+}
+async function readErrorBody(res) {
+    try {
+        return await res.text();
+    }
+    catch {
+        return "";
+    }
+}
+function parseApiErrorMessage(body, fallback) {
+    try {
+        const parsed = JSON.parse(body);
+        const details = parsed.errors?.details || parsed.errors?.title;
+        if (details) {
+            return details;
+        }
+    }
+    catch {
+        // ignore
+    }
+    return fallback;
+}
+/**
+ * POST /skills/login
+ * Body: { email, password }
+ * Response: { data: { token, email, families, ... } }
+ */
+export async function skillsLogin(email, password) {
+    const url = `${getApiBaseUrl()}/skills/login`;
+    const res = await fetch(url, {
+        method: "POST",
+        headers: {
+            Accept: "application/json",
+            "Content-Type": "application/json",
+        },
+        body: JSON.stringify({ email, password }),
+    });
+    const body = await readErrorBody(res);
+    if (!res.ok) {
+        throw new ApiError(parseApiErrorMessage(body, `Login failed (${res.status}).`), res.status, body);
+    }
+    const json = JSON.parse(body);
+    if (!json.data?.token) {
+        throw new ApiError("Login response missing token.", res.status, body);
+    }
+    if (!Array.isArray(json.data.families) || json.data.families.length === 0) {
+        throw new ApiError("This account has no Nucleo icon family access.", 403, body);
+    }
+    return json.data;
+}
+/**
+ * GET /skills/release?token=…&target=react|vanilla
+ * Response: { data: { version, families, files, downloadReady } }
+ */
+export async function fetchSkillsRelease(token, target) {
+    const url = new URL(`${getApiBaseUrl()}/skills/release`);
+    url.searchParams.set("token", token);
+    url.searchParams.set("target", target);
+    const res = await fetch(url, {
+        headers: { Accept: "application/json" },
+    });
+    const body = await readErrorBody(res);
+    if (!res.ok) {
+        throw new ApiError(parseApiErrorMessage(body, `Could not fetch release (${res.status}).`), res.status, body);
+    }
+    const json = JSON.parse(body);
+    if (!json.data?.version || !Array.isArray(json.data.files)) {
+        throw new ApiError("Release response missing version/files.", res.status, body);
+    }
+    return json.data;
+}
+/** Download a remote file (signed R2 URL) to disk. */
+export async function downloadUrlToFile(url, destPath) {
+    const res = await fetch(url);
+    if (!res.ok) {
+        throw new ApiError(`Download failed (${res.status}) for ${url}`, res.status);
+    }
+    if (!res.body) {
+        throw new ApiError("Download failed: empty response body.");
+    }
+    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);
+}

package/dist/commands/logout.d.ts

@@ -0,0 +1 @@
+export declare function runLogout(): Promise<void>;

package/dist/commands/logout.js

@@ -0,0 +1,8 @@
+import { clearCredentials } from "../credentials.js";
+import { credentialsPath } from "../config.js";
+export async function runLogout() {
+    await clearCredentials();
+    console.log(`✓ Signed out (removed ${credentialsPath()})`);
+    console.log("  Local install at ~/.nucleo/skills was kept.");
+    console.log("  Run nucleo-skills setup to sign in again.\n");
+}

package/dist/commands/setup.d.ts

@@ -0,0 +1,10 @@
+import type { AgentTool, PackageTarget } from "../config.js";
+export interface SetupOptions {
+    /** Skip API; copy a local prepared package directory */
+    from?: string;
+    target?: PackageTarget;
+    tools?: AgentTool[];
+    email?: string;
+    yes?: boolean;
+}
+export declare function runSetup(options?: SetupOptions): Promise<void>;

package/dist/commands/setup.js

@@ -0,0 +1,94 @@
+import { mkdir } from "node:fs/promises";
+import { confirm, select, checkbox } from "@inquirer/prompts";
+import { ApiError, fetchSkillsRelease } from "../api.js";
+import { installRoot, nucleoHomeDir } from "../config.js";
+import { buildMcp, ensureManifestTarget, installFromLocalDir, installFromRelease, readInstallManifest, } from "../install.js";
+import { configureTool } from "../adapters/agents.js";
+import { ensureSkillsSession, isInvalidTokenError } from "../session.js";
+async function fetchReleaseWithSession(target, emailHint) {
+    let session = await ensureSkillsSession(emailHint);
+    try {
+        return await fetchSkillsRelease(session.token, target);
+    }
+    catch (error) {
+        if (isInvalidTokenError(error)) {
+            console.log("Saved session expired or invalid — please sign in again.");
+            session = await ensureSkillsSession(emailHint, { forceLogin: true });
+            return await fetchSkillsRelease(session.token, target);
+        }
+        throw error;
+    }
+}
+export async function runSetup(options = {}) {
+    console.log("\nNucleo Skills setup");
+    console.log("───────────────────\n");
+    const target = options.target ??
+        (await select({
+            message: "Which package?",
+            choices: [
+                { name: "React components", value: "react" },
+                { name: "Vanilla SVG", value: "vanilla" },
+            ],
+        }));
+    const tools = options.tools ??
+        (await checkbox({
+            message: "Configure which tools? (space to toggle, enter to confirm)",
+            choices: [
+                { name: "Cursor", value: "cursor", checked: true },
+                { name: "Claude Code", value: "claude" },
+                { name: "Codex", value: "codex" },
+            ],
+            required: true,
+        }));
+    if (tools.length === 0) {
+        throw new Error("Select at least one tool to configure.");
+    }
+    await mkdir(nucleoHomeDir(), { recursive: true });
+    if (options.from) {
+        console.log(`\nInstalling from local folder:\n  ${options.from}\n`);
+        if (!options.yes) {
+            const ok = await confirm({
+                message: "Continue? (no API login — for testing only)",
+                default: true,
+            });
+            if (!ok) {
+                console.log("Cancelled.");
+                return;
+            }
+        }
+        await installFromLocalDir(options.from);
+        await ensureManifestTarget(target);
+    }
+    else {
+        console.log(`Fetching ${target} release…`);
+        let release;
+        try {
+            release = await fetchReleaseWithSession(target, options.email);
+        }
+        catch (error) {
+            if (error instanceof ApiError) {
+                throw new Error(error.message);
+            }
+            throw error;
+        }
+        console.log(`  Version:  ${release.version}`);
+        console.log(`  Families: ${release.families.join(", ")}`);
+        console.log(`  Files:    ${release.files.map((f) => f.id).join(", ")}`);
+        console.log("\nDownloading…");
+        await installFromRelease(release, target);
+    }
+    console.log("Building MCP…");
+    await buildMcp();
+    console.log("\nConfiguring agents…");
+    for (const tool of tools) {
+        await configureTool(tool);
+    }
+    const manifest = await readInstallManifest();
+    console.log("\n✓ Done");
+    console.log(`  Install path: ${installRoot()}`);
+    console.log(`  Target:       ${manifest?.target ?? target}`);
+    console.log(`  Version:      ${manifest?.version ?? "(none)"}`);
+    console.log(`  Families:     ${(manifest?.families ?? []).join(", ") || "(see manifest)"}`);
+    console.log("\nNext: reload MCP in your editor, then ask:");
+    console.log('  “What Nucleo icon families do I have?”\n');
+}

package/dist/commands/status.d.ts

@@ -0,0 +1 @@
+export declare function runStatus(): Promise<void>;

package/dist/commands/status.js

@@ -0,0 +1,30 @@
+import { existsSync } from "node:fs";
+import { installRoot, credentialsPath } from "../config.js";
+import { loadCredentials } from "../credentials.js";
+import { mcpEntryPath, readInstallManifest } from "../install.js";
+export async function runStatus() {
+    console.log("\nNucleo Skills status");
+    console.log("────────────────────\n");
+    console.log(`Credentials: ${existsSync(credentialsPath()) ? credentialsPath() : "(none)"}`);
+    const creds = await loadCredentials();
+    if (creds) {
+        console.log(`Signed in:   ${creds.email}`);
+        console.log(`Token saved: ${creds.savedAt}`);
+    }
+    else {
+        console.log("Signed in:   no");
+    }
+    const root = installRoot();
+    console.log(`\nInstall:     ${root}`);
+    if (!existsSync(root)) {
+        console.log("             (not installed — run nucleo-skills setup)\n");
+        return;
+    }
+    const manifest = await readInstallManifest();
+    console.log(`Version:     ${manifest?.version ?? "(missing)"}`);
+    console.log(`Target:      ${manifest?.target ?? "(missing)"}`);
+    console.log(`Product:     ${manifest?.product ?? "(missing)"}`);
+    console.log(`Families:    ${(manifest?.families ?? []).join(", ") || "(none)"}`);
+    console.log(`MCP entry:   ${existsSync(mcpEntryPath()) ? mcpEntryPath() : "(missing — run setup/update)"}`);
+    console.log("");
+}

package/dist/commands/update.d.ts

@@ -0,0 +1,8 @@
+import { type AgentTool } from "../config.js";
+export interface UpdateOptions {
+    from?: string;
+    check?: boolean;
+    tools?: AgentTool[];
+    yes?: boolean;
+}
+export declare function runUpdate(options?: UpdateOptions): Promise<void>;

package/dist/commands/update.js

@@ -0,0 +1,94 @@
+import { confirm } from "@inquirer/prompts";
+import { ApiError, fetchSkillsRelease } from "../api.js";
+import { installRoot } from "../config.js";
+import { buildMcp, ensureManifestTarget, installFromLocalDir, installFromRelease, readInstallManifest, } from "../install.js";
+import { configureTool } from "../adapters/agents.js";
+import { ensureSkillsSession, isInvalidTokenError } from "../session.js";
+async function fetchReleaseWithSession(target) {
+    let session = await ensureSkillsSession();
+    try {
+        return await fetchSkillsRelease(session.token, target);
+    }
+    catch (error) {
+        if (isInvalidTokenError(error)) {
+            console.log("Saved session expired or invalid — please sign in again.");
+            session = await ensureSkillsSession(undefined, { forceLogin: true });
+            return await fetchSkillsRelease(session.token, target);
+        }
+        throw error;
+    }
+}
+export async function runUpdate(options = {}) {
+    console.log("\nNucleo Skills update");
+    console.log("────────────────────\n");
+    const manifest = await readInstallManifest();
+    if (!manifest && !options.from) {
+        throw new Error(`No install found at ${installRoot()}.\nRun: nucleo-skills setup`);
+    }
+    const target = manifest?.target ?? "react";
+    const localVersion = manifest?.version ?? "0.0.0";
+    if (options.from) {
+        console.log(`Updating from local folder:\n  ${options.from}\n`);
+        await installFromLocalDir(options.from);
+        await ensureManifestTarget(target);
+        console.log("Building MCP…");
+        await buildMcp();
+        await reconfigure(options.tools);
+        const next = await readInstallManifest();
+        console.log(`\n✓ Updated (local)`);
+        console.log(`  Version: ${next?.version ?? "(none)"}`);
+        return;
+    }
+    let release;
+    try {
+        release = await fetchReleaseWithSession(target);
+    }
+    catch (error) {
+        if (error instanceof ApiError) {
+            throw new Error(error.message);
+        }
+        throw error;
+    }
+    const remoteVersion = release.version;
+    console.log(`  Installed: ${localVersion}`);
+    console.log(`  Latest:    ${remoteVersion}`);
+    console.log(`  Families:  ${release.families.join(", ")}`);
+    if (options.check) {
+        if (remoteVersion === localVersion) {
+            console.log("\nAlready up to date.");
+        }
+        else {
+            console.log("\nUpdate available. Run: nucleo-skills update");
+        }
+        return;
+    }
+    if (remoteVersion === localVersion) {
+        console.log("\nAlready up to date.");
+        return;
+    }
+    if (!options.yes) {
+        const ok = await confirm({
+            message: `Download and install ${remoteVersion}?`,
+            default: true,
+        });
+        if (!ok) {
+            console.log("Cancelled.");
+            return;
+        }
+    }
+    console.log("\nDownloading…");
+    await installFromRelease(release, target);
+    console.log("Building MCP…");
+    await buildMcp();
+    await reconfigure(options.tools ?? ["cursor"]);
+    const next = await readInstallManifest();
+    console.log(`\n✓ Updated to ${next?.version ?? remoteVersion}`);
+    console.log("  Reload MCP in your editor.\n");
+}
+async function reconfigure(tools) {
+    const list = tools && tools.length > 0 ? tools : ["cursor"];
+    console.log("Refreshing agent config…");
+    for (const tool of list) {
+        await configureTool(tool);
+    }
+}

package/dist/config.d.ts

@@ -0,0 +1,22 @@
+/** Default Nucleo API base. Override with NUCLEO_API_URL. */
+export declare const DEFAULT_API_URL = "https://nucleoapp.com/api";
+export declare function getApiBaseUrl(): string;
+/** Root for credentials + installed skills package */
+export declare function nucleoHomeDir(): string;
+export declare function credentialsPath(): string;
+/** Where the downloaded Pro package lives (MCP, skills, icons) */
+export declare function installRoot(): string;
+export type PackageTarget = "react" | "vanilla";
+export type AgentTool = "cursor" | "claude" | "codex";
+export interface NucleoCredentials {
+    email: string;
+    token: string;
+    savedAt: string;
+}
+export interface InstallManifest {
+    product?: string;
+    target?: PackageTarget | string;
+    version?: string;
+    families?: string[];
+    [key: string]: unknown;
+}

package/dist/config.js

@@ -0,0 +1,21 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+/** Default Nucleo API base. Override with NUCLEO_API_URL. */
+export const DEFAULT_API_URL = "https://nucleoapp.com/api";
+export function getApiBaseUrl() {
+    return (process.env.NUCLEO_API_URL?.trim() || DEFAULT_API_URL).replace(/\/$/, "");
+}
+/** Root for credentials + installed skills package */
+export function nucleoHomeDir() {
+    if (process.env.NUCLEO_HOME?.trim()) {
+        return process.env.NUCLEO_HOME.trim();
+    }
+    return join(homedir(), ".nucleo");
+}
+export function credentialsPath() {
+    return join(nucleoHomeDir(), "credentials.json");
+}
+/** Where the downloaded Pro package lives (MCP, skills, icons) */
+export function installRoot() {
+    return join(nucleoHomeDir(), "skills");
+}

package/dist/credentials.d.ts

@@ -0,0 +1,4 @@
+import { type NucleoCredentials } from "./config.js";
+export declare function loadCredentials(): Promise<NucleoCredentials | null>;
+export declare function saveCredentials(creds: Omit<NucleoCredentials, "savedAt">): Promise<void>;
+export declare function clearCredentials(): Promise<void>;

package/dist/credentials.js

@@ -0,0 +1,41 @@
+import { chmod, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { credentialsPath, nucleoHomeDir } from "./config.js";
+export async function loadCredentials() {
+    const path = credentialsPath();
+    if (!existsSync(path)) {
+        return null;
+    }
+    try {
+        const raw = await readFile(path, "utf8");
+        const parsed = JSON.parse(raw);
+        if (!parsed.token || !parsed.email) {
+            return null;
+        }
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+export async function saveCredentials(creds) {
+    await mkdir(nucleoHomeDir(), { recursive: true });
+    const path = credentialsPath();
+    const payload = {
+        ...creds,
+        savedAt: new Date().toISOString(),
+    };
+    await writeFile(path, `${JSON.stringify(payload, null, 2)}\n`, "utf8");
+    try {
+        await chmod(path, 0o600);
+    }
+    catch {
+        // Windows may ignore chmod; that's ok
+    }
+}
+export async function clearCredentials() {
+    const path = credentialsPath();
+    if (existsSync(path)) {
+        await rm(path, { force: true });
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,104 @@
+#!/usr/bin/env node
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { Command } from "commander";
+import { runLogout } from "./commands/logout.js";
+import { runSetup } from "./commands/setup.js";
+import { runStatus } from "./commands/status.js";
+import { runUpdate } from "./commands/update.js";
+function packageVersion() {
+    try {
+        const pkgPath = join(dirname(fileURLToPath(import.meta.url)), "..", "package.json");
+        const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+        return pkg.version || "0.0.0";
+    }
+    catch {
+        return "0.0.0";
+    }
+}
+function parseTools(value) {
+    return value
+        .split(",")
+        .map((t) => t.trim().toLowerCase())
+        .filter(Boolean);
+}
+const program = new Command();
+program
+    .name("nucleo-skills")
+    .description("Install and update Nucleo Pro MCP + icon skills")
+    .version(packageVersion());
+program
+    .command("setup")
+    .description("Sign in, download your licensed package, configure your editor")
+    .option("-t, --target <target>", "react | vanilla")
+    .option("--tools <list>", "comma-separated: cursor,claude,codex (default: prompt, or cursor with --yes)")
+    .option("--from <dir>", "Install from a local prepared package (skip API download)")
+    .option("--email <email>", "Nucleo account email (skip prompt)")
+    .option("-y, --yes", "Skip confirmation prompts")
+    .action(async (opts) => {
+    try {
+        const tools = opts.tools
+            ? parseTools(opts.tools)
+            : opts.yes
+                ? ["cursor"]
+                : undefined;
+        await runSetup({
+            from: opts.from,
+            target: opts.target,
+            tools,
+            email: opts.email,
+            yes: Boolean(opts.yes),
+        });
+    }
+    catch (error) {
+        console.error(`\nError: ${error instanceof Error ? error.message : String(error)}\n`);
+        process.exitCode = 1;
+    }
+});
+program
+    .command("update")
+    .description("Download the latest package and refresh MCP/skills")
+    .option("--from <dir>", "Update from a local prepared package (skip API)")
+    .option("--check", "Only check whether an update is available")
+    .option("--tools <list>", "comma-separated tools to refresh", "cursor")
+    .option("-y, --yes", "Skip confirmation prompts")
+    .action(async (opts) => {
+    try {
+        await runUpdate({
+            from: opts.from,
+            check: Boolean(opts.check),
+            tools: parseTools(opts.tools),
+            yes: Boolean(opts.yes),
+        });
+    }
+    catch (error) {
+        console.error(`\nError: ${error instanceof Error ? error.message : String(error)}\n`);
+        process.exitCode = 1;
+    }
+});
+program
+    .command("status")
+    .description("Show install path, version, and sign-in state")
+    .action(async () => {
+    try {
+        await runStatus();
+    }
+    catch (error) {
+        console.error(`\nError: ${error instanceof Error ? error.message : String(error)}\n`);
+        process.exitCode = 1;
+    }
+});
+program
+    .command("logout")
+    .description("Remove saved Nucleo credentials")
+    .action(async () => {
+    try {
+        await runLogout();
+    }
+    catch (error) {
+        console.error(`\nError: ${error instanceof Error ? error.message : String(error)}\n`);
+        process.exitCode = 1;
+    }
+});
+program.parse();

package/dist/install.d.ts

@@ -0,0 +1,18 @@
+import { type SkillsReleaseData } from "./api.js";
+import { type InstallManifest, type PackageTarget } from "./config.js";
+export declare function readInstallManifest(root?: string): Promise<InstallManifest | null>;
+export declare function cleanInstallRoot(root?: string): Promise<void>;
+/**
+ * Download all release files (signed URLs) and merge into the install root.
+ */
+export declare function installFromRelease(release: SkillsReleaseData, target: PackageTarget, root?: string): Promise<void>;
+/**
+ * Copy a local prepared package (e.g. packages/react) into the install root.
+ */
+export declare function installFromLocalDir(sourceDir: string, root?: string): Promise<void>;
+export declare function writeInstallManifest(manifest: InstallManifest, root?: string): Promise<void>;
+export declare function ensureManifestTarget(target: PackageTarget, extras?: Partial<InstallManifest>, root?: string): Promise<InstallManifest>;
+/** Ensure mcp deps are installed and dist is built */
+export declare function buildMcp(root?: string): Promise<void>;
+export declare function mcpEntryPath(root?: string): string;
+export declare function skillsSourceDir(root?: string): string;

package/dist/install.js

@@ -0,0 +1,145 @@
+import { existsSync } from "node:fs";
+import { cp, mkdir, readFile, rm, 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 { installRoot, nucleoHomeDir } from "./config.js";
+const execFileAsync = promisify(execFile);
+export async function readInstallManifest(root = installRoot()) {
+    const path = join(root, "manifest.json");
+    if (!existsSync(path)) {
+        return null;
+    }
+    try {
+        return JSON.parse(await readFile(path, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+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 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 });
+    try {
+        await extract(zipPath, { dir: tmp });
+        await mkdir(dest, { recursive: true });
+        await cp(tmp, dest, { recursive: true });
+    }
+    finally {
+        await rm(tmp, { recursive: true, force: true });
+    }
+}
+/**
+ * Download all release files (signed URLs) and merge into the install root.
+ */
+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).");
+    }
+    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 });
+    try {
+        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);
+        }
+    }
+    finally {
+        await rm(downloadsDir, { recursive: true, force: true }).catch(() => undefined);
+    }
+    await writeInstallManifest({
+        product: "nucleo-skills",
+        target,
+        version: release.version,
+        families: release.families,
+    }, root);
+}
+/**
+ * Copy a local prepared package (e.g. packages/react) into the install root.
+ */
+export async function installFromLocalDir(sourceDir, root = installRoot()) {
+    if (!existsSync(sourceDir)) {
+        throw new Error(`Local package path not found: ${sourceDir}`);
+    }
+    await cleanInstallRoot(root);
+    await cp(sourceDir, root, { recursive: true });
+}
+export async function writeInstallManifest(manifest, root = installRoot()) {
+    await mkdir(root, { recursive: true });
+    await writeFile(join(root, "manifest.json"), `${JSON.stringify(manifest, null, 2)}\n`, "utf8");
+}
+export async function ensureManifestTarget(target, extras = {}, root = installRoot()) {
+    const path = join(root, "manifest.json");
+    let manifest = {};
+    if (existsSync(path)) {
+        try {
+            manifest = JSON.parse(await readFile(path, "utf8"));
+        }
+        catch {
+            manifest = {};
+        }
+    }
+    manifest = {
+        ...manifest,
+        ...extras,
+        target: extras.target ?? manifest.target ?? target,
+        version: extras.version ?? manifest.version ?? "0.0.0-local",
+    };
+    if (extras.families) {
+        manifest.families = extras.families;
+    }
+    await writeInstallManifest(manifest, root);
+    return manifest;
+}
+/** Ensure mcp deps are installed and dist is built */
+export async function buildMcp(root = installRoot()) {
+    const mcpDir = join(root, "mcp");
+    if (!existsSync(mcpDir)) {
+        throw new Error(`MCP folder missing at ${mcpDir}. Package may be incomplete.`);
+    }
+    const distEntry = join(mcpDir, "dist", "index.js");
+    const hasDist = existsSync(distEntry);
+    await execFileAsync("npm", ["install", "--omit=dev"], {
+        cwd: mcpDir,
+        env: process.env,
+    });
+    if (!hasDist || existsSync(join(mcpDir, "src"))) {
+        try {
+            await execFileAsync("npm", ["run", "build"], {
+                cwd: mcpDir,
+                env: process.env,
+            });
+        }
+        catch (error) {
+            if (!existsSync(distEntry)) {
+                throw error;
+            }
+        }
+    }
+    if (!existsSync(distEntry)) {
+        throw new Error(`MCP build missing: expected ${distEntry}`);
+    }
+}
+export function mcpEntryPath(root = installRoot()) {
+    return join(root, "mcp", "dist", "index.js");
+}
+export function skillsSourceDir(root = installRoot()) {
+    return join(root, "skills");
+}

package/dist/session.d.ts

@@ -0,0 +1,12 @@
+export interface SkillsSession {
+    email: string;
+    token: string;
+}
+/**
+ * Return a skills session. Reuses ~/.nucleo/credentials.json when present.
+ * Pass forceLogin=true after an invalid-token release error.
+ */
+export declare function ensureSkillsSession(emailHint?: string, options?: {
+    forceLogin?: boolean;
+}): Promise<SkillsSession>;
+export declare function isInvalidTokenError(error: unknown): boolean;

package/dist/session.js

@@ -0,0 +1,64 @@
+import { password, input } from "@inquirer/prompts";
+import { ApiError, skillsLogin } from "./api.js";
+import { clearCredentials, loadCredentials, saveCredentials } from "./credentials.js";
+function formatLoginError(error) {
+    const msg = error.message;
+    if (/wrong credentials|authentication/i.test(msg)) {
+        return "Wrong email or password. Check your Nucleo credentials and try again.";
+    }
+    if (/no .+icon|icon family|icon access/i.test(msg)) {
+        return "This Nucleo account has no icon family access. A Pro icon license is required.";
+    }
+    if (error.status === 404 || error.status === 501) {
+        return "Could not sign in right now. Please try again later.";
+    }
+    if (!error.status) {
+        return "Could not reach Nucleo. Check your internet connection and try again.";
+    }
+    return msg;
+}
+async function promptLogin(emailHint) {
+    const email = emailHint ??
+        (await input({
+            message: "Nucleo email",
+            validate: (v) => (v.includes("@") ? true : "Enter a valid email"),
+        }));
+    const pwd = await password({ message: "Password", mask: "*" });
+    let loginResult;
+    try {
+        loginResult = await skillsLogin(email, pwd);
+    }
+    catch (error) {
+        if (error instanceof ApiError) {
+            throw new Error(formatLoginError(error));
+        }
+        throw error;
+    }
+    const resolvedEmail = loginResult.email || email;
+    await saveCredentials({ email: resolvedEmail, token: loginResult.token });
+    console.log(`✓ Signed in as ${resolvedEmail}`);
+    console.log(`  Families: ${loginResult.families.join(", ")}`);
+    return { email: resolvedEmail, token: loginResult.token };
+}
+/**
+ * Return a skills session. Reuses ~/.nucleo/credentials.json when present.
+ * Pass forceLogin=true after an invalid-token release error.
+ */
+export async function ensureSkillsSession(emailHint, options = {}) {
+    if (!options.forceLogin) {
+        const existing = await loadCredentials();
+        if (existing?.token) {
+            console.log(`✓ Signed in as ${existing.email}`);
+            return { email: existing.email, token: existing.token };
+        }
+    }
+    else {
+        await clearCredentials();
+    }
+    return promptLogin(emailHint);
+}
+export function isInvalidTokenError(error) {
+    return (error instanceof ApiError &&
+        (error.status === 400 || error.status === 401) &&
+        /token|credentials|authentication/i.test(error.message));
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@nucleoicons/skills",
+  "version": "0.1.0",
+  "description": "CLI to install and update Nucleo Pro MCP + icon skills",
+  "type": "module",
+  "bin": {
+    "nucleo-skills": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "node dist/index.js",
+    "prepublishOnly": "npm run build"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "nucleo",
+    "icons",
+    "mcp",
+    "cursor",
+    "cli",
+    "skills"
+  ],
+  "license": "UNLICENSED",
+  "publishConfig": {
+    "access": "public"
+  },
+  "homepage": "https://nucleoapp.com",
+  "dependencies": {
+    "@inquirer/prompts": "^7.5.0",
+    "commander": "^13.1.0",
+    "extract-zip": "^2.0.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.13.10",
+    "typescript": "^5.8.2"
+  }
+}