@featherk/icons 0.15.6 → 0.15.8

package/bin/featherk-fontawesome-setup.mjs

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { runFontAwesomeSetup } from "../dist/fontawesome/setup.mjs";
+
+process.exitCode = await runFontAwesomeSetup(process.argv.slice(2));

package/dist/docs-manifest.js

@@ -1,7 +1,7 @@
 // Generated by scripts/generate-docs-manifest.mjs. Do not edit.
 export const packageName = "@featherk/icons";
 
-export const version = "0.15.6";
+export const version = "0.15.8";
 
 export const paths = {
   CreateFontAwesomeManifest: "fontawesome/CreateFontAwesomeManifest.md",
@@ -11,10 +11,10 @@ export const paths = {
 };
 
 export const docs = {
-  CreateFontAwesomeManifest: "https://cdn.jsdelivr.net/npm/@featherk/icons@0.15.6/docs/fontawesome/CreateFontAwesomeManifest.md",
-  FontAwesome: "https://cdn.jsdelivr.net/npm/@featherk/icons@0.15.6/docs/fontawesome/FontAwesome.md",
-  FontAwesomeCLI: "https://cdn.jsdelivr.net/npm/@featherk/icons@0.15.6/docs/fontawesome/FontAwesomeCLI.md",
-  LICENSING: "https://cdn.jsdelivr.net/npm/@featherk/icons@0.15.6/docs/fontawesome/LICENSING.md",
+  CreateFontAwesomeManifest: "https://cdn.jsdelivr.net/npm/@featherk/icons@0.15.8/docs/fontawesome/CreateFontAwesomeManifest.md",
+  FontAwesome: "https://cdn.jsdelivr.net/npm/@featherk/icons@0.15.8/docs/fontawesome/FontAwesome.md",
+  FontAwesomeCLI: "https://cdn.jsdelivr.net/npm/@featherk/icons@0.15.8/docs/fontawesome/FontAwesomeCLI.md",
+  LICENSING: "https://cdn.jsdelivr.net/npm/@featherk/icons@0.15.8/docs/fontawesome/LICENSING.md",
 };
 
 export const docUrl = (name, host = "https://cdn.jsdelivr.net/npm") =>

package/dist/fontawesome/chunks/manifest-BB3q10t1.mjs

@@ -0,0 +1,20 @@
+import { readFile } from "node:fs/promises";
+const isKeyList = (value) => Array.isArray(value) && value.every((key) => typeof key === "string");
+function parseFontAwesomeManifest(manifest) {
+  if (!manifest || typeof manifest !== "object" || Array.isArray(manifest)) {
+    throw new Error("Font Awesome manifest must be a JSON object");
+  }
+  const { free, pro } = manifest;
+  if (!isKeyList(free) || pro !== void 0 && !isKeyList(pro)) {
+    throw new Error(
+      'Font Awesome manifest must contain "free" and optional "pro" key arrays'
+    );
+  }
+  return { free, pro: pro ?? [] };
+}
+async function readFontAwesomeManifest(path) {
+  return parseFontAwesomeManifest(JSON.parse(await readFile(path, "utf8")));
+}
+export {
+  readFontAwesomeManifest as r
+};

package/dist/fontawesome/chunks/manifest-C15Xa22L.cjs

@@ -0,0 +1,19 @@
+"use strict";
+const promises = require("node:fs/promises");
+const isKeyList = (value) => Array.isArray(value) && value.every((key) => typeof key === "string");
+function parseFontAwesomeManifest(manifest) {
+  if (!manifest || typeof manifest !== "object" || Array.isArray(manifest)) {
+    throw new Error("Font Awesome manifest must be a JSON object");
+  }
+  const { free, pro } = manifest;
+  if (!isKeyList(free) || pro !== void 0 && !isKeyList(pro)) {
+    throw new Error(
+      'Font Awesome manifest must contain "free" and optional "pro" key arrays'
+    );
+  }
+  return { free, pro: pro ?? [] };
+}
+async function readFontAwesomeManifest(path) {
+  return parseFontAwesomeManifest(JSON.parse(await promises.readFile(path, "utf8")));
+}
+exports.readFontAwesomeManifest = readFontAwesomeManifest;

package/dist/fontawesome/cli.cjs

@@ -1,10 +1,10 @@
 "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 fontawesome_catalog = require("./catalog.cjs");
 const generate = require("./chunks/generate-BBurrhLv.cjs");
+const manifest = require("./chunks/manifest-C15Xa22L.cjs");
 const usage = `Usage: featherk-fontawesome --manifest <icons.json> [--root <project>] [--source-root <installed-sources>] [--allow-pro] [--out <icons.mjs>] [--virtual-types <types.d.ts>]
 
 The JSON manifest contains { "free": [keys], "pro": [keys] }.
@@ -40,13 +40,9 @@ async function runFontAwesomeCli(args, io = {}) {
       );
     }
     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")
+    const manifest$1 = await manifest.readFontAwesomeManifest(
+      node_path.resolve(root, values.manifest)
     );
-    if (!manifest || typeof manifest !== "object" || Array.isArray(manifest)) {
-      throw new Error("Font Awesome manifest must be a JSON object");
-    }
-    const record = manifest;
     const common = {
       root,
       sourceRoot: values["source-root"],
@@ -54,17 +50,9 @@ async function runFontAwesomeCli(args, io = {}) {
       outFile: values.out,
       virtualTypesFile: values["virtual-types"]
     };
-    const isKeyList = (value) => Array.isArray(value) && value.every((key) => typeof key === "string");
-    const freeKeys = record.free;
-    const proKeys = record.pro;
-    if (!isKeyList(freeKeys) || proKeys !== void 0 && !isKeyList(proKeys)) {
-      throw new Error(
-        'Font Awesome manifest must contain "free" and optional "pro" key arrays'
-      );
-    }
     const keys = [
-      ...freeKeys,
-      ...values["allow-pro"] ? proKeys ?? [] : []
+      ...manifest$1.free,
+      ...values["allow-pro"] ? manifest$1.pro : []
     ];
     const installCommand = fontawesome_catalog.getFontAwesomeInstallCommand(keys, {
       allowPro: values["allow-pro"]

package/dist/fontawesome/cli.mjs

@@ -1,8 +1,8 @@
-import { readFile } from "node:fs/promises";
 import { resolve } from "node:path";
 import { parseArgs } from "node:util";
 import { getFontAwesomeInstallCommand } from "./catalog.mjs";
 import { g as generateFaIcons } from "./chunks/generate-Zq9q2YZD.mjs";
+import { r as readFontAwesomeManifest } from "./chunks/manifest-BB3q10t1.mjs";
 const usage = `Usage: featherk-fontawesome --manifest <icons.json> [--root <project>] [--source-root <installed-sources>] [--allow-pro] [--out <icons.mjs>] [--virtual-types <types.d.ts>]
 
 The JSON manifest contains { "free": [keys], "pro": [keys] }.
@@ -38,13 +38,9 @@ async function runFontAwesomeCli(args, io = {}) {
       );
     }
     const root = resolve(io.cwd ?? process.cwd(), values.root ?? ".");
-    const manifest = JSON.parse(
-      await readFile(resolve(root, values.manifest), "utf8")
+    const manifest = await readFontAwesomeManifest(
+      resolve(root, values.manifest)
     );
-    if (!manifest || typeof manifest !== "object" || Array.isArray(manifest)) {
-      throw new Error("Font Awesome manifest must be a JSON object");
-    }
-    const record = manifest;
     const common = {
       root,
       sourceRoot: values["source-root"],
@@ -52,17 +48,9 @@ async function runFontAwesomeCli(args, io = {}) {
       outFile: values.out,
       virtualTypesFile: values["virtual-types"]
     };
-    const isKeyList = (value) => Array.isArray(value) && value.every((key) => typeof key === "string");
-    const freeKeys = record.free;
-    const proKeys = record.pro;
-    if (!isKeyList(freeKeys) || proKeys !== void 0 && !isKeyList(proKeys)) {
-      throw new Error(
-        'Font Awesome manifest must contain "free" and optional "pro" key arrays'
-      );
-    }
     const keys = [
-      ...freeKeys,
-      ...values["allow-pro"] ? proKeys ?? [] : []
+      ...manifest.free,
+      ...values["allow-pro"] ? manifest.pro : []
     ];
     const installCommand = getFontAwesomeInstallCommand(keys, {
       allowPro: values["allow-pro"]

package/dist/fontawesome/manifest.d.ts

@@ -0,0 +1,14 @@
+/** Parsed manifest key groups; a missing `pro` group is empty. */
+export interface FontAwesomeKeysManifest {
+    free: string[];
+    pro: string[];
+}
+/**
+ * Validates parsed manifest JSON.
+ *
+ * @throws If the value is not an object with a `free` key array and an
+ * optional `pro` key array.
+ */
+export declare function parseFontAwesomeManifest(manifest: unknown): FontAwesomeKeysManifest;
+/** Reads and validates a manifest file at an absolute or cwd-relative path. */
+export declare function readFontAwesomeManifest(path: string): Promise<FontAwesomeKeysManifest>;

package/dist/fontawesome/setup.cjs

@@ -0,0 +1,477 @@
+"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-C15Xa22L.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> | --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.`
+    );
+  }
+  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.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 manifest.readFontAwesomeManifest(
+    node_path.resolve(context.cwd, values.manifest)
+  );
+  return [...free, ...pro];
+}
+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 };
+}
+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 (!node_fs.existsSync(node_path.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 = node_path.resolve(appRoot, ".npmrc");
+  const config = node_fs.existsSync(npmrcPath) ? node_fs.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" : "";
+      node_fs.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(
+      node_fs.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) => node_fs.existsSync(node_path.resolve(sourceRoot, name))
+  );
+  if (existing.length && !values.force) {
+    throw new Error(
+      `${display(sourceRoot)} already contains ${existing.join(", ")}. Use --force to overwrite.`
+    );
+  }
+  const lockfilePath = node_path.resolve(sourceRoot, "package-lock.json");
+  const removeStaleLockfile = node_fs.existsSync(lockfilePath) && readDependencies(node_path.resolve(sourceRoot, "package.json")) !== JSON.stringify(sortedDependencies);
+  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);
+  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 (!node_fs.existsSync(node_path.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(
+    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}. Scaffold it with --init.`
+    );
+  }
+  const hasLockfile = node_fs.existsSync(node_path.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) => node_path.relative(cwd, path) || "."
+  };
+  try {
+    const { values } = node_util.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 = node_path.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;
+  }
+}
+exports.checkNpmrc = checkNpmrc;
+exports.runFontAwesomeSetup = runFontAwesomeSetup;