@featherk/icons 0.13.9 → 0.14.1

package/README.md

@@ -66,6 +66,16 @@ variants, data URL usage, and related utilities) see [COMING-SOON.md](docs/COMIN
 
 [View the icon gallery](https://github.com/NantHealth/featherk/blob/integration/packages/icons/docs/ICONS.md)
 
+## Font Awesome Build Integration
+
+Font Awesome services are separate from `getCustomIcon()` and the owned icon registry. The package supplies a Vite plugin, Node generator, and CLI to prepare selected icons from the consumer's installed Font Awesome packages; it includes no Free or paid Font Awesome artwork and grants no license rights.
+
+Start with [Choose Font Awesome Icons and Create a Manifest](https://github.com/NantHealth/featherk/blob/integration/packages/icons/docs/fontawesome/CreateFontAwesomeManifest.md) for the UX/Design task of selecting and defining the exact icons your application will use.
+
+Dev then follows [Font Awesome setup](https://github.com/NantHealth/featherk/blob/integration/packages/icons/docs/fontawesome/FontAwesome.md) for the default Vite integration. For Dev-owned CLI generation, early type preparation, or non-Vite applications, see [CLI and non-Vite setup](https://github.com/NantHealth/featherk/blob/integration/packages/icons/docs/fontawesome/FontAwesomeCLI.md).
+
+For paid source packages, see [Pro licensing and setup](https://github.com/NantHealth/featherk/blob/integration/packages/icons/docs/fontawesome/LICENSING.md). Pro access is consumer-owned and optional; no paid artwork is distributed by this package.
+
 ## Adding icons
 
 Icons in this package are curated from the validated source assets in

package/dist/fontawesome/build.cjs

@@ -0,0 +1,4 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const generate = require("./chunks/generate-Bobf_ghm.cjs");
+exports.generateFaIcons = generate.generateFaIcons;

package/dist/fontawesome/build.d.ts

@@ -0,0 +1,3 @@
+export { generateFaIcons } from "./generate";
+export type { GenerateFaIconsOptions, GeneratedFaIcons, FontAwesomeProvenance, } from "./generate";
+export type { FontAwesomeSelection, FontAwesomeOptions, FontAwesomeIcon, } from "./types";

package/dist/fontawesome/build.mjs

@@ -0,0 +1,4 @@
+import { g } from "./chunks/generate-Bp92GTVi.mjs";
+export {
+  g as generateFaIcons
+};

package/dist/fontawesome/chunks/generate-Bobf_ghm.cjs

@@ -0,0 +1,288 @@
+"use strict";
+const node_module = require("node:module");
+const promises = require("node:fs/promises");
+const node_path = require("node:path");
+const node_crypto = require("node:crypto");
+const prefixes = {
+  "classic:solid": "fas",
+  "classic:regular": "far",
+  "classic:light": "fal",
+  "classic:thin": "fat",
+  "classic:brands": "fab",
+  "sharp:solid": "fass",
+  "sharp:regular": "fasr",
+  "sharp:light": "fasl",
+  "sharp:thin": "fast",
+  "duotone:solid": "fad",
+  "duotone:regular": "fadr",
+  "duotone:light": "fadl",
+  "duotone:thin": "fadt",
+  "sharp-duotone:solid": "fasds",
+  "sharp-duotone:regular": "fasdr",
+  "sharp-duotone:light": "fasdl",
+  "sharp-duotone:thin": "fasdt"
+};
+function expectedPrefix(selection) {
+  const prefix = prefixes[`${selection.family}:${selection.style}`];
+  if (!prefix) {
+    throw new Error(
+      `Unsupported Font Awesome family/style for "${selection.key}"`
+    );
+  }
+  return prefix;
+}
+function normalizeIcon(selection, definition) {
+  if (!definition || typeof definition !== "object") {
+    throw new Error(`Missing Font Awesome definition for "${selection.key}"`);
+  }
+  const source = definition;
+  if (source.iconName !== selection.name || source.prefix !== expectedPrefix(selection)) {
+    throw new Error(
+      `Font Awesome name/family/style mismatch for "${selection.key}"`
+    );
+  }
+  if (!Array.isArray(source.icon) || source.icon.length !== 5) {
+    throw new Error(`Invalid Font Awesome geometry for "${selection.key}"`);
+  }
+  const [width, height, , , pathData] = source.icon;
+  if (typeof width !== "number" || !Number.isFinite(width) || width <= 0 || typeof height !== "number" || !Number.isFinite(height) || height <= 0) {
+    throw new Error(`Invalid Font Awesome dimensions for "${selection.key}"`);
+  }
+  const paths = Array.isArray(pathData) ? pathData : [pathData];
+  const duotone = selection.family === "duotone" || selection.family === "sharp-duotone";
+  if (paths.length !== (duotone ? 2 : 1)) {
+    throw new Error(
+      `Unsupported Font Awesome path layers for "${selection.key}"`
+    );
+  }
+  for (const path of paths) {
+    if (typeof path !== "string" || !/^\s*[Mm]/.test(path) || !/^[MmZzLlHhVvCcSsQqTtAa0-9eE+.,\s-]+$/.test(path)) {
+      throw new Error(
+        `Unsafe or invalid Font Awesome path for "${selection.key}"`
+      );
+    }
+  }
+  const content = duotone ? `<path d="${paths[0]}" fill="var(--fa-secondary-color, currentColor)" opacity="var(--fa-secondary-opacity, 0.4)"/><path d="${paths[1]}" fill="var(--fa-primary-color, currentColor)" opacity="var(--fa-primary-opacity, 1)"/>` : `<path d="${paths[0]}" fill="currentColor"/>`;
+  return { name: selection.key, content, viewBox: `0 0 ${width} ${height}` };
+}
+function validateSelection(selection) {
+  if (!selection || typeof selection !== "object" || typeof selection.key !== "string" || !selection.key.trim()) {
+    throw new Error("Font Awesome selections require a non-empty key");
+  }
+  if (typeof selection.name !== "string" || !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(selection.name)) {
+    throw new Error(`Invalid Font Awesome name for "${selection.key}"`);
+  }
+  if (typeof selection.version !== "string" || !/^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/.test(
+    selection.version
+  )) {
+    throw new Error(
+      `Font Awesome "${selection.key}" requires an exact version`
+    );
+  }
+  if (typeof selection.package !== "string" || !/^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/.test(
+    selection.package
+  )) {
+    throw new Error(`Invalid Font Awesome package for "${selection.key}"`);
+  }
+  expectedPrefix(selection);
+  const exportName = selection.exportName ?? `fa${selection.name.split("-").map((part) => part[0].toUpperCase() + part.slice(1)).join("")}`;
+  if (typeof exportName !== "string" || !/^fa[A-Z0-9][A-Za-z0-9]*$/.test(exportName)) {
+    throw new Error(`Invalid Font Awesome export for "${selection.key}"`);
+  }
+  return exportName;
+}
+function serialize(value) {
+  return JSON.stringify(value).replace(/\u2028/g, "\\u2028").replace(/\u2029/g, "\\u2029");
+}
+async function validateOutput(root, file, declaration = false) {
+  const target = node_path.resolve(root, file);
+  const rootPath = await promises.realpath(root);
+  const relativeTarget = node_path.relative(rootPath, target);
+  if (node_path.isAbsolute(relativeTarget) || relativeTarget === ".." || relativeTarget.startsWith(`..${node_path.sep}`) || relativeTarget.split(node_path.sep).includes("node_modules")) {
+    throw new Error(
+      "Font Awesome output must be inside the consumer project, outside node_modules"
+    );
+  }
+  if ((declaration ? !target.endsWith(".d.ts") : ![".js", ".mjs"].includes(node_path.extname(target))) || node_path.basename(target).startsWith(".")) {
+    throw new Error(
+      declaration ? "Font Awesome virtual types output must be a named .d.ts file" : "Font Awesome output must be a named .js or .mjs module"
+    );
+  }
+  let current = node_path.dirname(target);
+  while (true) {
+    try {
+      const actual = await promises.realpath(current);
+      const boundary = node_path.relative(rootPath, actual);
+      if (node_path.isAbsolute(boundary) || boundary === ".." || boundary.startsWith(`..${node_path.sep}`)) {
+        throw new Error(
+          "Font Awesome output cannot escape the consumer project through a symlink"
+        );
+      }
+      const metadata = JSON.parse(
+        await promises.readFile(node_path.join(current, "package.json"), "utf8")
+      );
+      if (metadata.name === "@featherk/icons") {
+        throw new Error(
+          "Font Awesome output must not target the @featherk/icons package"
+        );
+      }
+    } catch (error) {
+      if (error.code !== "ENOENT") throw error;
+    }
+    if (current === rootPath) break;
+    const parent = node_path.dirname(current);
+    if (parent === current) throw new Error("Invalid Font Awesome output root");
+    current = parent;
+  }
+  for (const output of [
+    target,
+    target.replace(/\.(m?)js$/, ".d.$1ts"),
+    `${target}.licenses.txt`
+  ]) {
+    try {
+      const actual = await promises.realpath(output);
+      if (actual !== output)
+        throw new Error("Font Awesome output files must not be symlinks");
+    } catch (error) {
+      if (error.code !== "ENOENT") throw error;
+    }
+  }
+  return target;
+}
+async function writeOutput(target, result) {
+  await promises.mkdir(node_path.dirname(target), { recursive: true });
+  const outputs = [
+    [target, result.moduleCode],
+    [target.replace(/\.(m?)js$/, ".d.$1ts"), result.declarationCode],
+    [`${target}.licenses.txt`, result.notices]
+  ];
+  for (const [file, content] of outputs) {
+    await writeAtomically(file, content);
+  }
+}
+async function writeAtomically(file, content) {
+  await promises.mkdir(node_path.dirname(file), { recursive: true });
+  const temporary = `${file}.${node_crypto.randomUUID()}.tmp`;
+  try {
+    await promises.writeFile(temporary, content, { flag: "wx" });
+    await promises.rename(temporary, file);
+  } finally {
+    await promises.unlink(temporary).catch((error) => {
+      if (error.code !== "ENOENT") throw error;
+    });
+  }
+}
+async function generateFaIcons(options) {
+  const root = await promises.realpath(node_path.resolve(options.root ?? process.cwd()));
+  if (!Array.isArray(options.icons))
+    throw new Error("Font Awesome icons must be an array of selections");
+  const selections = options.icons.map((selection) => {
+    if (!selection || typeof selection !== "object") {
+      throw new Error("Font Awesome selections must be objects");
+    }
+    return {
+      key: selection.key,
+      name: selection.name,
+      version: selection.version,
+      family: selection.family,
+      style: selection.style,
+      package: selection.package,
+      ...selection.exportName === void 0 ? {} : { exportName: selection.exportName }
+    };
+  });
+  const keys = /* @__PURE__ */ new Set();
+  const exports$1 = selections.map((selection) => {
+    const exportName = validateSelection(selection);
+    if (keys.has(selection.key))
+      throw new Error(`Duplicate Font Awesome key "${selection.key}"`);
+    keys.add(selection.key);
+    return exportName;
+  });
+  const target = options.outFile === void 0 ? void 0 : await validateOutput(root, options.outFile);
+  const virtualTypesTarget = options.virtualTypesFile === void 0 ? void 0 : await validateOutput(root, options.virtualTypesFile, true);
+  if (target && virtualTypesTarget === target.replace(/\.(m?)js$/, ".d.$1ts")) {
+    throw new Error(
+      "Virtual types output must not overwrite the generated module's declarations"
+    );
+  }
+  const sourceRoot = options.sourceRoot === void 0 ? root : await promises.realpath(node_path.resolve(root, options.sourceRoot));
+  const requireSource = node_module.createRequire(node_path.join(sourceRoot, "package.json"));
+  const icons = /* @__PURE__ */ Object.create(null);
+  const provenance = [];
+  const dependencies = /* @__PURE__ */ new Set();
+  const notices = /* @__PURE__ */ new Map();
+  for (const [index, selection] of selections.entries()) {
+    const exportName = exports$1[index];
+    let metadataFile;
+    let definitionFile;
+    try {
+      metadataFile = requireSource.resolve(`${selection.package}/package.json`);
+      definitionFile = requireSource.resolve(
+        `${selection.package}/${exportName}`
+      );
+    } catch (error) {
+      throw new Error(
+        `Cannot resolve installed Font Awesome source "${selection.package}/${exportName}" for "${selection.key}". Install its pinned package and expose package.json and individual icon modules.`,
+        { cause: error }
+      );
+    }
+    const metadata = JSON.parse(await promises.readFile(metadataFile, "utf8"));
+    if (metadata.version !== selection.version) {
+      throw new Error(
+        `Font Awesome version mismatch for "${selection.key}": requested ${selection.version}, installed ${metadata.version}`
+      );
+    }
+    if (typeof metadata.name !== "string" || !metadata.name) {
+      throw new Error(`Missing source package name for "${selection.key}"`);
+    }
+    const licenseFile = node_path.join(node_path.dirname(metadataFile), "LICENSE.txt");
+    if (!notices.has(metadataFile)) {
+      const text = await promises.readFile(licenseFile, "utf8");
+      if (!text.trim())
+        throw new Error(`Missing license notice for "${selection.package}"`);
+      notices.set(
+        metadataFile,
+        `${metadata.name}@${metadata.version}
+${text.trim()}
+`
+      );
+    }
+    dependencies.add(metadataFile);
+    dependencies.add(licenseFile);
+    dependencies.add(definitionFile);
+    delete requireSource.cache[definitionFile];
+    const source = requireSource(definitionFile);
+    if (!Object.hasOwn(source, exportName)) {
+      throw new Error(
+        `Missing Font Awesome export "${exportName}" for "${selection.key}"`
+      );
+    }
+    icons[selection.key] = normalizeIcon(selection, source[exportName]);
+    provenance.push({ ...selection, exportName, sourcePackage: metadata.name });
+  }
+  const result = {
+    moduleCode: `import { createFontAwesomeService } from "@featherk/icons/fontawesome";
+const selections = JSON.parse(${serialize(serialize(icons))});
+export const getFaIcon = createFontAwesomeService(selections).getFaIcon;
+export const provenance = ${serialize(provenance)};
+`,
+    declarationCode: `import type { FontAwesomeIcon, FontAwesomeSelection } from "@featherk/icons/fontawesome";
+export type FontAwesomeKey = ${selections.length ? selections.map((selection) => serialize(selection.key)).join(" | ") : "never"};
+export declare function getFaIcon(key: FontAwesomeKey): FontAwesomeIcon;
+export declare const provenance: readonly (FontAwesomeSelection & { sourcePackage: string; exportName: string })[];
+`,
+    virtualDeclarationCode: "",
+    notices: [...notices.values()].join("\n"),
+    provenance,
+    dependencies: [...dependencies]
+  };
+  result.virtualDeclarationCode = `declare module "virtual:featherk/fontawesome" {
+${result.declarationCode.replaceAll("export declare ", "export ")}
+}
+`;
+  if (target) await writeOutput(target, result);
+  if (virtualTypesTarget)
+    await writeAtomically(virtualTypesTarget, result.virtualDeclarationCode);
+  return result;
+}
+exports.generateFaIcons = generateFaIcons;

package/dist/fontawesome/chunks/generate-Bp92GTVi.mjs

@@ -0,0 +1,289 @@
+import { createRequire } from "node:module";
+import { realpath, readFile, mkdir, writeFile, rename, unlink } from "node:fs/promises";
+import { resolve, join, dirname, relative, isAbsolute, sep, extname, basename } from "node:path";
+import { randomUUID } from "node:crypto";
+const prefixes = {
+  "classic:solid": "fas",
+  "classic:regular": "far",
+  "classic:light": "fal",
+  "classic:thin": "fat",
+  "classic:brands": "fab",
+  "sharp:solid": "fass",
+  "sharp:regular": "fasr",
+  "sharp:light": "fasl",
+  "sharp:thin": "fast",
+  "duotone:solid": "fad",
+  "duotone:regular": "fadr",
+  "duotone:light": "fadl",
+  "duotone:thin": "fadt",
+  "sharp-duotone:solid": "fasds",
+  "sharp-duotone:regular": "fasdr",
+  "sharp-duotone:light": "fasdl",
+  "sharp-duotone:thin": "fasdt"
+};
+function expectedPrefix(selection) {
+  const prefix = prefixes[`${selection.family}:${selection.style}`];
+  if (!prefix) {
+    throw new Error(
+      `Unsupported Font Awesome family/style for "${selection.key}"`
+    );
+  }
+  return prefix;
+}
+function normalizeIcon(selection, definition) {
+  if (!definition || typeof definition !== "object") {
+    throw new Error(`Missing Font Awesome definition for "${selection.key}"`);
+  }
+  const source = definition;
+  if (source.iconName !== selection.name || source.prefix !== expectedPrefix(selection)) {
+    throw new Error(
+      `Font Awesome name/family/style mismatch for "${selection.key}"`
+    );
+  }
+  if (!Array.isArray(source.icon) || source.icon.length !== 5) {
+    throw new Error(`Invalid Font Awesome geometry for "${selection.key}"`);
+  }
+  const [width, height, , , pathData] = source.icon;
+  if (typeof width !== "number" || !Number.isFinite(width) || width <= 0 || typeof height !== "number" || !Number.isFinite(height) || height <= 0) {
+    throw new Error(`Invalid Font Awesome dimensions for "${selection.key}"`);
+  }
+  const paths = Array.isArray(pathData) ? pathData : [pathData];
+  const duotone = selection.family === "duotone" || selection.family === "sharp-duotone";
+  if (paths.length !== (duotone ? 2 : 1)) {
+    throw new Error(
+      `Unsupported Font Awesome path layers for "${selection.key}"`
+    );
+  }
+  for (const path of paths) {
+    if (typeof path !== "string" || !/^\s*[Mm]/.test(path) || !/^[MmZzLlHhVvCcSsQqTtAa0-9eE+.,\s-]+$/.test(path)) {
+      throw new Error(
+        `Unsafe or invalid Font Awesome path for "${selection.key}"`
+      );
+    }
+  }
+  const content = duotone ? `<path d="${paths[0]}" fill="var(--fa-secondary-color, currentColor)" opacity="var(--fa-secondary-opacity, 0.4)"/><path d="${paths[1]}" fill="var(--fa-primary-color, currentColor)" opacity="var(--fa-primary-opacity, 1)"/>` : `<path d="${paths[0]}" fill="currentColor"/>`;
+  return { name: selection.key, content, viewBox: `0 0 ${width} ${height}` };
+}
+function validateSelection(selection) {
+  if (!selection || typeof selection !== "object" || typeof selection.key !== "string" || !selection.key.trim()) {
+    throw new Error("Font Awesome selections require a non-empty key");
+  }
+  if (typeof selection.name !== "string" || !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(selection.name)) {
+    throw new Error(`Invalid Font Awesome name for "${selection.key}"`);
+  }
+  if (typeof selection.version !== "string" || !/^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/.test(
+    selection.version
+  )) {
+    throw new Error(
+      `Font Awesome "${selection.key}" requires an exact version`
+    );
+  }
+  if (typeof selection.package !== "string" || !/^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/.test(
+    selection.package
+  )) {
+    throw new Error(`Invalid Font Awesome package for "${selection.key}"`);
+  }
+  expectedPrefix(selection);
+  const exportName = selection.exportName ?? `fa${selection.name.split("-").map((part) => part[0].toUpperCase() + part.slice(1)).join("")}`;
+  if (typeof exportName !== "string" || !/^fa[A-Z0-9][A-Za-z0-9]*$/.test(exportName)) {
+    throw new Error(`Invalid Font Awesome export for "${selection.key}"`);
+  }
+  return exportName;
+}
+function serialize(value) {
+  return JSON.stringify(value).replace(/\u2028/g, "\\u2028").replace(/\u2029/g, "\\u2029");
+}
+async function validateOutput(root, file, declaration = false) {
+  const target = resolve(root, file);
+  const rootPath = await realpath(root);
+  const relativeTarget = relative(rootPath, target);
+  if (isAbsolute(relativeTarget) || relativeTarget === ".." || relativeTarget.startsWith(`..${sep}`) || relativeTarget.split(sep).includes("node_modules")) {
+    throw new Error(
+      "Font Awesome output must be inside the consumer project, outside node_modules"
+    );
+  }
+  if ((declaration ? !target.endsWith(".d.ts") : ![".js", ".mjs"].includes(extname(target))) || basename(target).startsWith(".")) {
+    throw new Error(
+      declaration ? "Font Awesome virtual types output must be a named .d.ts file" : "Font Awesome output must be a named .js or .mjs module"
+    );
+  }
+  let current = dirname(target);
+  while (true) {
+    try {
+      const actual = await realpath(current);
+      const boundary = relative(rootPath, actual);
+      if (isAbsolute(boundary) || boundary === ".." || boundary.startsWith(`..${sep}`)) {
+        throw new Error(
+          "Font Awesome output cannot escape the consumer project through a symlink"
+        );
+      }
+      const metadata = JSON.parse(
+        await readFile(join(current, "package.json"), "utf8")
+      );
+      if (metadata.name === "@featherk/icons") {
+        throw new Error(
+          "Font Awesome output must not target the @featherk/icons package"
+        );
+      }
+    } catch (error) {
+      if (error.code !== "ENOENT") throw error;
+    }
+    if (current === rootPath) break;
+    const parent = dirname(current);
+    if (parent === current) throw new Error("Invalid Font Awesome output root");
+    current = parent;
+  }
+  for (const output of [
+    target,
+    target.replace(/\.(m?)js$/, ".d.$1ts"),
+    `${target}.licenses.txt`
+  ]) {
+    try {
+      const actual = await realpath(output);
+      if (actual !== output)
+        throw new Error("Font Awesome output files must not be symlinks");
+    } catch (error) {
+      if (error.code !== "ENOENT") throw error;
+    }
+  }
+  return target;
+}
+async function writeOutput(target, result) {
+  await mkdir(dirname(target), { recursive: true });
+  const outputs = [
+    [target, result.moduleCode],
+    [target.replace(/\.(m?)js$/, ".d.$1ts"), result.declarationCode],
+    [`${target}.licenses.txt`, result.notices]
+  ];
+  for (const [file, content] of outputs) {
+    await writeAtomically(file, content);
+  }
+}
+async function writeAtomically(file, content) {
+  await mkdir(dirname(file), { recursive: true });
+  const temporary = `${file}.${randomUUID()}.tmp`;
+  try {
+    await writeFile(temporary, content, { flag: "wx" });
+    await rename(temporary, file);
+  } finally {
+    await unlink(temporary).catch((error) => {
+      if (error.code !== "ENOENT") throw error;
+    });
+  }
+}
+async function generateFaIcons(options) {
+  const root = await realpath(resolve(options.root ?? process.cwd()));
+  if (!Array.isArray(options.icons))
+    throw new Error("Font Awesome icons must be an array of selections");
+  const selections = options.icons.map((selection) => {
+    if (!selection || typeof selection !== "object") {
+      throw new Error("Font Awesome selections must be objects");
+    }
+    return {
+      key: selection.key,
+      name: selection.name,
+      version: selection.version,
+      family: selection.family,
+      style: selection.style,
+      package: selection.package,
+      ...selection.exportName === void 0 ? {} : { exportName: selection.exportName }
+    };
+  });
+  const keys = /* @__PURE__ */ new Set();
+  const exports$1 = selections.map((selection) => {
+    const exportName = validateSelection(selection);
+    if (keys.has(selection.key))
+      throw new Error(`Duplicate Font Awesome key "${selection.key}"`);
+    keys.add(selection.key);
+    return exportName;
+  });
+  const target = options.outFile === void 0 ? void 0 : await validateOutput(root, options.outFile);
+  const virtualTypesTarget = options.virtualTypesFile === void 0 ? void 0 : await validateOutput(root, options.virtualTypesFile, true);
+  if (target && virtualTypesTarget === target.replace(/\.(m?)js$/, ".d.$1ts")) {
+    throw new Error(
+      "Virtual types output must not overwrite the generated module's declarations"
+    );
+  }
+  const sourceRoot = options.sourceRoot === void 0 ? root : await realpath(resolve(root, options.sourceRoot));
+  const requireSource = createRequire(join(sourceRoot, "package.json"));
+  const icons = /* @__PURE__ */ Object.create(null);
+  const provenance = [];
+  const dependencies = /* @__PURE__ */ new Set();
+  const notices = /* @__PURE__ */ new Map();
+  for (const [index, selection] of selections.entries()) {
+    const exportName = exports$1[index];
+    let metadataFile;
+    let definitionFile;
+    try {
+      metadataFile = requireSource.resolve(`${selection.package}/package.json`);
+      definitionFile = requireSource.resolve(
+        `${selection.package}/${exportName}`
+      );
+    } catch (error) {
+      throw new Error(
+        `Cannot resolve installed Font Awesome source "${selection.package}/${exportName}" for "${selection.key}". Install its pinned package and expose package.json and individual icon modules.`,
+        { cause: error }
+      );
+    }
+    const metadata = JSON.parse(await readFile(metadataFile, "utf8"));
+    if (metadata.version !== selection.version) {
+      throw new Error(
+        `Font Awesome version mismatch for "${selection.key}": requested ${selection.version}, installed ${metadata.version}`
+      );
+    }
+    if (typeof metadata.name !== "string" || !metadata.name) {
+      throw new Error(`Missing source package name for "${selection.key}"`);
+    }
+    const licenseFile = join(dirname(metadataFile), "LICENSE.txt");
+    if (!notices.has(metadataFile)) {
+      const text = await readFile(licenseFile, "utf8");
+      if (!text.trim())
+        throw new Error(`Missing license notice for "${selection.package}"`);
+      notices.set(
+        metadataFile,
+        `${metadata.name}@${metadata.version}
+${text.trim()}
+`
+      );
+    }
+    dependencies.add(metadataFile);
+    dependencies.add(licenseFile);
+    dependencies.add(definitionFile);
+    delete requireSource.cache[definitionFile];
+    const source = requireSource(definitionFile);
+    if (!Object.hasOwn(source, exportName)) {
+      throw new Error(
+        `Missing Font Awesome export "${exportName}" for "${selection.key}"`
+      );
+    }
+    icons[selection.key] = normalizeIcon(selection, source[exportName]);
+    provenance.push({ ...selection, exportName, sourcePackage: metadata.name });
+  }
+  const result = {
+    moduleCode: `import { createFontAwesomeService } from "@featherk/icons/fontawesome";
+const selections = JSON.parse(${serialize(serialize(icons))});
+export const getFaIcon = createFontAwesomeService(selections).getFaIcon;
+export const provenance = ${serialize(provenance)};
+`,
+    declarationCode: `import type { FontAwesomeIcon, FontAwesomeSelection } from "@featherk/icons/fontawesome";
+export type FontAwesomeKey = ${selections.length ? selections.map((selection) => serialize(selection.key)).join(" | ") : "never"};
+export declare function getFaIcon(key: FontAwesomeKey): FontAwesomeIcon;
+export declare const provenance: readonly (FontAwesomeSelection & { sourcePackage: string; exportName: string })[];
+`,
+    virtualDeclarationCode: "",
+    notices: [...notices.values()].join("\n"),
+    provenance,
+    dependencies: [...dependencies]
+  };
+  result.virtualDeclarationCode = `declare module "virtual:featherk/fontawesome" {
+${result.declarationCode.replaceAll("export declare ", "export ")}
+}
+`;
+  if (target) await writeOutput(target, result);
+  if (virtualTypesTarget)
+    await writeAtomically(virtualTypesTarget, result.virtualDeclarationCode);
+  return result;
+}
+export {
+  generateFaIcons as g
+};

package/dist/fontawesome/cli.cjs

@@ -0,0 +1,66 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const promises = require("node:fs/promises");
+const node_path = require("node:path");
+const node_util = require("node:util");
+const generate = require("./chunks/generate-Bobf_ghm.cjs");
+const usage = `Usage: featherk-fontawesome --manifest <icons.json> [--root <project>] [--source-root <installed-sources>] [--out <icons.mjs>] [--virtual-types <types.d.ts>]
+
+The JSON manifest must contain { "icons": [...] } with exact installed selections.
+Provide --out, --virtual-types, or both. Paths are relative to the project root.
+This command does not download assets or authenticate; install licensed packages first.
+Generated assets belong to the consuming project, never the @featherk/icons package.`;
+async function runFontAwesomeCli(args, io = {}) {
+  const stdout = io.stdout ?? console.log;
+  const stderr = io.stderr ?? console.error;
+  try {
+    const { values } = node_util.parseArgs({
+      args: [...args],
+      options: {
+        manifest: { type: "string" },
+        root: { type: "string" },
+        "source-root": { type: "string" },
+        out: { type: "string" },
+        "virtual-types": { type: "string" },
+        help: { type: "boolean", short: "h" }
+      },
+      strict: true,
+      allowPositionals: false
+    });
+    if (values.help) {
+      stdout(usage);
+      return 0;
+    }
+    if (!values.manifest?.trim() || !values.out?.trim() && !values["virtual-types"]?.trim()) {
+      throw new Error(
+        "Provide --manifest and at least one of --out or --virtual-types. Use --help for usage."
+      );
+    }
+    const root = node_path.resolve(io.cwd ?? process.cwd(), values.root ?? ".");
+    const manifest = JSON.parse(
+      await promises.readFile(node_path.resolve(root, values.manifest), "utf8")
+    );
+    if (!manifest || typeof manifest !== "object" || Array.isArray(manifest) || !Array.isArray(manifest.icons)) {
+      throw new Error(
+        'Font Awesome manifest must be a JSON object with an "icons" array'
+      );
+    }
+    const result = await generate.generateFaIcons({
+      root,
+      sourceRoot: values["source-root"],
+      icons: manifest.icons,
+      outFile: values.out,
+      virtualTypesFile: values["virtual-types"]
+    });
+    stdout(
+      `Prepared ${result.provenance.length} selected Font Awesome icon(s). Preserve generated license notices in application distribution.`
+    );
+    return 0;
+  } catch (error) {
+    stderr(
+      `Font Awesome generation failed: ${error instanceof Error ? error.message : "Unknown error"}`
+    );
+    return 1;
+  }
+}
+exports.runFontAwesomeCli = runFontAwesomeCli;