@nucleoicons/skills 0.1.7 → 0.1.9

package/README.md

@@ -5,7 +5,7 @@ CLI to install and update **Nucleo** MCP + icon skills on your machine.
 Once installed, your AI coding tool can help you **use Nucleo icons in code**. Typical uses:
 
 - Search icons by name or idea across your installed families (Pro and/or free)
-- Pick an icon and get the right React component or SVG for your project
+- Pick an icon and get the right **React** component, **Vue** SFC, or **vanilla SVG** for your project
 - Customize icons when inserting them (color, secondary color, stroke width, duo opacity, corners)
 
 Ask your editor naturally, for example: “find a settings icon in Nucleo” or “insert the home icon as a React component.”
@@ -14,7 +14,7 @@ Requires **Node.js 20+**.
 
 ## Install
 
-**Pro** (Nucleo account — licensed families):
+**Pro** (Nucleo account — licensed families **plus** free sets in the same install):
 
 ```bash
 npx @nucleoicons/skills setup --target react --tools cursor
@@ -26,13 +26,21 @@ npx @nucleoicons/skills setup --target react --tools cursor
 npx @nucleoicons/skills setup --free --target react --tools cursor
 ```
 
-**Required for setup:** `--target` (`react` or `vanilla`) and `--tools` (`cursor`, `claude`, `codex`).
+**Required for setup:** `--target` (`react`, `vue`, or `vanilla`) and `--tools` (`cursor`, `claude`, `codex`).
 
 ```bash
 npx @nucleoicons/skills setup --target react --tools cursor
-npx @nucleoicons/skills setup --free --target vanilla --tools cursor,claude
+npx @nucleoicons/skills setup --target vue --tools cursor
+npx @nucleoicons/skills setup --target vanilla --tools cursor,claude
+npx @nucleoicons/skills setup --free --target vue --tools cursor
 ```
 
+| `--target` | What you get              |
+| ---------- | ------------------------- |
+| `react`    | React components (`.tsx`) |
+| `vue`      | Vue SFCs (`.vue`)         |
+| `vanilla`  | SVG files                 |
+
 Setup installs the package under your user home (`~/.nucleo/skills`) and configures the editors you choose (skills + MCP, no manual config step).
 
 Reload MCP in your editor, then ask something like:
@@ -57,8 +65,8 @@ After updating, reload MCP in your editor again.
 
 ## Editors
 
-| Tool        | `--tools` value | Auto-configured |
-| ----------- | --------------- | --------------- |
-| Cursor      | `cursor`        | `~/.cursor/mcp.json` + `~/.cursor/skills/` |
-| Claude Code | `claude`        | `~/.claude.json` + `~/.claude/skills/` |
+| 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/api.d.ts

@@ -44,12 +44,12 @@ export interface DownloadProgress {
  */
 export declare function skillsLogin(email: string, password: string): Promise<SkillsLoginData>;
 /**
- * GET /skills/release?token=…&target=react|vanilla
+ * GET /skills/release?token=…&target=react|vanilla|vue
  * Response: { data: { version, families, files, downloadReady } }
  */
 export declare function fetchSkillsRelease(token: string, target: PackageTarget): Promise<SkillsReleaseData>;
 /**
- * GET /skills/release-free?target=react|vanilla (no auth)
+ * GET /skills/release-free?target=react|vanilla|vue (no auth)
  */
 export declare function fetchSkillsFreeRelease(target: PackageTarget): Promise<SkillsReleaseData>;
 declare function formatBytes(bytes: number): string;

package/dist/api.js

@@ -65,7 +65,7 @@ export async function skillsLogin(email, password) {
     return json.data;
 }
 /**
- * GET /skills/release?token=…&target=react|vanilla
+ * GET /skills/release?token=…&target=react|vanilla|vue
  * Response: { data: { version, families, files, downloadReady } }
  */
 export async function fetchSkillsRelease(token, target) {
@@ -86,7 +86,7 @@ export async function fetchSkillsRelease(token, target) {
     return { ...json.data, tier: json.data.tier ?? "pro" };
 }
 /**
- * GET /skills/release-free?target=react|vanilla (no auth)
+ * GET /skills/release-free?target=react|vanilla|vue (no auth)
  */
 export async function fetchSkillsFreeRelease(target) {
     const url = new URL(`${getApiBaseUrl()}/skills/release-free`);

package/dist/commands/setup.d.ts

@@ -1,4 +1,4 @@
-import type { AgentTool, PackageTarget } from "../config.js";
+import { type AgentTool, type PackageTarget } from "../config.js";
 export interface SetupOptions {
     /** Skip API; copy a local prepared package directory */
     from?: string;

package/dist/commands/setup.js

@@ -1,8 +1,8 @@
 import { confirm, select, checkbox } from "@inquirer/prompts";
 import { mkdir } from "node:fs/promises";
 import { ApiError, fetchSkillsFreeRelease, fetchSkillsRelease } from "../api.js";
-import { installRoot, nucleoHomeDir } from "../config.js";
-import { buildMcp, ensureManifestTarget, installFromLocalDir, installFromRelease, readInstallManifest, } from "../install.js";
+import { installRoot, isPackageTarget, nucleoHomeDir, } from "../config.js";
+import { buildMcp, ensureManifestTarget, hasProFamilies, installFromLocalDir, installFromRelease, readInstallManifest, } from "../install.js";
 import { configureTool } from "../adapters/agents.js";
 import { ensureSkillsSession, isInvalidTokenError } from "../session.js";
 async function fetchProReleaseWithSession(target, emailHint) {
@@ -23,11 +23,15 @@ export async function runSetup(options = {}) {
     const free = Boolean(options.free);
     console.log(free ? "\nNucleo Skills setup (free)" : "\nNucleo Skills setup");
     console.log(free ? "─────────────────────────\n" : "───────────────────\n");
+    if (options.target && !isPackageTarget(options.target)) {
+        throw new Error(`Unknown target "${options.target}". Use react, vanilla, or vue.`);
+    }
     const target = options.target ??
         (await select({
             message: "Which package?",
             choices: [
                 { name: "React components", value: "react" },
+                { name: "Vue components", value: "vue" },
                 { name: "Vanilla SVG", value: "vanilla" },
             ],
         }));
@@ -64,6 +68,10 @@ export async function runSetup(options = {}) {
         });
     }
     else if (free) {
+        const mergingIntoPro = hasProFamilies();
+        if (mergingIntoPro) {
+            console.log("Existing Pro install detected — free icons will be added alongside Pro.\n");
+        }
         console.log(`Fetching free ${target} release…`);
         let release;
         try {
@@ -82,7 +90,7 @@ export async function runSetup(options = {}) {
         await installFromRelease(release, target);
     }
     else {
-        console.log(`Fetching ${target} release…`);
+        console.log(`Fetching ${target} release (Pro + free)…`);
         let release;
         try {
             release = await fetchProReleaseWithSession(target, options.email);
@@ -111,5 +119,6 @@ export async function runSetup(options = {}) {
     console.log(`  Target:       ${manifest?.target ?? target}`);
     console.log(`  Tier:         ${manifest?.tier ?? (free ? "free" : "pro")}`);
     console.log(`  Version:      ${manifest?.version ?? "(none)"}`);
+    console.log(`  Families:     ${(manifest?.families ?? []).join(", ") || "(none)"}`);
     console.log("\nReload MCP in your editor, then try asking about Nucleo icons.\n");
 }

package/dist/commands/update.js

@@ -1,7 +1,7 @@
 import { confirm } from "@inquirer/prompts";
 import { ApiError, fetchSkillsFreeRelease, fetchSkillsRelease } from "../api.js";
 import { installRoot } from "../config.js";
-import { buildMcp, ensureManifestTarget, installFromLocalDir, installFromRelease, readInstallManifest, } from "../install.js";
+import { buildMcp, ensureManifestTarget, installFromLocalDir, installFromRelease, isFreeOnlyInstall, readInstallManifest, } from "../install.js";
 import { configureTool } from "../adapters/agents.js";
 import { ensureSkillsSession, isInvalidTokenError } from "../session.js";
 async function fetchProReleaseWithSession(target) {
@@ -18,18 +18,6 @@ async function fetchProReleaseWithSession(target) {
         throw error;
     }
 }
-function isFreeInstall(manifest) {
-    if (!manifest) {
-        return false;
-    }
-    if (manifest.tier === "free") {
-        return true;
-    }
-    if (typeof manifest.product === "string" && manifest.product.includes("free")) {
-        return true;
-    }
-    return false;
-}
 export async function runUpdate(options = {}) {
     console.log("\nNucleo Skills update");
     console.log("────────────────────\n");
@@ -39,14 +27,11 @@ export async function runUpdate(options = {}) {
     }
     const target = manifest?.target ?? "react";
     const localVersion = manifest?.version ?? "0.0.0";
-    const free = isFreeInstall(manifest);
+    const freeOnly = isFreeOnlyInstall(installRoot(), manifest);
     if (options.from) {
         console.log(`Updating from local folder:\n  ${options.from}\n`);
         await installFromLocalDir(options.from);
-        await ensureManifestTarget(target, {
-            tier: free ? "free" : "pro",
-            product: free ? "nucleo-skills-free" : "nucleo-skills",
-        });
+        await ensureManifestTarget(target);
         console.log("Building MCP…");
         await buildMcp();
         await reconfigure(options.tools);
@@ -57,12 +42,12 @@ export async function runUpdate(options = {}) {
     }
     let release;
     try {
-        if (free) {
+        if (freeOnly) {
             console.log("Channel:     free");
             release = await fetchSkillsFreeRelease(target);
         }
         else {
-            console.log("Channel:     pro");
+            console.log("Channel:     pro (+ free)");
             release = await fetchProReleaseWithSession(target);
         }
     }

package/dist/config.d.ts

@@ -6,7 +6,9 @@ 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 declare const PACKAGE_TARGETS: readonly ["react", "vanilla", "vue"];
+export type PackageTarget = (typeof PACKAGE_TARGETS)[number];
+export declare function isPackageTarget(value: string): value is PackageTarget;
 export type AgentTool = "cursor" | "claude" | "codex";
 export interface NucleoCredentials {
     email: string;
@@ -15,8 +17,8 @@ export interface NucleoCredentials {
 }
 export interface InstallManifest {
     product?: string;
-    /** free | pro — drives update channel without requiring --free again */
-    tier?: "free" | "pro" | string;
+    /** free | pro | pro+free — drives update channel without requiring --free again */
+    tier?: "free" | "pro" | "pro+free" | string;
     target?: PackageTarget | string;
     version?: string;
     families?: string[];

package/dist/config.js

@@ -19,3 +19,7 @@ export function credentialsPath() {
 export function installRoot() {
     return join(nucleoHomeDir(), "skills");
 }
+export const PACKAGE_TARGETS = ["react", "vanilla", "vue"];
+export function isPackageTarget(value) {
+    return PACKAGE_TARGETS.includes(value);
+}

package/dist/index.js

@@ -52,7 +52,7 @@ program
 program
     .command("setup")
     .description("Sign in, download your licensed package, configure your editor")
-    .option("-t, --target <target>", "react | vanilla")
+    .option("-t, --target <target>", "react | vanilla | vue")
     .option("--tools <list>", "comma-separated: cursor,claude,codex (default: prompt, or cursor with --yes)")
     .option("--free", "Install free icon families (no Nucleo login)")
     .option("--from <dir>", "Install from a local prepared package (skip API download)")

package/dist/install.d.ts

@@ -1,5 +1,9 @@
 import { type SkillsReleaseData } from "./api.js";
 import { type InstallManifest, type PackageTarget } from "./config.js";
+/** Licensed Pro families — never installed via the free (no-auth) channel. */
+export declare const PRO_FAMILIES: readonly ["core", "ui", "sharp", "micro", "pixel"];
+/** Free families from react-free.zip / vanilla-free.zip. */
+export declare const FREE_FAMILIES: readonly ["flags", "cursors", "credit-cards", "social-media", "isometric", "arcade", "glass"];
 /**
  * Resolve a real npm binary. Prefer the one next to the running Node
  * (`process.execPath`) so we don't depend on PATH / shell aliases
@@ -8,12 +12,42 @@ import { type InstallManifest, type PackageTarget } from "./config.js";
 export declare function resolveNpmBin(): string;
 export declare function readInstallManifest(root?: string): Promise<InstallManifest | null>;
 export declare function cleanInstallRoot(root?: string): Promise<void>;
+/** True if any Pro family catalog is present under the install root. */
+export declare function hasProFamilies(root?: string): boolean;
+/** True if any free family catalog is present under the install root. */
+export declare function hasFreeFamilies(root?: string): boolean;
 /**
- * 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.
+ * Detect installed icon families by looking for `{family}/icons.json`.
  */
-export declare function installFromRelease(release: SkillsReleaseData, target: PackageTarget, root?: string): Promise<void>;
+export declare function detectInstalledFamilies(root?: string): string[];
+export declare function resolveInstallTier(root?: string): {
+    hasPro: boolean;
+    hasFree: boolean;
+    tier: "free" | "pro" | "pro+free";
+};
+/**
+ * Free-only installs use the public free channel.
+ * Any Pro families on disk → Pro (authenticated) channel, which also ships free.
+ */
+export declare function isFreeOnlyInstall(root?: string, manifest?: InstallManifest | null): boolean;
+export interface InstallFromReleaseOptions {
+    /**
+     * When true, extract into the existing root without wiping.
+     * Used so `setup --free` can add free families beside Pro.
+     * Default: auto — merge free releases onto an existing Pro install.
+     */
+    merge?: boolean;
+}
+/**
+ * Download all release files (signed URLs) and install into the root.
+ *
+ * - Pro releases: replace the install root, then extract (Pro zips + free zip).
+ * - Free releases on top of Pro: merge (keep Pro families).
+ * - Free-only: replace the install root with free content.
+ *
+ * Downloads complete first — a failed download does not wipe a previous install.
+ */
+export declare function installFromRelease(release: SkillsReleaseData, target: PackageTarget, root?: string, options?: InstallFromReleaseOptions): Promise<void>;
 /**
  * Copy a local prepared package (e.g. packages/react) into the install root.
  */

package/dist/install.js

@@ -7,6 +7,18 @@ import extract from "extract-zip";
 import { downloadUrlToFile, formatBytes } from "./api.js";
 import { installRoot, nucleoHomeDir } from "./config.js";
 const execFileAsync = promisify(execFile);
+/** Licensed Pro families — never installed via the free (no-auth) channel. */
+export const PRO_FAMILIES = ["core", "ui", "sharp", "micro", "pixel"];
+/** Free families from react-free.zip / vanilla-free.zip. */
+export const FREE_FAMILIES = [
+    "flags",
+    "cursors",
+    "credit-cards",
+    "social-media",
+    "isometric",
+    "arcade",
+    "glass",
+];
 /**
  * Resolve a real npm binary. Prefer the one next to the running Node
  * (`process.execPath`) so we don't depend on PATH / shell aliases
@@ -58,6 +70,52 @@ export async function cleanInstallRoot(root = installRoot()) {
     await rm(root, { recursive: true, force: true });
     await mkdir(root, { recursive: true });
 }
+/** True if any Pro family catalog is present under the install root. */
+export function hasProFamilies(root = installRoot()) {
+    return PRO_FAMILIES.some((family) => existsSync(join(root, family, "icons.json")));
+}
+/** True if any free family catalog is present under the install root. */
+export function hasFreeFamilies(root = installRoot()) {
+    return FREE_FAMILIES.some((family) => existsSync(join(root, family, "icons.json")));
+}
+/**
+ * Detect installed icon families by looking for `{family}/icons.json`.
+ */
+export function detectInstalledFamilies(root = installRoot()) {
+    const known = [...PRO_FAMILIES, ...FREE_FAMILIES];
+    return known.filter((family) => existsSync(join(root, family, "icons.json")));
+}
+export function resolveInstallTier(root = installRoot()) {
+    const hasPro = hasProFamilies(root);
+    const hasFree = hasFreeFamilies(root);
+    if (hasPro && hasFree) {
+        return { hasPro, hasFree, tier: "pro+free" };
+    }
+    if (hasPro) {
+        return { hasPro, hasFree, tier: "pro" };
+    }
+    return { hasPro, hasFree, tier: "free" };
+}
+/**
+ * Free-only installs use the public free channel.
+ * Any Pro families on disk → Pro (authenticated) channel, which also ships free.
+ */
+export function isFreeOnlyInstall(root = installRoot(), manifest) {
+    if (hasProFamilies(root)) {
+        return false;
+    }
+    if (manifest?.tier === "pro" || manifest?.tier === "pro+free") {
+        return false;
+    }
+    if (manifest?.tier === "free") {
+        return true;
+    }
+    if (typeof manifest?.product === "string" && manifest.product.includes("free")) {
+        return true;
+    }
+    // No Pro on disk and no explicit Pro tier → free-only channel.
+    return true;
+}
 async function canRunUnzip() {
     try {
         await execFileAsync("unzip", ["-v"], { timeout: 5_000 });
@@ -104,11 +162,15 @@ async function assertInstallLooksComplete(root) {
     }
 }
 /**
- * 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.
+ * Download all release files (signed URLs) and install into the root.
+ *
+ * - Pro releases: replace the install root, then extract (Pro zips + free zip).
+ * - Free releases on top of Pro: merge (keep Pro families).
+ * - Free-only: replace the install root with free content.
+ *
+ * Downloads complete first — a failed download does not wipe a previous install.
  */
-export async function installFromRelease(release, target, root = installRoot()) {
+export async function installFromRelease(release, target, root = installRoot(), options = {}) {
     if (!release.downloadReady) {
         throw new Error(release.message ||
             "Downloads are not ready on the server yet. Please try again later.");
@@ -117,6 +179,15 @@ export async function installFromRelease(release, target, root = installRoot())
     if (missingUrl.length > 0) {
         throw new Error(`Release files missing download urls: ${missingUrl.map((f) => f.id).join(", ")}`);
     }
+    const isFreeRelease = release.tier === "free";
+    const merge = options.merge ?? (isFreeRelease && existsSync(root) && hasProFamilies(root));
+    // Safety: free channel must never claim Pro family modules.
+    if (isFreeRelease) {
+        const forbidden = release.files.filter((f) => PRO_FAMILIES.includes(f.id));
+        if (forbidden.length > 0) {
+            throw new Error(`Free release unexpectedly included Pro modules: ${forbidden.map((f) => f.id).join(", ")}`);
+        }
+    }
     const downloadsDir = join(nucleoHomeDir(), "downloads");
     await mkdir(downloadsDir, { recursive: true });
     const downloaded = [];
@@ -150,9 +221,14 @@ export async function installFromRelease(release, target, root = installRoot())
             }
             downloaded.push({ id: file.id, zipPath });
         }
-        // 2) Only now replace the install root
-        console.log("  Extracting…");
-        await cleanInstallRoot(root);
+        // 2) Extract — wipe unless merging free into Pro
+        console.log(merge ? "  Merging into existing install (Pro families kept)…" : "  Extracting…");
+        if (!merge) {
+            await cleanInstallRoot(root);
+        }
+        else {
+            await mkdir(root, { recursive: true });
+        }
         for (const file of downloaded) {
             const zipInfo = await stat(file.zipPath);
             process.stdout.write(`  ▸ ${file.id} (${formatBytes(zipInfo.size)}) `);
@@ -172,12 +248,14 @@ export async function installFromRelease(release, target, root = installRoot())
     finally {
         await rm(downloadsDir, { recursive: true, force: true }).catch(() => undefined);
     }
+    const families = detectInstalledFamilies(root);
+    const { tier } = resolveInstallTier(root);
     await writeInstallManifest({
-        product: release.tier === "free" ? "nucleo-skills-free" : "nucleo-skills",
-        tier: release.tier === "free" ? "free" : "pro",
+        product: tier === "free" ? "nucleo-skills-free" : "nucleo-skills",
+        tier,
         target,
         version: release.version,
-        families: release.families,
+        families,
     }, root);
 }
 /**
@@ -205,15 +283,18 @@ export async function ensureManifestTarget(target, extras = {}, root = installRo
             manifest = {};
         }
     }
+    const families = extras.families ?? detectInstalledFamilies(root);
+    const { tier: detectedTier } = resolveInstallTier(root);
     manifest = {
         ...manifest,
         ...extras,
         target: extras.target ?? manifest.target ?? target,
         version: extras.version ?? manifest.version ?? "0.0.0-local",
+        families,
+        tier: extras.tier ?? detectedTier,
+        product: extras.product ??
+            (detectedTier === "free" ? "nucleo-skills-free" : "nucleo-skills"),
     };
-    if (extras.families) {
-        manifest.families = extras.families;
-    }
     await writeInstallManifest(manifest, root);
     return manifest;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nucleoicons/skills",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "description": "CLI to install and update Nucleo MCP + icon skills (Pro and free)",
   "type": "module",
   "bin": {