@featherk/icons 0.15.7 → 0.16.0

package/docs/fontawesome/LICENSING.md

@@ -20,15 +20,15 @@ The steps below are for Dev after UX/Design has selected the desired Pro variant
 
 1. Confirm entitlement, Creator coverage, and approved releases with the license owner.
 2. Dev obtains an authorized **Pro Package Token** from the Font Awesome account and supplies it privately as `FONTAWESOME_PACKAGE_TOKEN`.
-3. Dev installs the npm packages named by the manifest's `package` fields at their exact `version`s into the dedicated private project through its environment-referenced npm configuration.
-4. Dev enables the Pro profile and prepares declarations before type checking/building the application.
+3. Dev runs `featherk-fontawesome-setup --manifest fontawesome.keys.json`, which pins Free packages into the application and Pro packages into the private `fontawesome-pro-sources/` project at their exact catalog versions. See [Consuming Applications](#consuming-applications).
+4. Dev builds with the application's normal scripts; wherever `fontawesome-pro-sources/` is installed, the builds include the Pro icons.
 5. Dev preserves upstream notices and verifies publication/deployment boundaries before distribution.
 
 A package token is not a Kit code, account password, or Kendo license key. Never paste it into chat, screenshots, source files, command arguments, or logs. Follow the organization's approved token issuance/rotation process; do not share account passwords.
 
 ## This FeatherK Repository
 
-Normal root installation/build, Free demos, tests, and public package publishing require no Pro token. `demos/pro` is a separate private source project, not a root workspace. It requests exact `@fortawesome/pro-regular-svg-icons@7.0.0` and `@fortawesome/pro-light-svg-icons@7.0.0` packages; no paid dependency is added to the normal demo workspace or public icons package.
+Normal root installation/build, Free demos, tests, and public package publishing require no Pro token. `demos/fontawesome-pro-sources` is a separate private source project, not a root workspace; it is the same [default layout](#default-isolated-pro-sources) every consuming application uses. It requests exact `@fortawesome/pro-regular-svg-icons@7.0.0` and `@fortawesome/pro-light-svg-icons@7.0.0` packages; no paid dependency is added to the normal demo workspace or public icons package.
 
 The committed source-project npm configuration contains only a placeholder:
 
@@ -42,41 +42,42 @@ Do not replace the placeholder with a token or move this private registry config
 From the repository root, after confirming Steps 1-2:
 
 ```sh
-# Step 3: Authenticated installation runs only inside demos/pro.
+# The Font Awesome commands run from the built package; build it first.
+npm run build --workspace=@featherk/icons
+# Step 3: Authenticated installation runs only inside demos/fontawesome-pro-sources.
 npm run setup:fontawesome:pro --workspace=@featherk/demos
-# Step 4: Start the explicitly licensed local profile.
-npm run dev:pro --workspace=@featherk/demos
+# Step 4: Start the demo; with the sources installed, the Pro page renders.
+npm run dev --workspace=@featherk/demos
 # Step 5: Build the application and preserve emitted notices.
-npm run build:pro --workspace=@featherk/demos
+npm run build --workspace=@featherk/demos
 ```
 
-The installer checks for the token without printing it. Initial installation creates an isolated lockfile; later runs use `npm ci` when it exists. Review and commit dependency/integrity metadata for reproducible CI, ensuring it contains no credentials. Source `node_modules` and application artifacts remain ignored. No paid installation has been performed as part of implementing this setup.
+`setup:fontawesome:pro` runs `featherk-fontawesome-setup` without arguments, which installs `demos/fontawesome-pro-sources` from its committed lockfile with `npm ci`. The installer checks for the token without printing it. Review and commit dependency/integrity metadata for reproducible CI, ensuring it contains no credentials. Source `node_modules` and application artifacts remain ignored. No paid installation has been performed as part of implementing this setup.
 
 The UX-approved Pro manifest requests Regular Rocket, Light Feather, and Light Heart. These pins are requested examples, not verified downloads. If entitlement, releases, or exports are unavailable, Dev must stop installation/generation and return to UX/Design for approval before changing the manifest or dependencies; never substitute silently.
 
-The profile wrappers enable the non-secret `FEATHERK_FONTAWESOME_PRO=1` build flag and remove the package token from child build environments. They invoke the demo's own commands, not the root Turborepo cached build. Do not put paid outputs into shared/untrusted caches.
+The demo has no separate Pro scripts: its normal `dev` and `build` include the Pro icons once `demos/fontawesome-pro-sources` is installed, and only the Free icons otherwise. `demos/turbo.json` adds `fontawesome-pro-sources/node_modules/.package-lock.json`, which npm writes on install, to the build's cache inputs, so the root Turborepo build never replays a Free build where Pro sources are installed, or the reverse. Do not put paid outputs into shared or remote caches.
 
-`sourceRoot: "pro"` resolves installed licensed packages while output guards remain relative to the demo project. Node resolution also finds already installed Free packages in parent workspace directories. The next normal preparation restores the Free-only generated key union.
+The demo's plugin options are `{ manifest: "fontawesome.keys.json" }`. With the sources installed, the plugin resolves licensed packages from `fontawesome-pro-sources/` while output guards remain relative to the demo project; Node resolution also finds already installed Free packages in parent workspace directories. Without them, it does not read that directory.
 
 Routes are `/icons/fontawesome/free` and `/icons/fontawesome/pro`; `/icons/fontawesome` redirects to Free. The Pro page shows an unavailable state without a licensed profile, never fabricated artwork. Enabling the profile with missing/invalid sources fails the build rather than hiding an error.
 
 ### Private Local Token Input
 
-Run one option in your own terminal. Secret input stays in the terminal, not the assistant.
+In an interactive terminal, the installer prompts for the token with hidden input when `FONTAWESOME_PACKAGE_TOKEN` is not set. Use the options below to manage the variable yourself instead. Run one option in your own terminal. Secret input stays in the terminal, not the assistant.
 
 Git Bash:
 
 ```bash
 # Step 2: Type the token at the hidden prompt.
-read -r -s -p "Font Awesome package token: " FONTAWESOME_PACKAGE_TOKEN
-export FONTAWESOME_PACKAGE_TOKEN
-# Step 3: Install, then remove the token from the shell environment.
-npm run setup:fontawesome:pro --workspace=@featherk/demos
+read -r -s -p "Font Awesome package token: " fa_token; echo
+# Step 3: Pass the token to the install command only, then discard it.
+FONTAWESOME_PACKAGE_TOKEN="$fa_token" npm run setup:fontawesome:pro --workspace=@featherk/demos
 setup_status=$?
-unset FONTAWESOME_PACKAGE_TOKEN
+unset fa_token
 # Step 4: Start only after successful installation.
 if [[ $setup_status -eq 0 ]]; then
-  npm run dev:pro --workspace=@featherk/demos
+  npm run dev --workspace=@featherk/demos
 fi
 ```
 
@@ -95,7 +96,7 @@ try {
   Remove-Item Env:FONTAWESOME_PACKAGE_TOKEN -ErrorAction SilentlyContinue
 }
 # Step 4: Start only after successful installation.
-npm run dev:pro --workspace=@featherk/demos
+npm run dev --workspace=@featherk/demos
 ```
 
 Do not continue after an install error. `401`/`403` can indicate invalid/revoked credentials or insufficient entitlement. Inspect status codes without printing token/config contents. Missing releases/exports need a source/approval review, not an unpinned upgrade.
@@ -104,21 +105,136 @@ Do not continue after an install error. `401`/`403` can indicate invalid/revoked
 
 Consumers need their own covered access or an enterprise agreement that actually covers them. The public FeatherK package grants no Pro rights.
 
-Two supported Vite layouts are:
+`@featherk/icons` provides `featherk-fontawesome-setup` for consumer setup. Run it through `npx` or an npm script from the application root, on a developer machine. It reads the UX-provided keys-only manifest, the same file the Vite plugin and CLI use (a `free` array of catalog keys plus an optional `pro` array), and pins each package to the exact catalog version.
+
+### Default: Isolated Pro Sources
+
+Every application uses this layout unless it has a specific reason not to:
+
+```sh
+npx featherk-fontawesome-setup --manifest fontawesome.keys.json
+```
+
+The command:
+
+1. Installs the exact Free pins into the application's `devDependencies` from public npm. This step needs no token.
+2. Writes the exact Pro pins into `fontawesome-pro-sources/`, a private source project next to the application's `package.json`, then installs it with the token from `FONTAWESOME_PACKAGE_TOKEN` or a hidden prompt. The project contains a `package.json`, a `.gitignore` for its `node_modules`, and an `.npmrc` with only the token placeholder:
+
+   ```ini
+   @fortawesome:registry=https://npm.fontawesome.com/
+   //npm.fontawesome.com/:_authToken=${FONTAWESOME_PACKAGE_TOKEN}
+   ```
+
+Commit `package.json`, `package-lock.json`, and `fontawesome-pro-sources/`, including its `package-lock.json`. Configure the Vite plugin with `featherkFontAwesome({ manifest: "fontawesome.keys.json" })`.
+
+The directory name `fontawesome-pro-sources` is fixed, so every team's setup looks the same. The plugin and CLI find the directory themselves, and installing it is what turns Pro icons on. The application's normal `dev` and `build` scripts need no changes:
+
+- **Where `fontawesome-pro-sources/` is installed** (its `node_modules` exists), builds generate the `free` and `pro` keys, resolving Pro packages from it.
+- **Where it is not installed**, builds generate the `free` keys alone and never read it. If a job should have installed it and didn't, code that uses a Pro key fails type checking, because the generated key union then contains only Free keys.
+
+The application's own `npm ci` never needs the token, so developers and CI jobs without Pro access can still install it and build Free-only. Only installing `fontawesome-pro-sources/` needs Pro access, and everyone who does, or who builds where it is installed, needs an applicable seat.
+
+A build cache keyed on tracked files, such as Turborepo's, must also key on whether the sources are installed, or it can replay a Free build where Pro is expected. Add the install marker that npm writes to the build's inputs, for example in Turborepo:
+
+```json
+"inputs": ["$TURBO_DEFAULT$", "fontawesome-pro-sources/node_modules/.package-lock.json"]
+```
+
+Keep builds that include Pro icons out of shared or remote caches.
+
+After changing the manifest, rerun the same command. It updates both sets of pins; when the Pro pins change, it removes the stale `fontawesome-pro-sources/package-lock.json` and the install regenerates it. Review and commit the result.
+
+On a fresh clone and in CI, run the application's normal `npm ci`, then install the source project from its committed lockfile:
+
+```sh
+npx featherk-fontawesome-setup
+```
+
+Without arguments, the command runs `npm ci` in `fontawesome-pro-sources/` with the token, skipping lifecycle scripts and ignoring npm workspace settings. In CI it requires the committed lockfile. See [CI and Deployment](#ci-and-deployment).
+
+### Setup Safety Checks
+
+Before supplying the token, the command checks the `.npmrc` it will install with: the application's for `--pro-in-app`, and `fontawesome-pro-sources/.npmrc` for the default layout. It refuses any of the following:
+
+- a `@fortawesome` registry other than `https://npm.fontawesome.com/`
+- any reference to `FONTAWESOME_PACKAGE_TOKEN` outside `//npm.fontawesome.com/:_authToken`
+- any other `npm.fontawesome.com` credential, including a literal token
+
+It also pins the Font Awesome registry on the npm command line, which overrides other npm configuration, so the token can only be sent to Font Awesome. It installs with `--ignore-scripts`, so lifecycle scripts never run while the token is present, passes the token only to that npm process, and never prints it. Setup with `--manifest` changes `package.json`, so it refuses to run in CI.
+
+The layouts cannot be mixed in one application. The default setup refuses an application whose `.npmrc` already routes `@fortawesome` to the Pro registry, and `--pro-in-app` refuses an application that has `fontawesome-pro-sources/`.
+
+### Exception: Free Only
+
+For an application that will use only Free icons:
+
+```sh
+npx featherk-fontawesome-setup --manifest fontawesome.keys.json --free-only
+```
+
+Free packages come from public npm. The command needs no token or CI configuration and creates no source project. The default command behaves the same way for a manifest without Pro keys; `--free-only` also guarantees it, failing if the manifest contains Pro keys, if `fontawesome-pro-sources/` exists, or if `.npmrc` routes `@fortawesome` to a registry. Configure the Vite plugin with `{ manifest: "fontawesome.keys.json" }`. To add Pro later, add the keys to the manifest and rerun without `--free-only`.
+
+### Exception: Pro in the Application
+
+Use this only when an isolated source project is not an option, for example when the application's toolchain cannot resolve packages from the separate `fontawesome-pro-sources/` project:
+
+```sh
+npx featherk-fontawesome-setup --manifest fontawesome.keys.json --pro-in-app
+```
+
+The command adds the two Font Awesome lines shown above to the application's own `.npmrc`, creating it if needed (existing settings are kept, and the lines are not duplicated on later runs), then installs the exact Free and Pro pins into the application's `devDependencies` with the token. Commit `.npmrc`, `package.json`, and `package-lock.json`, and configure the Vite plugin with `{ manifest: "fontawesome.keys.json" }`. Without `fontawesome-pro-sources/`, every build includes the Pro keys.
+
+The cost is that the scope line routes **all** `@fortawesome` packages, Free included, to the Font Awesome registry. Every install of the application, by every developer and CI job, then needs `FONTAWESOME_PACKAGE_TOKEN` and an applicable seat.
+
+#### Token-Scoped Installs
+
+`npm ci` runs lifecycle scripts from the application and every dependency, and later build tools run arbitrary Node code. Any of them can read a token in their environment. Log masking and Vite's `VITE_` client-variable filter do not prevent this. Do not export the token persistently or for a whole CI build. In a Pro-in-the-application setup, give it only to an install that skips scripts, then run anything that needs scripts without it:
+
+1. With the token: `npm ci --ignore-scripts`.
+2. Without the token, run any install scripts the application needs:
+   - `npm rebuild` runs the dependency install scripts that step 1 skipped. On npm 12 and later, dependency scripts run only when approved in the application's `allowScripts` (`npm install-scripts approve <pkg>`), and `npm rebuild` follows the same approvals. Older npm versions run all of them.
+   - `npm rebuild` does not run the application's own lifecycle scripts. Run those explicitly, for example `npm run prepare --if-present`.
+3. Without the token: `npm run dev`, `npm run build`, tests, and deployment. npm runs normally when the `.npmrc` placeholder is unset; only `@fortawesome` registry requests need it.
+
+Git Bash:
+
+```bash
+read -r -s -p "Font Awesome package token: " fa_token; echo
+FONTAWESOME_PACKAGE_TOKEN="$fa_token" npm ci --ignore-scripts
+install_status=$?
+unset fa_token
+[[ $install_status -eq 0 ]] && npm rebuild
+```
+
+PowerShell:
+
+```powershell
+$env:FONTAWESOME_PACKAGE_TOKEN = [System.Net.NetworkCredential]::new(
+  "", (Read-Host "Font Awesome package token" -AsSecureString)
+).Password
+try {
+  npm ci --ignore-scripts
+  if ($LASTEXITCODE -ne 0) { throw "Font Awesome package installation failed." }
+} finally {
+  Remove-Item Env:FONTAWESOME_PACKAGE_TOKEN -ErrorAction SilentlyContinue
+}
+npm rebuild
+```
 
-- **Application development dependencies:** configure environment-referenced authentication in the app and install exact Pro packages. Normal dependency installation then requires licensed access.
-- **Isolated optional source project:** install sources separately and pass `sourceRoot` to the Vite plugin. Keep application output within the consumer project.
+The default layout needs none of this: the application's `npm ci` has no token, and `featherk-fontawesome-setup` already installs the source project with `--ignore-scripts`.
 
-For non-Vite applications or declaration generation before a standalone type check, follow [CLI and non-Vite setup](FontAwesomeCLI.md). Registry authentication still belongs to the authorized package installation environment; the generator and browser never receive the token.
+### Generation and Licensing Boundaries
 
-For Vite, pass only selected catalog keys and opt in at the profile level, for example `featherkFontAwesome({ keys, allowPro: true, sourceRoot: "pro" })`. Keep Pro keys in the app's optional Pro group and include them only in an authorized build profile. The profile scripts above are repository demo helpers, not scripts automatically installed into consumer applications. The `allowPro` option prevents accidental selection; it does not verify license entitlement.
+Keep Pro keys in the manifest's `pro` group. Public or uncredentialed builds must not include paid inputs: run them where `fontawesome-pro-sources/` is not installed.
 
-For applications using both Free and Pro, UX provides catalog keys for both tiers; Dev keeps Free and Pro keys in the shared keys-only selection file and includes Pro keys only in the explicit authorized profile. Optional profiles must not silently include paid inputs in public/uncredentialed builds. Follow the [generated-output ignore guidance](FontAwesome.md#generated-output-and-source-checks): exclude generated files from ESLint/Prettier/Git while retaining TypeScript checks.
+For non-Vite applications or declaration generation before a standalone type check, follow [CLI and non-Vite setup](FontAwesomeCLI.md). Registry authentication still belongs to the authorized package installation environment; the generator and browser never receive the token. Listing a key under `pro`, and installing `fontawesome-pro-sources/` only where Pro is wanted, prevent accidental selection; they do not verify license entitlement. Follow the [generated-output ignore guidance](FontAwesome.md#generated-output-and-source-checks): exclude generated files from ESLint/Prettier/Git while retaining TypeScript checks.
 
 ## CI and Deployment
 
 FeatherK and `feather-k-<demo-name>` repositories use GitHub Actions. TeamCity applies only to enterprise apps using that platform.
 
+In the default layout, a Pro build has three steps: the application's normal `npm ci` without the token, a token-scoped `npx featherk-fontawesome-setup` that installs `fontawesome-pro-sources/` from its lockfile, and the application's normal build without the token. Builds that don't need Pro icons skip the middle step and come out Free-only.
+
 Use a dedicated trusted Actions job with a protected Environment and approval/branch rules. Supply the token only to source installation, not public publishing or client compilation. After checkout and Node/root dependency setup:
 
 ```yaml
@@ -128,12 +244,55 @@ Use a dedicated trusted Actions job with a protected Environment and approval/br
     NPM_CONFIG_CACHE: ${{ runner.temp }}/fontawesome-pro-cache
   run: npm run setup:fontawesome:pro --workspace=@featherk/demos
 - name: Build licensed demo application
-  run: npm run build:pro --workspace=@featherk/demos
+  run: npm run build --workspace=@featherk/demos
 ```
 
+In CI, detected from `CI`, `TEAMCITY_VERSION`, or `GITHUB_ACTIONS`, the setup command refuses `--manifest` setup, and the source-project install requires the committed `package-lock.json`. Unattended jobs therefore only run a locked `npm ci` and never resolve new versions. In every layout, supply the token only to the install step that skips lifecycle scripts, never to the whole job. With no token and no interactive terminal, the command fails instead of prompting.
+
 Configure the protected Environment separately; this fragment grants no license rights. Restrict paid caches/archives/artifacts, and never execute untrusted PR code with the token, including via `pull_request_target`. Normal public FeatherK publishing must not receive Pro credentials or use the licensed profile.
 
-In TeamCity, limit `env.FONTAWESOME_PACKAGE_TOKEN` Password parameters to trusted acquisition steps/agents. Install locked sources, remove credentials from subsequent steps, then run the app's Vite or explicit generator build. Tokens do not expand Creator seats.
+### TeamCity
+
+Do not define the token as an `env.` parameter. TeamCity passes `env.` parameters to every step in the build, so build tools and lifecycle scripts could read the token. Instead, scope it to one install step:
+
+1. In the build configuration, add a parameter named `fontawesome.package.token` with type **Password**. Use no `env.` prefix, so TeamCity does not export it to the steps' environment.
+2. Add a Command Line step that sets the variable for one command only. Each Command Line step runs in its own process, so the variable does not carry into later steps.
+
+   For the [default layout](#default-isolated-pro-sources), leave the application's existing `npm ci` step unchanged and add this step after it:
+
+   ```sh
+   # Linux agent
+   FONTAWESOME_PACKAGE_TOKEN='%fontawesome.package.token%' npx featherk-fontawesome-setup
+   ```
+
+   ```bat
+   rem Windows agent
+   set "FONTAWESOME_PACKAGE_TOKEN=%fontawesome.package.token%"
+   npx featherk-fontawesome-setup
+   ```
+
+   Leave the build step unchanged: with the sources installed, the normal build includes the Pro icons.
+
+   For [Pro in the application](#exception-pro-in-the-application), change the existing install step instead:
+
+   ```sh
+   # Linux agent
+   FONTAWESOME_PACKAGE_TOKEN='%fontawesome.package.token%' npm ci --ignore-scripts
+   ```
+
+   ```bat
+   rem Windows agent
+   set "FONTAWESOME_PACKAGE_TOKEN=%fontawesome.package.token%"
+   npm ci --ignore-scripts
+   ```
+
+   If the application or its dependencies need install scripts, add a step without the token. Use `npm rebuild` for dependency scripts, which follows `allowScripts` approvals on npm 12 and later. Run the application's own scripts explicitly, for example `npm run prepare --if-present`, because `npm rebuild` does not run them. See [Token-Scoped Installs](#token-scoped-installs).
+
+3. Leave the build, test, and deploy steps free of the parameter. They never reference it.
+
+Password parameters are masked in build logs, but masking does not stop code running in a step from reading the value. TeamCity also writes the step script, with the substituted value, to a temporary file on the agent. Limit the parameter to trusted build configurations and agents, and never run untrusted pull-request code in a build that defines it. Build agents must be able to reach `npm.fontawesome.com`. [Free-only](#exception-free-only) applications need no TeamCity configuration.
+
+Tokens do not expand Creator seats.
 
 Enterprise Pages must enforce authentication on deployed URLs/static assets; repository privacy alone is insufficient. Rendered SVGs remain extractable by authorized viewers. Preserve notices and distribute an application, not a standalone paid-icon catalog. Actual license terms govern permitted deployment.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@featherk/icons",
-  "version": "0.15.7",
+  "version": "0.16.0",
   "main": "dist/featherk-icons.umd.js",
   "module": "dist/featherk-icons.es.js",
   "types": "dist/index.d.ts",
@@ -40,10 +40,11 @@
   "files": [
     "dist",
     "docs",
-    "scripts/fontawesome.mjs"
+    "bin"
   ],
   "bin": {
-    "featherk-fontawesome": "scripts/fontawesome.mjs"
+    "featherk-fontawesome": "bin/featherk-fontawesome.mjs",
+    "featherk-fontawesome-setup": "bin/featherk-fontawesome-setup.mjs"
   },
   "peerDependencies": {
     "vite": "^7.0.0 || ^8.0.0"
@@ -56,7 +57,7 @@
   "scripts": {
     "build": "vite build && npm run build:fontawesome && npm run build:types && npm run build:docs-manifest",
     "build:fontawesome": "vite build --config vite.fontawesome.config.ts",
-    "build:types": "vue-tsc --emitDeclarationOnly --declaration --declarationDir dist",
+    "build:types": "vue-tsc -p tsconfig.build.json --emitDeclarationOnly --declaration --declarationDir dist",
     "build:docs-manifest": "node ../../scripts/generate-docs-manifest.mjs",
     "test": "vitest --config vitest.config.ts",
     "test:unit": "vitest run --config vitest.config.ts",

package/dist/fontawesome/catalog.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/fontawesome/cli.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/fontawesome/fontawesome-service.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/fontawesome/generate.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/fontawesome/normalize.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/fontawesome/vite.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/icon-service.test.d.ts

@@ -1 +0,0 @@
-export {};