gitnexus 1.6.11-rc.8 → 1.6.11

package/dist/cli/index.js

@@ -2,19 +2,19 @@
 // Heap re-spawn removed — only analyze.ts needs the 8GB heap (via its own ensureHeap()).
 // Removing it from here improves MCP server startup time significantly.
 import { Command } from 'commander';
-import { createRequire } from 'node:module';
+import { packageVersion } from '../core/package-version.js';
 import { createAnalyzerLbugLazyAction, createLazyAction, createLbugLazyAction, } from './lazy-action.js';
 import { EMBEDDING_DIMS_ERROR, normalizeEmbeddingDims } from './embedding-dims.js';
 import { registerGroupCommands } from './group.js';
 import { localizeCliHelp } from './help-i18n.js';
 import { t } from './i18n/index.js';
-const _require = createRequire(import.meta.url);
-const pkg = _require('../../package.json');
+import { writeCommandBanner } from './command-banner.js';
+import { runProcessCliUpdateNotice } from './update-notice.js';
 const program = new Command();
 function collectCodingAgents(value, previous) {
     return [...(previous ?? []), ...value.split(',')];
 }
-program.name('gitnexus').description('GitNexus local CLI and MCP server').version(pkg.version);
+program.name('gitnexus').description('GitNexus local CLI and MCP server').version(packageVersion());
 program
     .command('setup')
     .description('One-time setup: configure MCP for Cursor, Claude Code, Antigravity, OpenCode, CodeBuddy, Qoder, Codex')
@@ -25,6 +25,16 @@ program
     .description('Reverse `setup`: remove GitNexus MCP entries, skills, and hooks from all detected editors')
     .option('-f, --force', 'Apply the changes (default is a dry-run preview)')
     .action(createLazyAction(() => import('./uninstall.js'), 'uninstallCommand'));
+program
+    .command('auto-sync [action]')
+    .description('Control scheduled repository clone/pull and analysis from GITNEXUS_HOME/watch_config.yml')
+    .addHelpText('after', () => t('help.autoSync.details'))
+    .action(createLazyAction(() => import('./auto-sync.js'), 'autoSyncCommand'));
+program
+    .command('watch [action]')
+    .description('Ambiguous: use `analyze --watch` for local files, or `auto-sync` for scheduled remotes')
+    .addHelpText('after', () => t('help.watch.details'))
+    .action(createLazyAction(() => import('./watch.js'), 'watchAmbiguousCommand'));
 // Baseline of GITNEXUS_EMBEDDING_DIMS captured by the analyze preAction hook
 // before it overwrites the var, so the postAction hook can restore it. The
 // analyzeCommand env snapshot is taken AFTER this hook runs, so it cannot undo
@@ -38,7 +48,8 @@ program
     .description('Index a repository (full analysis)')
     .option('--watch', 'Keep the index current with serialized incremental refreshes')
     .option('--debounce <ms>', 'Watch quiet period before refreshing (default: 300 milliseconds)')
-    .option('-f, --force', 'Force full re-index even if up to date')
+    .option('-f, --force', 'Force graph and FTS rebuild; unchanged parser output may be reused')
+    .option('--no-parse-cache', 'Re-parse every source file instead of replaying cached parser output')
     .option('--repair-fts', 'Repair/rebuild search FTS indexes without full re-analysis')
     .option('--embeddings [limit]', 'Enable embedding generation for semantic search (off by default). ' +
     'Optional [limit] overrides the 50,000-node safety cap; pass 0 to disable the cap entirely.')
@@ -46,7 +57,7 @@ program
     'preserves any embeddings already present in the index.')
     .option('--skills', 'Generate repo-specific skill files from detected communities ' +
     '(no-op when --index-only is also set).')
-    .option('--skip-agents-md', 'Skip updating the gitnexus section in AGENTS.md and CLAUDE.md')
+    .option('--skip-agents-md', 'Skip updating the gitnexus section in AGENTS.md and CLAUDE.md. Does not skip standard skills in .claude/skills or .agents/skills; use --skip-skills for those. Community skills from --skills are unaffected.')
     .option('--pdg', 'Build the control-flow-graph / PDG substrate (BasicBlock nodes + CFG edges) ' +
     'for supported languages. Opt-in; off by default. (#2081 M1)')
     .option('--default-branch <branch>', 'Default branch used in the generated regression-compare example (base_ref). ' +
@@ -73,6 +84,10 @@ program
     .option('--wal-checkpoint-threshold <bytes>', 'LadybugDB WAL auto-checkpoint threshold in bytes during analyze ' +
     '(integer >= -1; default: 67108864 = 64 MiB; -1 keeps Ladybug stock ~16 MiB).')
     .option('--workers <n>', 'Parse worker pool size (>=1). Default: cores-1 capped at 16, auto-sized to the repo.')
+    .option('--spring-actuator <path>', 'Import local Spring Boot Actuator JSON snapshots (mappings, beans, conditions, ' +
+    'configprops, env). Explicit opt-in; disabled by default.')
+    .option('--asyncapi-spec <path>', 'Read AsyncAPI 3.x documents from this directory or file and resolve broker ' +
+    'addresses from them. Explicit opt-in; disabled by default.')
     .option('--embedding-threads <n>', 'Limit local ONNX embedding CPU threads')
     .option('--embedding-batch-size <n>', 'Number of nodes per embedding batch')
     .option('--embedding-sub-batch-size <n>', 'Number of chunks per embedding model call')
@@ -149,7 +164,7 @@ program
     .option('--http', 'Serve MCP over HTTP instead of stdio (for remote clients)')
     .option('-p, --port <port>', 'HTTP port (only with --http). Default: 3000', '3000')
     .option('--host <host>', 'HTTP bind address (only with --http). Default: 127.0.0.1 (loopback). Use 0.0.0.0 to expose to all interfaces.', '127.0.0.1')
-    .option('--auth-token <token>', 'Require this bearer token in the Authorization header (only with --http); may also be set via the GITNEXUS_MCP_AUTH_TOKEN env var. Required for a non-loopback bind (--host 0.0.0.0/::), which otherwise refuses to start.')
+    .option('--auth-token <token>', "Require this bearer token in the Authorization header (only with --http); may also be set via the GITNEXUS_MCP_AUTH_TOKEN env var, which also enables MCP Bearer auth on gitnexus serve's /api/mcp route. Required for a non-loopback bind (--host 0.0.0.0/::), which otherwise refuses to start.")
     .action(createLbugLazyAction(() => import('./mcp.js'), 'mcpCommand'));
 program
     .command('list')
@@ -165,6 +180,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')
@@ -309,6 +328,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(packageVersion());
 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/optional-grammars.d.ts

@@ -7,11 +7,12 @@
  * prebuilds activated via node-gyp-build. All can be skipped via
  * GITNEXUS_SKIP_OPTIONAL_GRAMMARS=1 (postinstall scripts), or can silently
  * soft-fail when no prebuild matches the host platform (and a source build was
- * unavailable / not attempted).
+ * unavailable / not attempted). tree-sitter-zig is the one npm-installed
+ * optionalDependency in the list; its `probe` overrides the vendored load.
  *
  * Either path produces the same observable: the .node binding is absent
  * at runtime. This helper detects that condition and surfaces a single
- * stderr line per missing grammar so users learn why .dart/.proto/.swift/.kt
+ * stderr line per missing grammar so users learn why .dart/.proto/.swift/.kt/.zig
  * support is unavailable instead of silently getting a degraded index.
  */
 /**

package/dist/cli/optional-grammars.js

@@ -7,17 +7,20 @@
  * prebuilds activated via node-gyp-build. All can be skipped via
  * GITNEXUS_SKIP_OPTIONAL_GRAMMARS=1 (postinstall scripts), or can silently
  * soft-fail when no prebuild matches the host platform (and a source build was
- * unavailable / not attempted).
+ * unavailable / not attempted). tree-sitter-zig is the one npm-installed
+ * optionalDependency in the list; its `probe` overrides the vendored load.
  *
  * Either path produces the same observable: the .node binding is absent
  * at runtime. This helper detects that condition and surfaces a single
- * stderr line per missing grammar so users learn why .dart/.proto/.swift/.kt
+ * stderr line per missing grammar so users learn why .dart/.proto/.swift/.kt/.zig
  * support is unavailable instead of silently getting a degraded index.
  */
+import { createRequire } from 'node:module';
 import { SupportedLanguages } from '../_shared/index.js';
 import { isGrammarRuntimeSkipped } from '../core/tree-sitter/parser-loader.js';
 import { requireVendoredGrammar } from '../core/tree-sitter/vendored-grammars.js';
 import { cliWarn } from './cli-message.js';
+const _require = createRequire(import.meta.url);
 const OPTIONAL_GRAMMARS = [
     {
         name: 'tree-sitter-dart',
@@ -38,6 +41,14 @@ const OPTIONAL_GRAMMARS = [
         extensions: ['.kt', '.kts'],
         language: SupportedLanguages.Kotlin,
     },
+    {
+        name: 'tree-sitter-zig',
+        pkg: '@tree-sitter-grammars/tree-sitter-zig',
+        extensions: ['.zig'],
+        language: SupportedLanguages.Zig,
+        // npm optionalDependency, not vendored — probe via plain require.
+        probe: () => _require('@tree-sitter-grammars/tree-sitter-zig'),
+    },
 ];
 /**
  * The file extensions backed by an optional grammar — the single source for
@@ -73,7 +84,12 @@ export function detectMissingOptionalGrammars() {
             continue;
         }
         try {
-            requireVendoredGrammar(g.pkg);
+            if (g.probe !== undefined) {
+                g.probe();
+            }
+            else {
+                requireVendoredGrammar(g.pkg);
+            }
         }
         catch (err) {
             const code = err?.code;

package/dist/cli/setup.js

@@ -9,10 +9,10 @@ import fs from 'fs/promises';
 import path from 'path';
 import os from 'os';
 import { execFile, execFileSync } from 'child_process';
-import { createRequire } from 'module';
 import { promisify } from 'util';
 import { fileURLToPath } from 'url';
 import { parseTree, modify, applyEdits, parse as parseJsonc } from 'jsonc-parser';
+import { packageVersion } from '../core/package-version.js';
 import { getGlobalDir } from '../storage/repo-manager.js';
 import { getEditorTargets, mcpTarget, skillTarget, hookTarget, detectIndentation, isEnoent, } from './editor-targets.js';
 const __filename = fileURLToPath(import.meta.url);
@@ -26,15 +26,14 @@ const execFileAsync = promisify(execFile);
 // re-stamped every release by scripts/sync-plugin-manifests.mjs (#2445),
 // since they too execute `gitnexus@<version>` on connect. Only the READMEs
 // stay on `gitnexus@latest` — they're quickstart docs, not executed state.
-const _require = createRequire(import.meta.url);
-const _pkg = _require('../../package.json');
-if (typeof _pkg.version !== 'string' || !_pkg.version) {
+const PKG_VERSION = packageVersion();
+if (!PKG_VERSION) {
     throw new Error('gitnexus/package.json#version is missing or not a string — cannot generate MCP fallback config.');
 }
 // Version-pinned ref for the persisted MCP entry — deliberately distinct from
 // the cjs's exported `gitnexus@latest` hint ref (resolve-analyze-cmd.cjs); the
 // two are not unified (see the comment above and that file's MCP_PINNED_REF).
-const MCP_PINNED_REF = `gitnexus@${_pkg.version}`;
+const MCP_PINNED_REF = `gitnexus@${PKG_VERSION}`;
 /**
  * Build the `command` string written into an editor's hook settings, which the
  * editor shell-evaluates. `hookPath` is already forward-slash-normalized.
@@ -947,15 +946,29 @@ async function installSkillsTo(targetDir) {
     for (const [skillName, source] of skillSources) {
         const skillDir = path.join(targetDir, skillName);
         try {
-            if (source.isDirectory) {
-                const dirSource = path.join(skillsRoot, skillName);
-                await copyDirRecursive(dirSource, skillDir);
+            const sourceSkillPath = source.isDirectory
+                ? path.join(skillsRoot, skillName, 'SKILL.md')
+                : path.join(skillsRoot, `${skillName}.md`);
+            const destinationSkillPath = path.join(skillDir, 'SKILL.md');
+            const [sourceSkillContent, destinationSkillContent] = await Promise.all([
+                fs.readFile(sourceSkillPath, 'utf-8'),
+                fs.readFile(destinationSkillPath, 'utf-8').catch((err) => {
+                    if (!isEnoent(err))
+                        throw err;
+                    return null;
+                }),
+            ]);
+            const preserved = destinationSkillContent !== null && destinationSkillContent !== sourceSkillContent;
+            if (preserved && !source.isDirectory) {
+                console.log(`[gitnexus] preserved customized skill ${destinationSkillPath}; ` +
+                    'delete the file and rerun setup to refresh it.');
             }
-            else {
-                const flatSource = path.join(skillsRoot, `${skillName}.md`);
-                const content = await fs.readFile(flatSource, 'utf-8');
+            else if (source.isDirectory) {
+                await copyDirRecursive(path.join(skillsRoot, skillName), skillDir);
+            }
+            else if (!preserved) {
                 await fs.mkdir(skillDir, { recursive: true });
-                await fs.writeFile(path.join(skillDir, 'SKILL.md'), content, 'utf-8');
+                await fs.writeFile(destinationSkillPath, sourceSkillContent, 'utf-8');
             }
             // A directory superseded by a shipped rename is warned about, never
             // deleted: the installer cannot prove it owns the contents (users
@@ -968,7 +981,8 @@ async function installSkillsTo(targetDir) {
                         `left ${legacyDir} in place — delete it manually if you have not customized it.`);
                 }
             }
-            installed.push(skillName);
+            if (!preserved)
+                installed.push(skillName);
         }
         catch {
             // Source skill not found — skip
@@ -987,10 +1001,22 @@ async function copyDirRecursive(src, dest) {
         const destPath = path.join(dest, entry.name);
         if (entry.isDirectory()) {
             await copyDirRecursive(srcPath, destPath);
+            continue;
         }
-        else {
-            await fs.copyFile(srcPath, destPath);
+        const [srcBuf, destBuf] = await Promise.all([
+            fs.readFile(srcPath),
+            fs.readFile(destPath).catch((err) => {
+                if (!isEnoent(err))
+                    throw err;
+                return null;
+            }),
+        ]);
+        if (destBuf !== null && !destBuf.equals(srcBuf)) {
+            console.log(`[gitnexus] preserved customized skill ${destPath}; ` +
+                'delete the file and rerun setup to refresh it.');
+            continue;
         }
+        await fs.writeFile(destPath, srcBuf);
     }
 }
 /**

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>;

package/dist/cli/update.js

@@ -0,0 +1,93 @@
+/**
+ * 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 { spawn } from 'node:child_process';
+import { homedir } from 'node:os';
+import { composeWin32NpmCommand } from '../core/embeddings/runtime-install.js';
+import { packageVersion } from '../core/package-version.js';
+import { STRICT_UPDATE_VERSION } from '../core/update-cache.js';
+import { refresh } from '../core/update-check.js';
+import { t } from './i18n/index.js';
+export const UPDATE_PACKAGE = 'gitnexus';
+function defaultInstalledVersion() {
+    return packageVersion();
+}
+export function updateInstallArgs(version) {
+    return ['i', '-g', `${UPDATE_PACKAGE}@${version}`];
+}
+export function updateInstallCommand(version) {
+    return `npm ${updateInstallArgs(version).join(' ')}`;
+}
+function isTestDeps(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        ('refresh' in value || 'runInstall' in value || 'writeStdout' in value));
+}
+function defaultRunInstall(version) {
+    const args = updateInstallArgs(version);
+    return new Promise((resolve, reject) => {
+        const child = process.platform === 'win32'
+            ? spawn(composeWin32NpmCommand(args), {
+                cwd: homedir(),
+                windowsHide: true,
+                shell: true,
+                stdio: 'inherit',
+            })
+            : spawn('npm', args, {
+                cwd: homedir(),
+                windowsHide: true,
+                stdio: 'inherit',
+            });
+        child.on('error', reject);
+        child.on('exit', (code, signal) => {
+            resolve(signal ? 1 : (code ?? 1));
+        });
+    });
+}
+export async function updateCommand(maybeDeps) {
+    const deps = isTestDeps(maybeDeps) ? maybeDeps : {};
+    const installedVersion = deps.installedVersion ?? defaultInstalledVersion();
+    const runRefresh = deps.refresh ?? refresh;
+    const writeStdout = deps.writeStdout ?? ((line) => console.log(line));
+    const runInstall = deps.runInstall ?? defaultRunInstall;
+    const setExitCode = deps.setExitCode ??
+        ((code) => {
+            process.exitCode = code;
+        });
+    const state = await runRefresh({
+        eligible: true,
+        ignoreOptOut: true,
+        installedVersion,
+    });
+    const latestVersion = state?.latestVersion && STRICT_UPDATE_VERSION.test(state.latestVersion)
+        ? state.latestVersion
+        : undefined;
+    if (state?.updateAvailable && latestVersion) {
+        writeStdout(t('update.available', { installedVersion, latestVersion }));
+        writeStdout(t('update.installing', { command: updateInstallCommand(latestVersion) }));
+        try {
+            const code = await runInstall(latestVersion);
+            if (code !== 0) {
+                writeStdout(t('update.installFailed', { command: updateInstallCommand(latestVersion) }));
+                setExitCode(code);
+                return;
+            }
+        }
+        catch (error) {
+            writeStdout(t('update.installError', {
+                message: error instanceof Error ? error.message : String(error),
+            }));
+            setExitCode(1);
+            return;
+        }
+        writeStdout(t('update.installed', { version: latestVersion }));
+        return;
+    }
+    if (latestVersion) {
+        writeStdout(t('update.current', { installedVersion }));
+        return;
+    }
+    writeStdout(t('update.checkFailed'));
+}

package/dist/cli/watch.d.ts

@@ -1,20 +1 @@
-import { type AnalyzeOptions as CoreAnalyzeOptions } from '../core/run-analyze.js';
-import type { AnalyzerRunnerIdentity } from '../storage/repo-manager.js';
-import type { AnalyzeOptions } from './analyze-options.js';
-import { type WatchRefreshError } from './watch-queue.js';
-export type WatchCliOptions = AnalyzeOptions;
-export declare function isRelevantWatchPath(filePath: string): boolean;
-export interface WatchEnvironmentBaseline {
-    readonly maxFileSize: string | undefined;
-    readonly workerTimeout: string | undefined;
-    readonly verbose: string | undefined;
-}
-export declare function resolveWatchOptions(repoPath: string, cli: WatchCliOptions, baseline: WatchEnvironmentBaseline, reportIgnoredConfig?: (names: readonly string[]) => void): Promise<CoreAnalyzeOptions>;
-export interface WatchFileLoop {
-    readonly waitForIdle: () => Promise<void>;
-    readonly close: () => Promise<void>;
-}
-export declare function shouldStopAfterWatchRefreshFailure(error: unknown, paths: readonly string[]): boolean;
-/** Start the real filesystem watcher with bounded, serialized refreshes. */
-export declare function startWatchFileLoop(repoPath: string, debounceMs: number, refresh: (paths: readonly string[]) => Promise<void>, onError: WatchRefreshError, onWatcherError?: (error: unknown) => void): Promise<WatchFileLoop>;
-export declare function watchCommandWithRunnerIdentity(runnerIdentityAtBootstrap: AnalyzerRunnerIdentity, inputPath?: string, cliOptions?: WatchCliOptions): Promise<void>;
+export declare function watchAmbiguousCommand(_action?: string): Promise<void>;