Staying current

What it is

Every author command — dev, check, theme and pack — looks at your @homepages/* packages before it does its own work. It compares what your workspace has installed against what is published, and then does one of three things:

• You are on the published release. Nothing is printed and nothing happens.
• You are behind, inside your major. The CLI updates your @homepages/* packages, streams the install so you can watch it, and then runs the command you typed.
• A new major is out. The CLI says so and asks whether to move you. The default is yes. Either way, the command you typed still runs afterwards.

Everything it prints goes to stderr, so check --json still puts exactly one machine-readable report on stdout.

Why it works this way

Your ranges have already said yes. The caret your workspace was scaffolded with covers every patch and minor on the major you are holding — see Versioning — so a release inside that major is one your package.json already permits. The only thing keeping you off it is your committed package-lock.json. Refreshing that lockfile changes nothing you declared; it makes the workspace match what it already claims to be.

A major is the opposite kind of event. Crossing one rewrites every @homepages/* range in your manifest at once, because the packages carry peer windows on each other and only move as a set — installing one of them by name is how you get an unmet peer instead of an upgrade. That is a decision rather than a sync, so it is asked, never assumed.

Checking before the command rather than after it is deliberate too. The kit and the CLI are published together at one version, and a command’s own code loads out of the kit you have installed — so a workspace far enough behind can fail to load a command at all. The thing that fixes drift has to run in front of the thing drift breaks.

How it works

The published version is looked up once a day

The lookup asks the registry your own npm config points at — a mirror or a private proxy answers for it — and remembers the answer for a day, in one small file per user: homepages/template-kit-currency.json, under XDG_CACHE_HOME or ~/.cache. One file per user rather than per workspace, so four workspaces on your machine cost one lookup a day between them, a declined major stays declined in all of them, and none of it is lost to rm -rf node_modules. Deleting the file is safe — the next command looks the version up again.

A lookup that fails is remembered for an hour rather than a day, so being offline once in the morning does not cost you the rest of the day. The whole lookup, config read included, gets three seconds; past that it is abandoned and your command runs, because an unreachable registry must never turn check into a hang.

What happens in each case

What is true of your workspace	What the CLI does
On the published release, or ahead of it	Nothing, silently
Behind, inside your major	Updates your declared @homepages/* packages, then runs your command
A new major is published	Asks [Y/n], defaulting to yes — yes (or enter) rewrites the ranges and installs, only no leaves you where you are
A major you already declined is still the latest	One line pointing at template-kit upgrade; that exact version is not asked about again, and the next one asks afresh
Your CLI and kit report different versions	Says so and asks you to reinstall — the two are published as one release, so that pairing was never shipped

An accepted major installs while a command is already running, and says so: that command finishes on the CLI it started as, and the next one you run is the new one.

When it stays out of the way

Each of these is checked before anything is installed, so none of them can half-happen.

Condition	What the CLI does
Not attached to a terminal — CI, a pipe, a container	Says you are behind and names the update; installs nothing
No package-lock.json at the workspace root	Says there is nothing to refresh; installs nothing
The registry is unreachable, answers badly, or is slower than three seconds	Nothing at all — unknown is never read as current
A local package overlay is in place	Nothing at all, silently; an install would destroy it
You switched it off — see below	Nothing at all

Switching it off

export HOMEPAGES_NO_AUTO_UPDATE=1     # every command, for this shell
template-kit check --no-auto-update   # this one command

The environment variable is read by every command that can install on your behalf, and any value except 0 counts as on. --no-auto-update is the same switch for a single run, and it is a flag on every command that runs this check. Both turn off the question as well as the update: with either in place, a new major is not mentioned and nothing is written.

One consequence worth knowing: template-kit upgrade honours the variable too, and refuses to do anything while it is set, telling you to unset it. A switch one command respected and another ignored would be worse than no switch, so unsetting it is the way back in.

Crossing a major on purpose

template-kit upgrade is the same operation the prompt runs, available whenever you want it — it rewrites every @homepages/* range together and installs once. It needs no terminal, so it is also the way to move a workspace in CI. Its flags, exit codes and constraints are in its reference page, and Cross a kit major is the procedure around it.

What it is not

Not an automatic major. No flag or variable makes a major automatic without asking first — the most that happens without you is a question, and its default is to move you; only a whole-word no keeps you where you are.

Not a second source of truth about versions. The version comes from the same registry the install runs against, so what you are told about and what you would get cannot disagree, and a workspace behind a corporate mirror hears about the versions that mirror actually carries.

Not telemetry. The only thing that leaves your machine is a request for a package’s published version. Nothing about you, your workspace or your templates is sent anywhere.

Not something upgrade runs behind. template-kit upgrade moves the versions itself, so nothing runs in front of it — which is also why --no-auto-update is not one of its flags. It reads the registry fresh rather than through the day-old answer above, because an explicit upgrade is also how you move off a bad release.

Where next

• Versioning — what each kind of release is allowed to change, and which kit major a submission is judged against.
• Cross a kit major — the procedure, end to end.
• template-kit upgrade — the command’s own reference.