iconify-search 0.0.1

package/README.md

@@ -0,0 +1,91 @@
+# iconify-search
+
+A command-line client for the [Iconify API](https://iconify.design/docs/api/), built with TypeScript and Bun.
+
+Browse and search 200k+ open-source icons, and build SVG URLs with transformations applied — straight from the terminal.
+
+## Install
+
+```bash
+bun install
+```
+
+Run via Bun:
+
+```bash
+bun run index.ts <command> [options]
+```
+
+Or link it as `iconify-search`:
+
+```bash
+bun link
+iconify-search <command> [options]
+```
+
+## Commands
+
+Icons are referenced as `prefix:name` (e.g. `mdi:home`), matching Iconify's own convention.
+
+Structured output (`search`, `collections`, `list`) is rendered as [TOON](https://github.com/toon-format/toon) by default — compact and readable. Pass `--json` for raw JSON.
+
+### `url <prefix:name>`
+
+Build an SVG URL for an icon, with optional transformations.
+
+```bash
+iconify-search url mdi:home
+iconify-search url mdi:home --color '#ba3329' --width 24
+iconify-search url mdi:home --rotate 90deg --flip horizontal --box
+```
+
+Options: `--color`, `--width`, `--height`, `--flip`, `--rotate`, `--box`, `--download`.
+
+### `search <query>`
+
+Search icons across all icon sets.
+
+```bash
+iconify-search search home
+iconify-search search arrow --limit 999 --prefixes mdi-,bi
+```
+
+Options: `--limit`, `--prefix`, `--prefixes`, `--category`, `--json`.
+
+### `collections`
+
+List available icon sets.
+
+```bash
+iconify-search collections
+iconify-search collections --prefixes fa,bi
+```
+
+Options: `--prefix`, `--prefixes`, `--json`.
+
+### `list <prefix>`
+
+List the icon names within an icon set.
+
+```bash
+iconify-search list mdi-light
+```
+
+Options: `--info`, `--chars`, `--json`.
+
+## Development
+
+```bash
+bun test          # run the test suite
+bunx tsc --noEmit # typecheck
+```
+
+The codebase separates pure logic from I/O:
+
+- `src/api.ts` — URL builders for every endpoint
+- `src/icon-ref.ts` — `prefix:name` parsing
+- `src/transform.ts` — reshaping API responses for output
+- `src/output.ts` — TOON / JSON formatting
+- `src/fetch.ts` — the network boundary
+- `src/commands/*` — command handlers (network injected for testability)
+- `src/cli.ts` — argument parsing and dispatch

package/dist/index.js

@@ -0,0 +1,675 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { parseArgs } from "node:util";
+
+// src/api.ts
+var API_BASE = "https://api.iconify.design";
+function buildSvgUrl(ref, options) {
+  const url = new URL(`${API_BASE}/${ref.prefix}/${ref.name}.svg`);
+  applyParams(url, options);
+  return url.toString();
+}
+function buildSearchUrl(query, options) {
+  const url = new URL(`${API_BASE}/search`);
+  url.searchParams.set("query", query);
+  applyParams(url, options);
+  return url.toString();
+}
+function buildCollectionsUrl(options) {
+  const url = new URL(`${API_BASE}/collections`);
+  applyParams(url, options);
+  return url.toString();
+}
+function buildCollectionUrl(prefix, options) {
+  const url = new URL(`${API_BASE}/collection`);
+  url.searchParams.set("prefix", prefix);
+  applyParams(url, options);
+  return url.toString();
+}
+function applyParams(url, params) {
+  for (const [key, value] of Object.entries(params)) {
+    if (value === undefined || value === false)
+      continue;
+    url.searchParams.set(key, value === true ? "1" : String(value));
+  }
+}
+
+// node_modules/@toon-format/toon/dist/index.mjs
+var NULL_LITERAL = "null";
+var DELIMITERS = {
+  comma: ",",
+  tab: "\t",
+  pipe: "|"
+};
+var DEFAULT_DELIMITER = DELIMITERS.comma;
+function escapeString(value) {
+  return value.replace(/\\/g, `\\\\`).replace(/"/g, `\\"`).replace(/\n/g, `\\n`).replace(/\r/g, `\\r`).replace(/\t/g, `\\t`).replace(/[\u0000-\u001F]/g, (c) => `\\u${c.charCodeAt(0).toString(16).padStart(4, "0")}`);
+}
+function isBooleanOrNullLiteral(token) {
+  return token === "true" || token === "false" || token === "null";
+}
+function normalizeValue(value) {
+  if (value === null)
+    return null;
+  if (typeof value === "object" && value !== null && "toJSON" in value && typeof value.toJSON === "function") {
+    const next = value.toJSON();
+    if (next !== value)
+      return normalizeValue(next);
+  }
+  if (typeof value === "string" || typeof value === "boolean")
+    return value;
+  if (typeof value === "number") {
+    if (Object.is(value, -0))
+      return 0;
+    if (!Number.isFinite(value))
+      return null;
+    return value;
+  }
+  if (typeof value === "bigint") {
+    if (value >= Number.MIN_SAFE_INTEGER && value <= Number.MAX_SAFE_INTEGER)
+      return Number(value);
+    return value.toString();
+  }
+  if (value instanceof Date)
+    return value.toISOString();
+  if (Array.isArray(value))
+    return value.map(normalizeValue);
+  if (value instanceof Set)
+    return Array.from(value).map(normalizeValue);
+  if (value instanceof Map)
+    return Object.fromEntries(Array.from(value, ([k, v]) => [String(k), normalizeValue(v)]));
+  if (isPlainObject(value)) {
+    const encodedValues = {};
+    for (const key in value)
+      if (Object.hasOwn(value, key))
+        encodedValues[key] = normalizeValue(value[key]);
+    return encodedValues;
+  }
+  return null;
+}
+function isJsonPrimitive(value) {
+  return value === null || typeof value === "string" || typeof value === "number" || typeof value === "boolean";
+}
+function isJsonArray(value) {
+  return Array.isArray(value);
+}
+function isJsonObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function isEmptyObject(value) {
+  return Object.keys(value).length === 0;
+}
+function isPlainObject(value) {
+  if (value === null || typeof value !== "object")
+    return false;
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === null || prototype === Object.prototype;
+}
+function isArrayOfPrimitives(value) {
+  return value.length === 0 || value.every((item) => isJsonPrimitive(item));
+}
+function isArrayOfArrays(value) {
+  return value.length === 0 || value.every((item) => isJsonArray(item));
+}
+function isArrayOfObjects(value) {
+  return value.length === 0 || value.every((item) => isJsonObject(item));
+}
+var NUMERIC_LIKE_PATTERN = /^-?\d+(?:\.\d+)?(?:e[+-]?\d+)?$/i;
+var LEADING_ZERO_PATTERN = /^0\d+$/;
+function isValidUnquotedKey(key) {
+  return /^[A-Z_][\w.]*$/i.test(key);
+}
+function isIdentifierSegment(key) {
+  return /^[A-Z_]\w*$/i.test(key);
+}
+function isSafeUnquoted(value, delimiter = DEFAULT_DELIMITER) {
+  if (!value)
+    return false;
+  if (value !== value.trim())
+    return false;
+  if (isBooleanOrNullLiteral(value) || isNumericLike(value))
+    return false;
+  if (value.includes(":"))
+    return false;
+  if (value.includes('"') || value.includes("\\"))
+    return false;
+  if (/[[\]{}]/.test(value))
+    return false;
+  if (/[\u0000-\u001F]/.test(value))
+    return false;
+  if (value.includes(delimiter))
+    return false;
+  if (value.startsWith("-"))
+    return false;
+  return true;
+}
+function isNumericLike(value) {
+  return NUMERIC_LIKE_PATTERN.test(value) || LEADING_ZERO_PATTERN.test(value);
+}
+var QUOTED_KEY_MARKER = Symbol("quotedKey");
+function tryFoldKeyChain(key, value, siblings, options, rootLiteralKeys, pathPrefix, flattenDepth) {
+  if (options.keyFolding !== "safe")
+    return;
+  if (!isJsonObject(value))
+    return;
+  const { segments, tail, leafValue } = collectSingleKeyChain(key, value, flattenDepth ?? options.flattenDepth);
+  if (segments.length < 2)
+    return;
+  if (!segments.every((seg) => isIdentifierSegment(seg)))
+    return;
+  const foldedKey = buildFoldedKey(segments);
+  const absolutePath = pathPrefix ? `${pathPrefix}.${foldedKey}` : foldedKey;
+  if (siblings.includes(foldedKey))
+    return;
+  if (rootLiteralKeys && rootLiteralKeys.has(absolutePath))
+    return;
+  return {
+    foldedKey,
+    remainder: tail,
+    leafValue,
+    segmentCount: segments.length
+  };
+}
+function collectSingleKeyChain(startKey, startValue, maxDepth) {
+  const segments = [startKey];
+  let currentValue = startValue;
+  while (segments.length < maxDepth) {
+    if (!isJsonObject(currentValue))
+      break;
+    const keys = Object.keys(currentValue);
+    if (keys.length !== 1)
+      break;
+    const nextKey = keys[0];
+    const nextValue = currentValue[nextKey];
+    segments.push(nextKey);
+    currentValue = nextValue;
+  }
+  if (!isJsonObject(currentValue) || isEmptyObject(currentValue))
+    return {
+      segments,
+      tail: undefined,
+      leafValue: currentValue
+    };
+  return {
+    segments,
+    tail: currentValue,
+    leafValue: currentValue
+  };
+}
+function buildFoldedKey(segments) {
+  return segments.join(".");
+}
+function encodePrimitive(value, delimiter) {
+  if (value === null)
+    return NULL_LITERAL;
+  if (typeof value === "boolean")
+    return String(value);
+  if (typeof value === "number")
+    return String(value);
+  return encodeStringLiteral(value, delimiter);
+}
+function encodeStringLiteral(value, delimiter = DEFAULT_DELIMITER) {
+  if (isSafeUnquoted(value, delimiter))
+    return value;
+  return `"${escapeString(value)}"`;
+}
+function encodeKey(key) {
+  if (isValidUnquotedKey(key))
+    return key;
+  return `"${escapeString(key)}"`;
+}
+function encodeAndJoinPrimitives(values, delimiter = DEFAULT_DELIMITER) {
+  return values.map((v) => encodePrimitive(v, delimiter)).join(delimiter);
+}
+function formatHeader(length, options) {
+  const key = options?.key;
+  const fields = options?.fields;
+  const delimiter = options?.delimiter ?? ",";
+  let header = "";
+  if (key != null)
+    header += encodeKey(key);
+  header += `[${length}${delimiter !== DEFAULT_DELIMITER ? delimiter : ""}]`;
+  if (fields) {
+    const quotedFields = fields.map((f) => encodeKey(f));
+    header += `{${quotedFields.join(delimiter)}}`;
+  }
+  header += ":";
+  return header;
+}
+function* encodeJsonValue(value, options, depth) {
+  if (isJsonPrimitive(value)) {
+    const encodedPrimitive = encodePrimitive(value, options.delimiter);
+    if (encodedPrimitive !== "")
+      yield encodedPrimitive;
+    return;
+  }
+  if (isJsonArray(value))
+    yield* encodeArrayLines(undefined, value, depth, options);
+  else if (isJsonObject(value))
+    yield* encodeObjectLines(value, depth, options);
+}
+function* encodeObjectLines(value, depth, options, rootLiteralKeys, pathPrefix, remainingDepth) {
+  const keys = Object.keys(value);
+  if (depth === 0 && !rootLiteralKeys)
+    rootLiteralKeys = new Set(keys.filter((k) => k.includes(".")));
+  const effectiveFlattenDepth = remainingDepth ?? options.flattenDepth;
+  for (const [key, val] of Object.entries(value))
+    yield* encodeKeyValuePairLines(key, val, depth, options, keys, rootLiteralKeys, pathPrefix, effectiveFlattenDepth);
+}
+function* encodeKeyValuePairLines(key, value, depth, options, siblings, rootLiteralKeys, pathPrefix, flattenDepth) {
+  const currentPath = pathPrefix ? `${pathPrefix}.${key}` : key;
+  const effectiveFlattenDepth = flattenDepth ?? options.flattenDepth;
+  if (options.keyFolding === "safe" && siblings) {
+    const foldResult = tryFoldKeyChain(key, value, siblings, options, rootLiteralKeys, pathPrefix, effectiveFlattenDepth);
+    if (foldResult) {
+      const { foldedKey, remainder, leafValue, segmentCount } = foldResult;
+      const encodedFoldedKey = encodeKey(foldedKey);
+      if (remainder === undefined) {
+        if (isJsonPrimitive(leafValue)) {
+          yield indentedLine(depth, `${encodedFoldedKey}: ${encodePrimitive(leafValue, options.delimiter)}`, options.indent);
+          return;
+        } else if (isJsonArray(leafValue)) {
+          yield* encodeArrayLines(foldedKey, leafValue, depth, options);
+          return;
+        } else if (isJsonObject(leafValue) && isEmptyObject(leafValue)) {
+          yield indentedLine(depth, `${encodedFoldedKey}:`, options.indent);
+          return;
+        }
+      }
+      if (isJsonObject(remainder)) {
+        yield indentedLine(depth, `${encodedFoldedKey}:`, options.indent);
+        const remainingDepth = effectiveFlattenDepth - segmentCount;
+        const foldedPath = pathPrefix ? `${pathPrefix}.${foldedKey}` : foldedKey;
+        yield* encodeObjectLines(remainder, depth + 1, options, rootLiteralKeys, foldedPath, remainingDepth);
+        return;
+      }
+    }
+  }
+  const encodedKey = encodeKey(key);
+  if (isJsonPrimitive(value))
+    yield indentedLine(depth, `${encodedKey}: ${encodePrimitive(value, options.delimiter)}`, options.indent);
+  else if (isJsonArray(value))
+    yield* encodeArrayLines(key, value, depth, options);
+  else if (isJsonObject(value)) {
+    yield indentedLine(depth, `${encodedKey}:`, options.indent);
+    if (!isEmptyObject(value))
+      yield* encodeObjectLines(value, depth + 1, options, rootLiteralKeys, currentPath, effectiveFlattenDepth);
+  }
+}
+function* encodeArrayLines(key, value, depth, options) {
+  if (value.length === 0) {
+    yield indentedLine(depth, key != null ? `${encodeKey(key)}: []` : "[]", options.indent);
+    return;
+  }
+  if (isArrayOfPrimitives(value)) {
+    yield indentedLine(depth, encodeInlineArrayLine(value, options.delimiter, key), options.indent);
+    return;
+  }
+  if (isArrayOfArrays(value)) {
+    if (value.every((arr) => isArrayOfPrimitives(arr))) {
+      yield* encodeArrayOfArraysAsListItemsLines(key, value, depth, options);
+      return;
+    }
+  }
+  if (isArrayOfObjects(value)) {
+    const header = extractTabularHeader(value);
+    if (header)
+      yield* encodeArrayOfObjectsAsTabularLines(key, value, header, depth, options);
+    else
+      yield* encodeMixedArrayAsListItemsLines(key, value, depth, options);
+    return;
+  }
+  yield* encodeMixedArrayAsListItemsLines(key, value, depth, options);
+}
+function* encodeArrayOfArraysAsListItemsLines(prefix, values, depth, options) {
+  yield indentedLine(depth, formatHeader(values.length, {
+    key: prefix,
+    delimiter: options.delimiter
+  }), options.indent);
+  for (const arr of values)
+    if (isArrayOfPrimitives(arr)) {
+      const arrayLine = encodeInlineArrayLine(arr, options.delimiter);
+      yield indentedListItem(depth + 1, arrayLine, options.indent);
+    }
+}
+function encodeInlineArrayLine(values, delimiter, prefix) {
+  const header = formatHeader(values.length, {
+    key: prefix,
+    delimiter
+  });
+  const joinedValue = encodeAndJoinPrimitives(values, delimiter);
+  if (values.length === 0)
+    return header;
+  return `${header} ${joinedValue}`;
+}
+function* encodeArrayOfObjectsAsTabularLines(prefix, rows, header, depth, options) {
+  yield indentedLine(depth, formatHeader(rows.length, {
+    key: prefix,
+    fields: header,
+    delimiter: options.delimiter
+  }), options.indent);
+  yield* writeTabularRowsLines(rows, header, depth + 1, options);
+}
+function extractTabularHeader(rows) {
+  if (rows.length === 0)
+    return;
+  const firstRow = rows[0];
+  const firstKeys = Object.keys(firstRow);
+  if (firstKeys.length === 0)
+    return;
+  if (isTabularArray(rows, firstKeys))
+    return firstKeys;
+}
+function isTabularArray(rows, header) {
+  for (const row of rows) {
+    if (Object.keys(row).length !== header.length)
+      return false;
+    for (const key of header) {
+      if (!(key in row))
+        return false;
+      if (!isJsonPrimitive(row[key]))
+        return false;
+    }
+  }
+  return true;
+}
+function* writeTabularRowsLines(rows, header, depth, options) {
+  for (const row of rows)
+    yield indentedLine(depth, encodeAndJoinPrimitives(header.map((key) => row[key]), options.delimiter), options.indent);
+}
+function* encodeMixedArrayAsListItemsLines(prefix, items, depth, options) {
+  yield indentedLine(depth, formatHeader(items.length, {
+    key: prefix,
+    delimiter: options.delimiter
+  }), options.indent);
+  for (const item of items)
+    yield* encodeListItemValueLines(item, depth + 1, options);
+}
+function* encodeObjectAsListItemLines(obj, depth, options) {
+  if (isEmptyObject(obj)) {
+    yield indentedLine(depth, "-", options.indent);
+    return;
+  }
+  const entries = Object.entries(obj);
+  const [firstKey, firstValue] = entries[0];
+  const restEntries = entries.slice(1);
+  if (isJsonArray(firstValue) && isArrayOfObjects(firstValue)) {
+    const header = extractTabularHeader(firstValue);
+    if (header) {
+      yield indentedListItem(depth, formatHeader(firstValue.length, {
+        key: firstKey,
+        fields: header,
+        delimiter: options.delimiter
+      }), options.indent);
+      yield* writeTabularRowsLines(firstValue, header, depth + 2, options);
+      if (restEntries.length > 0)
+        yield* encodeObjectLines(Object.fromEntries(restEntries), depth + 1, options);
+      return;
+    }
+  }
+  const encodedKey = encodeKey(firstKey);
+  if (isJsonPrimitive(firstValue))
+    yield indentedListItem(depth, `${encodedKey}: ${encodePrimitive(firstValue, options.delimiter)}`, options.indent);
+  else if (isJsonArray(firstValue))
+    if (firstValue.length === 0)
+      yield indentedListItem(depth, `${encodedKey}: []`, options.indent);
+    else if (isArrayOfPrimitives(firstValue))
+      yield indentedListItem(depth, `${encodedKey}${encodeInlineArrayLine(firstValue, options.delimiter)}`, options.indent);
+    else {
+      yield indentedListItem(depth, `${encodedKey}${formatHeader(firstValue.length, { delimiter: options.delimiter })}`, options.indent);
+      for (const item of firstValue)
+        yield* encodeListItemValueLines(item, depth + 2, options);
+    }
+  else if (isJsonObject(firstValue)) {
+    yield indentedListItem(depth, `${encodedKey}:`, options.indent);
+    if (!isEmptyObject(firstValue))
+      yield* encodeObjectLines(firstValue, depth + 2, options);
+  }
+  if (restEntries.length > 0)
+    yield* encodeObjectLines(Object.fromEntries(restEntries), depth + 1, options);
+}
+function* encodeListItemValueLines(value, depth, options) {
+  if (isJsonPrimitive(value))
+    yield indentedListItem(depth, encodePrimitive(value, options.delimiter), options.indent);
+  else if (isJsonArray(value))
+    if (isArrayOfPrimitives(value))
+      yield indentedListItem(depth, encodeInlineArrayLine(value, options.delimiter), options.indent);
+    else {
+      yield indentedListItem(depth, formatHeader(value.length, { delimiter: options.delimiter }), options.indent);
+      for (const item of value)
+        yield* encodeListItemValueLines(item, depth + 1, options);
+    }
+  else if (isJsonObject(value))
+    yield* encodeObjectAsListItemLines(value, depth, options);
+}
+function indentedLine(depth, content, indentSize) {
+  return " ".repeat(indentSize * depth) + content;
+}
+function indentedListItem(depth, content, indentSize) {
+  return indentedLine(depth, "- " + content, indentSize);
+}
+function applyReplacer(root, replacer) {
+  const replacedRoot = replacer("", root, []);
+  if (replacedRoot === undefined)
+    return transformChildren(root, replacer, []);
+  return transformChildren(normalizeValue(replacedRoot), replacer, []);
+}
+function transformChildren(value, replacer, path) {
+  if (isJsonObject(value))
+    return transformObject(value, replacer, path);
+  if (isJsonArray(value))
+    return transformArray(value, replacer, path);
+  return value;
+}
+function transformObject(obj, replacer, path) {
+  const result = {};
+  for (const [key, value] of Object.entries(obj)) {
+    const childPath = [...path, key];
+    const replacedValue = replacer(key, value, childPath);
+    if (replacedValue === undefined)
+      continue;
+    result[key] = transformChildren(normalizeValue(replacedValue), replacer, childPath);
+  }
+  return result;
+}
+function transformArray(arr, replacer, path) {
+  const result = [];
+  for (let i = 0;i < arr.length; i++) {
+    const value = arr[i];
+    const childPath = [...path, i];
+    const replacedValue = replacer(String(i), value, childPath);
+    if (replacedValue === undefined)
+      continue;
+    const normalizedValue = normalizeValue(replacedValue);
+    result.push(transformChildren(normalizedValue, replacer, childPath));
+  }
+  return result;
+}
+function encode(input, options) {
+  return Array.from(encodeLines(input, options)).join(`
+`);
+}
+function encodeLines(input, options) {
+  const normalizedValue = normalizeValue(input);
+  const resolvedOptions = resolveOptions(options);
+  return encodeJsonValue(resolvedOptions.replacer ? applyReplacer(normalizedValue, resolvedOptions.replacer) : normalizedValue, resolvedOptions, 0);
+}
+function resolveOptions(options) {
+  return {
+    indent: options?.indent ?? 2,
+    delimiter: options?.delimiter ?? DEFAULT_DELIMITER,
+    keyFolding: options?.keyFolding ?? "off",
+    flattenDepth: options?.flattenDepth ?? Number.POSITIVE_INFINITY,
+    replacer: options?.replacer
+  };
+}
+
+// src/output.ts
+function formatOutput(data, options) {
+  return options.json ? JSON.stringify(data, null, 2) : encode(data);
+}
+
+// src/transform.ts
+function collectionsTable(response) {
+  return Object.entries(response).map(([prefix, info]) => ({
+    prefix,
+    name: info.name ?? "",
+    total: info.total ?? 0,
+    category: info.category ?? ""
+  })).sort((a, b) => a.prefix.localeCompare(b.prefix));
+}
+function collectionIcons(response) {
+  const icons = new Set(response.uncategorized ?? []);
+  for (const names of Object.values(response.categories ?? {})) {
+    for (const name of names)
+      icons.add(name);
+  }
+  return [...icons];
+}
+
+// src/commands/collections.ts
+async function collectionsCommand(args, deps) {
+  const url = buildCollectionsUrl(args.options);
+  const response = await deps.fetchJson(url);
+  return formatOutput(collectionsTable(response), { json: args.json });
+}
+
+// src/commands/list.ts
+async function listCommand(args, deps) {
+  const url = buildCollectionUrl(args.prefix, args.options);
+  const response = await deps.fetchJson(url);
+  return formatOutput(collectionIcons(response), { json: args.json });
+}
+
+// src/commands/search.ts
+async function searchCommand(args, deps) {
+  const url = buildSearchUrl(args.query, args.options);
+  const response = await deps.fetchJson(url);
+  return formatOutput({ total: response.total, icons: response.icons }, { json: args.json });
+}
+
+// src/icon-ref.ts
+function parseIconRef(input) {
+  const [prefix, name, ...rest] = input.split(":");
+  if (!prefix || !name || rest.length > 0) {
+    throw new Error(`invalid icon "${input}": expected format prefix:name`);
+  }
+  return { prefix, name };
+}
+
+// src/commands/url.ts
+function urlCommand(args) {
+  const ref = parseIconRef(args.icon);
+  return buildSvgUrl(ref, args.options);
+}
+
+// src/cli.ts
+var USAGE = `Usage: iconify <command> [options]
+
+Commands:
+  url <prefix:name>   Build an SVG URL for an icon
+                      --color --width --height --flip --rotate --box --download
+  search <query>      Search icons across all sets
+                      --limit --prefix --prefixes --category
+  collections         List available icon sets
+                      --prefix --prefixes
+  list <prefix>       List icon names in an icon set
+                      --info --chars
+
+Structured output is TOON by default; pass --json for JSON.`;
+async function run(argv, deps) {
+  const [command, ...rest] = argv;
+  switch (command) {
+    case undefined:
+    case "help":
+    case "--help":
+    case "-h":
+      return USAGE;
+    case "url": {
+      const { values, positionals } = parseArgs({
+        args: rest,
+        allowPositionals: true,
+        options: {
+          color: { type: "string" },
+          width: { type: "string" },
+          height: { type: "string" },
+          flip: { type: "string" },
+          rotate: { type: "string" },
+          box: { type: "boolean" },
+          download: { type: "boolean" }
+        }
+      });
+      const icon = positionals[0];
+      if (!icon)
+        throw new Error("url: missing icon (e.g. mdi:home)");
+      return urlCommand({ icon, options: values });
+    }
+    case "search": {
+      const { values, positionals } = parseArgs({
+        args: rest,
+        allowPositionals: true,
+        options: {
+          limit: { type: "string" },
+          prefix: { type: "string" },
+          prefixes: { type: "string" },
+          category: { type: "string" },
+          json: { type: "boolean", default: false }
+        }
+      });
+      const query = positionals[0];
+      if (!query)
+        throw new Error("search: missing query");
+      const { json, ...options } = values;
+      return searchCommand({ query, options, json }, deps);
+    }
+    case "collections": {
+      const { values } = parseArgs({
+        args: rest,
+        options: {
+          prefix: { type: "string" },
+          prefixes: { type: "string" },
+          json: { type: "boolean", default: false }
+        }
+      });
+      const { json, ...options } = values;
+      return collectionsCommand({ options, json }, deps);
+    }
+    case "list": {
+      const { values, positionals } = parseArgs({
+        args: rest,
+        allowPositionals: true,
+        options: {
+          info: { type: "boolean" },
+          chars: { type: "boolean" },
+          json: { type: "boolean", default: false }
+        }
+      });
+      const prefix = positionals[0];
+      if (!prefix)
+        throw new Error("list: missing prefix");
+      const { json, ...options } = values;
+      return listCommand({ prefix, options, json }, deps);
+    }
+    default:
+      throw new Error(`unknown command: ${command}`);
+  }
+}
+
+// src/fetch.ts
+async function fetchJson(url) {
+  const response = await fetch(url);
+  if (!response.ok) {
+    throw new Error(`request failed (${response.status}): ${url}`);
+  }
+  return response.json();
+}
+
+// index.ts
+try {
+  const output = await run(process.argv.slice(2), { fetchJson });
+  console.log(output);
+} catch (error) {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exit(1);
+}

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "iconify-search",
+  "version": "0.0.1",
+  "module": "index.ts",
+  "type": "module",
+  "bin": { "iconify-search": "dist/index.js" },
+  "files": ["dist"],
+  "scripts": {
+    "test": "bun test",
+    "start": "bun run index.ts",
+    "build": "bun build index.ts --target node --outfile dist/index.js",
+    "prepublishOnly": "bun run build"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "@toon-format/toon": "^2.3.0"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  }
+}