@featherk/icons 0.15.7 → 0.16.0

package/dist/fontawesome/setup.cjs

@@ -0,0 +1,482 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const node_child_process = require("node:child_process");
+const node_fs = require("node:fs");
+const node_path = require("node:path");
+const node_readline = require("node:readline");
+const node_util = require("node:util");
+const fontawesome_catalog = require("./catalog.cjs");
+const manifest = require("./chunks/manifest-Yjw62jxG.cjs");
+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> [--free-only | --pro-in-app]
+  featherk-fontawesome-setup
+
+Run from the application root. The manifest contains
+{ "free": [keys], "pro": [keys] }, the same file the Vite plugin reads.
+
+--manifest (default): installs exact Free pins into the app's devDependencies
+from public npm, and writes exact Pro pins into an isolated private source
+project, ${manifest.fontAwesomeProSourcesDir}/, then installs it with the token. The
+app's own install never needs the token. Rerun after changing the manifest.
+Commit package.json, package-lock.json, and ${manifest.fontAwesomeProSourcesDir}/
+(its node_modules is ignored).
+
+No arguments: installs ${manifest.fontAwesomeProSourcesDir}/ from its committed
+lockfile with the token, for CI and fresh clones. Run it after the app's own
+"npm ci".
+
+--free-only: Free keys only from public npm. No token, no source project.
+
+--pro-in-app: installs Free and Pro pins into the app's own devDependencies
+and routes @fortawesome to the Pro registry in the app's .npmrc (token
+placeholder only). Every install of the app, including CI, then needs the
+token for "npm ci --ignore-scripts". Use only when the isolated project is not
+an option.
+
+The token comes from ${tokenVariable} or a hidden prompt in an interactive
+terminal. --manifest setup changes package.json and is refused in CI
+(CI, TEAMCITY_VERSION, or GITHUB_ACTIONS is set). Do not export the token
+persistently.`;
+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.`
+    );
+  }
+  node_readline.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 = node_child_process.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.manifest) {
+    throw new Error("Provide --manifest. Use --help for usage.");
+  }
+  const manifest$1 = await manifest.readFontAwesomeManifest(
+    node_path.resolve(context.cwd, values.manifest)
+  );
+  return manifest.fontAwesomeManifestKeys(manifest$1);
+}
+function resolvePins(keys) {
+  const tiers = new Map(
+    fontawesome_catalog.fontAwesomeCatalog.map((entry) => [entry.key, entry.tier])
+  );
+  const pins = /* @__PURE__ */ new Map();
+  for (const selection of fontawesome_catalog.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 };
+}
+function installIntoApp(pins, pro, token, context) {
+  const npmCli = requireNpm(context);
+  const environment = { ...context.env };
+  delete environment[tokenVariable];
+  if (pro && token) environment[tokenVariable] = token;
+  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",
+      ...pro ? [pinRegistry] : [],
+      ...specs
+    ],
+    cwd: context.cwd,
+    env: environment
+  });
+  if (status === 0) {
+    context.log(
+      `Installed ${specs.length} Font Awesome package(s) into the app: ${specs.join(" ")}`
+    );
+  }
+  return status;
+}
+function readDependencies(packageJsonPath) {
+  try {
+    const { dependencies = {} } = JSON.parse(
+      node_fs.readFileSync(packageJsonPath, "utf8")
+    );
+    return JSON.stringify(
+      Object.fromEntries(Object.entries(dependencies).sort())
+    );
+  } catch {
+    return void 0;
+  }
+}
+function writeSourceProject(sourceRoot, proPins, context) {
+  const dependencies = Object.fromEntries(
+    [...proPins].map(([name, pin]) => [name, pin.spec]).sort()
+  );
+  const created = !node_fs.existsSync(node_path.resolve(sourceRoot, "package.json"));
+  const lockfilePath = node_path.resolve(sourceRoot, "package-lock.json");
+  const removeStaleLockfile = node_fs.existsSync(lockfilePath) && readDependencies(node_path.resolve(sourceRoot, "package.json")) !== JSON.stringify(dependencies);
+  const files = {
+    ".npmrc": `${npmrcLines.join("\n")}
+`,
+    ".gitignore": "node_modules/\n",
+    "package.json": `${JSON.stringify(
+      {
+        name: manifest.fontAwesomeProSourcesDir,
+        version: "0.0.0",
+        private: true,
+        dependencies
+      },
+      null,
+      2
+    )}
+`
+  };
+  node_fs.mkdirSync(sourceRoot, { recursive: true });
+  for (const [name, content] of Object.entries(files)) {
+    node_fs.writeFileSync(node_path.resolve(sourceRoot, name), content);
+  }
+  if (removeStaleLockfile) node_fs.rmSync(lockfilePath);
+  context.log(
+    `${created ? "Created" : "Updated"} ${manifest.fontAwesomeProSourcesDir}/ with ${proPins.size} Pro package(s).`
+  );
+  if (removeStaleLockfile) {
+    context.log(
+      `Removed ${manifest.fontAwesomeProSourcesDir}/package-lock.json because the Pro pins changed; this install regenerates it.`
+    );
+  }
+}
+async function installSourceProject(sourceRoot, token, context) {
+  const npmCli = requireNpm(context);
+  const npmrc = `${manifest.fontAwesomeProSourcesDir}/.npmrc`;
+  const { fontAwesomeRegistry, hasAuth } = checkNpmrc(
+    node_fs.readFileSync(node_path.resolve(sourceRoot, ".npmrc"), "utf8"),
+    npmrc
+  );
+  if (!fontAwesomeRegistry || !hasAuth) {
+    throw new Error(
+      `${npmrc} must contain @fortawesome:registry=${registry} and ${authKey}=${tokenPlaceholder}. Rerun with --manifest to rewrite it.`
+    );
+  }
+  const locked = node_fs.existsSync(node_path.resolve(sourceRoot, "package-lock.json"));
+  if (context.isCi && !locked) {
+    throw new Error(
+      `${manifest.fontAwesomeProSourcesDir}/package-lock.json is required in CI. Run setup with --manifest locally first and commit the lockfile.`
+    );
+  }
+  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 = `${manifest.fontAwesomeProSourcesDir}/package-lock.json`;
+  context.log(
+    locked ? `Pro sources installed from ${lockfile}.` : `Pro sources installed. Review and commit ${lockfile}.`
+  );
+  return 0;
+}
+async function setupFromManifest(values, context) {
+  const { log } = context;
+  const freeOnly = Boolean(values["free-only"]);
+  const proInApp = Boolean(values["pro-in-app"]);
+  if (freeOnly && proInApp) {
+    throw new Error("Use either --free-only or --pro-in-app, not both.");
+  }
+  if (context.isCi) {
+    throw new Error(
+      `--manifest setup changes package.json and is a local step. In CI, run the app's own "npm ci", then featherk-fontawesome-setup without arguments to install ${manifest.fontAwesomeProSourcesDir}/.`
+    );
+  }
+  const appRoot = context.cwd;
+  if (!node_fs.existsSync(node_path.resolve(appRoot, "package.json"))) {
+    throw new Error(
+      "Run this command from the application root (package.json not found)."
+    );
+  }
+  const pins = resolvePins(await readKeys(values, context));
+  if (!pins.size) {
+    throw new Error("No Font Awesome keys selected.");
+  }
+  const freePins = new Map([...pins].filter(([, pin]) => pin.tier !== "pro"));
+  const proPins = new Map([...pins].filter(([, pin]) => pin.tier === "pro"));
+  if (freeOnly && proPins.size) {
+    throw new Error(
+      `--free-only cannot install Pro keys: ${[...proPins.values()].map((pin) => pin.key).join(", ")}.`
+    );
+  }
+  const npmrcPath = node_path.resolve(appRoot, ".npmrc");
+  const config = node_fs.existsSync(npmrcPath) ? node_fs.readFileSync(npmrcPath, "utf8") : "";
+  const { fontAwesomeRegistry, hasAuth } = checkNpmrc(config, ".npmrc");
+  const sourceRoot = node_path.resolve(appRoot, manifest.fontAwesomeProSourcesDir);
+  const isolated = manifest.isFontAwesomeIsolated(appRoot);
+  if (proInApp && isolated) {
+    throw new Error(
+      `${manifest.fontAwesomeProSourcesDir}/ exists, so this app keeps Pro in the isolated source project. Run without --pro-in-app, or remove ${manifest.fontAwesomeProSourcesDir}/ first.`
+    );
+  }
+  if (!proInApp && fontAwesomeRegistry) {
+    throw new Error(
+      `.npmrc routes @fortawesome to ${fontAwesomeRegistry}, so this app installs Pro in the app itself. Rerun with --pro-in-app.`
+    );
+  }
+  if (freeOnly && isolated) {
+    throw new Error(
+      `${manifest.fontAwesomeProSourcesDir}/ exists, so this app uses Pro. Run without --free-only, or remove ${manifest.fontAwesomeProSourcesDir}/ first.`
+    );
+  }
+  if (proInApp) {
+    const token = proPins.size ? await readToken(context) : void 0;
+    if (proPins.size) {
+      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" : "";
+        node_fs.writeFileSync(
+          npmrcPath,
+          `${config}${separator}${missing.join("\n")}
+`
+        );
+        log(
+          `${config ? "Updated" : "Created"} .npmrc with the Font Awesome registry and token placeholder.`
+        );
+      }
+    }
+    const status2 = installIntoApp(pins, proPins.size > 0, token, context);
+    if (status2 !== 0) return status2;
+    log(lifecycleNote);
+    log(
+      `Next: commit .npmrc, package.json, and package-lock.json. Configure the Vite plugin with { manifest }. Every later install, including CI, gives ${tokenVariable} only to "npm ci --ignore-scripts"; run needed install scripts and builds without it.`
+    );
+    return 0;
+  }
+  if (freePins.size) {
+    const status2 = installIntoApp(freePins, false, void 0, context);
+    if (status2 !== 0) return status2;
+    log(lifecycleNote);
+  }
+  if (!proPins.size) {
+    if (isolated) {
+      log(
+        `The manifest has no Pro keys; ${manifest.fontAwesomeProSourcesDir}/ is no longer needed and can be removed.`
+      );
+    }
+    log(
+      "Next: commit package.json and package-lock.json. Configure the Vite plugin with { manifest }; no token is needed."
+    );
+    return 0;
+  }
+  writeSourceProject(sourceRoot, proPins, context);
+  const status = await installSourceProject(sourceRoot, void 0, context);
+  if (status !== 0) return status;
+  log(
+    `Next: commit package.json, package-lock.json, and ${manifest.fontAwesomeProSourcesDir}/. Configure the Vite plugin with { manifest }; builds include Pro icons wherever ${manifest.fontAwesomeProSourcesDir}/ is installed. In CI, run the app's "npm ci" without the token, then featherk-fontawesome-setup with ${tokenVariable}, then the normal build.`
+  );
+  return 0;
+}
+const lifecycleNote = "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).";
+const removedFlags = [
+  "--keys",
+  "--source-root",
+  "--init",
+  "--force",
+  "--refresh-lock"
+];
+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
+  };
+  try {
+    const removed = removedFlags.find(
+      (flag) => args.some((arg) => arg === flag || arg.startsWith(`${flag}=`))
+    );
+    if (removed) {
+      throw new Error(
+        `${removed} was removed in 0.16.0. Run setup with --manifest; Pro sources always live in ${manifest.fontAwesomeProSourcesDir}/, and rerunning with --manifest updates them. Use --help for usage.`
+      );
+    }
+    const { values } = node_util.parseArgs({
+      args: [...args],
+      options: {
+        "free-only": { type: "boolean" },
+        "pro-in-app": { type: "boolean" },
+        manifest: { type: "string" },
+        help: { type: "boolean", short: "h" }
+      },
+      strict: true,
+      allowPositionals: false
+    });
+    if (values.help) {
+      context.log(usage);
+      return 0;
+    }
+    if (values.manifest !== void 0) {
+      return await setupFromManifest(values, context);
+    }
+    if (values["free-only"] || values["pro-in-app"]) {
+      throw new Error("--free-only and --pro-in-app require --manifest.");
+    }
+    if (!manifest.isFontAwesomeIsolated(cwd)) {
+      throw new Error(
+        `${manifest.fontAwesomeProSourcesDir}/package.json was not found. Run from the application root; for first-time setup, run with --manifest <icons.json>.`
+      );
+    }
+    return await installSourceProject(
+      node_path.resolve(cwd, manifest.fontAwesomeProSourcesDir),
+      void 0,
+      context
+    );
+  } catch (error) {
+    stderr(error instanceof Error ? error.message : "Unknown error");
+    return 1;
+  }
+}
+exports.checkNpmrc = checkNpmrc;
+exports.runFontAwesomeSetup = runFontAwesomeSetup;

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 manifest setup, or installs the isolated
+ * source project when no arguments are given.
+ *
+ * @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>;