gitnexus 1.6.11-rc.8 → 1.6.11

package/dist/cli/analyze-watch.d.ts

@@ -0,0 +1,20 @@
+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>;

package/dist/cli/analyze-watch.js

@@ -0,0 +1,434 @@
+/** Local incremental watch (`gitnexus analyze --watch`). Remote auto-sync lives in `auto-sync.ts`. */
+import path from 'node:path';
+import fs from 'node:fs/promises';
+import { watch } from 'chokidar';
+import { createWatchIgnorePredicate } from '../config/ignore-service.js';
+import { analyzeFailureMayHaveMutatedLiveIndex, runFullAnalysis, } from '../core/run-analyze.js';
+import { getGitRoot, hasGitDir } from '../storage/git.js';
+import { GITNEXUS_DIR } from '../storage/repo-meta.js';
+import { loadAnalyzeConfigStrict, mergeAnalyzeOptions, validateBranchName, } from './analyze-config.js';
+import { ensureHeap } from './analyze.js';
+import { cliError, cliInfo, cliWarn } from './cli-message.js';
+import { WATCH_FULL_REFRESH_PATH, WatchRefreshQueue, } from './watch-queue.js';
+const DEFAULT_DEBOUNCE_MS = 300;
+const MAX_TIMER_DELAY_MS = 2_147_483_647;
+const MAX_FILE_SIZE_KB = 32 * 1024;
+const TRANSIENT_WATCH_ERROR_CODES = new Set(['EACCES', 'ENOENT', 'ENOTDIR', 'EPERM']);
+function posixWatchPath(filePath) {
+    return filePath.replace(/\\/g, '/').replace(/^\.\/+/, '');
+}
+export function isRelevantWatchPath(filePath) {
+    const normalized = posixWatchPath(filePath);
+    return (normalized.length > 0 &&
+        normalized !== '.' &&
+        !normalized.startsWith('../') &&
+        !path.posix.isAbsolute(normalized) &&
+        !path.win32.isAbsolute(filePath));
+}
+function isIgnoreControlPath(filePath) {
+    const normalized = posixWatchPath(filePath);
+    return normalized === '.gitignore' || normalized === '.gitnexusignore';
+}
+function isConfigControlPath(filePath) {
+    return posixWatchPath(filePath) === '.gitnexusrc';
+}
+function isAnalyzerOwnedWatchPath(filePath) {
+    const normalized = posixWatchPath(filePath).replace(/\/+$/, '');
+    return normalized === GITNEXUS_DIR || normalized.startsWith(`${GITNEXUS_DIR}/`);
+}
+function repoRelativeWatchPath(repoPath, candidate) {
+    const relative = path.relative(repoPath, candidate).replace(/\\/g, '/');
+    if (!relative || relative.startsWith('../') || path.isAbsolute(relative))
+        return null;
+    return relative;
+}
+function setEnvironment(name, value) {
+    if (value === undefined)
+        delete process.env[name];
+    else
+        process.env[name] = value;
+}
+function positiveInteger(value, flag, maximum) {
+    if (value === undefined)
+        return undefined;
+    const parsed = Number(value);
+    if (!Number.isInteger(parsed) || parsed < 1)
+        throw new Error(`${flag} must be a positive integer`);
+    if (maximum !== undefined && parsed > maximum) {
+        throw new Error(`${flag} must not exceed ${maximum}`);
+    }
+    return parsed;
+}
+export async function resolveWatchOptions(repoPath, cli, baseline, reportIgnoredConfig = () => { }) {
+    const config = (await loadAnalyzeConfigStrict(repoPath)) ?? {};
+    const merged = mergeAnalyzeOptions(cli, config);
+    const unsupported = [
+        ['--force', cli.force],
+        ['--no-parse-cache', cli.parseCache === false],
+        ['--repair-fts', cli.repairFts],
+        ['--embeddings', cli.embeddings],
+        ['--drop-embeddings', cli.dropEmbeddings],
+        ['--skills', cli.skills],
+        ['--default-branch', cli.defaultBranch],
+        ['--skip-agents-md', cli.skipAgentsMd],
+        ['--skip-skills', cli.skipSkills],
+        ['--no-stats', cli.stats === false],
+        ['--self-commit', cli.selfCommit],
+        ['--index-only', cli.indexOnly],
+        ['--skip-git', cli.skipGit],
+        ['--spring-actuator', cli.springActuator],
+        // Rejected under --watch for the same reason as --spring-actuator: the
+        // watcher reacts to source changes, and nothing watches an out-of-band
+        // document directory. Honouring the flag here would read the documents once
+        // and then quietly serve a stale answer for the rest of the session.
+        ['--asyncapi-spec', cli.asyncapiSpec],
+        ['walCheckpointThreshold', cli.walCheckpointThreshold],
+        ['embeddingThreads', cli.embeddingThreads],
+        ['embeddingBatchSize', cli.embeddingBatchSize],
+        ['embeddingSubBatchSize', cli.embeddingSubBatchSize],
+        ['embeddingDevice', cli.embeddingDevice],
+        ['embeddingBaseUrl', cli.embeddingBaseUrl],
+        ['embeddingModel', cli.embeddingModel],
+        ['--embedding-auth-token', cli.embeddingAuthToken],
+        ['--embedding-dims', cli.embeddingDims],
+    ].filter(([, value]) => value !== undefined && value !== false);
+    if (unsupported.length > 0) {
+        throw new Error(`analyze --watch does not support ${unsupported.map(([name]) => name).join(', ')}`);
+    }
+    reportIgnoredConfig([
+        ['embeddings', config.embeddings],
+        ['dropEmbeddings', config.dropEmbeddings],
+        ['defaultBranch', config.defaultBranch],
+        ['skipAgentsMd', config.skipAgentsMd !== undefined],
+        ['skipSkills', config.skipSkills !== undefined],
+        ['stats', config.stats !== undefined],
+        ['springActuator', config.springActuator],
+        ['walCheckpointThreshold', config.walCheckpointThreshold],
+        ['embeddingThreads', config.embeddingThreads],
+        ['embeddingBatchSize', config.embeddingBatchSize],
+        ['embeddingSubBatchSize', config.embeddingSubBatchSize],
+        ['embeddingDevice', config.embeddingDevice],
+        ['embeddingBaseUrl', config.embeddingBaseUrl],
+        ['embeddingModel', config.embeddingModel],
+    ]
+        .filter(([, value]) => value !== undefined && value !== false)
+        .map(([name]) => String(name)));
+    const branch = merged.branch === undefined ? undefined : validateBranchName(merged.branch, '--branch');
+    const workerPoolSize = positiveInteger(merged.workers, '--workers');
+    const workerTimeoutSeconds = positiveInteger(merged.workerTimeout, 'workerTimeout');
+    const maxFileSize = positiveInteger(merged.maxFileSize, 'maxFileSize', MAX_FILE_SIZE_KB);
+    setEnvironment('GITNEXUS_MAX_FILE_SIZE', maxFileSize === undefined ? baseline.maxFileSize : String(maxFileSize));
+    if (workerTimeoutSeconds !== undefined) {
+        process.env.GITNEXUS_WORKER_SUB_BATCH_TIMEOUT_MS = String(workerTimeoutSeconds * 1000);
+    }
+    else {
+        setEnvironment('GITNEXUS_WORKER_SUB_BATCH_TIMEOUT_MS', baseline.workerTimeout);
+    }
+    setEnvironment('GITNEXUS_VERBOSE', merged.verbose ? '1' : baseline.verbose);
+    return {
+        pdg: merged.pdg,
+        branch,
+        registryName: merged.name,
+        allowDuplicateName: merged.allowDuplicateName,
+        workerPoolSize,
+        fetchWrappers: merged.fetchWrappers,
+        skipAgentsMd: true,
+        skipSkills: true,
+        noStats: true,
+        atomicIncremental: process.platform !== 'win32',
+    };
+}
+function refreshSummary(result, observedPaths, durationMs, lastSuccessfulRefreshAt) {
+    const measured = result.incrementalStats;
+    const changed = measured?.changedFiles ?? (result.alreadyUpToDate ? 0 : observedPaths.length);
+    const reparsed = measured?.reparsedFiles ??
+        (typeof result.pipelineResult?.reparsedFileCount === 'number'
+            ? result.pipelineResult.reparsedFileCount
+            : 0);
+    const dependents = measured?.affectedDependents ?? 0;
+    const mode = measured?.writeMode ?? (result.alreadyUpToDate ? 'no-op' : 'full');
+    return (`Refresh complete: ${changed} changed, ${reparsed} re-parsed, ` +
+        `${dependents} affected dependent(s), ${durationMs}ms, ${mode}; ` +
+        `last success ${lastSuccessfulRefreshAt}`);
+}
+async function waitUntilReady(watcher) {
+    await new Promise((resolve, reject) => {
+        const ready = () => {
+            watcher.off('error', failed);
+            resolve();
+        };
+        const failed = (error) => {
+            watcher.off('ready', ready);
+            reject(error);
+        };
+        watcher.once('ready', ready);
+        watcher.once('error', failed);
+    });
+}
+class WatchControlReloadError extends Error {
+    constructor(cause) {
+        super(cause instanceof Error ? cause.message : String(cause), { cause });
+        this.name = 'WatchControlReloadError';
+    }
+}
+export function shouldStopAfterWatchRefreshFailure(error, paths) {
+    return (paths.length > 0 &&
+        !(error instanceof WatchControlReloadError) &&
+        analyzeFailureMayHaveMutatedLiveIndex(error));
+}
+/** Start the real filesystem watcher with bounded, serialized refreshes. */
+export async function startWatchFileLoop(repoPath, debounceMs, refresh, onError, onWatcherError = (error) => onError(error, [])) {
+    let ignorePath = await createWatchIgnorePredicate(repoPath);
+    let ignoreControlValid = true;
+    let rearmPending = false;
+    let closed = false;
+    const queue = new WatchRefreshQueue(async (paths) => {
+        if (paths.some(isIgnoreControlPath) || !ignoreControlValid) {
+            const retryingInvalidControls = !ignoreControlValid;
+            try {
+                ignorePath = await createWatchIgnorePredicate(repoPath);
+                ignoreControlValid = true;
+                rearmPending = true;
+            }
+            catch (error) {
+                ignoreControlValid = false;
+                throw new WatchControlReloadError(retryingInvalidControls
+                    ? new Error('Ignore controls remain invalid; fix them before indexing more changes.', {
+                        cause: error,
+                    })
+                    : error);
+            }
+        }
+        // Re-arm before refreshing, never after: the refresh reads the whole
+        // repository, so a write that lands while the replacement watcher is
+        // arming is still picked up by this refresh, and a write that lands
+        // afterwards is reported by the armed watcher.
+        if (rearmPending)
+            await rearmWatcher();
+        await refresh(paths);
+    }, onError, debounceMs, {
+        maxWaitMs: Math.max(2_000, debounceMs * 10),
+        maxPendingPaths: 1_000,
+        holdEventsUntilInitialRefresh: true,
+        isPriorityPath: (filePath) => isIgnoreControlPath(filePath) || isConfigControlPath(filePath),
+    });
+    const createWatcher = () => {
+        const created = watch(repoPath, {
+            ignoreInitial: true,
+            atomic: true,
+            followSymlinks: false,
+            awaitWriteFinish: { stabilityThreshold: 100, pollInterval: 20 },
+            ignored: (candidate, stats) => {
+                const relative = repoRelativeWatchPath(repoPath, candidate);
+                if (relative !== null && isAnalyzerOwnedWatchPath(relative))
+                    return true;
+                if (relative !== null && (isIgnoreControlPath(relative) || isConfigControlPath(relative))) {
+                    return false;
+                }
+                return ignorePath(candidate, stats?.isDirectory() ?? false);
+            },
+        });
+        // Events from an instance being retired are kept: they overlap with the
+        // replacement's coverage and the queue coalesces the duplicates.
+        created.on('all', (event, changedPath) => {
+            if (event !== 'add' && event !== 'change' && event !== 'unlink')
+                return;
+            const relative = repoRelativeWatchPath(repoPath, changedPath);
+            if (relative && isRelevantWatchPath(relative) && !isAnalyzerOwnedWatchPath(relative)) {
+                queue.enqueue(relative);
+            }
+        });
+        created.on('error', (error) => {
+            // Replacement failures before the swap are reported through `waitUntilReady`.
+            if (created !== watcher)
+                return;
+            // Chokidar can surface a transient EPERM on Windows while an ignored
+            // analyzer-owned path is replaced. Re-arm the watcher and force one
+            // bounded catch-up refresh so a missed event cannot leave the graph
+            // stale. Other watcher errors may mean coverage was lost and stay fatal.
+            if (TRANSIENT_WATCH_ERROR_CODES.has(error.code ?? '')) {
+                rearmPending = true;
+                queue.enqueue(WATCH_FULL_REFRESH_PATH);
+                return;
+            }
+            onWatcherError(error);
+        });
+        return created;
+    };
+    let watcher = createWatcher();
+    // Chokidar emits `ready` once per instance and `add()` returns before the
+    // rescan it starts has finished, with no signal for that completion. A file
+    // an ignore-rule reload has just unignored is therefore still unregistered
+    // when `add()` returns, and because `ignoreInitial` suppresses the `add` the
+    // rescan would emit, an immediate rewrite of that file is dropped for good
+    // (reproduced on chokidar 4 and 5). So re-arm by arming a replacement
+    // watcher and awaiting its `ready` instead. The outgoing instance keeps
+    // reporting until the replacement is armed, so the swap has no blind window,
+    // and a replacement that fails to arm leaves the working instance in place.
+    const rearmWatcher = async () => {
+        rearmPending = false;
+        if (closed)
+            return;
+        const replacement = createWatcher();
+        try {
+            await waitUntilReady(replacement);
+        }
+        catch (error) {
+            rearmPending = true;
+            try {
+                await replacement.close();
+            }
+            catch {
+                // The instance never became live; the arm error is the one to report.
+            }
+            throw new WatchControlReloadError(new Error('Unable to re-arm the filesystem watcher', { cause: error }));
+        }
+        const retired = watcher;
+        watcher = replacement;
+        await retired.close();
+        // `close()` can land between arming the replacement and the swap above.
+        if (closed)
+            await replacement.close();
+    };
+    try {
+        await waitUntilReady(watcher);
+        await queue.runInitial();
+    }
+    catch (error) {
+        closed = true;
+        await watcher.close();
+        await queue.close();
+        throw error;
+    }
+    return {
+        waitForIdle: () => queue.waitForIdle(),
+        close: async () => {
+            closed = true;
+            await watcher.close();
+            await queue.close();
+        },
+    };
+}
+export async function watchCommandWithRunnerIdentity(runnerIdentityAtBootstrap, inputPath, cliOptions = {}) {
+    if (await ensureHeap({ cleanForwardedTermination: true }))
+        return;
+    const requestedRepoPath = inputPath ? path.resolve(inputPath) : getGitRoot(process.cwd());
+    if (requestedRepoPath === null || !hasGitDir(requestedRepoPath)) {
+        cliError('  gitnexus analyze --watch requires a Git repository.');
+        process.exitCode = 1;
+        return;
+    }
+    const repoPath = await fs.realpath(requestedRepoPath);
+    const baselineEnvironment = {
+        maxFileSize: process.env.GITNEXUS_MAX_FILE_SIZE,
+        workerTimeout: process.env.GITNEXUS_WORKER_SUB_BATCH_TIMEOUT_MS,
+        verbose: process.env.GITNEXUS_VERBOSE,
+    };
+    try {
+        let ignoredConfigSignature;
+        const reportIgnoredConfig = (names) => {
+            const signature = [...names].sort().join(',');
+            if (signature === ignoredConfigSignature)
+                return;
+            ignoredConfigSignature = signature;
+            if (names.length > 0) {
+                cliWarn(`Watch mode ignores unsupported .gitnexusrc settings: ${names.join(', ')}.`);
+            }
+        };
+        let debounceMs;
+        let analyzeOptions;
+        try {
+            debounceMs =
+                positiveInteger(cliOptions.debounce ?? String(DEFAULT_DEBOUNCE_MS), '--debounce', MAX_TIMER_DELAY_MS) ?? DEFAULT_DEBOUNCE_MS;
+            analyzeOptions = await resolveWatchOptions(repoPath, cliOptions, baselineEnvironment, reportIgnoredConfig);
+        }
+        catch (error) {
+            cliError(`  ${error instanceof Error ? error.message : String(error)}`);
+            process.exitCode = 1;
+            return;
+        }
+        let stopWatching;
+        const stopped = new Promise((resolve) => {
+            stopWatching = resolve;
+        });
+        const stop = () => stopWatching();
+        process.once('SIGINT', stop);
+        process.once('SIGTERM', stop);
+        try {
+            let loop;
+            let fatalRefreshError;
+            let configControlValid = true;
+            let lastSuccessfulRefreshAt;
+            try {
+                loop = await startWatchFileLoop(repoPath, debounceMs, async (paths) => {
+                    if (paths.some(isConfigControlPath) || !configControlValid) {
+                        const retryingInvalidConfig = !configControlValid;
+                        try {
+                            analyzeOptions = await resolveWatchOptions(repoPath, cliOptions, baselineEnvironment, reportIgnoredConfig);
+                            configControlValid = true;
+                        }
+                        catch (error) {
+                            configControlValid = false;
+                            throw new WatchControlReloadError(retryingInvalidConfig
+                                ? new Error('Configuration remains invalid; fix it before indexing more changes.', {
+                                    cause: error,
+                                })
+                                : error);
+                        }
+                    }
+                    const startedAt = Date.now();
+                    const result = await runFullAnalysis(repoPath, analyzeOptions, {
+                        onProgress: () => { },
+                        onLog: process.env.GITNEXUS_VERBOSE === '1'
+                            ? (message) => cliInfo(`  ${message}`)
+                            : undefined,
+                    }, runnerIdentityAtBootstrap);
+                    lastSuccessfulRefreshAt = new Date().toISOString();
+                    if (paths.length === 0) {
+                        cliInfo(result.alreadyUpToDate
+                            ? `Watching ${repoPath}; index is up to date.`
+                            : `Watching ${repoPath}; initial index ready in ${Date.now() - startedAt}ms.`);
+                    }
+                    else {
+                        cliInfo(refreshSummary(result, paths, Date.now() - startedAt, lastSuccessfulRefreshAt));
+                    }
+                }, (error, paths) => {
+                    const detail = paths.length > 0 ? ` (${paths.length} queued path(s))` : '';
+                    if (shouldStopAfterWatchRefreshFailure(error, paths)) {
+                        fatalRefreshError = error;
+                        cliError(`Refresh failed${detail}: ${error instanceof Error ? error.message : String(error)}. ` +
+                            'Watch mode is stopping because the live index may have been updated in place.');
+                        stopWatching();
+                        return;
+                    }
+                    const lastSuccess = lastSuccessfulRefreshAt ?? 'none yet';
+                    cliWarn(`Refresh failed${detail}: ${error instanceof Error ? error.message : String(error)}. ` +
+                        `Retry scheduled; last success ${lastSuccess}.`);
+                }, (error) => {
+                    fatalRefreshError = error;
+                    cliError(`Watcher failed: ${error instanceof Error ? error.message : String(error)}. ` +
+                        'Watch mode is stopping.');
+                    stopWatching();
+                });
+            }
+            catch (error) {
+                cliError(`  Unable to start watcher: ${error instanceof Error ? error.message : String(error)}`);
+                process.exitCode = 1;
+                return;
+            }
+            await stopped;
+            await loop.close();
+            if (fatalRefreshError !== undefined)
+                process.exitCode = 1;
+        }
+        finally {
+            process.removeListener('SIGINT', stop);
+            process.removeListener('SIGTERM', stop);
+        }
+    }
+    finally {
+        setEnvironment('GITNEXUS_MAX_FILE_SIZE', baselineEnvironment.maxFileSize);
+        setEnvironment('GITNEXUS_WORKER_SUB_BATCH_TIMEOUT_MS', baselineEnvironment.workerTimeout);
+        setEnvironment('GITNEXUS_VERBOSE', baselineEnvironment.verbose);
+    }
+}

package/dist/cli/analyze.js

@@ -524,6 +524,8 @@ const ANALYZE_CLI_ENV_KEYS = [
     'GITNEXUS_EMBEDDING_SUB_BATCH_SIZE',
     'GITNEXUS_EMBEDDING_DEVICE',
     'GITNEXUS_ANALYZE_PROGRESS_ACTIVE',
+    'GITNEXUS_ANALYZER_IDENTITY_IN_PROCESS_GUARDS',
+    'GITNEXUS_RESOLVE_DEF_GRAPH_ID_MEMO',
     'GITNEXUS_EMBEDDING_URL',
     'GITNEXUS_EMBEDDING_MODEL',
     'GITNEXUS_EMBEDDING_API_KEY',
@@ -600,14 +602,13 @@ export const analyzeCommand = async (inputPath, options, runnerIdentityAtBootstr
 export const analyzeCommandWithRunnerIdentity = async (runnerIdentityAtBootstrap, inputPath, options) => analyzeCommand(inputPath, options, runnerIdentityAtBootstrap);
 export async function analyzeOrWatchCommandWithRunnerIdentity(runnerIdentityAtBootstrap, inputPath, options = {}) {
     if (options.watch) {
-        const { watchCommandWithRunnerIdentity } = await import('./watch.js');
+        const { watchCommandWithRunnerIdentity } = await import('./analyze-watch.js');
         await watchCommandWithRunnerIdentity(runnerIdentityAtBootstrap, inputPath, options);
         return;
     }
     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
@@ -784,6 +785,16 @@ const analyzeCommandImpl = async (inputPath, cliOptions, runnerIdentityAtBootstr
         !setPositiveEnv('--embedding-sub-batch-size', 'GITNEXUS_EMBEDDING_SUB_BATCH_SIZE', options.embeddingSubBatchSize)) {
         return;
     }
+    // An empty value resolves to the repository root, so `--asyncapi-spec ""`
+    // walks the whole tree — defeating the module's own rule that there is no
+    // glob-based auto-discovery, and spending the walk budget on `node_modules`.
+    // The HTTP entry point already rejects exactly this value; two doors onto one
+    // option must not hold different rules.
+    if (options.asyncapiSpec !== undefined && options.asyncapiSpec.trim() === '') {
+        cliError('  --asyncapi-spec must be a non-empty path.\n');
+        process.exitCode = 1;
+        return;
+    }
     if (options.embeddingDevice) {
         const allowed = new Set(['auto', 'cpu', 'dml', 'cuda', 'wasm']);
         if (!allowed.has(options.embeddingDevice)) {
@@ -928,9 +939,9 @@ const analyzeCommandImpl = async (inputPath, cliOptions, runnerIdentityAtBootstr
             }
         }
     }
-    if (options.repairFts && options.force) {
-        cliError('  Cannot combine `--repair-fts` with `--force`. ' +
-            'Use `--repair-fts` for fast FTS-only repair, or `--force` for a full rebuild.\n');
+    if (options.repairFts && (options.force || options.parseCache === false)) {
+        cliError('  Cannot combine `--repair-fts` with a full rebuild. ' +
+            'Use `--repair-fts` alone for fast FTS-only repair.\n');
         process.exitCode = 1;
         return;
     }
@@ -1072,10 +1083,11 @@ const analyzeCommandImpl = async (inputPath, cliOptions, runnerIdentityAtBootstr
         const skipAgentsMd = skipAll || options.skipAgentsMd;
         const skipSkills = skipAll || options.skipSkills;
         const runOptions = {
-            // Pipeline re-index — OR'd with --skills because skill generation
-            // needs a fresh pipelineResult. Has no bearing on the registry
-            // collision guard (see allowDuplicateName below).
-            force: options.force || options.skills,
+            // Pipeline re-index — OR'd with --skills because skill generation needs
+            // a fresh pipelineResult, and with --no-parse-cache because bypassing
+            // parser output is meaningful only when the pipeline runs.
+            force: options.force || options.skills || options.parseCache === false,
+            useParseCache: options.parseCache !== false,
             repairFts: options.repairFts,
             embeddings: embeddingsEnabled,
             embeddingsNodeLimit,
@@ -1112,6 +1124,8 @@ const analyzeCommandImpl = async (inputPath, cliOptions, runnerIdentityAtBootstr
             // Extra fetch-wrapper names from `.gitnexusrc` (#1589/#1852 residual);
             // forwarded to the routes phase consumer scan.
             fetchWrappers: options.fetchWrappers,
+            springActuatorPath: options.springActuator,
+            asyncApiSpecPath: options.asyncapiSpec,
             // The CLI always process.exit()s after this returns (success path at the
             // end of analyzeCommandImpl, error/interrupt paths via process.exit too),
             // so the finalize close skips the native conn/db close — it can double-free
@@ -1173,6 +1187,9 @@ const analyzeCommandImpl = async (inputPath, cliOptions, runnerIdentityAtBootstr
             console.error = origError;
             bar.stop();
             console.log('  Already up to date\n');
+            if (runOptions.registryName) {
+                console.log(`  Registry name: ${result.repoName}\n`);
+            }
             if (baseRefRefreshed.length > 0) {
                 console.log(`  Updated base_ref to "${resolvedDefaultBranch}" in ${baseRefRefreshed.join(', ')}\n`);
             }
@@ -1247,6 +1264,7 @@ const analyzeCommandImpl = async (inputPath, cliOptions, runnerIdentityAtBootstr
                         // exercised on the `--skills` path by analyze-no-stats-bridge.test.ts.
                         noStats: options.stats === false,
                         hasPdg: options.pdg === true,
+                        hasSpringActuator: options.springActuator !== undefined,
                     });
                 }
             }

package/dist/cli/auto-sync.d.ts

@@ -0,0 +1 @@
+export declare function autoSyncCommand(action?: string): Promise<void>;

package/dist/cli/auto-sync.js

@@ -0,0 +1,107 @@
+/** Remote auto-sync CLI (`gitnexus auto-sync`). Local incremental watch lives in `analyze-watch.ts`. */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { getAutoSyncConfigPath, getAutoSyncMutexPath, readAutoSyncWatchStatus, resetAutoSyncState, startAutoSyncWatch, stopAutoSyncWatch, } from '../core/auto-sync/index.js';
+export async function autoSyncCommand(action = 'start') {
+    if (action === 'init') {
+        await initWatchConfig();
+        return;
+    }
+    if (action === 'reset') {
+        if (!(await resetAutoSyncState())) {
+            process.stderr.write(`[auto-sync] Cannot reset analysis state while the watch mutex is held. Confirm no watch process is running, then remove ${getAutoSyncMutexPath()}.\n`);
+            process.exitCode = 1;
+            return;
+        }
+        process.stdout.write('[auto-sync] Reset analysis state.\n');
+        return;
+    }
+    if (action === 'status') {
+        printStatus(await readAutoSyncWatchStatus());
+        return;
+    }
+    if (action === 'stop') {
+        if ((await stopAutoSyncWatch()) !== 'stopped')
+            process.exitCode = 1;
+        return;
+    }
+    if (action === 'restart') {
+        const result = await stopAutoSyncWatch();
+        if (result === 'refused' || result === 'timeout') {
+            process.exitCode = 1;
+            return;
+        }
+        await startWatchProcess();
+        return;
+    }
+    if (action !== 'start') {
+        process.stderr.write(`[auto-sync] Unknown auto-sync action: ${action}\n`);
+        process.exitCode = 1;
+        return;
+    }
+    await startWatchProcess();
+}
+async function startWatchProcess() {
+    const handle = await startAutoSyncWatch();
+    if (!handle) {
+        process.exitCode = 1;
+        return;
+    }
+    const stop = () => {
+        void handle.stop().then(() => {
+            process.stderr.write('[auto-sync] Watch stopped.\n');
+            process.exit(0);
+        }, (error) => {
+            const message = error instanceof Error ? error.message : String(error);
+            process.stderr.write(`[auto-sync] Failed to stop watch: ${message}\n`);
+            process.exit(1);
+        });
+    };
+    process.once('SIGINT', stop);
+    process.once('SIGTERM', stop);
+}
+function printStatus(status) {
+    const parts = [`state=${status.state}`];
+    if (status.pid)
+        parts.push(`pid=${status.pid}`);
+    if (status.configPath)
+        parts.push(`config=${status.configPath}`);
+    if (status.message)
+        parts.push(`message=${status.message}`);
+    parts.push(`updated_at=${status.updatedAt}`);
+    process.stdout.write(`${parts.join(' ')}\n`);
+}
+async function initWatchConfig() {
+    const configPath = getAutoSyncConfigPath();
+    try {
+        await fs.mkdir(path.dirname(configPath), { recursive: true });
+        await fs.writeFile(configPath, defaultSyncConfig(path.resolve(path.dirname(configPath), 'repos')), {
+            flag: 'wx',
+        });
+    }
+    catch (err) {
+        if (err.code === 'EEXIST') {
+            process.stderr.write(`[auto-sync] Config already exists: ${configPath}\n`);
+            process.exitCode = 1;
+            return;
+        }
+        throw err;
+    }
+    process.stdout.write(`[auto-sync] Created ${configPath}\n`);
+}
+function defaultSyncConfig(localPath) {
+    return [
+        'sync_interval_minutes: 10',
+        'max_concurrency: 1',
+        'repo_git_timeout: 10s',
+        'analyze_timeout: 5m',
+        'analyze_failure_threshold: 3',
+        'projects:',
+        `  - local_path: ${localPath}`,
+        '    branches: [master, main]',
+        '    overwrite_local_changes: false',
+        '    remote_urls:',
+        '      - git@github.com:owner/repo.git',
+        '',
+    ].join('\n');
+}

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;