@featherk/icons 0.15.7 → 0.15.8

package/docs/fontawesome/LICENSING.md

@@ -42,6 +42,8 @@ Do not replace the placeholder with a token or move this private registry config
 From the repository root, after confirming Steps 1-2:
 
 ```sh
+# 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/pro.
 npm run setup:fontawesome:pro --workspace=@featherk/demos
 # Step 4: Start the explicitly licensed local profile.
@@ -50,7 +52,7 @@ npm run dev:pro --workspace=@featherk/demos
 npm run build:pro --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.
+FeatherK's demos use the [isolated source project](#optional-pro-isolated-source-project) layout: `setup:fontawesome:pro` runs `featherk-fontawesome-setup --source-root pro`. 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.
 
 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.
 
@@ -62,18 +64,17 @@ Routes are `/icons/fontawesome/free` and `/icons/fontawesome/pro`; `/icons/fonta
 
 ### 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
@@ -104,16 +105,104 @@ 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, once per application, on a developer machine. It reads the UX-provided keys-only manifest (or `--keys a,b`) and pins each package to the exact catalog version. The manifest is the same file the Vite plugin and CLI use: a `free` array of catalog keys plus an optional `pro` array.
+
+### Standard: Free and Pro Together
+
+Most applications use both tiers, so the standard setup installs Free and Pro packages together as ordinary `devDependencies`:
+
+```sh
+npx featherk-fontawesome-setup --manifest fontawesome.keys.json
+```
+
+The command:
+
+1. Adds these lines to the application's `.npmrc`, creating it if needed. Existing settings are kept, and the lines are not duplicated on later runs:
+
+   ```ini
+   @fortawesome:registry=https://npm.fontawesome.com/
+   //npm.fontawesome.com/:_authToken=${FONTAWESOME_PACKAGE_TOKEN}
+   ```
+
+2. Installs the exact Free and Pro pins with `npm install --save-dev --save-exact`, using the token from `FONTAWESOME_PACKAGE_TOKEN` or a hidden prompt.
+
+Commit `.npmrc`, `package.json`, and `package-lock.json`. Then configure the Vite plugin with `allowPro: true` and the manifest's Free and Pro keys, without `sourceRoot` or separate Pro scripts.
+
+The scope line routes **all** `@fortawesome` packages, Free included, to the Font Awesome registry. Every install therefore needs `FONTAWESOME_PACKAGE_TOKEN`, and everyone who installs the application needs 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. 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
+```
+
+The setup command follows the same rule. It installs with `--ignore-scripts` and passes the token only to that npm process. For CI, see [TeamCity](#teamcity).
 
-- **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.
+Before supplying the token, the command checks `.npmrc`. It refuses any of the following:
 
-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.
+- 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
 
-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.
+It also pins the Font Awesome registry on the npm command line, which overrides other npm configuration. The token therefore can only be sent to Font Awesome. The command refuses to run in CI, because it changes `package.json`. It installs with `--ignore-scripts`, so lifecycle scripts never run while the token is present, and it never prints the token. The isolated source-project install applies the same checks, and also requires both Font Awesome lines.
 
-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.
+### 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 writes no `.npmrc` lines and needs no token or CI configuration. It fails if the manifest contains Pro keys, or if `.npmrc` already routes `@fortawesome` to a registry. Leave `allowPro` unset.
+
+Free-only is a per-application choice, not a per-developer one. In a Free and Pro application, the lockfile resolves Free packages through the Font Awesome registry, so a developer without the token cannot install that application. To move a Free-only application to Pro later, add the Pro keys to the manifest and rerun the command without `--free-only`, then add the CI token parameter.
+
+### Optional Pro: Isolated Source Project
+
+Some projects must keep Pro optional so normal installs never need a token. FeatherK's own demos work this way. They install Pro packages into a separate private project and pass `sourceRoot` to the Vite plugin only in an authorized profile, for example `featherkFontAwesome({ keys, allowPro: true, sourceRoot: "pro" })`. The same command supports this layout:
+
+```sh
+# Scaffold .npmrc (token placeholder only), package.json with exact Pro pins, and .gitignore.
+npx featherk-fontawesome-setup --source-root fontawesome-pro-sources --init --manifest fontawesome.keys.json
+# Install with the token; this creates fontawesome-pro-sources/package-lock.json.
+npx featherk-fontawesome-setup --source-root fontawesome-pro-sources
+```
+
+Commit the scaffolded files and the lockfile. `--init` pins only Pro keys, because Free packages belong in the application's own `devDependencies`. It refuses to overwrite existing files unless you pass `--force`, and it needs no token. When `--init --force` changes the dependencies, for example by adding a Pro package, it removes the now-stale `package-lock.json`. The next install then regenerates it with `npm install`; review and commit the new lockfile. After editing the source project's `package.json` by hand, run the install with `--refresh-lock` to update the lockfile. Later runs use `npm ci` in the source project and remove npm workspace settings, so `--workspace` invocations target only that project. In CI, `--init` and `--refresh-lock` are refused and the lockfile is required. The application's own `npm ci` needs no token. CI adds a separate token-scoped install step for the source project before the Pro build.
+
+Keep Pro keys in the manifest's `pro` group and include them only in the authorized profile. Optional profiles must not silently include paid inputs in public/uncredentialed builds. The `dev:pro`/`build:pro` profile scripts above are repository demo helpers.
+
+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. The `allowPro` option prevents accidental selection; it does 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
 
@@ -131,9 +220,38 @@ Use a dedicated trusted Actions job with a protected Environment and approval/br
   run: npm run build:pro --workspace=@featherk/demos
 ```
 
+In CI, detected from `CI`, `TEAMCITY_VERSION`, or `GITHUB_ACTIONS`, the setup command refuses app-root setup and `--init`, and an isolated 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. See [Token-Scoped Installs](#token-scoped-installs). 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 the 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. Change the existing install step to a Command Line step that sets the variable for the install command only. Each Command Line step runs in its own process, so the variable does not carry into later steps.
+
+   Linux agent:
+
+   ```sh
+   FONTAWESOME_PACKAGE_TOKEN='%fontawesome.package.token%' npm ci --ignore-scripts
+   ```
+
+   Windows agent:
+
+   ```bat
+   set "FONTAWESOME_PACKAGE_TOKEN=%fontawesome.package.token%"
+   npm ci --ignore-scripts
+   ```
+
+3. 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).
+4. Leave the build, test, and deploy steps unchanged. They never reference the parameter.
+
+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`.
+
+This applies to the [standard Free and Pro setup](#standard-free-and-pro-together). For the [isolated source project](#optional-pro-isolated-source-project), the app's normal install needs no token. Add a separate token-scoped step that runs the source install script, for example `npm run fontawesome:install:pro`, before the Pro build. [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.15.8",
   "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 {};