@featherk/icons 0.15.8 → 0.16.0

package/dist/fontawesome/setup.cjs

@@ -6,7 +6,7 @@ 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 manifest = require("./chunks/manifest-Yjw62jxG.cjs");
 const tokenVariable = "FONTAWESOME_PACKAGE_TOKEN";
 const tokenPlaceholder = `\${${tokenVariable}}`;
 const registry = "https://npm.fontawesome.com/";
@@ -25,30 +25,35 @@ const workspaceVariables = [
   "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]
+  featherk-fontawesome-setup --manifest <icons.json> [--free-only | --pro-in-app]
+  featherk-fontawesome-setup
 
-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.
+Run from the application root. The manifest contains
+{ "free": [keys], "pro": [keys] }, the same file the Vite plugin reads.
 
---free-only: Free keys only from public npm. No .npmrc changes, no token.
+--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).
 
---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.
+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. App-root setup changes package.json and is refused in CI
-(CI, TEAMCITY_VERSION, or GITHUB_ACTIONS is set).`;
+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") {
@@ -127,19 +132,13 @@ function requireNpm(context) {
   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.");
+    throw new Error("Provide --manifest. Use --help for usage.");
   }
-  const { free, pro } = await manifest.readFontAwesomeManifest(
+  const manifest$1 = await manifest.readFontAwesomeManifest(
     node_path.resolve(context.cwd, values.manifest)
   );
-  return [...free, ...pro];
+  return manifest.fontAwesomeManifestKeys(manifest$1);
 }
 function resolvePins(keys) {
   const tiers = new Map(
@@ -194,54 +193,11 @@ function checkNpmrc(config, file) {
   }
   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.`
-    );
-  }
+function installIntoApp(pins, pro, token, context) {
   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.`
-      );
-    }
-  }
+  delete environment[tokenVariable];
+  if (pro && token) environment[tokenVariable] = token;
   const specs = [...pins].map(([name, pin]) => `${name}@${pin.spec}`);
   const status = context.runNpm({
     npmCli,
@@ -252,27 +208,18 @@ async function setupAppRoot(values, context) {
       "--ignore-scripts",
       "--no-audit",
       "--no-fund",
-      ...freeOnly ? [] : [pinRegistry],
+      ...pro ? [pinRegistry] : [],
       ...specs
     ],
-    cwd: appRoot,
+    cwd: context.cwd,
     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.`
+  if (status === 0) {
+    context.log(
+      `Installed ${specs.length} Font Awesome package(s) into the app: ${specs.join(" ")}`
     );
   }
-  return 0;
+  return status;
 }
 function readDependencies(packageJsonPath) {
   try {
@@ -286,109 +233,61 @@ function readDependencies(packageJsonPath) {
     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()
+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: "fontawesome-pro-sources",
+        name: manifest.fontAwesomeProSourcesDir,
         version: "0.0.0",
         private: true,
-        dependencies: sortedDependencies
+        dependencies
       },
       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).`
+  context.log(
+    `${created ? "Created" : "Updated"} ${manifest.fontAwesomeProSourcesDir}/ with ${proPins.size} Pro package(s).`
   );
   if (removeStaleLockfile) {
-    log(
-      `Removed ${display(sourceRoot)}/package-lock.json because the dependencies changed; the next install regenerates it.`
+    context.log(
+      `Removed ${manifest.fontAwesomeProSourcesDir}/package-lock.json because the Pro pins changed; this 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;
+async function installSourceProject(sourceRoot, token, 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 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}. Scaffold it with --init.`
+      `${npmrc} must contain @fortawesome:registry=${registry} and ${authKey}=${tokenPlaceholder}. Rerun with --manifest to rewrite it.`
     );
   }
-  const hasLockfile = node_fs.existsSync(node_path.resolve(sourceRoot, "package-lock.json"));
-  if (context.isCi && !hasLockfile) {
+  const locked = node_fs.existsSync(node_path.resolve(sourceRoot, "package-lock.json"));
+  if (context.isCi && !locked) {
     throw new Error(
-      `${display(sourceRoot)}/package-lock.json is required in CI. Install locally first and commit the lockfile.`
+      `${manifest.fontAwesomeProSourcesDir}/package-lock.json is required in CI. Run setup with --manifest 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)
@@ -408,12 +307,119 @@ async function installSourceProject(sourceRoot, values, context) {
     env: environment
   });
   if (status !== 0) return status;
-  const lockfile = `${display(sourceRoot)}/package-lock.json`;
-  log(
+  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;
@@ -425,20 +431,23 @@ async function runFontAwesomeSetup(args, io = {}) {
     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) || "."
+    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: {
-        "source-root": { type: "string" },
         "free-only": { type: "boolean" },
-        init: { type: "boolean" },
-        keys: { type: "string" },
+        "pro-in-app": { type: "boolean" },
         manifest: { type: "string" },
-        force: { type: "boolean" },
-        "refresh-lock": { type: "boolean" },
         help: { type: "boolean", short: "h" }
       },
       strict: true,
@@ -448,26 +457,22 @@ async function runFontAwesomeSetup(args, io = {}) {
       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.manifest !== void 0) {
+      return await setupFromManifest(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["free-only"] || values["pro-in-app"]) {
+      throw new Error("--free-only and --pro-in-app require --manifest.");
     }
-    if (values.init && values["refresh-lock"]) {
+    if (!manifest.isFontAwesomeIsolated(cwd)) {
       throw new Error(
-        "--refresh-lock applies to the install step, not --init."
+        `${manifest.fontAwesomeProSourcesDir}/package.json was not found. Run from the application root; for first-time setup, run with --manifest <icons.json>.`
       );
     }
-    const sourceRoot = node_path.resolve(cwd, values["source-root"]);
-    return values.init ? await initSourceProject(sourceRoot, values, context) : await installSourceProject(sourceRoot, values, context);
+    return await installSourceProject(
+      node_path.resolve(cwd, manifest.fontAwesomeProSourcesDir),
+      void 0,
+      context
+    );
   } catch (error) {
     stderr(error instanceof Error ? error.message : "Unknown error");
     return 1;

package/dist/fontawesome/setup.d.ts

@@ -30,8 +30,8 @@ export declare function checkNpmrc(config: string, file: string): {
     hasAuth: boolean;
 };
 /**
- * Parses setup arguments and runs app-root setup, source-project scaffolding,
- * or source-project installation.
+ * 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.