@nucleoicons/skills 0.1.6 → 0.1.8

package/README.md

@@ -4,7 +4,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 licensed families (core, ui, sharp, micro, pixel)
+- 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
 - Customize icons when inserting them (color, secondary color, stroke width, duo opacity, corners)
 
@@ -14,15 +14,25 @@ Requires **Node.js 20+**.
 
 ## Install
 
+**Pro** (Nucleo account — licensed families **plus** free sets in the same install):
+
 ```bash
 npx @nucleoicons/skills setup --target react --tools cursor
 ```
 
+**Free** (no account — glass, arcade, isometric, flags, cursors, social-media, credit-cards):
+
+```bash
+npx @nucleoicons/skills setup --free --target react --tools cursor
+```
+
+If Pro is already installed, `setup --free` **merges** free families in and keeps Pro. Free-only installs never download Pro families (login required for Pro).
+
 **Required for setup:** `--target` (`react` or `vanilla`) and `--tools` (`cursor`, `claude`, `codex`).
 
 ```bash
 npx @nucleoicons/skills setup --target react --tools cursor
-npx @nucleoicons/skills setup --target vanilla --tools cursor,claude
+npx @nucleoicons/skills setup --free --target vanilla --tools cursor,claude
 ```
 
 Setup installs the package under your user home (`~/.nucleo/skills`) and configures the editors you choose (skills + MCP, no manual config step).
@@ -35,6 +45,8 @@ What Nucleo icon families do I have?
 
 ## Update
 
+Same command for free and Pro — the CLI remembers which package you installed (`--free` is not needed again):
+
 ```bash
 npx @nucleoicons/skills update
 ```

package/dist/api.d.ts

@@ -27,6 +27,7 @@ export interface SkillsReleaseFile {
 export interface SkillsReleaseData {
     version: string;
     target: PackageTarget | string;
+    tier?: "free" | "pro" | string;
     families: string[];
     downloadReady: boolean;
     files: SkillsReleaseFile[];
@@ -47,6 +48,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>;
+/**
+ * GET /skills/release-free?target=react|vanilla (no auth)
+ */
+export declare function fetchSkillsFreeRelease(target: PackageTarget): Promise<SkillsReleaseData>;
 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<{

package/dist/api.js

@@ -83,7 +83,26 @@ export async function fetchSkillsRelease(token, target) {
     if (!json.data?.version || !Array.isArray(json.data.files)) {
         throw new ApiError("Release response missing version/files.", res.status, body);
     }
-    return json.data;
+    return { ...json.data, tier: json.data.tier ?? "pro" };
+}
+/**
+ * GET /skills/release-free?target=react|vanilla (no auth)
+ */
+export async function fetchSkillsFreeRelease(target) {
+    const url = new URL(`${getApiBaseUrl()}/skills/release-free`);
+    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 free release (${res.status}).`), res.status, body);
+    }
+    const json = JSON.parse(body);
+    if (!json.data?.version || !Array.isArray(json.data.files)) {
+        throw new ApiError("Free release response missing version/files.", res.status, body);
+    }
+    return { ...json.data, tier: json.data.tier ?? "free" };
 }
 function formatBytes(bytes) {
     if (bytes < 1024) {

package/dist/commands/setup.d.ts

@@ -6,5 +6,7 @@ export interface SetupOptions {
     tools?: AgentTool[];
     email?: string;
     yes?: boolean;
+    /** Free icons package — no Nucleo login */
+    free?: boolean;
 }
 export declare function runSetup(options?: SetupOptions): Promise<void>;

package/dist/commands/setup.js

@@ -1,11 +1,11 @@
-import { mkdir } from "node:fs/promises";
 import { confirm, select, checkbox } from "@inquirer/prompts";
-import { ApiError, fetchSkillsRelease } from "../api.js";
+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 { buildMcp, ensureManifestTarget, hasProFamilies, installFromLocalDir, installFromRelease, readInstallManifest, } from "../install.js";
 import { configureTool } from "../adapters/agents.js";
 import { ensureSkillsSession, isInvalidTokenError } from "../session.js";
-async function fetchReleaseWithSession(target, emailHint) {
+async function fetchProReleaseWithSession(target, emailHint) {
     let session = await ensureSkillsSession(emailHint);
     try {
         return await fetchSkillsRelease(session.token, target);
@@ -20,8 +20,9 @@ async function fetchReleaseWithSession(target, emailHint) {
     }
 }
 export async function runSetup(options = {}) {
-    console.log("\nNucleo Skills setup");
-    console.log("───────────────────\n");
+    const free = Boolean(options.free);
+    console.log(free ? "\nNucleo Skills setup (free)" : "\nNucleo Skills setup");
+    console.log(free ? "─────────────────────────\n" : "───────────────────\n");
     const target = options.target ??
         (await select({
             message: "Which package?",
@@ -57,13 +58,38 @@ export async function runSetup(options = {}) {
             }
         }
         await installFromLocalDir(options.from);
-        await ensureManifestTarget(target);
+        await ensureManifestTarget(target, {
+            tier: free ? "free" : "pro",
+            product: free ? "nucleo-skills-free" : "nucleo-skills",
+        });
+    }
+    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 {
+            release = await fetchSkillsFreeRelease(target);
+        }
+        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);
     }
     else {
-        console.log(`Fetching ${target} release…`);
+        console.log(`Fetching ${target} release (Pro + free)…`);
         let release;
         try {
-            release = await fetchReleaseWithSession(target, options.email);
+            release = await fetchProReleaseWithSession(target, options.email);
         }
         catch (error) {
             if (error instanceof ApiError) {
@@ -87,8 +113,8 @@ export async function runSetup(options = {}) {
     console.log("\n✓ Done");
     console.log(`  Install path: ${installRoot()}`);
     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(", ") || "(see manifest)"}`);
-    console.log("\nNext: reload MCP in your editor, then ask:");
-    console.log('  “What Nucleo icon families do I have?”\n');
+    console.log(`  Families:     ${(manifest?.families ?? []).join(", ") || "(none)"}`);
+    console.log("\nReload MCP in your editor, then try asking about Nucleo icons.\n");
 }

package/dist/commands/status.js

@@ -23,6 +23,7 @@ export async function runStatus() {
     const manifest = await readInstallManifest();
     console.log(`Version:     ${manifest?.version ?? "(missing)"}`);
     console.log(`Target:      ${manifest?.target ?? "(missing)"}`);
+    console.log(`Tier:        ${manifest?.tier ?? "(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)"}`);

package/dist/commands/update.js

@@ -1,10 +1,10 @@
 import { confirm } from "@inquirer/prompts";
-import { ApiError, fetchSkillsRelease } from "../api.js";
+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 fetchReleaseWithSession(target) {
+async function fetchProReleaseWithSession(target) {
     let session = await ensureSkillsSession();
     try {
         return await fetchSkillsRelease(session.token, target);
@@ -27,6 +27,7 @@ export async function runUpdate(options = {}) {
     }
     const target = manifest?.target ?? "react";
     const localVersion = manifest?.version ?? "0.0.0";
+    const freeOnly = isFreeOnlyInstall(installRoot(), manifest);
     if (options.from) {
         console.log(`Updating from local folder:\n  ${options.from}\n`);
         await installFromLocalDir(options.from);
@@ -41,7 +42,14 @@ export async function runUpdate(options = {}) {
     }
     let release;
     try {
-        release = await fetchReleaseWithSession(target);
+        if (freeOnly) {
+            console.log("Channel:     free");
+            release = await fetchSkillsFreeRelease(target);
+        }
+        else {
+            console.log("Channel:     pro (+ free)");
+            release = await fetchProReleaseWithSession(target);
+        }
     }
     catch (error) {
         if (error instanceof ApiError) {

package/dist/config.d.ts

@@ -15,6 +15,8 @@ export interface NucleoCredentials {
 }
 export interface InstallManifest {
     product?: 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/index.js

@@ -54,6 +54,7 @@ program
     .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("--free", "Install free icon families (no Nucleo login)")
     .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")
@@ -70,6 +71,7 @@ program
             tools,
             email: opts.email,
             yes: Boolean(opts.yes),
+            free: Boolean(opts.free),
         });
     }
     catch (error) {

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,11 +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: "nucleo-skills",
+        product: tier === "free" ? "nucleo-skills-free" : "nucleo-skills",
+        tier,
         target,
         version: release.version,
-        families: release.families,
+        families,
     }, root);
 }
 /**
@@ -204,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,7 +1,7 @@
 {
   "name": "@nucleoicons/skills",
-  "version": "0.1.6",
-  "description": "CLI to install and update Nucleo Pro MCP + icon skills",
+  "version": "0.1.8",
+  "description": "CLI to install and update Nucleo MCP + icon skills (Pro and free)",
   "type": "module",
   "bin": {
     "nucleo-skills": "./dist/index.js"