@svgicons-com/cli 0.1.0-alpha.1

package/src/config.js

@@ -0,0 +1,134 @@
+import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { homedir, platform } from 'node:os';
+
+const DEFAULT_BASE_URL = 'https://svgicons.com';
+let configPathOverride = '';
+let credentialOverrides = {};
+
+export function defaultBaseUrl() {
+  return process.env.SVGICONS_BASE_URL || DEFAULT_BASE_URL;
+}
+
+export function configPath() {
+  if (configPathOverride) {
+    return configPathOverride;
+  }
+
+  if (process.env.SVGICONS_CLI_CONFIG_DIR) {
+    return join(process.env.SVGICONS_CLI_CONFIG_DIR, 'config.json');
+  }
+
+  const home = homedir();
+  const os = platform();
+
+  if (os === 'win32') {
+    const base = process.env.APPDATA || join(home, 'AppData', 'Roaming');
+    return join(base, 'svgicons', 'cli', 'config.json');
+  }
+
+  if (os === 'darwin') {
+    return join(home, 'Library', 'Application Support', 'svgicons', 'cli', 'config.json');
+  }
+
+  const base = process.env.XDG_CONFIG_HOME || join(home, '.config');
+  return join(base, 'svgicons', 'cli', 'config.json');
+}
+
+export async function readConfig() {
+  try {
+    const raw = await readFile(configPath(), 'utf8');
+    return JSON.parse(raw);
+  } catch (error) {
+    if (error?.code === 'ENOENT') {
+      return {};
+    }
+
+    throw new Error(`Unable to read Svg/icons CLI config: ${error.message}`);
+  }
+}
+
+export async function writeConfig(config) {
+  const path = configPath();
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, `${JSON.stringify(config, null, 2)}\n`, { mode: 0o600 });
+}
+
+export async function clearConfig() {
+  await rm(configPath(), { force: true });
+}
+
+export async function credentials() {
+  const config = await readConfig();
+  const envToken = process.env.SVGICONS_TOKEN || process.env.SVGICONS_API_TOKEN;
+  const baseUrl = credentialOverrides.baseUrl
+    || process.env.SVGICONS_BASE_URL
+    || config.baseUrl
+    || DEFAULT_BASE_URL;
+  const token = credentialOverrides.token !== undefined
+    ? credentialOverrides.token
+    : envToken || config.token || '';
+
+  return {
+    baseUrl: normalizeBaseUrl(baseUrl),
+    token,
+  };
+}
+
+export async function credentialsStatus() {
+  const config = await readConfig();
+  const envToken = process.env.SVGICONS_TOKEN || process.env.SVGICONS_API_TOKEN;
+  const envBaseUrl = process.env.SVGICONS_BASE_URL;
+  const hasTokenOverride = credentialOverrides.token !== undefined;
+  const baseUrl = credentialOverrides.baseUrl || envBaseUrl || config.baseUrl || DEFAULT_BASE_URL;
+  const token = hasTokenOverride ? credentialOverrides.token : envToken || config.token || '';
+
+  return {
+    configPath: configPath(),
+    baseUrl: normalizeBaseUrl(baseUrl),
+    baseUrlSource: credentialOverrides.baseUrl
+      ? 'command'
+      : envBaseUrl
+        ? 'environment'
+        : config.baseUrl
+          ? 'config'
+          : 'default',
+    hasToken: Boolean(token),
+    tokenSource: hasTokenOverride
+      ? 'command'
+      : envToken
+        ? 'environment'
+        : config.token
+          ? 'config'
+          : 'none',
+    createdAt: config.createdAt || null,
+  };
+}
+
+export function setConfigPathOverride(path) {
+  configPathOverride = path ? String(path) : '';
+}
+
+export function setCredentialOverrides(overrides = {}) {
+  credentialOverrides = {
+    ...credentialOverrides,
+    ...Object.fromEntries(
+      Object.entries(overrides).filter(([, value]) => value !== undefined),
+    ),
+  };
+}
+
+export function clearRuntimeOverrides() {
+  configPathOverride = '';
+  credentialOverrides = {};
+}
+
+export function normalizeBaseUrl(value) {
+  const baseUrl = String(value || DEFAULT_BASE_URL).trim().replace(/\/+$/, '');
+
+  if (!/^https?:\/\//i.test(baseUrl)) {
+    throw new Error('Base URL must start with http:// or https://');
+  }
+
+  return baseUrl;
+}

package/src/downloads.js

@@ -0,0 +1,173 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import { dirname, extname, isAbsolute, join, resolve } from 'node:path';
+
+export function parseIconReference(reference) {
+  const value = String(reference || '').trim();
+  const match = value.match(/^(\d+)-([a-z0-9][a-z0-9._-]*)$/i);
+
+  if (!match) {
+    throw new Error('Icon reference must include id and name, for example: 33716-arrow-circle-up-fill');
+  }
+
+  return {
+    id: Number(match[1]),
+    slug: sanitizeFileSegment(match[2]),
+  };
+}
+
+export function parseIconLookupReference(reference) {
+  const value = String(reference || '').trim();
+
+  if (!value) {
+    throw new Error('Icon reference is required.');
+  }
+
+  const urlMatch = value.match(/\/icon\/(\d+)(?:\/([^/?#]+))?/i);
+  if (urlMatch) {
+    return {
+      id: Number(urlMatch[1]),
+      slug: urlMatch[2] ? sanitizeFileSegment(decodeURIComponent(urlMatch[2])) : '',
+    };
+  }
+
+  const idSlugMatch = value.match(/^(\d+)(?:-([a-z0-9][a-z0-9._-]*))?$/i);
+  if (idSlugMatch) {
+    return {
+      id: Number(idSlugMatch[1]),
+      slug: idSlugMatch[2] ? sanitizeFileSegment(idSlugMatch[2]) : '',
+    };
+  }
+
+  throw new Error('Icon reference must be an id, id-name, or svgicons.com icon URL.');
+}
+
+export function assertIconReferenceMatches(reference, icon) {
+  const expected = parseIconReference(reference);
+  const actualSlug = sanitizeFileSegment(icon?.name || '');
+
+  if (Number(icon?.id) !== expected.id || actualSlug !== expected.slug) {
+    throw new Error(`Icon reference mismatch. Expected ${expected.id}-${expected.slug}, got ${icon?.id || 'unknown'}-${actualSlug || 'unknown'}.`);
+  }
+
+  return expected;
+}
+
+export function iconDownloadFilename(icon) {
+  const id = Number(icon?.id);
+  const name = sanitizeFileSegment(icon?.name || 'icon');
+
+  return `${Number.isFinite(id) && id > 0 ? id : 'icon'}-${name}.svg`;
+}
+
+export function resolveIconDownloadPath(output, icon, cwd = process.cwd()) {
+  const filename = iconDownloadFilename(icon);
+
+  if (!output || output === true) {
+    return resolve(cwd, filename);
+  }
+
+  const target = isAbsolute(String(output))
+    ? String(output)
+    : resolve(cwd, String(output));
+
+  if (extname(target).toLowerCase() === '.svg') {
+    return target;
+  }
+
+  return join(target, filename);
+}
+
+export function resolveArchiveDownloadPath(output, filename, cwd = process.cwd()) {
+  const safeFilename = sanitizeFileName(filename || 'svgicons-collection-export.zip', 'zip');
+
+  if (!output || output === true) {
+    return resolve(cwd, safeFilename);
+  }
+
+  const target = isAbsolute(String(output))
+    ? String(output)
+    : resolve(cwd, String(output));
+
+  if (extname(target).toLowerCase() === '.zip') {
+    return target;
+  }
+
+  return join(target, safeFilename);
+}
+
+export async function writeIconSvg(path, svg, force = false) {
+  if (!svg || typeof svg !== 'string') {
+    throw new Error('The icon response did not include SVG markup.');
+  }
+
+  await mkdir(dirname(path), { recursive: true });
+
+  try {
+    await writeFile(path, svg.endsWith('\n') ? svg : `${svg}\n`, {
+      flag: force ? 'w' : 'wx',
+    });
+  } catch (error) {
+    if (error?.code === 'EEXIST') {
+      throw new Error(`File already exists: ${path}. Use --force to overwrite it.`);
+    }
+
+    throw error;
+  }
+
+  return path;
+}
+
+export async function writeBinaryFile(path, bytes, force = false) {
+  if (!bytes || bytes.length === 0) {
+    throw new Error('The download response did not include file data.');
+  }
+
+  await mkdir(dirname(path), { recursive: true });
+
+  try {
+    await writeFile(path, bytes, {
+      flag: force ? 'w' : 'wx',
+    });
+  } catch (error) {
+    if (error?.code === 'EEXIST') {
+      throw new Error(`File already exists: ${path}. Use --force to overwrite it.`);
+    }
+
+    throw error;
+  }
+
+  return path;
+}
+
+export function sanitizeFileSegment(value) {
+  const cleaned = String(value)
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9._-]+/g, '-')
+    .replace(/-+/g, '-')
+    .replace(/^[ ._-]+|[ ._-]+$/g, '')
+    .slice(0, 120);
+
+  return cleaned || 'icon';
+}
+
+export function sanitizeFileName(value, fallbackExtension) {
+  const extension = fallbackExtension ? `.${fallbackExtension.replace(/^\./, '')}` : '';
+  const cleaned = String(value || '')
+    .trim()
+    .replace(/[<>:"/\\|?*\x00-\x1F]+/g, '-')
+    .replace(/\s+/g, '-')
+    .replace(/-+/g, '-')
+    .replace(/^[ ._-]+|[ ._-]+$/g, '')
+    .slice(0, 160);
+
+  if (!cleaned) {
+    return `download${extension}`;
+  }
+
+  if (extension && extname(cleaned).toLowerCase() !== extension.toLowerCase()) {
+    return `${cleaned}${extension}`;
+  }
+
+  return cleaned;
+}

package/src/errors.js

@@ -0,0 +1,127 @@
+import { redactString } from './redact.js';
+
+export class CliError extends Error {
+  constructor(code, message, details = {}) {
+    super(redactString(message));
+    this.name = 'CliError';
+    this.code = code;
+    this.status = details.status;
+    this.details = details;
+  }
+}
+
+export function missingTokenError() {
+  return new CliError(
+    'missing_token',
+    'A Pro API token is required. Run: svgicons login --token <token>',
+  );
+}
+
+export function networkError(error, url) {
+  return new CliError('network_error', `Unable to reach ${url}: ${error?.message || error}`, { url });
+}
+
+export function invalidJsonError(url) {
+  return new CliError('invalid_json', `Invalid JSON response from ${url}`, { url });
+}
+
+export function httpError(status, url, data = {}) {
+  const message = data?.message || data?.error?.message || `HTTP ${status} from ${url}`;
+  const code = classifyHttpError(status, message, data);
+
+  return new CliError(code, message, {
+    status,
+    url,
+    requiredScopes: data?.requiredScopes,
+    missingScope: data?.missingScope,
+    pricingUrl: data?.pricingUrl,
+  });
+}
+
+export function mcpError(message, details = {}) {
+  return new CliError('mcp_error', message || 'MCP request failed', details);
+}
+
+export function usageError(message, details = {}) {
+  return new CliError('usage_error', message, details);
+}
+
+export function exportFailedError(exportJob, message = '') {
+  return new CliError(
+    'export_failed',
+    message || exportJob?.failureMessage || `Collection export ${exportJob?.id || ''} failed.`.trim(),
+    { exportId: exportJob?.id, status: exportJob?.status },
+  );
+}
+
+export function exportTimeoutError(exportJob, timeoutSeconds) {
+  return new CliError(
+    'export_timeout',
+    `Timed out waiting for export ${exportJob?.id}. Use --timeout <seconds> or --no-wait.`,
+    { exportId: exportJob?.id, timeoutSeconds },
+  );
+}
+
+export function exportNotReadyError(exportJob) {
+  return new CliError(
+    'export_not_ready',
+    'The completed export did not provide a download URL.',
+    { exportId: exportJob?.id, status: exportJob?.status },
+  );
+}
+
+export function licenseViolationError(report) {
+  return new CliError(
+    'license_violation',
+    `${report.violations.length} icon license violation(s) found.`,
+    {
+      checkedIcons: report.checkedIcons,
+      violations: report.violations,
+    },
+  );
+}
+
+export function serializeError(error) {
+  return {
+    error: {
+      code: error?.code || 'error',
+      message: redactString(error?.message || String(error)),
+      status: error?.status,
+      details: error?.details,
+    },
+  };
+}
+
+function classifyHttpError(status, message, data) {
+  const text = String(message || '').toLowerCase();
+
+  if (status === 401) {
+    return 'auth_required';
+  }
+
+  if (status === 403) {
+    if (data?.missingScope || text.includes('missing') && text.includes('scope')) {
+      return 'missing_scope';
+    }
+
+    if (text.includes('email verification') || text.includes('unverified')) {
+      return 'email_unverified';
+    }
+
+    if (text.includes('pro plan') || text.includes('pro subscription') || text.includes('requires pro')) {
+      return 'pro_required';
+    }
+
+    return 'forbidden';
+  }
+
+  if (status === 404) {
+    return 'not_found';
+  }
+
+  if (status === 429) {
+    return 'rate_limited';
+  }
+
+  return 'http_error';
+}

package/src/format.js

@@ -0,0 +1,121 @@
+export function printJson(value) {
+  console.log(JSON.stringify(value, null, 2));
+}
+
+export function printSearchResults(payload) {
+  const icons = payload.data || [];
+
+  if (icons.length === 0) {
+    console.log('No icons found.');
+    return;
+  }
+
+  for (const icon of icons) {
+    const set = icon.iconSet?.name ? ` - ${icon.iconSet.name}` : '';
+    console.log(`${icon.id}\t${icon.name}${set}`);
+    if (icon.pageUrl) {
+      console.log(`  ${icon.pageUrl}`);
+    }
+  }
+
+  if (payload.meta?.hasMore) {
+    console.log(`More results available. Next offset: ${payload.meta.nextOffset}`);
+  }
+}
+
+export function printCollection(collection) {
+  console.log(`${collection.id}\t${collection.name}`);
+  console.log(`  icons: ${collection.iconsCount ?? 0}`);
+  console.log(`  framework: ${collection.framework || 'svg'}`);
+  console.log(`  color: ${collection.colorPolicy || 'currentColor'}`);
+  console.log(`  naming: ${collection.namingPolicy || 'kebab'}`);
+  if (collection.showUrl) {
+    console.log(`  ${collection.showUrl}`);
+  }
+}
+
+export function printCollectionDetail(payload, options = {}) {
+  const collection = payload.data || payload;
+  printCollection(collection);
+
+  if (collection.description) {
+    console.log(`  description: ${collection.description}`);
+  }
+
+  const licenses = collection.licenseSummary || [];
+  if (licenses.length > 0) {
+    console.log('');
+    console.log('Licenses:');
+    for (const item of licenses) {
+      console.log(`  ${item.license || 'Unknown'}: ${item.iconsCount || 0} icons`);
+    }
+  }
+
+  const iconSets = collection.iconSetSummary || [];
+  if (iconSets.length > 0) {
+    console.log('');
+    console.log('Icon sets:');
+    for (const item of iconSets) {
+      console.log(`  ${item.name || item.prefix}: ${item.iconsCount || 0} icons`);
+    }
+  }
+
+  if (options.icons) {
+    const icons = payload.icons?.data || [];
+    if (icons.length > 0) {
+      console.log('');
+      console.log('Icons:');
+      for (const icon of icons) {
+        const set = icon.iconSet?.name ? ` - ${icon.iconSet.name}` : '';
+        console.log(`  ${icon.id}\t${icon.name}${set}`);
+      }
+    }
+  }
+}
+
+export function printExport(exportJob) {
+  console.log(`Export ${exportJob.id}: ${exportJob.status}`);
+  console.log(`  formats: ${(exportJob.formats || []).join(', ')}`);
+  if (exportJob.statusUrl) {
+    console.log(`  status: ${exportJob.statusUrl}`);
+  }
+  if (exportJob.downloadUrl) {
+    console.log(`  download: ${exportJob.downloadUrl}`);
+  }
+}
+
+export function printScanProposal(proposal, options = {}) {
+  console.log(`Scanned ${proposal.stats.filesScanned} files in ${proposal.root}`);
+  console.log(`Suggested collection: ${proposal.collection.name}`);
+  console.log('');
+
+  if (proposal.concepts.length > 0) {
+    console.log('Detected UI concepts:');
+    for (const concept of proposal.concepts.slice(0, 20)) {
+      console.log(`  ${concept.name} (${concept.count})`);
+    }
+    console.log('');
+  }
+
+  if (proposal.existingIconIds.length > 0) {
+    console.log(`Existing svgicons.com icon URLs found: ${proposal.existingIconIds.join(', ')}`);
+    console.log('');
+  }
+
+  if ((proposal.generatedIconRefs || []).length > 0) {
+    console.log(`Generated SVG imports found: ${proposal.generatedIconRefs.join(', ')}`);
+    console.log('');
+  }
+
+  if (proposal.stats.inlineSvgCount > 0) {
+    console.log(`Inline SVG blocks found: ${proposal.stats.inlineSvgCount}`);
+    console.log('');
+  }
+
+  if (!options.modified) {
+    console.log('No files were modified.');
+  }
+  console.log(`Next search: svgicons search "${proposal.concepts[0]?.name || 'dashboard'}"`);
+  console.log(`Write manifest: svgicons scan "${proposal.root}" --write-manifest`);
+  console.log(`Create collection: svgicons collection create --name "${proposal.collection.name}" --description "${proposal.collection.description}"`);
+}