fix(cli): harden and simplify update checks

Author: waleedlatif1

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

@@ -114,35 +114,41 @@ shared profile cannot also set its own endpoint or API key.
 | `SIM_API_KEY` | API key — skips `sim login` entirely |
 | `SIM_WORKSPACE` | Workspace to target |
 | `SIM_OUTPUT` | Output format |
-| `SIM_CONFIG_DIR` | Relocate both files away from `~/.sim` |
+| `SIM_CONFIG_DIR` | Relocate the config directory and update cache; file-specific overrides below still win |
 | `SIM_CONFIG_FILE` | Relocate only the config file |
 | `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 |
+| `SIM_NO_UPDATE_CHECK` | Turn off update checks |
 
 ## Update notices
 
-At most once a day, and only when stderr is a terminal, the CLI asks
+On eligible invocations, the CLI uses a daily cache before asking
 `registry.npmjs.org` what is published under the `latest` tag. Prerelease
-installs are skipped entirely rather than compared against their own channel,
-so a `-preview` or `-dev` build is never told to upgrade. When a newer one exists it prints a single line on stderr naming
-both versions and the command that upgrades:
+installs are skipped entirely, so a `-preview` or `-dev` build is never told to
+upgrade. 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 Sim API key, no
-workspace, no command — and it never follows a redirect away from the registry
-it asked.
+Apart from the configured registry URL, the request identifies only the CLI
+version — no Sim API key, workspace, or command — and it never follows a
+redirect away from the registry it asked.
 
 One caveat worth stating plainly: if you point `npm_config_registry` at a
-private mirror, the check goes to that mirror instead of npm, and any
-credentials embedded in that URL (an Artifactory or Nexus `?token=…`) are sent
-with it — they have to be, or the mirror would reject the request. Those are
-your registry's credentials, not Sim's, and they go only to the host you
-configured.
+private mirror, the check goes to that mirror instead of npm. Query-string
+credentials (an Artifactory or Nexus `?token=…`, for example) are preserved and
+sent as part of the configured registry request — they have to be, or the
+mirror would reject it. As with other registry traffic, configured proxies or
+TLS inspection can observe what that network setup permits. A registry URL
+containing username/password userinfo, such as
+`https://user:password@registry.example`, is rejected and no update check is
+made.
+
+Malformed and non-HTTP(S) configured registry values also disable the update
+check rather than making an unexpected request to the public registry.
 
 The notice is skipped entirely when:
 
@@ -153,27 +159,33 @@ The notice is skipped entirely when:
 - the CLI is running under `npx`, which resolves the newest version every time
 - the CLI is running from a checkout of the sim repository, whose version
   deliberately trails the published one
-- the installed version is a prerelease from the `staging` or `dev` channel
-
-The once-a-day pace comes from a timestamp in `update-check.json`, kept beside
-the config and credentials files: `~/.sim/update-check.json` by default, and
-under `SIM_CONFIG_DIR` when that is set. If it cannot be written — a read-only
-home in a container, or a `~/.sim` left root-owned by an earlier `sudo` install
-— the pace cannot be remembered, so the check runs once per command instead of
-once per day. It stays bounded by the same one-second timeout, and
-`SIM_NO_UPDATE_CHECK=1` still turns it off.
-
-Set `npm_config_registry` to ask a mirror instead; its path and query are
-preserved, so a token-authenticated Artifactory or Nexus base works.
+- the installed version is a prerelease
+
+The daily pace comes from a timestamp in the config directory's
+`update-check.json`: `~/.sim/update-check.json` by default, or under
+`SIM_CONFIG_DIR` when that is set. `SIM_CONFIG_FILE` and
+`SIM_CREDENTIALS_FILE` do not move the cache, so it may not sit beside a file
+relocated with either of those variables.
+
+This throttle is best-effort across processes. Two commands that start together
+can both see a stale cache and check. Cache replacement is atomic, so either
+complete write can win without leaving a partially interleaved file. If the
+cache cannot be written — for example, because the config directory is
+read-only — every eligible invocation attempts a check because there is no
+timestamp to reuse.
+
+The registry check has a one-second deadline. On expiry, the CLI terminates its
+short-lived request process so stalled DNS, connection, or response work cannot
+remain active and delay the command. `SIM_NO_UPDATE_CHECK=1` still turns the
+check off.
 
 The command the notice prints matches how Sim was installed — `npm install -g`,
 `pnpm add -g`, `bun add -g`, or `yarn global add` — so running it updates the
 executable already on your `PATH` rather than installing a second copy under a
 different package manager.
 
-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
-be used.
+Node's `fetch` uses `HTTP(S)_PROXY` when opted in with `NODE_USE_ENV_PROXY=1`
+(Node 22.21+ or 24.0+) or `--use-env-proxy` (Node 22.21+ or 24.5+).
 
 For CI, set `SIM_API_KEY` and `SIM_WORKSPACE` and nothing needs to touch the
 filesystem at all.

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

@@ -118,9 +118,9 @@ one installs a second copy instead of replacing the executable on your `PATH`:
   </Tab>
 </Tabs>
 
-The CLI normally tells you this itself, once a day, on stderr, and the command
-it prints already matches your installation. It stays quiet when stderr is
-redirected, in CI, and under `npx`.
+The CLI can also tell you this through a cached daily check on eligible
+invocations, and the command it prints already matches your installation. It
+stays quiet when stderr is redirected, in CI, and under `npx`.
 
 ## An update notice appears in output I am parsing
 

packages/sim-cli/README.md

@@ -256,21 +256,25 @@ The main environment variables are:
 | `SIM_API_KEY` | API key, usually for CI |
 | `SIM_WORKSPACE` | Workspace to target |
 | `SIM_OUTPUT` | `table`, `json`, `yaml`, or `text` |
-| `SIM_CONFIG_DIR` | Directory containing CLI config and credentials |
+| `SIM_CONFIG_DIR` | Base directory for CLI config, credentials, and the update cache |
 | `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` what is
-published under the `latest` tag and prints one line on stderr when a newer
-version exists. Prerelease installs are skipped entirely. The once-a-day pace
-depends on a writable `~/.sim`; without one the check runs per command, still
-bounded by a one-second timeout. It sends nothing but its own version and never
-your Sim API key. If `npm_config_registry` points at a private mirror, the check
-goes there instead and carries whatever credentials that URL embeds, since the
-mirror would otherwise refuse it. Set `SIM_NO_UPDATE_CHECK=1` to turn it off;
-the full list of cases where it stays quiet is in the
-[configuration guide](https://docs.sim.ai/cli/configuration).
+On eligible interactive invocations, `sim` uses a daily cache before asking
+`registry.npmjs.org` what is published under the `latest` tag and prints one
+line on stderr when a newer version exists. Prerelease installs are skipped
+entirely. The cache lives in `~/.sim` by default and follows `SIM_CONFIG_DIR`;
+without a writable cache, each eligible invocation checks again. Concurrent
+invocations can also perform duplicate checks. The registry request has a
+one-second deadline; the short-lived request process is terminated on expiry.
+Apart from the configured registry URL, it sends only its own version and never
+your Sim API key. If `npm_config_registry` points at a private mirror, its query
+string is preserved, including any query-string credentials. Registry URLs
+containing username/password userinfo are rejected. Set
+`SIM_NO_UPDATE_CHECK=1` to turn it off; malformed or non-HTTP(S) configured
+registry values also fail closed. The full list of cases where it stays quiet
+is in the [configuration guide](https://docs.sim.ai/cli/configuration).
 
 ## Documentation
 

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

@@ -198,15 +198,15 @@ describe('the update check', () => {
     await parse(['--help'], program)
     expect(fired).toBe(0)
 
-    // And the sentinel is not inert: the same hook does fire for a real action,
-    // which is what makes the assertion above mean something.
     const dir = mkdtempSync(join(tmpdir(), 'sim-cli-program-'))
+    const previousConfigDir = process.env.SIM_CONFIG_DIR
     process.env.SIM_CONFIG_DIR = dir
     try {
       await parse(['configure', '--set-output', 'json'], program)
       expect(fired).toBe(1)
     } finally {
-      process.env.SIM_CONFIG_DIR = undefined
+      if (previousConfigDir === undefined) Reflect.deleteProperty(process.env, 'SIM_CONFIG_DIR')
+      else process.env.SIM_CONFIG_DIR = previousConfigDir
       rmSync(dir, { recursive: true, force: true })
     }
   })
@@ -227,8 +227,6 @@ describe('the update check', () => {
     const preAction = preActionHooks(program)
 
     expect(preAction).toHaveLength(1)
-    // Invoking it must resolve, never throw: it runs in front of the user's
-    // command, and a rejection here would fail the command itself.
     await expect(preAction[0](program, program)).resolves.toBeUndefined()
   })
 })

packages/sim-cli/src/program.ts

@@ -152,9 +152,6 @@ 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)