gitnexus 1.6.11-rc.48 → 1.6.11-rc.49

package/README.md

@@ -264,6 +264,7 @@ gitnexus wiki --provider grok    # Local Grok Build CLI (uses `grok login`, no A
 gitnexus wiki --base-url http://llama-box.local:8080/v1 --allow-insecure-connection llama-box.local
                                   # Allow an exact LAN/self-hosted HTTP LLM host; env: GITNEXUS_ALLOW_INSECURE_CONNECTION
 gitnexus doctor                  # Show runtime platform capabilities and embedding configuration
+gitnexus update                  # Install the latest published GitNexus (`npm i -g gitnexus@<x.y.z>`)
 
 # Direct graph queries — the same tools the MCP server exposes, no MCP daemon needed
 gitnexus query "<concept>"                                    # Process-grouped hybrid search
@@ -492,6 +493,40 @@ bigger cycle) and `N` increments per published rc. Example sequence:
 `1.6.3-rc.1`. See the [Releases page](https://github.com/abhigyanpatwari/GitNexus/releases)
 for the full list; stable `latest` is unaffected.
 
+## Update notifications
+
+GitNexus checks the npm registry's `latest` dist-tag at most once every 24
+hours per installation and tells you when a newer stable version exists. The
+result is cached under `$GITNEXUS_HOME` (`~/.gitnexus` by default), so the
+check never runs on the command's hot path and never blocks output. Where the
+notice appears:
+
+- **CLI** — one line on stderr when you run a command interactively (never on
+  stdout, so `gitnexus query … | jq` and other piped output stay clean), a
+  line in `gitnexus doctor` when an update is known. Automatic notices never
+  install. `gitnexus update` checks even when notices are opted out, then
+  runs `npm i -g gitnexus@<x.y.z>` (same idea as `claude update` /
+  `codex update`).
+- **MCP server** — one structured log record on the server's stderr per
+  process per version (visible in your host's MCP log panel). Tool results,
+  resources, prompts, and server instructions never carry update text.
+- **Web UI** — a dismissible banner when the server reports a newer version;
+  dismissal persists per version.
+
+The check is skipped entirely (no network request, no output) when `CI` is
+truthy, when the install is not an npm global/local install (npx cache, dev
+checkout, Docker image — the Docker CLI image sets the opt-out itself), or
+when opted out:
+
+| Variable | Effect |
+| --- | --- |
+| `GITNEXUS_NO_UPDATE_NOTIFIER` | Truthy (`1`, `true`, …) disables the update check on every surface. |
+| `NO_UPDATE_NOTIFIER` | Cross-tool convention; honored the same way. |
+| `npm_config_registry` | The check reads the `latest` dist-tag from this registry instead of `https://registry.npmjs.org`. Credentials are never sent, and registries that require authentication are not supported (the check silently skips). |
+
+Eval harnesses running a global install can set `GITNEXUS_NO_UPDATE_NOTIFIER`
+for a quiet registry.
+
 ## Troubleshooting
 
 ### `Cannot destructure property 'package' of 'node.target' as it is null`

package/dist/cli/analyze.js

@@ -609,7 +609,6 @@ export async function analyzeOrWatchCommandWithRunnerIdentity(runnerIdentityAtBo
     await analyzeCommandWithRunnerIdentity(runnerIdentityAtBootstrap, inputPath, options);
 }
 const analyzeCommandImpl = async (inputPath, cliOptions, runnerIdentityAtBootstrap) => {
-    console.log('\n  GitNexus Analyzer\n');
     // ── Resolve the target repo root ──────────────────────────────────
     // Resolved FIRST because `.gitnexusrc` is read from the repo root (not the
     // caller's cwd), and config can set defaults that the validation below

package/dist/cli/command-banner.d.ts

@@ -0,0 +1,15 @@
+/**
+ * One-line identity printed before every CLI action:
+ * `GitNexus Analyzer (1.6.10)`. Goes to stderr so stdout stays
+ * pipe/JSON-safe (`gitnexus query … | jq`, `status --json`).
+ */
+import type { Command } from 'commander';
+export declare function installedCliVersion(): string;
+export declare function commandDisplayName(name: string): string;
+export declare function commandBannerTitle(command: Command): string;
+export declare function formatCommandBanner(title: string, version?: string): string;
+export interface WriteCommandBannerDependencies {
+    write?: (text: string) => void;
+    version?: string;
+}
+export declare function writeCommandBanner(command: Command, deps?: WriteCommandBannerDependencies): void;

package/dist/cli/command-banner.js

@@ -0,0 +1,44 @@
+/**
+ * One-line identity printed before every CLI action:
+ * `GitNexus Analyzer (1.6.10)`. Goes to stderr so stdout stays
+ * pipe/JSON-safe (`gitnexus query … | jq`, `status --json`).
+ */
+import { createRequire } from 'node:module';
+const _require = createRequire(import.meta.url);
+const pkg = _require('../../package.json');
+const SKIP_COMMAND_BANNER = new Set(['__update-check', 'help']);
+const SPECIAL_TITLES = {
+    analyze: 'Analyzer',
+    mcp: 'MCP',
+};
+export function installedCliVersion() {
+    return typeof pkg.version === 'string' ? pkg.version : '';
+}
+export function commandDisplayName(name) {
+    return (SPECIAL_TITLES[name] ??
+        name
+            .split('-')
+            .filter(Boolean)
+            .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+            .join(' '));
+}
+export function commandBannerTitle(command) {
+    const names = [];
+    for (let current = command; current?.parent; current = current.parent) {
+        names.unshift(current.name());
+    }
+    return names.map(commandDisplayName).join(' ');
+}
+export function formatCommandBanner(title, version = installedCliVersion()) {
+    if (!title)
+        return '';
+    return version ? `\n  GitNexus ${title} (${version})\n` : `\n  GitNexus ${title}\n`;
+}
+export function writeCommandBanner(command, deps = {}) {
+    if (SKIP_COMMAND_BANNER.has(command.name()))
+        return;
+    const text = formatCommandBanner(commandBannerTitle(command), deps.version ?? installedCliVersion());
+    if (!text)
+        return;
+    (deps.write ?? ((line) => process.stderr.write(line)))(text);
+}

package/dist/cli/doctor.d.ts

@@ -1,5 +1,6 @@
 import { type EmbeddingRuntimeResolution } from '../core/embeddings/runtime-install.js';
 import { type NativeCheckResult } from '../core/lbug/native-check.js';
+import { type ValidatedUpdateCache } from '../core/update-cache.js';
 export declare function displayWidth(value: string): number;
 export declare function padDisplayEnd(value: string, columns: number): string;
 /**
@@ -59,4 +60,10 @@ export declare function poolSizeDoctorLine(pool: number, envRaw: string | undefi
  * stderr right below said the opposite. Render what the check actually found.
  */
 export declare function nativeStatusLine(check: NativeCheckResult): string;
+export declare function cachedUpdateDoctorLine(options: {
+    installedVersion: string;
+    eligible: boolean;
+    env: NodeJS.ProcessEnv;
+    readCache: () => ValidatedUpdateCache | null;
+}): string | null;
 export declare const doctorCommand: () => Promise<void>;

package/dist/cli/doctor.js

@@ -8,7 +8,10 @@ import { checkLbugNative, probeFtsExtensionLoad, probeVectorExtensionLoad, } fro
 import { getEffectiveBufferPoolSize, getOsPageSize, isPageSizeAwareLadybug, } from '../core/lbug/lbug-config.js';
 import { diagnoseExtensionLoad } from '../core/lbug/extension-load-error.js';
 import { getExtensionInstallPolicy } from '../core/lbug/extension-loader.js';
+import { updateEligibleInstallSync } from '../core/install-context.js';
+import { readValidatedUpdateCacheSync } from '../core/update-cache.js';
 import { t } from './i18n/index.js';
+import { cachedUpdateNoticeLine } from './update-notice.js';
 function isCombiningMark(codePoint) {
     return ((codePoint >= 0x0300 && codePoint <= 0x036f) ||
         (codePoint >= 0x1ab0 && codePoint <= 0x1aff) ||
@@ -160,6 +163,9 @@ function nativeStatusText(check) {
             return '✗ lbugjs.node missing';
     }
 }
+export function cachedUpdateDoctorLine(options) {
+    return cachedUpdateNoticeLine(options);
+}
 export const doctorCommand = async () => {
     const fingerprint = getRuntimeFingerprint();
     const capabilities = getRuntimeCapabilities();
@@ -169,6 +175,14 @@ export const doctorCommand = async () => {
     console.log(`  ${label('doctor.labels.os', 10)}${fingerprint.platform}/${fingerprint.arch}`);
     console.log(`  ${label('doctor.labels.node', 10)}${fingerprint.node}`);
     console.log(`  ${label('doctor.labels.gitnexus', 10)}${fingerprint.gitnexus}`);
+    const updateLine = cachedUpdateDoctorLine({
+        installedVersion: fingerprint.gitnexus,
+        eligible: updateEligibleInstallSync(),
+        env: process.env,
+        readCache: () => readValidatedUpdateCacheSync(),
+    });
+    if (updateLine)
+        console.log(`  ${updateLine}`);
     console.log(`  ${label('doctor.labels.ladybugdb', 10)}${fingerprint.ladybugdb ?? 'unknown'}`);
     // OS page size next to the LadybugDB version because the two interact:
     // @ladybugdb/core < 0.18.0 assumed 4 KiB pages in its buffer manager and

package/dist/cli/help-i18n.js

@@ -19,6 +19,7 @@ const COMMAND_DESCRIPTION_KEYS = {
     list: 'help.command.list.description',
     status: 'help.command.status.description',
     doctor: 'help.command.doctor.description',
+    update: 'help.command.update.description',
     embeddings: 'help.command.embeddings.description',
     'embeddings install': 'help.command.embeddings.install.description',
     clean: 'help.command.clean.description',

package/dist/cli/i18n/en.d.ts

@@ -7,6 +7,13 @@ export declare const en: {
     readonly 'common.storage': "Storage";
     readonly 'common.deleted': "Deleted: {{target}}";
     readonly 'common.error': "Error: {{message}}";
+    readonly 'update.available': "GitNexus {{latestVersion}} is available (you are running {{installedVersion}}).";
+    readonly 'update.current': "GitNexus {{installedVersion}} is current or newer than the latest stable version.";
+    readonly 'update.installing': "Installing with {{command}}…";
+    readonly 'update.installed': "Installed gitnexus@{{version}}. Restart long-running mcp/serve processes.";
+    readonly 'update.installFailed': "npm install failed. You can retry: {{command}}";
+    readonly 'update.installError': "Could not run npm: {{message}}";
+    readonly 'update.checkFailed': "Could not check for updates (offline, private registry, or the check failed open).";
     readonly 'list.title': "Indexed Repositories ({{count}})";
     readonly 'list.indexed': "Indexed";
     readonly 'list.commit': "Commit";
@@ -137,6 +144,7 @@ export declare const en: {
     readonly 'help.command.list.description': "List all indexed repositories";
     readonly 'help.command.status.description': "Show index status for current repo";
     readonly 'help.command.doctor.description': "Show runtime platform capabilities and embedding configuration";
+    readonly 'help.command.update.description': "Install the latest published GitNexus globally (`npm i -g gitnexus@<x.y.z>`).";
     readonly 'help.command.embeddings.description': "Manage the on-demand local embedding runtime";
     readonly 'help.command.embeddings.install.description': "Install the local embedding stack (@huggingface/transformers + onnxruntime-node) on demand. Heals installs where npm skipped the optional packages (e.g. behind an HTTP proxy, #2370). Downloads only from your configured npm registry — mirrors and proxies apply.";
     readonly 'help.command.clean.description': "Delete GitNexus index for current repo";

package/dist/cli/i18n/en.js

@@ -7,6 +7,13 @@ export const en = {
     'common.storage': 'Storage',
     'common.deleted': 'Deleted: {{target}}',
     'common.error': 'Error: {{message}}',
+    'update.available': 'GitNexus {{latestVersion}} is available (you are running {{installedVersion}}).',
+    'update.current': 'GitNexus {{installedVersion}} is current or newer than the latest stable version.',
+    'update.installing': 'Installing with {{command}}…',
+    'update.installed': 'Installed gitnexus@{{version}}. Restart long-running mcp/serve processes.',
+    'update.installFailed': 'npm install failed. You can retry: {{command}}',
+    'update.installError': 'Could not run npm: {{message}}',
+    'update.checkFailed': 'Could not check for updates (offline, private registry, or the check failed open).',
     'list.title': 'Indexed Repositories ({{count}})',
     'list.indexed': 'Indexed',
     'list.commit': 'Commit',
@@ -139,6 +146,7 @@ export const en = {
     'help.command.list.description': 'List all indexed repositories',
     'help.command.status.description': 'Show index status for current repo',
     'help.command.doctor.description': 'Show runtime platform capabilities and embedding configuration',
+    'help.command.update.description': 'Install the latest published GitNexus globally (`npm i -g gitnexus@<x.y.z>`).',
     'help.command.embeddings.description': 'Manage the on-demand local embedding runtime',
     'help.command.embeddings.install.description': 'Install the local embedding stack (@huggingface/transformers + onnxruntime-node) on demand. Heals installs where npm skipped the optional packages (e.g. behind an HTTP proxy, #2370). Downloads only from your configured npm registry — mirrors and proxies apply.',
     'help.command.clean.description': 'Delete GitNexus index for current repo',

package/dist/cli/i18n/resources.d.ts

@@ -8,6 +8,13 @@ export declare const cliResources: {
         readonly 'common.storage': "Storage";
         readonly 'common.deleted': "Deleted: {{target}}";
         readonly 'common.error': "Error: {{message}}";
+        readonly 'update.available': "GitNexus {{latestVersion}} is available (you are running {{installedVersion}}).";
+        readonly 'update.current': "GitNexus {{installedVersion}} is current or newer than the latest stable version.";
+        readonly 'update.installing': "Installing with {{command}}…";
+        readonly 'update.installed': "Installed gitnexus@{{version}}. Restart long-running mcp/serve processes.";
+        readonly 'update.installFailed': "npm install failed. You can retry: {{command}}";
+        readonly 'update.installError': "Could not run npm: {{message}}";
+        readonly 'update.checkFailed': "Could not check for updates (offline, private registry, or the check failed open).";
         readonly 'list.title': "Indexed Repositories ({{count}})";
         readonly 'list.indexed': "Indexed";
         readonly 'list.commit': "Commit";
@@ -138,6 +145,7 @@ export declare const cliResources: {
         readonly 'help.command.list.description': "List all indexed repositories";
         readonly 'help.command.status.description': "Show index status for current repo";
         readonly 'help.command.doctor.description': "Show runtime platform capabilities and embedding configuration";
+        readonly 'help.command.update.description': "Install the latest published GitNexus globally (`npm i -g gitnexus@<x.y.z>`).";
         readonly 'help.command.embeddings.description': "Manage the on-demand local embedding runtime";
         readonly 'help.command.embeddings.install.description': "Install the local embedding stack (@huggingface/transformers + onnxruntime-node) on demand. Heals installs where npm skipped the optional packages (e.g. behind an HTTP proxy, #2370). Downloads only from your configured npm registry — mirrors and proxies apply.";
         readonly 'help.command.clean.description': "Delete GitNexus index for current repo";
@@ -279,6 +287,13 @@ export declare const cliResources: {
         'common.storage': string;
         'common.deleted': string;
         'common.error': string;
+        'update.available': string;
+        'update.current': string;
+        'update.installing': string;
+        'update.installed': string;
+        'update.installFailed': string;
+        'update.installError': string;
+        'update.checkFailed': string;
         'list.title': string;
         'list.indexed': string;
         'list.commit': string;
@@ -409,6 +424,7 @@ export declare const cliResources: {
         'help.command.list.description': string;
         'help.command.status.description': string;
         'help.command.doctor.description': string;
+        'help.command.update.description': string;
         'help.command.embeddings.description': string;
         'help.command.embeddings.install.description': string;
         'help.command.clean.description': string;

package/dist/cli/i18n/zh-CN.d.ts

@@ -7,6 +7,13 @@ export declare const zhCN: {
     'common.storage': string;
     'common.deleted': string;
     'common.error': string;
+    'update.available': string;
+    'update.current': string;
+    'update.installing': string;
+    'update.installed': string;
+    'update.installFailed': string;
+    'update.installError': string;
+    'update.checkFailed': string;
     'list.title': string;
     'list.indexed': string;
     'list.commit': string;
@@ -137,6 +144,7 @@ export declare const zhCN: {
     'help.command.list.description': string;
     'help.command.status.description': string;
     'help.command.doctor.description': string;
+    'help.command.update.description': string;
     'help.command.embeddings.description': string;
     'help.command.embeddings.install.description': string;
     'help.command.clean.description': string;

package/dist/cli/i18n/zh-CN.js

@@ -7,6 +7,13 @@ export const zhCN = {
     'common.storage': '存储',
     'common.deleted': '已删除：{{target}}',
     'common.error': '错误：{{message}}',
+    'update.available': 'GitNexus {{latestVersion}} 已发布（当前运行 {{installedVersion}}）。',
+    'update.current': 'GitNexus {{installedVersion}} 已是最新稳定版或不低于该版本。',
+    'update.installing': '正在执行 {{command}}…',
+    'update.installed': '已安装 gitnexus@{{version}}。请重启仍在运行的 mcp/serve 进程。',
+    'update.installFailed': 'npm 安装失败。可重试：{{command}}',
+    'update.installError': '无法运行 npm：{{message}}',
+    'update.checkFailed': '无法检查更新（离线、私有仓库，或检查失败）。',
     'list.title': '已索引仓库（{{count}}）',
     'list.indexed': '索引时间',
     'list.commit': '提交',
@@ -137,6 +144,7 @@ export const zhCN = {
     'help.command.list.description': '列出所有已索引仓库',
     'help.command.status.description': '显示当前仓库的索引状态',
     'help.command.doctor.description': '显示运行平台能力和嵌入配置',
+    'help.command.update.description': '通过 npm 全局安装最新发布的 GitNexus（`npm i -g gitnexus@<x.y.z>`）。',
     'help.command.embeddings.description': '管理按需安装的本地嵌入运行时',
     'help.command.embeddings.install.description': '按需安装本地嵌入组件（@huggingface/transformers + onnxruntime-node）。修复 npm 跳过可选包的安装（例如在 HTTP 代理后，#2370）。仅从你配置的 npm registry 下载 — 镜像和代理均生效。',
     'help.command.clean.description': '删除当前仓库的 GitNexus 索引',

package/dist/cli/index.js

@@ -8,6 +8,8 @@ import { EMBEDDING_DIMS_ERROR, normalizeEmbeddingDims } from './embedding-dims.j
 import { registerGroupCommands } from './group.js';
 import { localizeCliHelp } from './help-i18n.js';
 import { t } from './i18n/index.js';
+import { writeCommandBanner } from './command-banner.js';
+import { runProcessCliUpdateNotice } from './update-notice.js';
 const _require = createRequire(import.meta.url);
 const pkg = _require('../../package.json');
 const program = new Command();
@@ -180,6 +182,10 @@ program
     .command('doctor')
     .description('Show runtime platform capabilities and embedding configuration')
     .action(createLazyAction(() => import('./doctor.js'), 'doctorCommand'));
+program
+    .command('update')
+    .description('Install the latest published GitNexus globally (`npm i -g gitnexus@<x.y.z>`).')
+    .action(createLazyAction(() => import('./update.js'), 'updateCommand'));
 program
     .command('embeddings')
     .description('Manage the on-demand local embedding runtime')
@@ -324,6 +330,14 @@ program
     .option('--host <host>', 'Bind address or resolvable hostname (default: 127.0.0.1; non-loopback requires GITNEXUS_AUTH_TOKEN; hostnames resolve to IPv4)')
     .option('--idle-timeout <seconds>', 'Auto-shutdown after N seconds idle (0 = disabled)', '0')
     .action(createLbugLazyAction(() => import('./eval-server.js'), 'evalServerCommand'));
+program.command('__update-check', { hidden: true }).action(async () => {
+    const { refresh } = await import('../core/update-check.js');
+    await refresh();
+});
 registerGroupCommands(program);
 localizeCliHelp(program);
+program.hook('preAction', (_thisCommand, actionCommand) => {
+    writeCommandBanner(actionCommand);
+});
+runProcessCliUpdateNotice(typeof pkg.version === 'string' ? pkg.version : '');
 program.parse(process.argv);

package/dist/cli/mcp.d.ts

@@ -26,9 +26,24 @@
  * `mcpCommand` after the sentinel install. The regression test at
  * `gitnexus/test/integration/mcp/import-closure.test.ts` enforces this.
  */
+import type { UpdateState } from '../core/update-check.js';
+interface McpUpdateLogger {
+    info(bindings: Record<string, unknown>, message: string): unknown;
+}
+interface McpUpdateChecker {
+    evaluate(): Promise<UpdateState | null>;
+    armUpdateRefreshScheduler(onState: (state: UpdateState | null) => void): () => void;
+}
+type LoadMcpUpdateChecker = () => Promise<McpUpdateChecker>;
+/**
+ * Start the process-scoped MCP update adapter after its transport startup
+ * boundary. All failures stay inside this best-effort side channel.
+ */
+export declare function startMcpUpdateNotifier(logger: McpUpdateLogger, loadChecker?: LoadMcpUpdateChecker): Promise<void>;
 export declare const mcpCommand: (options?: {
     http?: boolean;
     port?: string;
     host?: string;
     authToken?: string;
 }) => Promise<void>;
+export {};

package/dist/cli/mcp.js

@@ -27,6 +27,48 @@
  * `gitnexus/test/integration/mcp/import-closure.test.ts` enforces this.
  */
 import { installGlobalStdoutSentinel } from '../mcp/stdio-context.js';
+const announcedUpdateVersions = new Set();
+/**
+ * Start the process-scoped MCP update adapter after its transport startup
+ * boundary. All failures stay inside this best-effort side channel.
+ */
+export async function startMcpUpdateNotifier(logger, loadChecker = () => import('../core/update-check.js')) {
+    let checker;
+    try {
+        checker = await loadChecker();
+    }
+    catch {
+        return;
+    }
+    const announce = (state) => {
+        try {
+            if (!state?.updateAvailable ||
+                !state.latestVersion ||
+                announcedUpdateVersions.has(state.latestVersion)) {
+                return;
+            }
+            announcedUpdateVersions.add(state.latestVersion);
+            logger.info({ event: 'gitnexus.update_available', latestVersion: state.latestVersion }, 'GitNexus update available');
+        }
+        catch {
+            // Logging must never escape into MCP startup or scheduler promises.
+        }
+    };
+    try {
+        announce(await checker.evaluate());
+    }
+    catch {
+        // Cache evaluation and any detached refresh are best-effort.
+    }
+    let stop;
+    try {
+        stop = checker.armUpdateRefreshScheduler(announce);
+    }
+    catch {
+        return;
+    }
+    process.once('exit', () => stop?.());
+}
 export const mcpCommand = async (options) => {
     // Install the global stdout sentinel as the very first thing — before
     // ANY other module loads. The static-import closure above is leaf-only
@@ -94,8 +136,10 @@ export const mcpCommand = async (options) => {
             logger.error({ err: err instanceof Error ? err.message : err }, 'Failed to start the MCP HTTP server');
             process.exit(1);
         }
+        void startMcpUpdateNotifier(logger).catch(() => { });
         return;
     }
     // Start MCP server (serves all repos, discovers new ones lazily)
     await startMCPServer(backend, repositoryPolicy);
+    void startMcpUpdateNotifier(logger).catch(() => { });
 };

package/dist/cli/update-notice.d.ts

@@ -0,0 +1,34 @@
+import { type ValidatedUpdateCache } from '../core/update-cache.js';
+type SpawnResult = {
+    unref(): void;
+};
+type SpawnLike = (command: string, args: readonly string[], options: {
+    detached: true;
+    stdio: 'ignore';
+    windowsHide: true;
+}) => SpawnResult;
+export interface CliUpdateNoticeDependencies {
+    argv: string[];
+    env: NodeJS.ProcessEnv;
+    installedVersion: string;
+    isTTY: boolean | undefined;
+    eligible: boolean;
+    now: number;
+    readCache: (options: {
+        env: NodeJS.ProcessEnv;
+        now: number;
+    }) => ValidatedUpdateCache | null;
+    writeStderr: (line: string) => unknown;
+    spawn: SpawnLike;
+}
+export declare function updateNoticeText(installedVersion: string, latestVersion: string): string;
+/** Shared cache-gated notice line used by the CLI banner and `doctor`. */
+export declare function cachedUpdateNoticeLine(options: {
+    installedVersion: string;
+    eligible: boolean;
+    env: NodeJS.ProcessEnv;
+    readCache: () => ValidatedUpdateCache | null;
+}): string | null;
+export declare function runCliUpdateNotice(deps: CliUpdateNoticeDependencies): void;
+export declare function runProcessCliUpdateNotice(installedVersion: string): void;
+export {};

package/dist/cli/update-notice.js

@@ -0,0 +1,91 @@
+import { spawn as nodeSpawn } from 'node:child_process';
+import { updateEligibleInstallSync } from '../core/install-context.js';
+import { isNewerVersion, readValidatedUpdateCacheSync, updateNotifierOptedOut, updateRefreshInProgress, } from '../core/update-cache.js';
+import { t } from './i18n/index.js';
+const EXCLUDED_COMMANDS = new Set([
+    'augment',
+    'mcp',
+    'serve',
+    'eval-server',
+    'update',
+    '__update-check',
+]);
+const EXCLUDED_FLAGS = new Set(['--help', '-h', '--version', '-V']);
+function excludedInvocation(argv) {
+    const args = argv.slice(2);
+    if (args.some((arg) => EXCLUDED_FLAGS.has(arg)))
+        return true;
+    const command = args.find((arg) => !arg.startsWith('-'));
+    return command !== undefined && EXCLUDED_COMMANDS.has(command);
+}
+export function updateNoticeText(installedVersion, latestVersion) {
+    return t('update.available', { installedVersion, latestVersion });
+}
+/** Shared cache-gated notice line used by the CLI banner and `doctor`. */
+export function cachedUpdateNoticeLine(options) {
+    try {
+        if (!options.eligible || updateNotifierOptedOut(options.env))
+            return null;
+        const cache = options.readCache();
+        if (!cache?.latestVersion || !isNewerVersion(options.installedVersion, cache.latestVersion)) {
+            return null;
+        }
+        return updateNoticeText(options.installedVersion, cache.latestVersion);
+    }
+    catch {
+        return null;
+    }
+}
+export function runCliUpdateNotice(deps) {
+    try {
+        if (deps.isTTY !== true ||
+            updateNotifierOptedOut(deps.env) ||
+            !deps.eligible ||
+            excludedInvocation(deps.argv)) {
+            return;
+        }
+        const cache = deps.readCache({ env: deps.env, now: deps.now });
+        if (cache?.latestVersion && isNewerVersion(deps.installedVersion, cache.latestVersion)) {
+            deps.writeStderr(`${updateNoticeText(deps.installedVersion, cache.latestVersion)}\n`);
+        }
+        if (cache === null || cache.stale) {
+            // Coalesce parallel invocations: when a live process holds the refresh
+            // lock, its refresh covers us, so don't fork another CLI.
+            if (!updateRefreshInProgress(deps.env)) {
+                try {
+                    deps
+                        .spawn(process.execPath, [deps.argv[1] ?? '', '__update-check'], {
+                        detached: true,
+                        stdio: 'ignore',
+                        windowsHide: true,
+                    })
+                        .unref();
+                }
+                catch {
+                    // Update refresh is best-effort and must never reach Commander parsing.
+                }
+            }
+        }
+    }
+    catch {
+        // Cache reads and all adapter logic fail open.
+    }
+}
+export function runProcessCliUpdateNotice(installedVersion) {
+    if (process.stderr.isTTY !== true ||
+        updateNotifierOptedOut(process.env) ||
+        excludedInvocation(process.argv)) {
+        return;
+    }
+    runCliUpdateNotice({
+        argv: process.argv,
+        env: process.env,
+        installedVersion,
+        isTTY: process.stderr.isTTY,
+        eligible: updateEligibleInstallSync(),
+        now: Date.now(),
+        readCache: readValidatedUpdateCacheSync,
+        writeStderr: (line) => process.stderr.write(line),
+        spawn: nodeSpawn,
+    });
+}

package/dist/cli/update.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Explicit `gitnexus update`: refresh the latest dist-tag, then install
+ * `gitnexus@<version>` globally with npm — the same shape as `claude update`
+ * / `codex update`. Other commands only notify; they never spawn npm.
+ */
+import { type UpdateState } from '../core/update-check.js';
+export declare const UPDATE_PACKAGE = "gitnexus";
+export interface UpdateCommandDependencies {
+    installedVersion: string;
+    refresh: (options: {
+        eligible: true;
+        ignoreOptOut: true;
+        installedVersion: string;
+    }) => Promise<UpdateState | null>;
+    writeStdout: (line: string) => void;
+    runInstall: (version: string) => Promise<number>;
+    setExitCode: (code: number) => void;
+}
+export declare function updateInstallArgs(version: string): string[];
+export declare function updateInstallCommand(version: string): string;
+export declare function updateCommand(maybeDeps?: unknown): Promise<void>;