feat(cli): say so when the installed n8nac is behind what is published

[EtienneLescot]

Closes #660. Stacked on #661, because both touch update-ai.ts. Review or merge that one first; the diff here is the last commit only.

Nothing in this repo ever compared the installed CLI against the registry. No update-notifier, no query, no warning.

That was survivable while generated agent instructions ran npx --yes n8nac@<tag>: npx re-resolved the dist tag on every single call, so an agent silently ran the newest publish and nobody had to think about versions. #657 makes the generated context name a locally installed n8nac, which is roughly eight times faster per call but pins the version. The invisible update is gone, so something has to say so out loud.

What it does

One dim line on stderr at the end of a successful update-ai:

ℹ  n8nac: 2.7.0 is published, this is 2.6.0. Update with `npm i n8nac@latest`, adding `-g` if you installed globally, then rerun `update-ai`.

update-ai is the right place: it runs rarely, it is exactly when the agent context is regenerated, and it already knows both the version and the dist tag.

Why it cannot hurt

• Reads the registry's dist-tags document, about 80 bytes. No packument.
• Three-second abort signal, and a catch that swallows offline, refused, malformed and unexpected alike.
• Runs only after the command has already succeeded. update-ai is documented as never throwing and that stays true.
• stderr, never stdout. The reason is written down at update-ai.ts:267-269: around forty commands take --json.
• Silent under --silent, and silent in a dev checkout, where a maintainer on a locally bumped version should not be told to update.

Opt-outs

Reuses what already exists rather than inventing a variable. CI=true and DO_NOT_TRACK=1 are both already read by packages/telemetry. Added NO_UPDATE_NOTIFIER, the de-facto standard name for this one check.

These want a doc line. The natural home is the Update section #657 adds to docs/docs/usage/cli.md, which does not exist on this branch. I will add it there rather than write a conflicting version here.

No semver dependency

A plain inequality against the dist tag is enough for a hint, and skipping dev checkouts removes the only case where it could read backwards. semver is not a direct dependency of packages/cli and one string compare does not earn it.

Checks

Seven new unit tests covering the opt-outs, the missing-version case, a refused response, a rejected fetch, a malformed document, an absent dist tag, and the abort signal being sent. Fetch is injected, matching the global-swap pattern already used in preflight-node-validator.test.ts.

packages/cli: 457 tests pass, typecheck clean. Also exercised against the live registry: latest and next both resolve, an up-to-date version reports nothing, and CI=true never opens a socket.

Adjacent, not fixed here

checkAndRefreshIfStale has no production caller. Outside dist and node_modules, the only references are its own definition and two tests, so only the explicit update-ai path runs today. Worth its own issue.

🤖 Generated with Claude Code

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Advanced

Run ID: 64d384d6-f649-4b74-9c27-459cdf3027b8

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}