Skip to content

armgit / Ix

Public Imported from GitHub
0

Understand any codebase instantly. System intelligence for codebases, built for humans and AI.

fix(cli): only check for updates when a person is watching (#681)

Ian Hock5dea6674f69e
diff --git a/ix-cli/src/cli/__tests__/update-check-gate.test.ts b/ix-cli/src/cli/__tests__/update-check-gate.test.ts
new file mode 100644
index 00000000..59fe267a
--- /dev/null
+++ b/ix-cli/src/cli/__tests__/update-check-gate.test.ts
@@ -0,0 +1,65 @@
+// Copyright 2026 Ix Infrastructure Inc.
+
+import { describe, expect, it } from "vitest";
+
+import { updateCheckEnabled } from "../commands/upgrade.js";
+
+/** A terminal session with nothing special set. */
+const tty = (argv: string[], env: NodeJS.ProcessEnv = {}) => updateCheckEnabled(argv, env, true);
+/** Anything capturing stderr: an agent, a pipe, a CI log. */
+const captured = (argv: string[], env: NodeJS.ProcessEnv = {}) => updateCheckEnabled(argv, env, false);
+
+describe("updateCheckEnabled", () => {
+ it("runs for an ordinary command at a terminal", () => {
+ expect(tty(["status"])).toBe(true);
+ expect(tty(["context", "resolveWorkspaceRoot"])).toBe(true);
+ });
+
+ it("does not run when stderr is captured", () => {
+ // The case that matters: an agent runs `ix <cmd> 2>&1` and the notice
+ // lands at the top of every tool result it reads.
+ expect(captured(["status"])).toBe(false);
+ });
+
+ it("does not run when a machine-readable format was asked for", () => {
+ for (const format of ["llm", "json"]) {
+ expect(tty(["search", "Widget", "--format", format])).toBe(false);
+ expect(tty(["search", "Widget", `--format=${format}`])).toBe(false);
+ }
+ });
+
+ it("still runs for an explicit --format text", () => {
+ expect(tty(["search", "Widget", "--format", "text"])).toBe(true);
+ expect(tty(["search", "Widget", "--format=text"])).toBe(true);
+ });
+
+ it("leaves the check on when --format has no value to read", () => {
+ // commander reports the error; the gate should not guess.
+ expect(tty(["search", "Widget", "--format"])).toBe(true);
+ });
+
+ it("honours IX_NO_UPDATE_CHECK", () => {
+ for (const value of ["1", "true", "TRUE", "yes"]) {
+ expect(tty(["status"], { IX_NO_UPDATE_CHECK: value })).toBe(false);
+ }
+ });
+
+ it("treats an empty or falsy IX_NO_UPDATE_CHECK as unset", () => {
+ for (const value of ["", "0", "false", " "]) {
+ expect(tty(["status"], { IX_NO_UPDATE_CHECK: value })).toBe(true);
+ }
+ });
+
+ it("keeps the existing exemptions", () => {
+ // `upgrade` reports versions itself; `mcp` speaks JSON-RPC on stdio, where
+ // a stray notice is a protocol error.
+ expect(tty(["upgrade"])).toBe(false);
+ expect(tty(["mcp"])).toBe(false);
+ expect(tty(["status"], { IX_MCP_CHILD: "1" })).toBe(false);
+ });
+
+ it("does not mistake another flag's value for a format", () => {
+ expect(tty(["text", "--format-ish", "json"])).toBe(true);
+ expect(tty(["search", "--path", "--format"])).toBe(true);
+ });
+});
diff --git a/ix-cli/src/cli/commands/upgrade.ts b/ix-cli/src/cli/commands/upgrade.ts
index 2c055c7c..d9d2d675 100644
--- a/ix-cli/src/cli/commands/upgrade.ts
+++ b/ix-cli/src/cli/commands/upgrade.ts
@@ -1235,6 +1235,53 @@ function detectPlatform(): string {
* Check for updates (non-blocking, cached for 1 hour).
* Call this from other commands to notify users.
*/
+/**
+ * Whether the background update check should run for this invocation.
+ *
+ * The notice it can print is four or five lines on stderr, and it fires on
+ * ordinary commands. That is fine for a person at a terminal and wrong for
+ * everything else: an agent runs `ix <cmd> 2>&1`, so the notice lands at the
+ * top of every tool result it reads, and it led 100% of the `ix` calls in a
+ * recorded benchmark. A script or a CI log gets the same treatment.
+ *
+ * Skipping the check rather than only the print also drops the unawaited
+ * network fetch, which is what delays process exit on an otherwise local
+ * command.
+ *
+ * `--format` is read straight from argv because this runs before commander has
+ * parsed anything; an unparseable or absent value just leaves the check on.
+ */
+export function updateCheckEnabled(
+ argv: readonly string[],
+ env: NodeJS.ProcessEnv,
+ stderrIsTerminal: boolean,
+): boolean {
+ // `upgrade` reports versions itself, and `mcp` speaks JSON-RPC on stdio
+ // where a stray notice is a protocol error.
+ if (argv[0] === "upgrade" || argv[0] === "mcp") return false;
+ if (env.IX_MCP_CHILD === "1") return false;
+ if (isTruthyEnv(env.IX_NO_UPDATE_CHECK)) return false;
+ if (!stderrIsTerminal) return false;
+ const format = requestedFormat(argv);
+ if (format !== undefined && format !== "text") return false;
+ return true;
+}
+
+function isTruthyEnv(value: string | undefined): boolean {
+ if (value === undefined) return false;
+ const normalized = value.trim().toLowerCase();
+ return normalized !== "" && normalized !== "0" && normalized !== "false";
+}
+
+function requestedFormat(argv: readonly string[]): string | undefined {
+ for (let i = 0; i < argv.length; i += 1) {
+ const arg = argv[i];
+ if (arg === "--format") return argv[i + 1];
+ if (arg !== undefined && arg.startsWith("--format=")) return arg.slice("--format=".length);
+ }
+ return undefined;
+}
+
export async function checkForUpdate(): Promise<void> {
const current = getCurrentVersion();
const cache = readCache();
diff --git a/ix-cli/src/cli/main.ts b/ix-cli/src/cli/main.ts
index 2a35e39b..e8363896 100644
--- a/ix-cli/src/cli/main.ts
+++ b/ix-cli/src/cli/main.ts
@@ -5,7 +5,8 @@ import { Command } from "commander";
import { registerOssCommands, registerProStubs } from "./register/oss.js";
import { tryLoadProCommands } from "./register/pro-loader.js";
import { buildHelpText } from "./help-text.js";
-import { checkForUpdate } from "./commands/upgrade.js";
+import { checkForUpdate, updateCheckEnabled } from "./commands/upgrade.js";
+import { stderrIsTerminal } from "./stderr.js";
import { renderCliError } from "./errors.js";
import { getEndpoint } from "./config.js";
@@ -85,9 +86,11 @@ registerOssCommands(program);
registerProStubs(program);
}
- // Check for updates (non-blocking, cached 1hr) — skip for upgrade command itself
+ // Check for updates (non-blocking, cached 1hr). Only when a person is
+ // watching stderr — see updateCheckEnabled for why, and for the
+ // IX_NO_UPDATE_CHECK opt-out.
const args = process.argv.slice(2);
- if (args[0] !== "upgrade" && args[0] !== "mcp" && process.env.IX_MCP_CHILD !== "1") {
+ if (updateCheckEnabled(args, process.env, stderrIsTerminal())) {
// Deliberately not awaited — but it must still be caught here. The catch
// inside checkForUpdate only guards its inner fetch chain; the function's
// own promise covers the synchronous cached-read path, and a corrupt
diff --git a/ix-cli/src/cli/stderr.ts b/ix-cli/src/cli/stderr.ts
index 13e790b1..eeddbe81 100644
--- a/ix-cli/src/cli/stderr.ts
+++ b/ix-cli/src/cli/stderr.ts
@@ -27,5 +27,15 @@ export function stderrDim(message: string): void {
* whatever the first import happened to see.
*/
export function canRenderProgress(): boolean {
+ return stderrIsTerminal();
+}
+
+/**
+ * Whether stderr is a terminal, i.e. whether anything written there is going to
+ * a person watching rather than into a capture.
+ *
+ * Read at each call, for the reason given on `canRenderProgress`.
+ */
+export function stderrIsTerminal(): boolean {
return Boolean(process.stderr.isTTY);
}