gitnexus 1.6.3-rc.8 → 1.6.3

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

@@ -56,6 +56,7 @@ interface RepoHandle {
     lbugPath: string;
     indexedAt: string;
     lastCommit: string;
+    remoteUrl?: string;
     stats?: RegistryEntry['stats'];
 }
 export declare class LocalBackend {
@@ -65,6 +66,13 @@ export declare class LocalBackend {
     private reinitPromises;
     private lastStalenessCheck;
     private groupToolSvc;
+    /**
+     * One-shot stderr warnings for sibling-clone drift, keyed by
+     * `${repoId}|${cwdGitRoot}`. Without this guard every tool call
+     * from inside a sibling clone would print the same warning,
+     * making MCP stderr unreadable.
+     */
+    private warnedSiblingDrift;
     /**
      * Cross-repo group tools (CLI). Shares logic with MCP `group_*` handlers.
      */
@@ -110,14 +118,55 @@ export declare class LocalBackend {
      * List all registered repos with their metadata.
      * Re-reads the global registry so newly indexed repos are discovered
      * without restarting the MCP server.
+     *
+     * Each entry includes:
+     *   - `staleness`: if the indexed clone's own HEAD has moved past
+     *     the recorded `lastCommit` (option D in the issue's fix list).
+     *   - `siblings`: other registered entries sharing the same
+     *     `remoteUrl` (option B's payoff: callers can see at a glance
+     *     that another clone of the same logical repo is registered).
+     *   - `remoteUrl`: the canonical origin URL recorded at index time.
      */
     listRepos(): Promise<Array<{
         name: string;
         path: string;
         indexedAt: string;
         lastCommit: string;
+        remoteUrl?: string;
         stats?: any;
+        staleness?: {
+            commitsBehind: number;
+            hint?: string;
+        };
+        siblings?: Array<{
+            name: string;
+            path: string;
+            lastCommit: string;
+        }>;
     }>>;
+    /**
+     * Best-effort sibling-clone drift warning.
+     *
+     * When the resolved index has a `remoteUrl` recorded and the caller's
+     * `process.cwd()` is inside a *different* clone of the same repo, emit
+     * one stderr line per (repo, cwd) pair so the operator knows the
+     * graph may be stale relative to what's actually on disk under their
+     * cwd. Silent on path matches and on repos without a remote URL.
+     *
+     * Limitation: in MCP stdio server mode `process.cwd()` is the
+     * server's CWD at start time, *not* the agent client's CWD. The
+     * warning therefore only fires when the MCP server itself was
+     * launched from inside a sibling clone (typical for `npx gitnexus
+     * serve` from a polecat workspace). Surfacing the client's CWD
+     * would require a per-tool-call `cwd` parameter — out of scope for
+     * the current MCP contract.
+     *
+     * Pure side-effect (stderr); never affects the returned handle.
+     * After the first computation for a given (repo, cwd) pair the
+     * result is cached so subsequent `resolveRepo()` calls don't
+     * re-shell-out to git.
+     */
+    private maybeWarnSiblingDrift;
     callTool(method: string, params: any): Promise<any>;
     /**
      * Query tool — process-grouped search.
@@ -236,11 +285,26 @@ export declare class LocalBackend {
         includeTests: boolean;
     }): Promise<any | null>;
     private handleGroupTool;
+    /**
+     * Dispatch impact/query/context when `repo` is `@groupName` or `@groupName/memberPath`
+     * (group mode — not the global indexed-repo `repo` parameter).
+     */
+    private callToolAtGroupRepo;
     private groupList;
     private groupSync;
-    private groupContracts;
-    private groupQuery;
-    private groupStatus;
+    /**
+     * MCP resource body for `gitnexus://group/{name}/contracts` (Issue #794).
+     */
+    readGroupContractsResource(groupName: string, filter: {
+        type?: string;
+        repo?: string;
+        unmatchedOnly?: boolean;
+    }): Promise<string>;
+    /**
+     * MCP resource body for `gitnexus://group/{name}/status` (Issue #794).
+     */
+    readGroupStatusResource(groupName: string): Promise<string>;
+    private static formatGroupResourcePayload;
     /**
      * Fetch Route nodes with their consumers in a single query.
      * Shared by routeMap and shapeCheck to avoid N+1 query patterns.

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

@@ -16,9 +16,11 @@ export { isWriteQuery };
 import { parseDiffHunks } from '../../storage/git.js';
 import { listRegisteredRepos, cleanupOldKuzuFiles, } from '../../storage/repo-manager.js';
 import { GroupService } from '../../core/group/service.js';
+import { resolveAtGroupMemberRepoPath } from '../../core/group/resolve-at-member.js';
 import { collectBestChunks } from '../../core/embeddings/types.js';
 import { EMBEDDING_TABLE_NAME, EMBEDDING_INDEX_NAME } from '../../core/lbug/schema.js';
 import { PhaseTimer } from '../../core/search/phase-timer.js';
+import { checkStaleness, checkCwdMatch } from '../../core/git-staleness.js';
 // AI context generation is CLI-only (gitnexus analyze)
 // import { generateAIContextFiles } from '../../cli/ai-context.js';
 /**
@@ -161,6 +163,13 @@ export class LocalBackend {
     reinitPromises = new Map();
     lastStalenessCheck = new Map();
     groupToolSvc = null;
+    /**
+     * One-shot stderr warnings for sibling-clone drift, keyed by
+     * `${repoId}|${cwdGitRoot}`. Without this guard every tool call
+     * from inside a sibling clone would print the same warning,
+     * making MCP stderr unreadable.
+     */
+    warnedSiblingDrift = new Set();
     /**
      * Cross-repo group tools (CLI). Shares logic with MCP `group_*` handlers.
      */
@@ -171,6 +180,7 @@ export class LocalBackend {
                 impact: (r, p) => this.impact(r, p),
                 query: (r, p) => this.query(r, p),
                 impactByUid: (id, uid, d, o) => this.impactByUid(id, uid, d, o),
+                context: (r, p) => this.context(r, p),
             };
             this.groupToolSvc = new GroupService(port);
         }
@@ -216,6 +226,7 @@ export class LocalBackend {
                 lbugPath,
                 indexedAt: entry.indexedAt,
                 lastCommit: entry.lastCommit,
+                remoteUrl: entry.remoteUrl,
                 stats: entry.stats,
             };
             this.repos.set(id, handle);
@@ -268,23 +279,43 @@ export class LocalBackend {
      */
     async resolveRepo(repoParam) {
         const result = this.resolveRepoFromCache(repoParam);
-        if (result)
+        if (result) {
+            // Issue: silent graph drift across sibling clones.
+            // If the caller's cwd lives in a *different* on-disk clone of
+            // the same repo (matched by `remoteUrl`), warn once per
+            // (repo, cwd) pair on stderr. We do not fail or refuse to
+            // serve — the index is still the best answer we have — but
+            // the operator/agent has to know the answer may be stale.
+            this.maybeWarnSiblingDrift(result).catch(() => {
+                /* best-effort; never throw from resolveRepo */
+            });
             return result;
+        }
         // Miss — refresh registry and try once more
         await this.refreshRepos();
         const retried = this.resolveRepoFromCache(repoParam);
-        if (retried)
+        if (retried) {
+            this.maybeWarnSiblingDrift(retried).catch(() => { });
             return retried;
+        }
         // Still no match — throw with helpful message
         if (this.repos.size === 0) {
             throw new Error('No indexed repositories. Run: gitnexus analyze');
         }
+        // Build a disambiguated "Available: …" list (#829). When two handles
+        // share a name, annotate each colliding label with its path so the
+        // caller can actually pick the right one. Single-name entries render
+        // identically to pre-#829 output.
+        const nameCounts = new Map();
+        for (const h of this.repos.values()) {
+            const key = h.name.toLowerCase();
+            nameCounts.set(key, (nameCounts.get(key) ?? 0) + 1);
+        }
+        const labels = [...this.repos.values()].map((h) => (nameCounts.get(h.name.toLowerCase()) ?? 0) > 1 ? `${h.name} (${h.repoPath})` : h.name);
         if (repoParam) {
-            const names = [...this.repos.values()].map((h) => h.name);
-            throw new Error(`Repository "${repoParam}" not found. Available: ${names.join(', ')}`);
+            throw new Error(`Repository "${repoParam}" not found. Available: ${labels.join(', ')}`);
         }
-        const names = [...this.repos.values()].map((h) => h.name);
-        throw new Error(`Multiple repositories indexed. Specify which one with the "repo" parameter. Available: ${names.join(', ')}`);
+        throw new Error(`Multiple repositories indexed. Specify which one with the "repo" parameter. Available: ${labels.join(', ')}`);
     }
     /**
      * Try to resolve a repo from the in-memory cache. Returns null on miss.
@@ -396,16 +427,113 @@ export class LocalBackend {
      * List all registered repos with their metadata.
      * Re-reads the global registry so newly indexed repos are discovered
      * without restarting the MCP server.
+     *
+     * Each entry includes:
+     *   - `staleness`: if the indexed clone's own HEAD has moved past
+     *     the recorded `lastCommit` (option D in the issue's fix list).
+     *   - `siblings`: other registered entries sharing the same
+     *     `remoteUrl` (option B's payoff: callers can see at a glance
+     *     that another clone of the same logical repo is registered).
+     *   - `remoteUrl`: the canonical origin URL recorded at index time.
      */
     async listRepos() {
         await this.refreshRepos();
-        return [...this.repos.values()].map((h) => ({
-            name: h.name,
-            path: h.repoPath,
-            indexedAt: h.indexedAt,
-            lastCommit: h.lastCommit,
-            stats: h.stats,
-        }));
+        const handles = [...this.repos.values()];
+        // Pre-group registered handles by `remoteUrl` so the sibling
+        // lookup is O(1) per handle. We reuse the in-memory `this.repos`
+        // (already populated by `refreshRepos`) instead of doing a fresh
+        // `readRegistry()` per entry — that would be N file reads for N
+        // registered repos.
+        const isWin = process.platform === 'win32';
+        const norm = (p) => (isWin ? path.resolve(p).toLowerCase() : path.resolve(p));
+        const byRemote = new Map();
+        for (const h of handles) {
+            if (!h.remoteUrl)
+                continue;
+            const list = byRemote.get(h.remoteUrl) ?? [];
+            list.push(h);
+            byRemote.set(h.remoteUrl, list);
+        }
+        return handles.map((h) => {
+            const stale = checkStaleness(h.repoPath, h.lastCommit);
+            const selfNorm = norm(h.repoPath);
+            const siblings = h.remoteUrl
+                ? (byRemote.get(h.remoteUrl) ?? []).filter((e) => norm(e.repoPath) !== selfNorm)
+                : [];
+            return {
+                name: h.name,
+                path: h.repoPath,
+                indexedAt: h.indexedAt,
+                lastCommit: h.lastCommit,
+                remoteUrl: h.remoteUrl,
+                stats: h.stats,
+                staleness: stale.isStale
+                    ? { commitsBehind: stale.commitsBehind, hint: stale.hint }
+                    : undefined,
+                siblings: siblings.length > 0
+                    ? siblings.map((s) => ({
+                        name: s.name,
+                        path: s.repoPath,
+                        lastCommit: s.lastCommit,
+                    }))
+                    : undefined,
+            };
+        });
+    }
+    /**
+     * Best-effort sibling-clone drift warning.
+     *
+     * When the resolved index has a `remoteUrl` recorded and the caller's
+     * `process.cwd()` is inside a *different* clone of the same repo, emit
+     * one stderr line per (repo, cwd) pair so the operator knows the
+     * graph may be stale relative to what's actually on disk under their
+     * cwd. Silent on path matches and on repos without a remote URL.
+     *
+     * Limitation: in MCP stdio server mode `process.cwd()` is the
+     * server's CWD at start time, *not* the agent client's CWD. The
+     * warning therefore only fires when the MCP server itself was
+     * launched from inside a sibling clone (typical for `npx gitnexus
+     * serve` from a polecat workspace). Surfacing the client's CWD
+     * would require a per-tool-call `cwd` parameter — out of scope for
+     * the current MCP contract.
+     *
+     * Pure side-effect (stderr); never affects the returned handle.
+     * After the first computation for a given (repo, cwd) pair the
+     * result is cached so subsequent `resolveRepo()` calls don't
+     * re-shell-out to git.
+     */
+    async maybeWarnSiblingDrift(handle) {
+        if (!handle.remoteUrl)
+            return;
+        let cwd;
+        try {
+            cwd = process.cwd();
+        }
+        catch {
+            return;
+        }
+        // Early-exit cache: keyed on (repo, cwd) BEFORE any git shellout.
+        // After the first call for a given cwd, this short-circuits the
+        // up-to-four `execSync`/`execFileSync` calls inside `checkCwdMatch`
+        // — important for MCP-server mode where `process.cwd()` is constant
+        // and `resolveRepo` runs on every tool call.
+        const cacheKey = `${handle.id}|${cwd}`;
+        if (this.warnedSiblingDrift.has(cacheKey))
+            return;
+        const match = await checkCwdMatch(cwd);
+        if (match.match !== 'sibling-by-remote' ||
+            !match.entry ||
+            !match.cwdGitRoot ||
+            match.entry.path !== handle.repoPath ||
+            !match.hint) {
+            // Cache "nothing to warn about" outcomes too — `checkCwdMatch`
+            // is deterministic for a fixed (registry, cwd) pair, so re-running
+            // it yields nothing new.
+            this.warnedSiblingDrift.add(cacheKey);
+            return;
+        }
+        this.warnedSiblingDrift.add(cacheKey);
+        console.error(`GitNexus: ${match.hint}`);
     }
     // ─── Tool Dispatch ───────────────────────────────────────────────
     async callTool(method, params) {
@@ -415,6 +543,12 @@ export class LocalBackend {
         if (method.startsWith('group_')) {
             return this.handleGroupTool(method, params || {});
         }
+        const p = params && typeof params === 'object' ? params : {};
+        if ((method === 'impact' || method === 'query' || method === 'context') &&
+            typeof p.repo === 'string' &&
+            p.repo.startsWith('@')) {
+            return this.callToolAtGroupRepo(method, p);
+        }
         // Resolve repo from optional param (re-reads registry on miss)
         const repo = await this.resolveRepo(params?.repo);
         switch (method) {
@@ -691,12 +825,22 @@ export class LocalBackend {
         for (const bm25Result of bm25Results) {
             const fullPath = bm25Result.filePath;
             try {
-                const symbols = await executeParameterized(repo.id, `
-          MATCH (n)
-          WHERE n.filePath = $filePath
-          RETURN n.id AS id, n.name AS name, labels(n)[0] AS type, n.filePath AS filePath, n.startLine AS startLine, n.endLine AS endLine
-          LIMIT 3
-        `, { filePath: fullPath });
+                // Prefer direct nodeId lookup (exact FTS-matched nodes) over filePath fallback.
+                // Without this, LIMIT 3 on filePath returns arbitrary symbols rather than
+                // the nodes that actually scored highest in the BM25 index.
+                const nodeIds = bm25Result.nodeIds?.length ? bm25Result.nodeIds : null;
+                const symbols = nodeIds
+                    ? await executeParameterized(repo.id, `
+              MATCH (n)
+              WHERE n.id IN $nodeIds
+              RETURN n.id AS id, n.name AS name, labels(n)[0] AS type, n.filePath AS filePath, n.startLine AS startLine, n.endLine AS endLine
+            `, { nodeIds })
+                    : await executeParameterized(repo.id, `
+              MATCH (n)
+              WHERE n.filePath = $filePath
+              RETURN n.id AS id, n.name AS name, labels(n)[0] AS type, n.filePath AS filePath, n.startLine AS startLine, n.endLine AS endLine
+              LIMIT 3
+            `, { filePath: fullPath });
                 if (symbols.length > 0) {
                     for (const sym of symbols) {
                         results.push({
@@ -2293,32 +2437,150 @@ export class LocalBackend {
                 return this.groupList(params);
             case 'group_sync':
                 return this.groupSync(params);
-            case 'group_contracts':
-                return this.groupContracts(params);
-            case 'group_query':
-                return this.groupQuery(params);
-            case 'group_status':
-                return this.groupStatus(params);
             default:
-                throw new Error(`Unknown group tool: ${method}`);
+                throw new Error(`Unknown group tool: ${method}. Removed tools: use repo "@<groupName>" on impact, query, or context (optional "/<memberPath>"), or MCP resources.`);
         }
     }
+    /**
+     * Dispatch impact/query/context when `repo` is `@groupName` or `@groupName/memberPath`
+     * (group mode — not the global indexed-repo `repo` parameter).
+     */
+    async callToolAtGroupRepo(method, params) {
+        await this.refreshRepos();
+        if (params.service !== undefined &&
+            params.service !== null &&
+            String(params.service).trim() === '') {
+            return { error: 'service must not be an empty string' };
+        }
+        const raw = String(params.repo).slice(1);
+        const slash = raw.indexOf('/');
+        const groupName = (slash === -1 ? raw : raw.slice(0, slash)).trim();
+        const memberRest = slash === -1 ? undefined : raw.slice(slash + 1).trim() || undefined;
+        const resolved = await resolveAtGroupMemberRepoPath(groupName, memberRest);
+        if (resolved.ok === false)
+            return { error: resolved.error };
+        const svc = this.getGroupService();
+        if (method === 'impact') {
+            const impactArgs = {
+                name: groupName,
+                repo: resolved.repoPath,
+                target: params.target,
+                direction: params.direction,
+            };
+            if (params.maxDepth !== undefined)
+                impactArgs.maxDepth = params.maxDepth;
+            if (params.crossDepth !== undefined)
+                impactArgs.crossDepth = params.crossDepth;
+            if (params.relationTypes !== undefined)
+                impactArgs.relationTypes = params.relationTypes;
+            if (params.includeTests !== undefined)
+                impactArgs.includeTests = params.includeTests;
+            if (params.minConfidence !== undefined)
+                impactArgs.minConfidence = params.minConfidence;
+            if (params.service !== undefined && params.service !== null)
+                impactArgs.service = params.service;
+            if (typeof params.subgroup === 'string')
+                impactArgs.subgroup = params.subgroup;
+            if (params.timeoutMs !== undefined)
+                impactArgs.timeoutMs = params.timeoutMs;
+            if (params.timeout !== undefined)
+                impactArgs.timeout = params.timeout;
+            return svc.groupImpact(impactArgs);
+        }
+        if (method === 'query') {
+            const queryArgs = {
+                name: groupName,
+                query: params.query,
+            };
+            if (typeof params.task_context === 'string')
+                queryArgs.task_context = params.task_context;
+            if (typeof params.goal === 'string')
+                queryArgs.goal = params.goal;
+            if (typeof params.limit === 'number')
+                queryArgs.limit = params.limit;
+            if (typeof params.max_symbols === 'number')
+                queryArgs.max_symbols = params.max_symbols;
+            if (params.include_content !== undefined)
+                queryArgs.include_content = params.include_content;
+            if (params.service !== undefined && params.service !== null)
+                queryArgs.service = params.service;
+            if (memberRest !== undefined) {
+                queryArgs.subgroup = memberRest;
+                queryArgs.subgroupExact = true;
+            }
+            return svc.groupQuery(queryArgs);
+        }
+        if (method === 'context') {
+            const targetSym = typeof params.target === 'string' && params.target.trim() !== ''
+                ? params.target.trim()
+                : typeof params.name === 'string' && params.name.trim() !== ''
+                    ? params.name.trim()
+                    : undefined;
+            const contextArgs = {
+                name: groupName,
+                target: targetSym,
+            };
+            if (typeof params.uid === 'string')
+                contextArgs.uid = params.uid;
+            if (typeof params.file_path === 'string')
+                contextArgs.file_path = params.file_path;
+            if (params.include_content !== undefined)
+                contextArgs.include_content = params.include_content;
+            if (params.service !== undefined && params.service !== null)
+                contextArgs.service = params.service;
+            if (memberRest !== undefined) {
+                contextArgs.subgroup = memberRest;
+                contextArgs.subgroupExact = true;
+            }
+            return svc.groupContext(contextArgs);
+        }
+        throw new Error(`Internal: unsupported group-repo tool ${method}`);
+    }
     async groupList(params) {
         return this.getGroupService().groupList(params);
     }
     async groupSync(params) {
         return this.getGroupService().groupSync(params);
     }
-    async groupContracts(params) {
-        return this.getGroupService().groupContracts(params);
+    /**
+     * MCP resource body for `gitnexus://group/{name}/contracts` (Issue #794).
+     */
+    async readGroupContractsResource(groupName, filter) {
+        try {
+            const params = { name: groupName };
+            if (filter.type !== undefined)
+                params.type = filter.type;
+            if (filter.repo !== undefined)
+                params.repo = filter.repo;
+            if (filter.unmatchedOnly === true)
+                params.unmatchedOnly = true;
+            const raw = await this.getGroupService().groupContracts(params);
+            return LocalBackend.formatGroupResourcePayload(raw);
+        }
+        catch (e) {
+            return `error: ${e instanceof Error ? e.message : String(e)}`;
+        }
     }
-    async groupQuery(params) {
-        await this.refreshRepos();
-        return this.getGroupService().groupQuery(params);
+    /**
+     * MCP resource body for `gitnexus://group/{name}/status` (Issue #794).
+     */
+    async readGroupStatusResource(groupName) {
+        try {
+            const raw = await this.getGroupService().groupStatus({ name: groupName });
+            return LocalBackend.formatGroupResourcePayload(raw);
+        }
+        catch (e) {
+            return `error: ${e instanceof Error ? e.message : String(e)}`;
+        }
     }
-    async groupStatus(params) {
-        await this.refreshRepos();
-        return this.getGroupService().groupStatus(params);
+    static formatGroupResourcePayload(raw) {
+        if (raw && typeof raw === 'object' && 'error' in raw) {
+            const err = raw.error;
+            if (typeof err === 'string' && err.length > 0) {
+                return `error: ${err}`;
+            }
+        }
+        return JSON.stringify(raw, null, 2);
     }
     /**
      * Fetch Route nodes with their consumers in a single query.

package/dist/mcp/resources.d.ts

@@ -25,6 +25,37 @@ export declare function getResourceDefinitions(): ResourceDefinition[];
  * Dynamic resource templates
  */
 export declare function getResourceTemplates(): ResourceTemplate[];
+/** Query parameters for `gitnexus://group/{name}/contracts` */
+export type GroupContractsResourceFilter = {
+    type?: string;
+    repo?: string;
+    unmatchedOnly?: boolean;
+};
+/** Normalized parse result for GitNexus MCP resource URIs */
+export type ParsedGitnexusResource = {
+    kind: 'repos';
+} | {
+    kind: 'setup';
+} | {
+    kind: 'repo';
+    repoName: string;
+    resourceType: string;
+    param?: string;
+} | {
+    kind: 'group';
+    groupName: string;
+    resourceType: 'contracts';
+    contractsFilter: GroupContractsResourceFilter;
+} | {
+    kind: 'group';
+    groupName: string;
+    resourceType: 'status';
+};
+/**
+ * Parse a GitNexus resource URI (repos, setup, per-repo, or per-group templates).
+ * Used by `readResource` and tests (round-trip / dispatch coverage).
+ */
+export declare function parseResourceUri(uri: string): ParsedGitnexusResource;
 /**
  * Read a resource and return its content
  */