@svgicons-com/cli 0.1.0-alpha.3 → 0.1.0-alpha.5

package/README.md

@@ -8,7 +8,7 @@ Public icon search works without changing the default endpoint. Pro workflows re
 
 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.3`.
+Current package version: `0.1.0-alpha.5`.
 
 ## Requirements
 
@@ -60,6 +60,7 @@ 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 icon png 33716-arrow-circle-up-fill --size 512 --output ./icons
 svgicons collection list
 svgicons collection create --name "Dashboard icons" --description "Navigation and status icons"
 svgicons collection show "Dashboard icons" --icons
@@ -69,7 +70,15 @@ 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 svelte --output ./exports
+svgicons collection export "Dashboard icons" --formats solid --output ./exports
+svgicons collection export "Dashboard icons" --formats blade --output ./exports
+svgicons collection export "Dashboard icons" --formats storybook --output ./exports
+svgicons collection export "Dashboard icons" --formats npm-package --package-name svgicons-dashboard-icons --output ./exports
+svgicons collection export "Dashboard icons" --formats png-pack --png-sizes 24,48,512 --output ./exports
+svgicons collection export "Dashboard icons" --formats iconify-json --output ./exports
 svgicons collection export "Dashboard icons" --formats react-ts --no-size-props --no-typescript --output ./exports
+svgicons collection export "Dashboard icons" --formats react-ts,solid --default-size 20 --component-suffix Glyph --no-decorative --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
@@ -116,6 +125,16 @@ The icon reference must include both the numeric ID and the icon name, such as `
 
 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`.
 
+Export a Pro PNG asset from a single icon:
+
+```bash
+svgicons icon png 33716-arrow-circle-up-fill --size 512 --output ./icons
+svgicons icon png 33716-arrow-circle-up-fill --sizes 128,256,512 --density 1,2 --zip --output ./icons
+svgicons icon png 33716-arrow-circle-up-fill --size 512 --color black --background solid --background-color "#ffffff"
+```
+
+Single-icon PNG export uses the Pro REST API, not the public anonymous search API. The token needs `icons:read` and `exports:create`. The icon reference must include both ID and name, and the server verifies that the name matches before rendering.
+
 Read-only icon commands accept a numeric ID, an `id-name` reference, or a full svgicons.com icon URL:
 
 ```bash
@@ -174,13 +193,28 @@ The command polls every 2 seconds for up to 180 seconds by default. Use `--timeo
 Supported export flags:
 
 ```bash
---formats react-ts,vue
+--formats react-ts,vue,svelte,solid,blade,storybook,npm-package,png-pack,iconify-json
 --color-policy currentColor|preserve|strip
 --naming-policy kebab|pascal|camel
 --size-props / --no-size-props
 --typescript / --no-typescript
+--default-size 24
+--title-prop / --no-title-prop
+--decorative / --no-decorative
+--component-suffix Icon
+--package-name svgicons-dashboard-icons
+--package-version 0.1.0
+--png-sizes 24,48,512
+--png-densities 1,2
+--png-background transparent|solid
+--png-background-color "#ffffff"
+--png-color preserve|black|white|custom
+--png-icon-color "#2563eb"
+--png-padding 48
 ```
 
+Use `--formats png` as a shorthand for `--formats png-pack`. PNG pack exports are generated by the server queue worker and downloaded as part of the collection ZIP. Use `--formats svelte` to include Svelte components, `--formats solid` to include Solid components, `--formats blade` to include Laravel Blade components, `--formats storybook` to include a React Storybook gallery, `--formats npm-package` to include a React TypeScript package scaffold, or `--formats iconify-json` to include an Iconify-compatible `iconify.json` file in the collection ZIP.
+
 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:

package/RELEASE_NOTES.md

@@ -1,4 +1,27 @@
-# Svg/icons CLI 0.1.0-alpha.3
+# Svg/icons CLI 0.1.0-alpha.5
+
+This alpha refresh keeps the npm alpha channel aligned with the current Svg/icons Pro export workflow.
+
+## New in 0.1.0-alpha.5
+
+- Version bump for npm alpha publication after `0.1.0-alpha.4`.
+- No runtime command changes from `0.1.0-alpha.4`.
+- Keeps the package README and release notes aligned with the current CLI export surface.
+
+## 0.1.0-alpha.4
+
+This alpha brought the CLI up to date with the current Svg/icons Pro export workflow.
+
+- Added single-icon PNG export with `svgicons icon png`, including PNG and ZIP variant downloads.
+- Added collection PNG pack export with size, density, background, color, padding, and fit options.
+- Added collection export format support for `svelte`, `solid`, `blade`, `storybook`, `npm-package`, and `iconify-json`.
+- Added `png` as a shorthand for the `png-pack` collection export format.
+- Added safe framework export options: `--default-size`, `--component-suffix`, `--title-prop`, `--no-title-prop`, `--decorative`, and `--no-decorative`.
+- Added npm package export metadata options: `--package-name` and `--package-version`.
+- Added `svgicons export download <export-id> --collection <collection>` for downloading queued collection export ZIPs.
+- Updated CLI docs and tests for the newer Pro API export formats.
+
+## 0.1.0-alpha.3
 
 This alpha refresh improves token setup safety. `login` now rejects obviously truncated numeric tokens, which commonly happens when a shell command is run without quoting a Sanctum-style token containing `|`.
 
@@ -44,6 +67,7 @@ Before publishing, run:
 
 ```bash
 npm --prefix cli test
+cd cli
 npm pack --dry-run
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@svgicons-com/cli",
-  "version": "0.1.0-alpha.3",
+  "version": "0.1.0-alpha.5",
   "description": "Svg/icons CLI alpha for icon search, Pro collections, exports, project scanning, and license workflows.",
   "type": "module",
   "bin": {
@@ -13,7 +13,7 @@
     "RELEASE_NOTES.md"
   ],
   "scripts": {
-    "test": "node --test tests"
+    "test": "node --test"
   },
   "engines": {
     "node": ">=18.18"

package/src/api.js

@@ -79,14 +79,26 @@ export async function proApiDownload(pathOrUrl, options = {}) {
   let response;
 
   try {
-    response = await fetch(url, {
+    const headers = {
+      Accept: 'image/png, application/zip, application/octet-stream',
+      Authorization: `Bearer ${token}`,
+      'User-Agent': 'svgicons-cli/0.1.0-alpha',
+      ...options.headers,
+    };
+    const init = {
       method: options.method || 'GET',
-      headers: {
-        Accept: 'application/zip, application/octet-stream',
-        Authorization: `Bearer ${token}`,
-        'User-Agent': 'svgicons-cli/0.1.0-alpha',
-        ...options.headers,
-      },
+      headers,
+    };
+
+    if (options.body !== undefined) {
+      headers['Content-Type'] = headers['Content-Type'] || 'application/json';
+      init.body = typeof options.body === 'string' || options.body instanceof Buffer
+        ? options.body
+        : JSON.stringify(options.body);
+    }
+
+    response = await fetch(url, {
+      ...init,
     });
   } catch (error) {
     throw networkError(error, url);

package/src/cli.js

@@ -22,6 +22,7 @@ import {
   parseIconReference,
   resolveArchiveDownloadPath,
   resolveIconDownloadPath,
+  resolvePngDownloadPath,
   sanitizeFileSegment,
   writeBinaryFile,
   writeIconSvg,
@@ -56,10 +57,29 @@ const KNOWN_SCOPES = [
   'exports:create',
   'mcp:use',
 ];
-const EXPORT_FORMATS = ['svg-folder', 'svg-sprite', 'json-manifest', 'license-manifest', 'react-ts', 'vue'];
+const EXPORT_FORMATS = [
+  'svg-folder',
+  'svg-sprite',
+  'json-manifest',
+  'license-manifest',
+  'react-ts',
+  'vue',
+  'svelte',
+  'solid',
+  'blade',
+  'storybook',
+  'npm-package',
+  'png-pack',
+  'iconify-json',
+];
 const FRAMEWORKS = ['svg', 'react-ts', 'vue', 'sprite'];
 const COLOR_POLICIES = ['currentColor', 'preserve', 'strip'];
 const NAMING_POLICIES = ['kebab', 'pascal', 'camel'];
+const PNG_SIZES = [16, 24, 32, 48, 96, 128, 256, 512, 1024];
+const PNG_DENSITIES = [1, 2, 3, 4];
+const PNG_BACKGROUNDS = ['transparent', 'solid'];
+const PNG_COLORS = ['preserve', 'black', 'white', 'custom'];
+const PNG_FITS = ['contain'];
 
 export async function run(argv) {
   const { args, options: globalOptions } = extractGlobalOptions(argv);
@@ -633,7 +653,12 @@ async function icon(args) {
     return;
   }
 
-  throw new Error('Unknown icon command. Use: show, raw, url, open, download.');
+  if (subcommand === 'png') {
+    await iconPng(rest);
+    return;
+  }
+
+  throw new Error('Unknown icon command. Use: show, raw, url, open, download, png.');
 }
 
 async function iconShow(args) {
@@ -715,6 +740,40 @@ async function iconDownload(args) {
   console.log(`  ${outputPath}`);
 }
 
+async function iconPng(args) {
+  const options = parseOptions(args);
+  const [iconReference] = options._;
+  const reference = parseIconReference(iconReference);
+  const payload = buildIconPngPayload(reference, options);
+  const download = await proApiDownload(`/api/pro/icons/${encodeURIComponent(reference.id)}/png-export`, {
+    method: 'POST',
+    body: payload,
+    headers: {
+      'Content-Type': 'application/json',
+    },
+  });
+  const outputPath = resolvePngDownloadPath(options.output || options.o, download.filename, process.cwd());
+
+  await writeBinaryFile(outputPath, download.bytes, booleanOption(options.force, false));
+
+  if (options.json) {
+    printJson({
+      icon: {
+        id: reference.id,
+        name: reference.slug,
+      },
+      outputPath,
+      contentType: download.contentType,
+      filename: download.filename,
+      options: payload,
+    });
+    return;
+  }
+
+  console.log(`Downloaded PNG export`);
+  console.log(`  ${outputPath}`);
+}
+
 async function collection(args) {
   const [subcommand, ...rest] = args;
 
@@ -1173,7 +1232,7 @@ async function buildProject(args) {
   const format = options.format || manifest.format || 'svg';
 
   if (format !== 'svg') {
-    throw usageError('Local build currently supports format svg. Use collection export for React TypeScript or Vue component ZIPs.');
+    throw usageError('Local build currently supports format svg. Use collection export for React TypeScript, Vue, Svelte, or Solid component ZIPs.');
   }
 
   const outputDir = resolve(String(options.output || options.o || manifest.output));
@@ -1830,17 +1889,163 @@ function extensionSet(value) {
 }
 
 function buildExportOptions(options) {
+  const formats = exportFormatsOption(options.formats);
+  const png = buildCollectionPngOptions(options);
+  const includesPng = formats?.includes('png-pack') || Object.keys(png).length > 0;
+  const normalizedFormats = includesPng && formats === undefined
+    ? ['png-pack']
+    : formats;
+
   return {
-    formats: enumCsvOption(options.formats, 'export format', EXPORT_FORMATS),
+    formats: normalizedFormats,
     options: {
       colorPolicy: enumOption(options['color-policy'], 'color policy', COLOR_POLICIES),
       namingPolicy: enumOption(options['naming-policy'], 'naming policy', NAMING_POLICIES),
       sizeProps: booleanFlagPair(options, 'size-props', 'no-size-props'),
       typescript: booleanFlagPair(options, 'typescript', 'no-typescript'),
+      defaultSize: boundedIntegerOption(options['default-size'], 'default component size', 1, 1024),
+      titleProp: booleanFlagPair(options, 'title-prop', 'no-title-prop'),
+      decorative: booleanFlagPair(options, 'decorative', 'no-decorative'),
+      componentSuffix: identifierOption(options['component-suffix'], 'component suffix'),
+      packageName: packageNameOption(options['package-name']),
+      packageVersion: packageVersionOption(options['package-version']),
+      png: includesPng ? png : undefined,
     },
   };
 }
 
+function buildIconPngPayload(reference, options) {
+  return {
+    iconName: reference.slug,
+    sizes: integerCsvOption(options.sizes ?? options.size, 'PNG size', PNG_SIZES, [512]),
+    densities: integerCsvOption(options.densities ?? options.density, 'PNG density', PNG_DENSITIES, [1]),
+    backgroundType: enumOption(options.background, 'PNG background', PNG_BACKGROUNDS),
+    backgroundColor: options['background-color'],
+    iconColorMode: enumOption(options.color, 'PNG icon color mode', PNG_COLORS),
+    iconColor: options['icon-color'],
+    padding: integerOption(options.padding, 'PNG padding'),
+    fit: enumOption(options.fit, 'PNG fit mode', PNG_FITS),
+    filename: options.filename,
+    zip: booleanOption(options.zip, undefined),
+  };
+}
+
+function buildCollectionPngOptions(options) {
+  return stripUndefined({
+    sizes: integerCsvOption(options['png-sizes'] ?? options['png-size'], 'PNG size', PNG_SIZES, undefined),
+    densities: integerCsvOption(options['png-densities'] ?? options['png-density'], 'PNG density', [1, 2, 3], undefined),
+    backgroundType: enumOption(options['png-background'], 'PNG background', PNG_BACKGROUNDS),
+    backgroundColor: options['png-background-color'],
+    iconColorMode: enumOption(options['png-color'], 'PNG icon color mode', PNG_COLORS),
+    iconColor: options['png-icon-color'],
+    padding: integerOption(options['png-padding'], 'PNG padding'),
+    fit: enumOption(options['png-fit'], 'PNG fit mode', PNG_FITS),
+  });
+}
+
+function exportFormatsOption(value) {
+  const values = csvOption(value);
+
+  if (!values) {
+    return undefined;
+  }
+
+  const normalized = values.map((item) => item === 'png' ? 'png-pack' : item);
+  const invalid = normalized.filter((item) => !EXPORT_FORMATS.includes(item));
+  if (invalid.length > 0) {
+    throw usageError(`Invalid export format: ${invalid.join(', ')}. Allowed values: ${EXPORT_FORMATS.join(', ')}, png`);
+  }
+
+  return [...new Set(normalized)];
+}
+
+function integerCsvOption(value, label, allowed, fallback) {
+  const values = csvOption(value);
+
+  if (!values) {
+    return fallback;
+  }
+
+  const parsed = values.map((item) => Number(item));
+  const invalid = parsed.filter((item) => !Number.isInteger(item) || !allowed.includes(item));
+
+  if (invalid.length > 0) {
+    throw usageError(`Invalid ${label}: ${invalid.join(', ')}. Allowed values: ${allowed.join(', ')}`);
+  }
+
+  return [...new Set(parsed)];
+}
+
+function integerOption(value, label) {
+  if (value === undefined || value === true || value === '') {
+    return undefined;
+  }
+
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed)) {
+    throw usageError(`Invalid ${label}: ${value}. Expected an integer.`);
+  }
+
+  return parsed;
+}
+
+function boundedIntegerOption(value, label, min, max) {
+  const parsed = integerOption(value, label);
+
+  if (parsed === undefined) {
+    return undefined;
+  }
+
+  if (parsed < min || parsed > max) {
+    throw usageError(`Invalid ${label}: ${value}. Allowed range: ${min}-${max}.`);
+  }
+
+  return parsed;
+}
+
+function identifierOption(value, label) {
+  if (value === undefined || value === true || value === '') {
+    return undefined;
+  }
+
+  const parsed = String(value);
+  if (!/^[A-Za-z][A-Za-z0-9]{0,31}$/.test(parsed)) {
+    throw usageError(`Invalid ${label}: ${value}. Use 1-32 letters or numbers, starting with a letter.`);
+  }
+
+  return parsed;
+}
+
+function packageNameOption(value) {
+  if (value === undefined || value === true || value === '') {
+    return undefined;
+  }
+
+  const parsed = String(value);
+  if (parsed.length > 214 || parsed.toLowerCase() !== parsed || !/^(?:@[a-z0-9][a-z0-9._-]*\/[a-z0-9][a-z0-9._-]*|[a-z0-9][a-z0-9._-]*)$/.test(parsed)) {
+    throw usageError(`Invalid npm package name: ${value}. Use a lowercase npm package name such as svgicons-dashboard or @svgicons-com/dashboard.`);
+  }
+
+  return parsed;
+}
+
+function packageVersionOption(value) {
+  if (value === undefined || value === true || value === '') {
+    return undefined;
+  }
+
+  const parsed = String(value);
+  if (parsed.length > 64 || !/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/.test(parsed)) {
+    throw usageError(`Invalid npm package version: ${value}. Use a semver-like version such as 1.0.0 or 1.0.0-beta.1.`);
+  }
+
+  return parsed;
+}
+
+function stripUndefined(value) {
+  return Object.fromEntries(Object.entries(value).filter(([, item]) => item !== undefined));
+}
+
 function enumOption(value, label, allowed) {
   if (value === undefined || value === true || value === '') {
     return undefined;
@@ -1894,6 +2099,7 @@ Usage:
   svgicons icon url <icon-ref>
   svgicons icon open <icon-ref>
   svgicons icon download <icon-id-name> [--output ./icons] [--force]
+  svgicons icon png <icon-id-name> [--size 512] [--density 1,2] [--output ./icons] [--force]
   svgicons collection list [--json]
   svgicons collection create --name "Dashboard icons"
   svgicons collection show <collection-id-or-name> [--icons] [--json]
@@ -1902,7 +2108,7 @@ Usage:
   svgicons collection add <collection-id-or-name> <icon-id...>
   svgicons collection remove <collection-id-or-name> <icon-id...>
   svgicons collection delete <collection-id-or-name> [--yes]
-  svgicons collection export <collection-id-or-name> [--formats react-ts,vue] [--no-size-props] [--no-typescript] [--output ./exports]
+  svgicons collection export <collection-id-or-name> [--formats react-ts,vue,svelte,solid,blade,storybook,npm-package,png-pack,iconify-json] [--default-size 24] [--component-suffix Icon] [--package-name svgicons-dashboard] [--package-version 0.1.0] [--title-prop|--no-title-prop] [--decorative|--no-decorative] [--no-size-props] [--no-typescript] [--output ./exports]
   svgicons export status <export-id> --collection <collection-id-or-name>
   svgicons export download <export-id> --collection <collection-id-or-name> [--output ./exports]
   svgicons init [--collection <collection-id-or-name>] [--output svgicons-icons]

package/src/downloads.js

@@ -95,6 +95,25 @@ export function resolveArchiveDownloadPath(output, filename, cwd = process.cwd()
   return join(target, safeFilename);
 }
 
+export function resolvePngDownloadPath(output, filename, cwd = process.cwd()) {
+  const safeFilename = sanitizeFileName(filename || 'svgicons-icon.png', 'png');
+
+  if (!output || output === true) {
+    return resolve(cwd, safeFilename);
+  }
+
+  const target = isAbsolute(String(output))
+    ? String(output)
+    : resolve(cwd, String(output));
+
+  const extension = extname(target).toLowerCase();
+  if (extension === '.png' || extension === '.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.');