* cli: publish freellmapi to npm (#671)
The README and docs/clients.md have documented `npx freellmapi setup-claude`
since the CLI workspace landed, but the package was never pushed to the
registry — every documented command failed with npm E404.
The CLI itself is fine; only the release path was missing. This adds it:
- cli-release.yml publishes on pushes to main that touch cli/**, guarded by a
registry version check so ordinary source changes are a no-op and only a
version bump ships. workflow_dispatch covers the first publish. Publishes
with --provenance so the tarball is traceable to this repo and commit.
- The workflow installs the packed tarball and runs the binary before
publishing, which catches a `files` array that drops a runtime import —
something the unit tests cannot see.
- cli/README.md and cli/LICENSE: the package shipped neither, so the npm page
would have been blank for a package we ask people to npx. Both are added to
`files`, along with homepage/bugs/keywords.
- The documented setup command omitted the credential and exited with "No API
key supplied", so README and docs/clients.md now show --api-key and the
FREELLMAPI_API_KEY alternative.
Publishing needs an NPM_TOKEN repository secret; the workflow fails with an
explicit message when it is absent rather than erroring inside npm publish.
* cli-release: skip instead of failing when NPM_TOKEN is absent
As written, merging this workflow would have put a red X on main: the push
trigger fires, 0.3.0 is unpublished, and the token check exits 1. The secret
cannot be added until the npm account is available, so the first consequence of
landing the fix would have been a broken main.
An automatic run now warns and skips. A manual run still fails loudly, since
explicitly asking for a publish and silently getting none is worse than an
error. The step summary says which case it hit.
* cli-release: use trusted publishing (OIDC) instead of NPM_TOKEN
npm revoked every classic token in December 2025, so the "classic automation
token" this workflow was written around no longer exists. The replacement,
granular access tokens, default to enforcing 2FA on write and the "bypass 2FA"
escape hatch is being wound down through 2026 — it loses sensitive management
actions this August and direct publish around January 2027. A token-based
workflow would have been deprecated before its first run.
Trusted publishing mints a short-lived OIDC credential per job, so there is no
long-lived secret in the repository at all, and npm attaches provenance without
being asked. Node moves to 24 because OIDC needs npm >= 11.5.1 / Node >=
22.14.0; that is still inside the repo's engines range.
Trusted publishing cannot bootstrap a package that does not exist — npm has no
package settings page to configure a publisher against until a first version
exists — so 0.3.0 is published by hand and every later version goes through
this workflow. The npmjs.com setup is documented in the header.
* cli: drop the leading ./ from the bin path
Publishing 0.3.0 warned:
npm warn publish "bin[freellmapi]" script name dist/index.js was invalid and removed
The wording is alarming but benign — npm normalises "./dist/index.js" to
"dist/index.js" and publishes the corrected form, so 0.3.0 on the registry does
have a working bin. Writing it normalised keeps the warning out of future
releases and stops the next person having to verify the registry to find out
whether the binary survived.
Tashfeen