gitnexus 1.6.6-rc.5 → 1.6.6-rc.7

package/dist/cli/index.js

@@ -108,6 +108,7 @@ program
     .option('--gist', 'Publish wiki as a public GitHub Gist after generation')
     .option('-v, --verbose', 'Enable verbose output (show LLM commands and responses)')
     .option('--review', 'Stop after grouping to review module structure before generating pages')
+    .option('--lang <lang>', 'Output language for generated documentation (e.g. english, chinese, spanish, japanese)')
     .action(createLazyAction(() => import('./wiki.js'), 'wikiCommand'));
 program
     .command('augment <pattern>')

package/dist/cli/wiki.d.ts

@@ -19,5 +19,6 @@ export interface WikiCommandOptions {
     review?: boolean;
     timeout?: string;
     retries?: string;
+    lang?: string;
 }
 export declare const wikiCommand: (inputPath?: string, options?: WikiCommandOptions) => Promise<void>;

package/dist/cli/wiki.js

@@ -364,6 +364,7 @@ export const wikiCommand = async (inputPath, options) => {
         force: options?.force,
         concurrency: options?.concurrency ? parseInt(options.concurrency, 10) : undefined,
         reviewOnly: options?.review,
+        lang: options?.lang,
     };
     const generator = new WikiGenerator(repoPath, storagePath, lbugPath, llmConfig, wikiOptions, (phase, percent, detail) => {
         const label = detail || phase;

package/dist/core/wiki/generator.d.ts

@@ -16,11 +16,14 @@ export interface WikiOptions {
     concurrency?: number;
     /** If true, stop after building module tree for user review */
     reviewOnly?: boolean;
+    /** Output language for generated documentation (e.g. 'english', 'chinese', 'spanish') */
+    lang?: string;
 }
 export interface WikiMeta {
     fromCommit: string;
     generatedAt: string;
     model: string;
+    lang: string;
     moduleFiles: Record<string, string[]>;
     moduleTree: ModuleTreeNode[];
 }
@@ -62,6 +65,16 @@ export declare class WikiGenerator {
      * Also touches the DB connection periodically to prevent idle timeout.
      */
     private streamOpts;
+    /**
+     * Return the effective lang string: strip control characters, trim, cap at 50 chars,
+     * then validate against a character allowlist. Returns '' if the value is absent or invalid.
+     * Used for both prompt construction and meta storage/comparison so they are always in sync.
+     */
+    private effectiveLang;
+    /**
+     * Append an output-language instruction to a system prompt when --lang is set.
+     */
+    private buildSystemPrompt;
     /**
      * Route LLM call to the appropriate provider (OpenAI-compatible or Cursor CLI).
      */

package/dist/core/wiki/generator.js

@@ -89,6 +89,27 @@ export class WikiGenerator {
             },
         };
     }
+    /**
+     * Return the effective lang string: strip control characters, trim, cap at 50 chars,
+     * then validate against a character allowlist. Returns '' if the value is absent or invalid.
+     * Used for both prompt construction and meta storage/comparison so they are always in sync.
+     */
+    effectiveLang() {
+        const lang = (this.options.lang ?? '')
+            .replace(/[\x00-\x1F\x7F]/g, '')
+            .trim()
+            .slice(0, 50);
+        return /^[a-zA-Z -]+$/.test(lang) ? lang : '';
+    }
+    /**
+     * Append an output-language instruction to a system prompt when --lang is set.
+     */
+    buildSystemPrompt(base) {
+        const lang = this.effectiveLang();
+        if (!lang)
+            return base;
+        return `${base}\n\nIMPORTANT: Write ALL documentation content in ${lang}. This includes prose, code comments in examples, and diagram labels. Note: page titles (H1 headings) are generated separately and will remain in English.`;
+    }
     /**
      * Route LLM call to the appropriate provider (OpenAI-compatible or Cursor CLI).
      */
@@ -112,6 +133,13 @@ export class WikiGenerator {
         const forceMode = this.options.force;
         // Up-to-date check (skip if --force)
         if (!forceMode && existingMeta && existingMeta.fromCommit === currentCommit) {
+            const currentLang = this.effectiveLang();
+            const metaLang = existingMeta.lang ?? '';
+            if (currentLang !== metaLang) {
+                const prevDisplay = metaLang || 'english (default)';
+                const nextDisplay = currentLang || 'english (default)';
+                throw new Error(`Wiki was generated in ${prevDisplay}; use --force to regenerate in ${nextDisplay}.`);
+            }
             // Still regenerate the HTML viewer in case it's missing
             await this.ensureHTMLViewer();
             return { pagesGenerated: 0, mode: 'up-to-date', failedModules: [] };
@@ -139,6 +167,13 @@ export class WikiGenerator {
         let result;
         try {
             if (!forceMode && existingMeta && existingMeta.fromCommit) {
+                const currentLang = this.effectiveLang();
+                const metaLang = existingMeta.lang ?? '';
+                if (currentLang !== metaLang) {
+                    const prevDisplay = metaLang || 'english (default)';
+                    const nextDisplay = currentLang || 'english (default)';
+                    throw new Error(`Wiki was generated in ${prevDisplay}; use --force to regenerate in ${nextDisplay}.`);
+                }
                 result = await this.incrementalUpdate(existingMeta, currentCommit);
             }
             else {
@@ -257,6 +292,7 @@ export class WikiGenerator {
             fromCommit: currentCommit,
             generatedAt: new Date().toISOString(),
             model: this.llmConfig.model,
+            lang: this.effectiveLang(),
             moduleFiles,
             moduleTree,
         });
@@ -298,6 +334,9 @@ export class WikiGenerator {
             FILE_LIST: fileList,
             DIRECTORY_TREE: dirTree,
         });
+        // Grouping is a structured-data phase (JSON output), not documentation.
+        // Do NOT apply buildSystemPrompt here — a language instruction would risk
+        // translating module-name keys, breaking slug stability and JSON parsing.
         const response = await this.invokeLLM(prompt, GROUPING_SYSTEM_PROMPT, this.streamOpts('Grouping files', 15, 13));
         const grouping = this.parseGroupingResponse(response.content, files);
         // Convert to tree nodes
@@ -444,8 +483,8 @@ export class WikiGenerator {
             INCOMING_CALLS: formatCallEdges(interCalls.incoming),
             PROCESSES: formatProcesses(processes),
         });
-        const response = await this.invokeLLM(prompt, MODULE_SYSTEM_PROMPT, this.streamOpts(node.name));
-        // Write page with front matter
+        const response = await this.invokeLLM(prompt, this.buildSystemPrompt(MODULE_SYSTEM_PROMPT), this.streamOpts(node.name));
+        // H1 uses the English module name (stable slug source); body is LLM-translated.
         const pageContent = sanitizeMermaidMarkdown(`# ${node.name}\n\n${response.content}`);
         await fs.writeFile(path.join(this.wikiDir, `${node.slug}.md`), pageContent, 'utf-8');
     }
@@ -480,7 +519,7 @@ export class WikiGenerator {
             CROSS_MODULE_CALLS: formatCallEdges(crossCalls),
             CROSS_PROCESSES: formatProcesses(processes),
         });
-        const response = await this.invokeLLM(prompt, PARENT_SYSTEM_PROMPT, this.streamOpts(node.name));
+        const response = await this.invokeLLM(prompt, this.buildSystemPrompt(PARENT_SYSTEM_PROMPT), this.streamOpts(node.name));
         const pageContent = sanitizeMermaidMarkdown(`# ${node.name}\n\n${response.content}`);
         await fs.writeFile(path.join(this.wikiDir, `${node.slug}.md`), pageContent, 'utf-8');
     }
@@ -516,7 +555,7 @@ export class WikiGenerator {
             MODULE_EDGES: edgesText,
             TOP_PROCESSES: formatProcesses(topProcesses),
         });
-        const response = await this.invokeLLM(prompt, OVERVIEW_SYSTEM_PROMPT, this.streamOpts('Generating overview', 88));
+        const response = await this.invokeLLM(prompt, this.buildSystemPrompt(OVERVIEW_SYSTEM_PROMPT), this.streamOpts('Generating overview', 88));
         const pageContent = sanitizeMermaidMarkdown(`# ${path.basename(this.repoPath)} — Wiki\n\n${response.content}`);
         await fs.writeFile(path.join(this.wikiDir, 'overview.md'), pageContent, 'utf-8');
     }
@@ -538,6 +577,7 @@ export class WikiGenerator {
                 ...existingMeta,
                 fromCommit: currentCommit,
                 generatedAt: new Date().toISOString(),
+                lang: this.effectiveLang(),
             });
             return { pagesGenerated: 0, mode: 'incremental', failedModules: [] };
         }
@@ -627,6 +667,7 @@ export class WikiGenerator {
             fromCommit: currentCommit,
             generatedAt: new Date().toISOString(),
             model: this.llmConfig.model,
+            lang: this.effectiveLang(),
         });
         this.onProgress('done', 100, 'Incremental update complete');
         return { pagesGenerated, mode: 'incremental', failedModules: [...this.failedModules] };

package/dist/mcp/local/local-backend.d.ts

@@ -59,6 +59,22 @@ interface RepoHandle {
     remoteUrl?: string;
     stats?: RegistryEntry['stats'];
 }
+/**
+ * Resolve the git diff cwd for detect_changes, auto-detecting linked worktrees.
+ *
+ * When `launchCwd` is a linked worktree of the same canonical repository as
+ * `repoPath` (i.e. `getGitRoot(launchCwd)` differs from `repoPath` but both
+ * share the same `getCanonicalRepoRoot`), returns the worktree's git root so
+ * that `git diff` sees the correct working directory and index.
+ *
+ * Returns `repoPath` unchanged in all other cases (non-worktree, git
+ * unavailable, unrelated repo).
+ *
+ * Extracted as a module-level export so tests can pass any `launchCwd` instead
+ * of relying on `process.cwd()`, which is fixed to the server launch directory
+ * and cannot be changed mid-process.
+ */
+export declare function resolveWorktreeCwd(repoPath: string, launchCwd: string): string;
 export declare class LocalBackend {
     private repos;
     private contextCache;

package/dist/mcp/local/local-backend.js

@@ -14,7 +14,8 @@ export { isWriteQuery };
 // at MCP server startup — crashes on unsupported Node ABI versions (#89)
 // git utilities available if needed
 // import { isGitRepo, getCurrentCommit, getGitRoot } from '../../storage/git.js';
-import { parseDiffHunks } from '../../storage/git.js';
+import { parseDiffHunks, getCanonicalRepoRoot, getGitRoot, } from '../../storage/git.js';
+import { realpathSync } from 'fs';
 import { listRegisteredRepos, cleanupOldKuzuFiles, } from '../../storage/repo-manager.js';
 import { GroupService } from '../../core/group/service.js';
 import { resolveAtGroupMemberRepoPath } from '../../core/group/resolve-at-member.js';
@@ -160,6 +161,55 @@ function logQueryTiming(query, phases) {
     const truncated = query.length > 80 ? `${query.slice(0, 80)}…` : query;
     logger.debug({ query: truncated, totalMs, phases }, 'GitNexus query timing');
 }
+/** Resolve symlinks for path comparison; falls back to path.resolve on error.
+ * Uses `realpathSync.native` (not the pure-JS `realpathSync`) so that Windows
+ * 8.3 short names (e.g. RUNNER~1 → runneradmin) are expanded to long form,
+ * matching the output of `git rev-parse --show-toplevel`. */
+function tryRealpath(p) {
+    try {
+        return realpathSync.native(p);
+    }
+    catch {
+        return path.resolve(p);
+    }
+}
+/**
+ * Resolve the git diff cwd for detect_changes, auto-detecting linked worktrees.
+ *
+ * When `launchCwd` is a linked worktree of the same canonical repository as
+ * `repoPath` (i.e. `getGitRoot(launchCwd)` differs from `repoPath` but both
+ * share the same `getCanonicalRepoRoot`), returns the worktree's git root so
+ * that `git diff` sees the correct working directory and index.
+ *
+ * Returns `repoPath` unchanged in all other cases (non-worktree, git
+ * unavailable, unrelated repo).
+ *
+ * Extracted as a module-level export so tests can pass any `launchCwd` instead
+ * of relying on `process.cwd()`, which is fixed to the server launch directory
+ * and cannot be changed mid-process.
+ */
+export function resolveWorktreeCwd(repoPath, launchCwd) {
+    try {
+        const launchGitRoot = getGitRoot(launchCwd);
+        if (launchGitRoot) {
+            // Normalise via realpathSync before comparing so macOS /var → /private/var
+            // symlinks (and Windows 8.3 short names) don't create false mismatches.
+            const realLaunch = tryRealpath(launchGitRoot);
+            const realRepo = tryRealpath(repoPath);
+            if (realLaunch !== realRepo) {
+                const launchCanonical = getCanonicalRepoRoot(launchCwd);
+                const repoCanonical = getCanonicalRepoRoot(repoPath);
+                if (launchCanonical && repoCanonical && launchCanonical === repoCanonical) {
+                    return launchGitRoot;
+                }
+            }
+        }
+    }
+    catch {
+        // Best-effort; fall through to repoPath.
+    }
+    return repoPath;
+}
 export class LocalBackend {
     repos = new Map();
     contextCache = new Map();
@@ -1770,11 +1820,50 @@ export class LocalBackend {
         }
         let diffOutput;
         try {
+            // Resolve the cwd for git diff.
+            //
+            // In a linked worktree (e.g. /repo/wt-feature/), the user's staged and
+            // unstaged changes live in that worktree's separate working directory and
+            // index. Running `git diff` from the canonical repo root sees a different
+            // working tree and returns empty output.
+            //
+            // Resolution order (see resolveWorktreeCwd for details):
+            //   1. params.worktree — explicit override, validated against the
+            //      registered repo's canonical root.
+            //   2. Auto-detect — if the server's launch cwd (process.cwd()) is a
+            //      linked worktree of the same canonical repo, use its git root.
+            //   3. repo.repoPath — fallback (original behaviour, handled inside
+            //      resolveWorktreeCwd when no worktree is detected).
+            //
+            // Start with the auto-detected value; override with the validated
+            // explicit param when provided. This avoids a dead initial assignment.
+            let diffCwd = resolveWorktreeCwd(repo.repoPath, process.cwd());
+            if (params.worktree) {
+                if (!path.isAbsolute(params.worktree)) {
+                    return {
+                        error: `worktree must be an absolute path, got: "${params.worktree}"`,
+                    };
+                }
+                const providedResolved = path.resolve(params.worktree);
+                const repoCanonical = getCanonicalRepoRoot(repo.repoPath);
+                if (!repoCanonical) {
+                    return {
+                        error: `Could not determine canonical root for repo "${repo.repoPath}". Is git available?`,
+                    };
+                }
+                const worktreeCanonical = getCanonicalRepoRoot(providedResolved);
+                if (!worktreeCanonical || tryRealpath(worktreeCanonical) !== tryRealpath(repoCanonical)) {
+                    return {
+                        error: `worktree "${params.worktree}" is not a worktree of repo "${repo.repoPath}". Ensure the path is inside the same git repository.`,
+                    };
+                }
+                diffCwd = providedResolved;
+            }
             // maxBuffer raised from Node's 1MB default to 256MB to avoid ENOBUFS on
             // repos with large unstaged/untracked diffs (e.g. unignored build folders).
             // See issue: spawnSync git ENOBUFS in detect_changes(scope="unstaged").
             diffOutput = execFileSync('git', diffArgs, {
-                cwd: repo.repoPath,
+                cwd: diffCwd,
                 encoding: 'utf-8',
                 maxBuffer: 256 * 1024 * 1024,
             });

package/dist/mcp/tools.js

@@ -218,6 +218,8 @@ Maps git diff hunks to indexed symbols, then traces which processes are impacted
 WHEN TO USE: Before committing — to understand what your changes affect. Pre-commit review, PR preparation.
 AFTER THIS: Review affected processes. Use context() on high-risk symbols. READ gitnexus://repo/{name}/process/{name} for full traces.
 
+GIT WORKTREE SUPPORT: GitNexus automatically detects when the MCP server was launched from inside a linked git worktree and runs git diff against that worktree — no extra parameters needed in the common case. Pass "worktree" explicitly only when the server was started from a different directory than the worktree you are editing (e.g., the server runs from the canonical root but your changes are in a linked worktree at a different path).
+
 Returns: changed symbols, affected processes, and a risk summary.`,
         annotations: READ_ONLY_TOOL_ANNOTATIONS,
         inputSchema: {
@@ -233,6 +235,10 @@ Returns: changed symbols, affected processes, and a risk summary.`,
                     type: 'string',
                     description: 'Branch/commit for "compare" scope (e.g., "main")',
                 },
+                worktree: {
+                    type: 'string',
+                    description: 'Absolute path to a linked git worktree. Pass this when your changes are in a worktree (the .git entry at that path is a file, not a directory). GitNexus will run git diff from that worktree so staged/unstaged changes are correctly detected.',
+                },
                 repo: {
                     type: 'string',
                     description: 'Repository name or path. Omit if only one repo is indexed.',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gitnexus",
-  "version": "1.6.6-rc.5",
+  "version": "1.6.6-rc.7",
   "description": "Graph-powered code intelligence for AI agents. Index any codebase, query via MCP or CLI.",
   "author": "Abhigyan Patwari",
   "license": "PolyForm-Noncommercial-1.0.0",