feat(cli): tell the user when their sim is out of date

`sim tools execute` shipped in 2.1.5. Someone on 2.1.2 looking for it saw a
help listing without it and concluded the CLI could not do it - a missing
subcommand is indistinguishable from a feature that was never built, and
nothing in the CLI could tell them otherwise. It had no update check, no
version negotiation, and no way to learn what "current" is.

Once a day, at an interactive terminal, the root `preAction` hook asks
`registry.npmjs.org` for the dist-tags of the channel it was installed from and
prints one line on stderr when a newer version exists. The request carries the
CLI version and nothing else - no key, no workspace, no command - and
`SIM_NO_UPDATE_CHECK=1` turns it off.

Everything about it fails silently, and it says nothing when stderr is not a
terminal, in CI, under `npx`, from a checkout, or to a prerelease install. The
last two are not politeness: the repo manifest trails npm permanently by design
because the publish workflow bumps the version in-job under
`permissions: contents: read` and never commits it back, so without the
checkout guard every engineer here would be told daily to upgrade to a version
their own tree already contains; and `staging` publishes on every push, so
advising a prerelease user would be stale within the hour.

Comparison is scoped to one channel, which is what makes "upgrade" to an older
stable version structurally impossible rather than merely guarded against. The
comparator implements semver precedence including the numeric prerelease rule -
`preview.9` precedes `preview.44`, which a string comparison gets backwards.

The `preAction` hook is deliberate over a teardown in the entrypoint:
commander answers `--help` and `--version` during parsing, so the two
latency-sensitive invocations are excluded by construction, and some commands
call `process.exit` directly where a `finally` would never run.

Timeout is a hard 1s rather than `SIM_TIMEOUT_SECONDS`, which defaults to an
hour and governs work the user actually asked for. The check is stamped whether
or not it succeeds, so a blackholed registry costs one second a day instead of
one per command.

Author: mzxchandra

apps/docs/content/docs/cli/configuration.mdx

@@ -119,6 +119,24 @@ shared profile cannot also set its own endpoint or API key.
 | `SIM_CREDENTIALS_FILE` | Relocate only the credentials file |
 | `SIM_TIMEOUT_SECONDS` | Per-request timeout; `0` waits indefinitely. Defaults to `3600`, above every timeout the server itself applies |
 | `SIM_DEBUG` | Trace each request's method, URL, status and duration to stderr |
+| `SIM_NO_UPDATE_CHECK` | Turn off the once-a-day update notice |
+
+## Update notices
+
+At most once a day, and only when stderr is a terminal, the CLI asks
+`registry.npmjs.org` which version is published under the dist-tag it was
+installed from. When a newer one exists it prints a single line on stderr naming
+both versions and the command that upgrades:
+
+```
+Update available: sim 2.1.2 → 2.1.5. Run: npm install -g sim@latest
+```
+
+The request carries the CLI version and nothing else — no API key, no workspace,
+no command. It is skipped entirely when stderr is redirected, in CI, under
+`npx`, and for prerelease installs, so scripted output is never affected. Set
+`SIM_NO_UPDATE_CHECK=1` to turn it off, and `npm_config_registry` to ask a
+mirror instead.
 
 Node ignores `HTTPS_PROXY` unless you also set `NODE_USE_ENV_PROXY=1`, and only
 from Node 22.21 and 24.5. The CLI warns when a proxy is configured but will not

apps/docs/content/docs/cli/troubleshooting.mdx

@@ -85,6 +85,29 @@ editing the file by hand:
 sim --output table configure --set-output json
 ```
 
+## A command is missing that the documentation describes
+
+The docs track the current release, so a command that exists here and not in
+`sim --help` usually means the installed CLI is older than the feature. Compare
+`sim --version` against the published version and upgrade:
+
+```bash
+sim --version
+npm install -g sim@latest
+```
+
+The CLI normally tells you this itself, once a day, on stderr. It stays quiet
+when stderr is redirected, in CI, and under `npx`.
+
+## An update notice appears in output I am parsing
+
+It should not: the notice is written to stderr, never stdout, so `--output json`
+piped to `jq` is unaffected. If something merges the two streams, silence it:
+
+```bash
+export SIM_NO_UPDATE_CHECK=1
+```
+
 ## Anything else
 
 An unexpected error prints a stack trace. That is a bug in the CLI — please

packages/sim-cli/README.md

@@ -259,6 +259,13 @@ The main environment variables are:
 | `SIM_CONFIG_DIR` | Directory containing CLI config and credentials |
 | `SIM_TIMEOUT_SECONDS` | Per-request timeout; `0` waits indefinitely |
 | `SIM_DEBUG` | Print request diagnostics to stderr |
+| `SIM_NO_UPDATE_CHECK` | Turn off the update notice |
+
+Once a day, at an interactive terminal, `sim` asks `registry.npmjs.org` which
+version is published under the tag it was installed from, and prints one line on
+stderr when a newer one exists. It sends nothing but its own version, never a
+key, and stays quiet when stderr is not a terminal, in CI, and under `npx`. Set
+`SIM_NO_UPDATE_CHECK=1` to turn it off.
 
 ## Documentation
 

packages/sim-cli/src/config/paths.ts

@@ -19,3 +19,17 @@ export function configPath(): string {
 export function credentialsPath(): string {
   return process.env.SIM_CREDENTIALS_FILE || join(configDir(), 'credentials')
 }
+
+/**
+ * Where the once-a-day update check remembers that it ran.
+ *
+ * Cache, not configuration, so it is safe to delete at any time and gets no
+ * `SIM_*` override of its own: nobody relocates a cache deliberately, and
+ * `SIM_CONFIG_DIR` already moves it for the two callers that matter — the test
+ * harness and anyone keeping `~/.sim` somewhere else. It is kept out of the
+ * config file because that file is INI the user edits, and a timestamp inside a
+ * `[profile x]` section would surface in `sim configure` and `sim whoami`.
+ */
+export function updateCachePath(): string {
+  return join(configDir(), 'update-check.json')
+}

packages/sim-cli/src/program.test.ts

@@ -1,8 +1,11 @@
 /**
  * @vitest-environment node
  */
+import { mkdtempSync, readdirSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
 import type { Command } from 'commander'
-import { describe, expect, it } from 'vitest'
+import { describe, expect, it, vi } from 'vitest'
 import { buildProgram } from './program'
 import { CLI_VERSION } from './version'
 
@@ -159,3 +162,35 @@ describe('help typed after a command that does not exist', () => {
     expect(implicit.out).toContain('Usage: sim profiles add')
   })
 })
+
+describe('the update check', () => {
+  /**
+   * The notice must cost `--version` and `--help` nothing. Commander answers
+   * both during parsing, before any action hook runs, so the guarantee is
+   * structural — this holds it in place if the check is ever moved.
+   */
+  it('never runs for the two commands commander answers during parsing', async () => {
+    const stderr = process.stderr
+    const wasTty = stderr.isTTY
+    const dir = mkdtempSync(join(tmpdir(), 'sim-cli-program-'))
+    const requests: string[] = []
+    Object.defineProperty(stderr, 'isTTY', { configurable: true, value: true })
+    process.env.SIM_CONFIG_DIR = dir
+    vi.stubGlobal('fetch', (input: URL) => {
+      requests.push(String(input))
+      return Promise.resolve(Response.json({ latest: '99.0.0' }))
+    })
+
+    try {
+      await parse(['--version'])
+      await parse(['--help'])
+      expect(requests).toEqual([])
+      expect(readdirSync(dir)).toEqual([])
+    } finally {
+      vi.unstubAllGlobals()
+      process.env.SIM_CONFIG_DIR = undefined
+      Object.defineProperty(stderr, 'isTTY', { configurable: true, value: wasTty })
+      rmSync(dir, { recursive: true, force: true })
+    }
+  })
+})

packages/sim-cli/src/program.ts

@@ -10,6 +10,7 @@ import {
   buildGeneratedCommands,
   refuseHelpAfterUnknownCommand,
 } from './runtime/build'
+import { announceUpdateIfAvailable } from './update/check'
 import { CLI_VERSION } from './version'
 
 /** Root program description, shared by `--help` and the generated docs. */
@@ -151,6 +152,11 @@ export function buildProgram(options: { version?: boolean } = {}): Command {
 
   program.addHelpText('after', HELP_EPILOGUE)
 
+  // Root hooks are inherited by the whole tree, and commander answers `--help`
+  // and `--version` during parsing without ever reaching an action — so the two
+  // invocations that must stay instant are excluded by construction.
+  program.hook('preAction', () => announceUpdateIfAvailable())
+
   refuseHelpAfterUnknownCommand(program)
   assertNoReservedProgramFlags(program)