@svgicons-com/cli 0.1.0-alpha.1

package/README.md

@@ -0,0 +1,281 @@
+# Svg/icons CLI Alpha
+
+The Svg/icons CLI alpha is a developer workflow client for Pro Plan API tokens. It can search icons, recommend icons for a UI brief, create Icon Collections, add icons to collections, queue exports, and scan a local codebase for UI concepts.
+
+The scanner is read-only by default. It never edits project files unless a future command explicitly adds that behavior.
+
+Current package version: `0.1.0-alpha.1`.
+
+## Requirements
+
+- Node.js 18.18 or newer
+- A Svg/icons Pro API token for collection and export commands
+
+## Login
+
+```bash
+svgicons login --token YOUR_PRO_API_TOKEN
+```
+
+The explicit auth namespace is also supported:
+
+```bash
+svgicons auth login --token YOUR_PRO_API_TOKEN
+svgicons auth status
+svgicons doctor
+```
+
+Use `--base-url http://127.0.0.1:8000` when testing against a local Laravel server.
+
+You can also avoid writing a config file by setting `SVGICONS_TOKEN` or `SVGICONS_API_TOKEN`.
+
+Inspect local config without exposing the stored token:
+
+```bash
+svgicons config list
+svgicons config get baseUrl
+svgicons config set baseUrl https://svgicons.com
+```
+
+## Commands
+
+```bash
+svgicons version
+svgicons auth login --token YOUR_PRO_API_TOKEN
+svgicons auth status --json
+svgicons config list --json
+svgicons doctor --json
+svgicons search "arrow left" --limit 10
+svgicons search "arrow left" --anonymous
+svgicons recommend "billing settings dashboard" --limit 12
+svgicons recommend "billing settings dashboard" --create-collection --collection-name "Billing icons"
+svgicons pick "settings gear" --download --output ./icons
+svgicons pick "credit card" --add "Billing icons"
+svgicons pick "settings gear" --interactive
+svgicons icon show 33716
+svgicons icon url 33716-arrow-circle-up-fill
+svgicons icon raw 33716-arrow-circle-up-fill
+svgicons icon download 33716-arrow-circle-up-fill --output ./icons
+svgicons collection list
+svgicons collection create --name "Dashboard icons" --description "Navigation and status icons"
+svgicons collection show "Dashboard icons" --icons
+svgicons collection rename "Dashboard icons" --name "Billing icons"
+svgicons collection update "Billing icons" --framework vue --color-policy preserve
+svgicons collection add "Dashboard icons" 33716 240297
+svgicons collection remove "Dashboard icons" 33716-arrow-circle-up-fill
+svgicons collection delete "Dashboard icons" --yes
+svgicons collection export "Dashboard icons" --formats react-ts,vue --color-policy currentColor --output ./exports
+svgicons collection export "Dashboard icons" --formats react-ts --no-size-props --no-typescript --output ./exports
+svgicons export status 55 --collection "Dashboard icons"
+svgicons export download 55 --collection "Dashboard icons" --output ./exports
+svgicons init --collection "Dashboard icons" --output ./src/icons
+svgicons sync
+svgicons build --ci
+svgicons update --check
+svgicons license check --allow MIT,Apache-2.0,ISC --fail
+svgicons license export --format markdown --output THIRD_PARTY_ICONS.md
+svgicons scan .
+svgicons scan . --write-manifest
+```
+
+Use `--json` on commands when integrating with scripts.
+
+## Release status
+
+This package is an alpha release. It is safe to test in real projects, but command names and JSON response shapes may still change before a stable `1.0.0`.
+
+See `RELEASE_NOTES.md` for included workflows, safety notes, and known limitations.
+
+Maintainers should use `../docs/svgicons-cli-npm-publishing.md` before publishing a new npm version.
+
+## Download one icon
+
+Download a single SVG file to the current folder:
+
+```bash
+svgicons icon download 33716-arrow-circle-up-fill
+```
+
+Download to a folder:
+
+```bash
+svgicons icon download 33716-arrow-circle-up-fill --output ./icons
+```
+
+Download to a specific file:
+
+```bash
+svgicons icon download 33716-arrow-circle-up-fill --output ./icons/arrow-up.svg
+```
+
+The icon reference must include both the numeric ID and the icon name, such as `33716-arrow-circle-up-fill`. The CLI checks the returned icon metadata before writing the file. This makes sequential ID-only download scripts less useful.
+
+This command uses the MCP `get_icon` tool with raw SVG output, so the token needs `mcp:use` and `icons:read`. Existing files are not overwritten unless you add `--force`.
+
+Read-only icon commands accept a numeric ID, an `id-name` reference, or a full svgicons.com icon URL:
+
+```bash
+svgicons icon show 33716
+svgicons icon url 33716-arrow-circle-up-fill
+svgicons icon raw https://svgicons.com/icon/33716/arrow-circle-up-fill
+```
+
+## Recommend and pick icons
+
+Ask Svg/icons for icon candidates based on a UI brief:
+
+```bash
+svgicons recommend "billing settings dashboard with invoices, payment methods, and security"
+```
+
+`recommend` uses the hosted MCP `recommend_icons_for_ui` tool. It returns metadata by default, so it can work without writing files. Add `--json` for automation.
+
+Create a Pro Icon Collection directly from a recommendation:
+
+```bash
+svgicons recommend "billing settings dashboard" --create-collection --collection-name "Billing icons"
+```
+
+This uses the MCP `generate_icon_kit_for_project` tool and requires a Pro token with `mcp:use` and `collections:write`.
+
+For deterministic scripts, `pick` selects the first search result:
+
+```bash
+svgicons pick "settings gear"
+svgicons pick "settings gear" --download --output ./icons
+svgicons pick "credit card" --add "Billing icons"
+```
+
+Use `--download` when you want the selected SVG written locally. Use `--add <collection>` when you want the selected icon added to an Icon Collection.
+
+For manual terminal selection, opt in to the interactive picker:
+
+```bash
+svgicons pick "settings gear" --interactive
+svgicons pick "settings gear" --interactive --download --output ./icons
+```
+
+`--interactive` requires a real terminal and is rejected in CI/non-interactive shells. Omit it for deterministic scripts.
+
+## Export and download a collection ZIP
+
+Queue an export, wait for the background job to finish, and download the ZIP:
+
+```bash
+svgicons collection export "Dashboard icons" --formats react-ts,vue --output ./exports
+```
+
+The command polls every 2 seconds for up to 180 seconds by default. Use `--timeout 300` for larger collections, or `--no-wait` if you only want to queue the export and manually download it later.
+
+Supported export flags:
+
+```bash
+--formats react-ts,vue
+--color-policy currentColor|preserve|strip
+--naming-policy kebab|pascal|camel
+--size-props / --no-size-props
+--typescript / --no-typescript
+```
+
+Collection commands accept a numeric ID, exact slug, or exact case-insensitive collection name. The legacy `kit` alias remains available for old scripts.
+
+Lifecycle commands are available for collection maintenance:
+
+```bash
+svgicons collection show "Dashboard icons" --icons
+svgicons collection update "Dashboard icons" --description "Core product UI icons"
+svgicons collection rename "Dashboard icons" --name "Billing icons"
+svgicons collection remove "Billing icons" 33716-arrow-circle-up-fill
+svgicons collection delete "Billing icons" --yes
+```
+
+`collection delete` prompts for confirmation in an interactive shell. Use `--yes` in CI or scripts.
+
+If you queued an export with `--no-wait`, check and download it later:
+
+```bash
+svgicons export status 55 --collection "Dashboard icons"
+svgicons export download 55 --collection "Dashboard icons" --output ./exports
+```
+
+## Local project manifest and lockfile
+
+Initialize a local project:
+
+```bash
+svgicons init --collection "Dashboard icons" --output ./src/icons
+```
+
+This creates `svgicons.json`. The manifest can reference individual icon IDs or Icon Collections:
+
+```json
+{
+  "version": 1,
+  "format": "svg",
+  "output": "./src/icons",
+  "icons": [{ "ref": "33716-arrow-circle-up-fill" }],
+  "collections": [{ "ref": "Dashboard icons" }]
+}
+```
+
+Sync the manifest into a deterministic lockfile:
+
+```bash
+svgicons sync
+```
+
+This writes `svgicons.lock` with icon SVG markup, source icon set metadata, license data, and SVG hashes. Build local SVG files from the lockfile:
+
+```bash
+svgicons build --ci
+```
+
+`build` uses only `svgicons.lock`, so CI builds do not depend on live API responses. Re-running `build` writes stable SVG files with stable names.
+
+Check whether locked icons changed upstream:
+
+```bash
+svgicons update --check
+```
+
+## License audit
+
+Check local icon licenses from `svgicons.lock`:
+
+```bash
+svgicons license check --allow MIT,Apache-2.0,ISC,CC0-1.0 --fail
+```
+
+Use `--deny` for forbidden licenses:
+
+```bash
+svgicons license check --deny GPL,CC-BY-NC-SA-4.0 --fail
+```
+
+Export a license summary for your repository:
+
+```bash
+svgicons license export --format markdown --output THIRD_PARTY_ICONS.md
+svgicons license export --format json --output third-party-icons.json
+svgicons license export --format csv --output third-party-icons.csv
+```
+
+## Scanner
+
+The scanner reads common frontend files, detects UI concepts such as dashboard, search, billing, upload, auth, and settings, and reports a proposed Icon Collection. It also detects existing `svgicons.com/icon/{id}/{name}` links, generated SVG imports, and inline SVG blocks.
+
+```bash
+svgicons scan ./src --max-files 300
+```
+
+To update a local `svgicons.json` manifest from detected icon refs, opt in explicitly:
+
+```bash
+svgicons scan . --write-manifest
+```
+
+To create a collection from existing icon URLs found in the scan, opt in explicitly:
+
+```bash
+svgicons scan . --create-collection
+```

package/RELEASE_NOTES.md

@@ -0,0 +1,42 @@
+# Svg/icons CLI 0.1.0-alpha.1
+
+This alpha release prepares the CLI for real Pro Plan workflows against the svgicons.com Laravel backend.
+
+## Included
+
+- Token login/logout plus `auth status`, known scopes, config inspection, and `doctor`.
+- Public icon search through the hosted MCP endpoint, with authenticated search when a token is configured.
+- Icon metadata, URL, raw SVG, browser open, and strict `id-name` SVG download.
+- Icon Collection list, create, show, rename, update, add, remove, delete, export, status, and ZIP download.
+- Backward-compatible `kit` alias for collection commands.
+- Local `svgicons.json` manifest, deterministic `svgicons.lock`, SVG build output, update checks, and license audits.
+- Project scanner that detects UI concepts, svgicons.com URLs, generated SVG imports, and inline SVG blocks.
+- `recommend` for UI-brief icon recommendations and Pro generated collections.
+- `pick` for deterministic first-result selection, plus opt-in interactive terminal selection.
+
+## Safety Notes
+
+- The scanner is read-only by default. It writes only when `--write-manifest` or `--create-collection` is used.
+- Destructive collection deletion requires confirmation or `--yes`.
+- `--interactive` is rejected in CI/non-interactive shells.
+- Tokens and authorization headers are redacted from config and diagnostic output.
+- SVG download remains strict: the reference must include both icon ID and name.
+
+## Known Limitations
+
+- The package is still alpha. Command names and JSON response shapes may change before a stable `1.0.0`.
+- The interactive picker is intentionally simple and terminal-only.
+- Search and recommendation quality depend on the current MCP metadata search implementation.
+- Local `build` currently writes SVG files. Framework component ZIPs are produced through collection exports.
+- Live Pro workflows require an active Pro account, verified email, and API token scopes matching the command.
+
+## Verification Checklist
+
+Before publishing, run:
+
+```bash
+npm --prefix cli test
+npm pack --dry-run
+```
+
+When backend changes are also included, run the relevant Laravel tests for Pro API tokens, MCP, Icon Collections, and collection exports.

package/bin/svgicons.js

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+
+import { run } from '../src/cli.js';
+import { serializeError } from '../src/errors.js';
+
+run(process.argv.slice(2)).catch((error) => {
+  if (process.argv.includes('--json')) {
+    console.error(JSON.stringify(serializeError(error), null, 2));
+  } else {
+    console.error(error?.message || String(error));
+  }
+  process.exitCode = 1;
+});

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@svgicons-com/cli",
+  "version": "0.1.0-alpha.1",
+  "description": "Svg/icons CLI alpha for icon search, Pro collections, exports, project scanning, and license workflows.",
+  "type": "module",
+  "bin": {
+    "svgicons": "./bin/svgicons.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "README.md",
+    "RELEASE_NOTES.md"
+  ],
+  "scripts": {
+    "test": "node --test tests"
+  },
+  "engines": {
+    "node": ">=18.18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "UNLICENSED",
+  "private": false
+}

package/src/api.js

@@ -0,0 +1,194 @@
+import { credentials } from './config.js';
+import { httpError, invalidJsonError, mcpError, missingTokenError, networkError } from './errors.js';
+
+let rpcId = 1;
+
+export async function callMcpTool(name, args = {}, options = {}) {
+  const response = await mcpRequest('tools/call', {
+    name,
+    arguments: args,
+  }, options);
+
+  const result = response.result || {};
+  const content = result.structuredContent || parseMcpText(result.content);
+
+  if (result.isError || content?.error) {
+    throw mcpError(content?.error?.message || 'MCP tool returned an error', {
+      tool: name,
+      error: content?.error,
+    });
+  }
+
+  return content;
+}
+
+export async function mcpRequest(method, params = {}, options = {}) {
+  const creds = await credentials();
+  const token = options.token ?? creds.token;
+  const baseUrl = options.baseUrl ?? creds.baseUrl;
+
+  const response = await request(`${baseUrl}/mcp`, {
+    method: 'POST',
+    token,
+    body: {
+      jsonrpc: '2.0',
+      id: rpcId++,
+      method,
+      params,
+    },
+  });
+
+  if (response.error) {
+    throw mcpError(response.error.message || 'MCP request failed', {
+      code: response.error.code,
+      data: response.error.data,
+    });
+  }
+
+  return response;
+}
+
+export async function proApi(path, options = {}) {
+  const creds = await credentials();
+  const token = options.token ?? creds.token;
+  const baseUrl = options.baseUrl ?? creds.baseUrl;
+
+  if (!token) {
+    throw missingTokenError();
+  }
+
+  return request(`${baseUrl}${path}`, {
+    ...options,
+    token,
+  });
+}
+
+export async function proApiDownload(pathOrUrl, options = {}) {
+  const creds = await credentials();
+  const token = options.token ?? creds.token;
+  const baseUrl = options.baseUrl ?? creds.baseUrl;
+
+  if (!token) {
+    throw missingTokenError();
+  }
+
+  const url = /^https?:\/\//i.test(pathOrUrl)
+    ? pathOrUrl
+    : `${baseUrl}${pathOrUrl}`;
+
+  let response;
+
+  try {
+    response = await fetch(url, {
+      method: options.method || 'GET',
+      headers: {
+        Accept: 'application/zip, application/octet-stream',
+        Authorization: `Bearer ${token}`,
+        'User-Agent': 'svgicons-cli/0.1.0-alpha',
+        ...options.headers,
+      },
+    });
+  } catch (error) {
+    throw networkError(error, url);
+  }
+
+  if (!response.ok) {
+    const text = await response.text();
+    let data = {};
+
+    try {
+      data = text ? JSON.parse(text) : {};
+    } catch {
+      data = {};
+    }
+
+    throw httpError(response.status, url, data);
+  }
+
+  return {
+    bytes: Buffer.from(await response.arrayBuffer()),
+    filename: filenameFromContentDisposition(response.headers.get('content-disposition')),
+    contentType: response.headers.get('content-type'),
+  };
+}
+
+async function request(url, options = {}) {
+  const headers = {
+    Accept: 'application/json',
+    'User-Agent': 'svgicons-cli/0.1.0-alpha',
+    ...options.headers,
+  };
+
+  const init = {
+    method: options.method || 'GET',
+    headers,
+  };
+
+  if (options.token) {
+    headers.Authorization = `Bearer ${options.token}`;
+  }
+
+  if (options.body !== undefined) {
+    headers['Content-Type'] = 'application/json';
+    init.body = JSON.stringify(options.body);
+  }
+
+  let response;
+
+  try {
+    response = await fetch(url, init);
+  } catch (error) {
+    throw networkError(error, url);
+  }
+
+  const text = await response.text();
+  const data = text ? safeJson(text, url) : {};
+
+  if (!response.ok) {
+    throw httpError(response.status, url, data);
+  }
+
+  return data;
+}
+
+function filenameFromContentDisposition(header) {
+  if (!header) {
+    return null;
+  }
+
+  const utf8Match = header.match(/filename\*=UTF-8''([^;]+)/i);
+  if (utf8Match) {
+    return decodeURIComponent(utf8Match[1].trim().replace(/^"|"$/g, ''));
+  }
+
+  const asciiMatch = header.match(/filename="?([^";]+)"?/i);
+  if (asciiMatch) {
+    return asciiMatch[1].trim();
+  }
+
+  return null;
+}
+
+function safeJson(text, url) {
+  try {
+    return JSON.parse(text);
+  } catch {
+    throw invalidJsonError(url);
+  }
+}
+
+function parseMcpText(content) {
+  const firstText = Array.isArray(content)
+    ? content.find((item) => item?.type === 'text')?.text
+    : '';
+
+  if (!firstText) {
+    return {};
+  }
+
+  try {
+    return JSON.parse(firstText);
+  } catch {
+    return {};
+  }
+}