@featherk/icons 0.15.7 → 0.15.8

package/dist/fontawesome/setup.d.ts

@@ -0,0 +1,39 @@
+/** Runs npm with the given arguments and returns its exit status. */
+export type FontAwesomeNpmRunner = (options: {
+    npmCli: string;
+    args: string[];
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+}) => number;
+/** Injectable process I/O used by the setup entry point and its tests. */
+export interface FontAwesomeSetupIO {
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+    stdout?: (message: string) => void;
+    stderr?: (message: string) => void;
+    /** Called when the token is not in the environment. */
+    promptForToken?: () => Promise<string>;
+    runNpm?: FontAwesomeNpmRunner;
+}
+/**
+ * Checks where an .npmrc could send the package token before it is supplied.
+ * The token variable may appear only in the npm.fontawesome.com auth entry,
+ * that host may carry no other credential, and @fortawesome may route only to
+ * the Font Awesome registry.
+ *
+ * @returns The configured @fortawesome registry, if any, and whether the
+ * placeholder auth entry exists.
+ * @throws If the config could expose the token or a literal credential.
+ */
+export declare function checkNpmrc(config: string, file: string): {
+    fontAwesomeRegistry?: string;
+    hasAuth: boolean;
+};
+/**
+ * Parses setup arguments and runs app-root setup, source-project scaffolding,
+ * or source-project installation.
+ *
+ * @returns `0` on success, npm's exit status when an install fails, and `1`
+ * when argument, manifest, config, or environment validation fails.
+ */
+export declare function runFontAwesomeSetup(args: readonly string[], io?: FontAwesomeSetupIO): Promise<number>;

package/dist/fontawesome/setup.mjs

@@ -0,0 +1,477 @@
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync, writeFileSync, mkdirSync, rmSync } from "node:fs";
+import { resolve, relative } from "node:path";
+import { emitKeypressEvents } from "node:readline";
+import { parseArgs } from "node:util";
+import { fontAwesomeCatalog, resolveFontAwesomeKeys } from "./catalog.mjs";
+import { r as readFontAwesomeManifest } from "./chunks/manifest-BB3q10t1.mjs";
+const tokenVariable = "FONTAWESOME_PACKAGE_TOKEN";
+const tokenPlaceholder = `\${${tokenVariable}}`;
+const registry = "https://npm.fontawesome.com/";
+const authKey = "//npm.fontawesome.com/:_authToken";
+const pinRegistry = `--@fortawesome:registry=${registry}`;
+const npmrcLines = [
+  "# Route @fortawesome packages to the Font Awesome Pro registry.",
+  `@fortawesome:registry=${registry}`,
+  "# Authenticate using the token from the environment; never commit a token.",
+  `${authKey}=${tokenPlaceholder}`
+];
+const workspaceVariables = [
+  "npm_config_workspace",
+  "npm_config_workspaces",
+  "NPM_CONFIG_WORKSPACE",
+  "NPM_CONFIG_WORKSPACES"
+];
+const usage = `Usage:
+  featherk-fontawesome-setup (--manifest <icons.json> | --keys <a,b>) [--free-only]
+  featherk-fontawesome-setup --source-root <dir> [--refresh-lock]
+  featherk-fontawesome-setup --source-root <dir> --init (--manifest <icons.json> | --keys <a,b>) [--force]
+
+Default (Free + Pro): run once from the application root on a developer
+machine. Adds the @fortawesome registry lines to .npmrc (token placeholder
+only) and installs exact pins for all selected keys as devDependencies.
+Commit .npmrc, package.json, and package-lock.json. Later installs, including
+CI, give ${tokenVariable} only to "npm ci --ignore-scripts", then run any
+needed install scripts (npm rebuild for dependencies, plus the app's own) and
+builds without it. Do not export the token persistently.
+
+--free-only: Free keys only from public npm. No .npmrc changes, no token.
+
+--source-root <dir>: install licensed packages into an isolated private
+source project instead (npm ci when its lockfile exists). --init scaffolds
+that project; with --force, a lockfile for different dependencies is removed
+so the next install regenerates it. --refresh-lock runs npm install to update
+the lockfile after editing package.json by hand. In CI, --init and
+--refresh-lock are refused and a lockfile is required.
+
+The token comes from ${tokenVariable} or a hidden prompt in an interactive
+terminal. App-root setup changes package.json and is refused in CI
+(CI, TEAMCITY_VERSION, or GITHUB_ACTIONS is set).`;
+function promptForTerminalToken() {
+  const input = process.stdin;
+  if (!input.isTTY || typeof input.setRawMode !== "function") {
+    throw new Error(
+      `${tokenVariable} is not set and this is not an interactive terminal. Provide it through an approved CI secret environment.`
+    );
+  }
+  emitKeypressEvents(input);
+  process.stdout.write("Font Awesome Pro Package Token (input hidden): ");
+  const wasRaw = input.isRaw;
+  input.setRawMode(true);
+  input.resume();
+  return new Promise((resolveToken, rejectToken) => {
+    const characters = [];
+    const finish = (error) => {
+      input.off("keypress", onKeypress);
+      input.setRawMode(wasRaw);
+      input.pause();
+      process.stdout.write("\n");
+      if (error) rejectToken(error);
+      else resolveToken(characters.join(""));
+    };
+    const onKeypress = (character, key = {}) => {
+      if (key.ctrl && key.name === "c") {
+        finish(new Error("Token entry cancelled."));
+        return;
+      }
+      if (key.name === "return" || key.name === "enter") {
+        finish();
+        return;
+      }
+      if (key.name === "backspace") {
+        if (characters.length) {
+          characters.pop();
+          process.stdout.write("\b \b");
+        }
+        return;
+      }
+      if (!key.ctrl && !key.meta && character && !character.startsWith("\x1B")) {
+        for (const item of character) {
+          if (item >= " " && item <= "~") {
+            characters.push(item);
+            process.stdout.write("*");
+          }
+        }
+      }
+    };
+    input.on("keypress", onKeypress);
+  });
+}
+const spawnNpm = ({ npmCli, args, cwd, env }) => {
+  const result = spawnSync(process.execPath, [npmCli, ...args], {
+    cwd,
+    env,
+    stdio: "inherit"
+  });
+  if (result.error) throw result.error;
+  return result.status ?? 1;
+};
+async function readToken(context) {
+  const token = context.env[tokenVariable] || await context.promptForToken();
+  if (!token) {
+    throw new Error(
+      "A Font Awesome Pro Package Token is required to install Pro packages."
+    );
+  }
+  return token;
+}
+function requireNpm(context) {
+  const npmCli = context.env.npm_execpath;
+  if (!npmCli) {
+    throw new Error(
+      "Run this command through an npm script or npx so npm is available."
+    );
+  }
+  return npmCli;
+}
+async function readKeys(values, context) {
+  if (values.keys && values.manifest) {
+    throw new Error("Provide either --keys or --manifest, not both.");
+  }
+  if (values.keys) {
+    return values.keys.split(",").map((key) => key.trim()).filter(Boolean);
+  }
+  if (!values.manifest) {
+    throw new Error("Provide --manifest or --keys. Use --help for usage.");
+  }
+  const { free, pro } = await readFontAwesomeManifest(
+    resolve(context.cwd, values.manifest)
+  );
+  return [...free, ...pro];
+}
+function resolvePins(keys) {
+  const tiers = new Map(
+    fontAwesomeCatalog.map((entry) => [entry.key, entry.tier])
+  );
+  const pins = /* @__PURE__ */ new Map();
+  for (const selection of resolveFontAwesomeKeys(keys, { allowPro: true })) {
+    const spec = selection.package === selection.registryPackage ? selection.version : `npm:${selection.registryPackage}@${selection.version}`;
+    const existing = pins.get(selection.package);
+    if (existing && existing.spec !== spec) {
+      throw new Error(
+        `Conflicting pins for ${selection.package}: ${existing.spec} and ${spec}.`
+      );
+    }
+    if (!existing) {
+      pins.set(selection.package, {
+        tier: tiers.get(selection.key),
+        spec,
+        key: selection.key
+      });
+    }
+  }
+  return pins;
+}
+function checkNpmrc(config, file) {
+  let fontAwesomeRegistry;
+  let hasAuth = false;
+  for (const raw of config.split(/\r?\n/)) {
+    const line = raw.trim();
+    if (!line || line.startsWith("#") || line.startsWith(";")) continue;
+    const separator = line.indexOf("=");
+    const key = (separator < 0 ? line : line.slice(0, separator)).trim();
+    const value = separator < 0 ? "" : line.slice(separator + 1).trim();
+    if (key === "@fortawesome:registry") {
+      fontAwesomeRegistry = value;
+    } else if (key === authKey && value === tokenPlaceholder) {
+      hasAuth = true;
+    } else if (key.includes("npm.fontawesome.com")) {
+      throw new Error(
+        `${file} may configure npm.fontawesome.com only as ${authKey}=${tokenPlaceholder}; remove "${key}".`
+      );
+    } else if (line.includes(tokenVariable)) {
+      throw new Error(
+        `${file} references ${tokenVariable} in "${key}"; the token may only authenticate npm.fontawesome.com.`
+      );
+    }
+  }
+  if (fontAwesomeRegistry !== void 0 && fontAwesomeRegistry.replace(/\/?$/, "/") !== registry) {
+    throw new Error(
+      `${file} routes @fortawesome to ${fontAwesomeRegistry}; the Pro token may only be sent to ${registry}.`
+    );
+  }
+  return { fontAwesomeRegistry, hasAuth };
+}
+async function setupAppRoot(values, context) {
+  const { log } = context;
+  if (context.isCi) {
+    throw new Error(
+      `App-root setup changes package.json and is a local, one-time step. In CI, give ${tokenVariable} only to "npm ci --ignore-scripts", then run needed install scripts and the build without it.`
+    );
+  }
+  const appRoot = context.cwd;
+  if (!existsSync(resolve(appRoot, "package.json"))) {
+    throw new Error(
+      "Run this command from the application root (package.json not found)."
+    );
+  }
+  const freeOnly = Boolean(values["free-only"]);
+  const pins = resolvePins(await readKeys(values, context));
+  const proPins = [...pins.values()].filter((pin) => pin.tier === "pro");
+  if (freeOnly && proPins.length) {
+    throw new Error(
+      `--free-only cannot install Pro keys: ${proPins.map((pin) => pin.key).join(", ")}.`
+    );
+  }
+  if (!pins.size) {
+    throw new Error("No Font Awesome keys selected.");
+  }
+  const npmrcPath = resolve(appRoot, ".npmrc");
+  const config = existsSync(npmrcPath) ? readFileSync(npmrcPath, "utf8") : "";
+  const { fontAwesomeRegistry, hasAuth } = checkNpmrc(config, ".npmrc");
+  if (freeOnly && fontAwesomeRegistry) {
+    throw new Error(
+      `.npmrc routes @fortawesome to ${fontAwesomeRegistry}, so this app is set up for Pro. Run without --free-only.`
+    );
+  }
+  const npmCli = requireNpm(context);
+  const environment = { ...context.env };
+  if (!freeOnly) {
+    environment[tokenVariable] = await readToken(context);
+    const missing = [];
+    if (!fontAwesomeRegistry) missing.push(npmrcLines[0], npmrcLines[1]);
+    if (!hasAuth) missing.push(npmrcLines[2], npmrcLines[3]);
+    if (missing.length) {
+      const separator = config && !config.endsWith("\n") ? "\n" : "";
+      writeFileSync(npmrcPath, `${config}${separator}${missing.join("\n")}
+`);
+      log(
+        `${config ? "Updated" : "Created"} .npmrc with the Font Awesome registry and token placeholder.`
+      );
+    }
+  }
+  const specs = [...pins].map(([name, pin]) => `${name}@${pin.spec}`);
+  const status = context.runNpm({
+    npmCli,
+    args: [
+      "install",
+      "--save-dev",
+      "--save-exact",
+      "--ignore-scripts",
+      "--no-audit",
+      "--no-fund",
+      ...freeOnly ? [] : [pinRegistry],
+      ...specs
+    ],
+    cwd: appRoot,
+    env: environment
+  });
+  if (status !== 0) return status;
+  log(`Installed ${specs.length} Font Awesome package(s): ${specs.join(" ")}`);
+  log(
+    "Lifecycle scripts were skipped. If needed, run npm rebuild for dependency scripts and the app's own scripts (e.g. npm run prepare --if-present)."
+  );
+  if (freeOnly) {
+    log(
+      "Next: commit package.json and package-lock.json. Keep the Vite plugin's allowPro unset (Free only); no CI token is needed."
+    );
+  } else {
+    log(
+      `Next: commit .npmrc, package.json, and package-lock.json. Set allowPro: true in the Vite plugin (no sourceRoot). Later installs, including CI, give ${tokenVariable} only to "npm ci --ignore-scripts"; run needed install scripts and builds without it. See LICENSING.md for the TeamCity setup.`
+    );
+  }
+  return 0;
+}
+function readDependencies(packageJsonPath) {
+  try {
+    const { dependencies = {} } = JSON.parse(
+      readFileSync(packageJsonPath, "utf8")
+    );
+    return JSON.stringify(
+      Object.fromEntries(Object.entries(dependencies).sort())
+    );
+  } catch {
+    return void 0;
+  }
+}
+async function initSourceProject(sourceRoot, values, context) {
+  const { log, display } = context;
+  if (context.isCi) {
+    throw new Error(
+      "--init is a local, one-time step. Commit the scaffolded source project instead of generating it in CI."
+    );
+  }
+  const pins = resolvePins(await readKeys(values, context));
+  const dependencies = {};
+  const skipped = [];
+  for (const [name, pin] of pins) {
+    if (pin.tier === "pro") dependencies[name] = pin.spec;
+    else skipped.push(pin.key);
+  }
+  if (!Object.keys(dependencies).length) {
+    throw new Error(
+      "No Pro keys selected. Free packages belong in the application's own devDependencies."
+    );
+  }
+  const sortedDependencies = Object.fromEntries(
+    Object.entries(dependencies).sort()
+  );
+  const files = {
+    ".npmrc": `${npmrcLines.join("\n")}
+`,
+    ".gitignore": "node_modules/\n",
+    "package.json": `${JSON.stringify(
+      {
+        name: "fontawesome-pro-sources",
+        version: "0.0.0",
+        private: true,
+        dependencies: sortedDependencies
+      },
+      null,
+      2
+    )}
+`
+  };
+  const existing = Object.keys(files).filter(
+    (name) => existsSync(resolve(sourceRoot, name))
+  );
+  if (existing.length && !values.force) {
+    throw new Error(
+      `${display(sourceRoot)} already contains ${existing.join(", ")}. Use --force to overwrite.`
+    );
+  }
+  const lockfilePath = resolve(sourceRoot, "package-lock.json");
+  const removeStaleLockfile = existsSync(lockfilePath) && readDependencies(resolve(sourceRoot, "package.json")) !== JSON.stringify(sortedDependencies);
+  mkdirSync(sourceRoot, { recursive: true });
+  for (const [name, content] of Object.entries(files)) {
+    writeFileSync(resolve(sourceRoot, name), content);
+  }
+  if (removeStaleLockfile) rmSync(lockfilePath);
+  if (skipped.length) {
+    log(
+      `Skipped Free keys (install them in the application instead): ${skipped.join(", ")}`
+    );
+  }
+  log(
+    `Scaffolded ${display(sourceRoot)} with ${Object.keys(dependencies).length} Pro package(s).`
+  );
+  if (removeStaleLockfile) {
+    log(
+      `Removed ${display(sourceRoot)}/package-lock.json because the dependencies changed; the next install regenerates it.`
+    );
+  }
+  log(
+    "Next: run this command with --source-root and without --init, then commit the source project and its package-lock.json."
+  );
+  return 0;
+}
+async function installSourceProject(sourceRoot, values, context) {
+  const { log, display } = context;
+  const npmCli = requireNpm(context);
+  for (const name of ["package.json", ".npmrc"]) {
+    if (!existsSync(resolve(sourceRoot, name))) {
+      throw new Error(
+        `${display(sourceRoot)}/${name} was not found. Check --source-root, or scaffold the project with --init.`
+      );
+    }
+  }
+  const npmrc = `${display(sourceRoot)}/.npmrc`;
+  const { fontAwesomeRegistry, hasAuth } = checkNpmrc(
+    readFileSync(resolve(sourceRoot, ".npmrc"), "utf8"),
+    npmrc
+  );
+  if (!fontAwesomeRegistry || !hasAuth) {
+    throw new Error(
+      `${npmrc} must contain @fortawesome:registry=${registry} and ${authKey}=${tokenPlaceholder}. Scaffold it with --init.`
+    );
+  }
+  const hasLockfile = existsSync(resolve(sourceRoot, "package-lock.json"));
+  if (context.isCi && !hasLockfile) {
+    throw new Error(
+      `${display(sourceRoot)}/package-lock.json is required in CI. Install locally first and commit the lockfile.`
+    );
+  }
+  if (context.isCi && values["refresh-lock"]) {
+    throw new Error(
+      "--refresh-lock updates the lockfile and is a local step. In CI, install from the committed lockfile."
+    );
+  }
+  const locked = hasLockfile && !values["refresh-lock"];
+  const environment = {
+    ...context.env,
+    [tokenVariable]: await readToken(context)
+  };
+  for (const name of workspaceVariables) delete environment[name];
+  const status = context.runNpm({
+    npmCli,
+    args: [
+      locked ? "ci" : "install",
+      "--workspaces=false",
+      "--ignore-scripts",
+      "--no-audit",
+      "--no-fund",
+      pinRegistry
+    ],
+    cwd: sourceRoot,
+    env: environment
+  });
+  if (status !== 0) return status;
+  const lockfile = `${display(sourceRoot)}/package-lock.json`;
+  log(
+    locked ? `Pro sources installed from ${lockfile}.` : `Pro sources installed. Review and commit ${lockfile}.`
+  );
+  return 0;
+}
+async function runFontAwesomeSetup(args, io = {}) {
+  const cwd = io.cwd ?? process.cwd();
+  const env = io.env ?? process.env;
+  const stderr = io.stderr ?? console.error;
+  const context = {
+    cwd,
+    env,
+    // TeamCity and GitHub Actions are detected directly; TeamCity does not set CI.
+    isCi: Boolean(env.CI) && env.CI !== "false" || Boolean(env.TEAMCITY_VERSION || env.GITHUB_ACTIONS),
+    log: io.stdout ?? console.log,
+    promptForToken: io.promptForToken ?? promptForTerminalToken,
+    runNpm: io.runNpm ?? spawnNpm,
+    display: (path) => relative(cwd, path) || "."
+  };
+  try {
+    const { values } = parseArgs({
+      args: [...args],
+      options: {
+        "source-root": { type: "string" },
+        "free-only": { type: "boolean" },
+        init: { type: "boolean" },
+        keys: { type: "string" },
+        manifest: { type: "string" },
+        force: { type: "boolean" },
+        "refresh-lock": { type: "boolean" },
+        help: { type: "boolean", short: "h" }
+      },
+      strict: true,
+      allowPositionals: false
+    });
+    if (values.help) {
+      context.log(usage);
+      return 0;
+    }
+    if (values["source-root"] === void 0) {
+      if (values.init || values.force || values["refresh-lock"]) {
+        throw new Error(
+          "--init, --force, and --refresh-lock apply only with --source-root."
+        );
+      }
+      return await setupAppRoot(values, context);
+    }
+    if (values["free-only"]) {
+      throw new Error(
+        "--free-only applies only to app-root setup; an isolated source project holds Pro packages."
+      );
+    }
+    if (values.init && values["refresh-lock"]) {
+      throw new Error(
+        "--refresh-lock applies to the install step, not --init."
+      );
+    }
+    const sourceRoot = resolve(cwd, values["source-root"]);
+    return values.init ? await initSourceProject(sourceRoot, values, context) : await installSourceProject(sourceRoot, values, context);
+  } catch (error) {
+    stderr(error instanceof Error ? error.message : "Unknown error");
+    return 1;
+  }
+}
+export {
+  checkNpmrc,
+  runFontAwesomeSetup
+};

package/docs/ICONS.md

@@ -211,4 +211,4 @@
 |rating_star_selected|switch_left|switch_off|switch_on|switch_right| |
 <!-- markdownlint-enable MD033-->
 
-> Generated: 2026-10-13T18:46:27.037Z
+> Generated: 2026-10-15T15:30:54.353Z

package/docs/fontawesome/FontAwesomeCLI.md

@@ -53,6 +53,8 @@ Output must remain inside the consumer project, outside `node_modules` and the `
 
 The API and Vite plugin accept `sourceRoot` to resolve installed packages from a separate source project without moving the output boundary. The CLI equivalent is `--source-root`. Relative source paths resolve from `root`; authentication still happens during npm installation, never in the generator or browser.
 
+To install source packages, use the separate `featherk-fontawesome-setup` command described in [Consuming Applications](LICENSING.md#consuming-applications). It supports the standard Free and Pro app-root setup, Free-only setup, and the isolated source project. The generator does not install anything; the setup command is the only FeatherK tool that receives the package token.
+
 ## Generated Output and Source Checks
 
 Generated declarations belong in TypeScript so selected keys receive type checking, but should be excluded from source linting, formatting, and version control. Add the exact output path separately to ESLint's global ignores, `.prettierignore`, and `.gitignore`; these are independent settings. Do not ignore all `.d.ts` files or exclude generated declarations from TypeScript.