gitnexus 1.5.3 → 1.6.0

package/dist/core/group/matching.js

@@ -0,0 +1,198 @@
+function isGrpcWildcard(cid) {
+    return cid.startsWith('grpc::') && cid.endsWith('/*');
+}
+export function normalizeContractId(id) {
+    const colonIdx = id.indexOf('::');
+    if (colonIdx === -1)
+        return id;
+    const type = id.substring(0, colonIdx);
+    const rest = id.substring(colonIdx + 2);
+    switch (type) {
+        case 'http': {
+            const parts = rest.split('::');
+            if (parts.length >= 2) {
+                const method = parts[0].toUpperCase();
+                let pathPart = parts.slice(1).join('::');
+                pathPart = pathPart.replace(/\/+$/, '');
+                return `http::${method}::${pathPart}`;
+            }
+            return id;
+        }
+        case 'grpc': {
+            // Canonical form: `grpc::<lowercased-package-or-service>[/<method>]`.
+            //
+            // The package/service segment is lowercased because gRPC package
+            // names are effectively case-insensitive across language bindings
+            // (`auth.AuthService`, `auth.authservice`, `AUTH.AUTHSERVICE` all
+            // describe the same wire protocol service). The RPC method segment
+            // is preserved as-is because the HTTP/2 path used on the wire is
+            // case-sensitive per the gRPC spec (`/Service/MethodName`), and
+            // method names in generated clients match the proto source exactly.
+            //
+            // A package-only id (no slash) and a package/method id are treated
+            // as DISTINCT canonical forms: `grpc::userservice` does not match
+            // `grpc::userservice/Login`. That's by design — callers that want
+            // service-level manifest matching against method-level providers
+            // should use the gRPC wildcard form `grpc::UserService/*` which is
+            // handled by runWildcardMatch below.
+            const slashIdx = rest.indexOf('/');
+            if (slashIdx > 0) {
+                const pkg = rest.substring(0, slashIdx).toLowerCase();
+                const method = rest.substring(slashIdx);
+                return `grpc::${pkg}${method}`;
+            }
+            if (slashIdx === 0) {
+                // Malformed "/method" with leading slash — keep as-is so two
+                // equally malformed ids can still match each other.
+                return `grpc::${rest}`;
+            }
+            // No slash: package/service only. Lowercase to match the package
+            // segment produced by the pkg/method branch above.
+            return `grpc::${rest.toLowerCase()}`;
+        }
+        case 'topic':
+            return `topic::${rest.trim().toLowerCase()}`;
+        case 'lib':
+            return `lib::${rest.toLowerCase()}`;
+        default:
+            return id;
+    }
+}
+function findMatchingKeys(contractId, index) {
+    const normalized = normalizeContractId(contractId);
+    if (index.has(normalized))
+        return [normalized];
+    if (normalized.startsWith('http::*::')) {
+        const pathPart = normalized.substring('http::*::'.length);
+        const matches = [];
+        for (const key of index.keys()) {
+            if (key.startsWith('http::') && key.endsWith(`::${pathPart}`)) {
+                matches.push(key);
+            }
+        }
+        return matches;
+    }
+    return [];
+}
+export function buildProviderIndex(contracts) {
+    const providers = contracts.filter((c) => c.role === 'provider');
+    const index = new Map();
+    for (const p of providers) {
+        const key = normalizeContractId(p.contractId);
+        const list = index.get(key) || [];
+        list.push(p);
+        index.set(key, list);
+    }
+    return index;
+}
+export function runExactMatch(contracts, providerIndex) {
+    const index = providerIndex ?? buildProviderIndex(contracts);
+    // Skip gRPC wildcard consumers — they go to wildcard pass only
+    const consumers = contracts.filter((c) => c.role === 'consumer' && !isGrpcWildcard(c.contractId));
+    const matched = [];
+    const matchedConsumerIds = new Set();
+    const matchedProviderIds = new Set();
+    for (const consumer of consumers) {
+        const matchingKeys = findMatchingKeys(consumer.contractId, index);
+        if (matchingKeys.length === 0)
+            continue;
+        const allMatchingProviders = matchingKeys.flatMap((k) => index.get(k) || []);
+        for (const provider of allMatchingProviders) {
+            if (provider.repo === consumer.repo) {
+                if (!provider.service || !consumer.service || provider.service === consumer.service) {
+                    continue;
+                }
+            }
+            matched.push({
+                from: {
+                    repo: consumer.repo,
+                    service: consumer.service,
+                    symbolUid: consumer.symbolUid,
+                    symbolRef: consumer.symbolRef,
+                },
+                to: {
+                    repo: provider.repo,
+                    service: provider.service,
+                    symbolUid: provider.symbolUid,
+                    symbolRef: provider.symbolRef,
+                },
+                type: consumer.type,
+                contractId: consumer.contractId,
+                matchType: 'exact',
+                confidence: 1.0,
+            });
+            matchedConsumerIds.add(`${consumer.repo}::${consumer.contractId}`);
+            matchedProviderIds.add(`${provider.repo}::${provider.contractId}`);
+        }
+    }
+    // normalUnmatched: contracts that weren't matched in exact pass
+    const normalUnmatched = contracts.filter((c) => {
+        if (isGrpcWildcard(c.contractId))
+            return false; // excluded from exact, handled separately
+        const id = `${c.repo}::${c.contractId}`;
+        return c.role === 'provider' ? !matchedProviderIds.has(id) : !matchedConsumerIds.has(id);
+    });
+    // Re-add gRPC wildcard contracts — they were never in exact matching
+    const grpcWildcards = contracts.filter((c) => isGrpcWildcard(c.contractId));
+    const unmatched = [...normalUnmatched, ...grpcWildcards];
+    return { matched, unmatched };
+}
+export function runWildcardMatch(unmatched, providerIndex) {
+    const wildcardConsumers = unmatched.filter((c) => c.role === 'consumer' && isGrpcWildcard(c.contractId));
+    const matched = [];
+    const matchedConsumerIds = new Set();
+    for (const consumer of wildcardConsumers) {
+        const normalized = normalizeContractId(consumer.contractId);
+        // "grpc::com.example.userservice/*" → "com.example.userservice"
+        // "grpc::userservice/*" → "userservice"
+        const fqService = normalized.slice(normalized.indexOf('::') + 2, -2); // strip "grpc::" and "/*"
+        for (const [key, providers] of providerIndex) {
+            // Only match against non-wildcard gRPC providers (method-level IDs)
+            if (!key.startsWith('grpc::') || key.endsWith('/*'))
+                continue;
+            const afterPrefix = key.slice(6); // strip "grpc::"
+            const slashIdx = afterPrefix.indexOf('/');
+            if (slashIdx < 0)
+                continue;
+            const providerFqService = afterPrefix.slice(0, slashIdx);
+            // Match: exact FQ service, or bare-name match when consumer has no package
+            const isMatch = providerFqService === fqService ||
+                (!fqService.includes('.') && providerFqService.endsWith('.' + fqService));
+            if (!isMatch)
+                continue;
+            for (const provider of providers) {
+                // Skip same-repo same-service (same logic as runExactMatch)
+                if (provider.repo === consumer.repo) {
+                    if (!provider.service || !consumer.service || provider.service === consumer.service) {
+                        continue;
+                    }
+                }
+                matched.push({
+                    from: {
+                        repo: consumer.repo,
+                        service: consumer.service,
+                        symbolUid: consumer.symbolUid,
+                        symbolRef: consumer.symbolRef,
+                    },
+                    to: {
+                        repo: provider.repo,
+                        service: provider.service,
+                        symbolUid: provider.symbolUid,
+                        symbolRef: provider.symbolRef,
+                    },
+                    type: consumer.type,
+                    contractId: consumer.contractId, // consumer's wildcard ID
+                    matchType: 'wildcard',
+                    confidence: Math.min(provider.confidence, consumer.confidence),
+                });
+                matchedConsumerIds.add(`${consumer.repo}::${consumer.contractId}`);
+            }
+        }
+    }
+    const remaining = unmatched.filter((c) => {
+        if (c.role !== 'consumer' || !isGrpcWildcard(c.contractId))
+            return true;
+        return !matchedConsumerIds.has(`${c.repo}::${c.contractId}`);
+    });
+    return { matched, remaining };
+}

package/dist/core/group/normalization.d.ts

@@ -0,0 +1,3 @@
+import type { CrossLink, StoredContract } from './types.js';
+export declare function dedupeContracts(items: StoredContract[]): StoredContract[];
+export declare function dedupeCrossLinks(items: CrossLink[]): CrossLink[];

package/dist/core/group/normalization.js

@@ -0,0 +1,115 @@
+function contractKey(contract) {
+    return [contract.repo, contract.contractId, contract.role, contract.symbolRef.filePath].join('\0');
+}
+function endpointKey(endpoint) {
+    return [
+        endpoint.repo,
+        endpoint.service ?? '',
+        endpoint.symbolRef.filePath,
+        endpoint.symbolRef.name,
+    ].join('\0');
+}
+/**
+ * Score a contract by how much information it carries, so `dedupeContracts`
+ * can prefer the "richer" record when two contracts collide on the same
+ * `(repo, contractId, role, filePath)` key.
+ *
+ * Weights express a priority ordering, not calibrated probabilities:
+ *   +3 — `symbolUid` resolved (tier 1 of the downstream lookup — highest
+ *        signal because it's the strongest anchor for cross-impact traversal
+ *        and the only one that's robust to renames)
+ *   +2 — any of `filePath`, `symbolRef.name`, or `symbolName` that's more
+ *        specific than the contractId itself (tier 2 signal — resolves
+ *        uniquely in most cases and survives across syncs)
+ *   +1 — `service` tag (monorepo attribution — useful but not sufficient
+ *        on its own) or non-manifest origin (auto-extracted contracts are
+ *        preferred over manifest-declared synthetic ones because the former
+ *        are grounded in real source code)
+ *
+ * The absolute numbers don't matter, only their relative ordering.
+ */
+function contractRichness(contract) {
+    let score = 0;
+    if (contract.symbolUid)
+        score += 3;
+    if (contract.symbolRef.filePath)
+        score += 2;
+    if (contract.symbolRef.name && contract.symbolRef.name !== contract.contractId)
+        score += 2;
+    if (contract.symbolName && contract.symbolName !== contract.contractId)
+        score += 2;
+    if (contract.service)
+        score += 1;
+    if (contract.meta.source !== 'manifest')
+        score += 1;
+    return score;
+}
+function mergeContracts(existing, incoming) {
+    const [primary, secondary] = contractRichness(incoming) > contractRichness(existing)
+        ? [incoming, existing]
+        : [existing, incoming];
+    const symbolRefName = primary.symbolRef.name || secondary.symbolRef.name;
+    return {
+        ...secondary,
+        ...primary,
+        symbolUid: primary.symbolUid || secondary.symbolUid,
+        symbolRef: {
+            filePath: primary.symbolRef.filePath || secondary.symbolRef.filePath,
+            name: symbolRefName,
+        },
+        symbolName: primary.symbolName || secondary.symbolName || symbolRefName,
+        confidence: Math.max(existing.confidence, incoming.confidence),
+        service: primary.service ?? secondary.service,
+        meta: { ...secondary.meta, ...primary.meta },
+    };
+}
+function mergeEndpoints(existing, incoming) {
+    return {
+        repo: existing.repo,
+        service: existing.service ?? incoming.service,
+        symbolUid: existing.symbolUid || incoming.symbolUid,
+        symbolRef: {
+            filePath: existing.symbolRef.filePath || incoming.symbolRef.filePath,
+            name: existing.symbolRef.name || incoming.symbolRef.name,
+        },
+    };
+}
+function crossLinkKey(link) {
+    return [
+        link.type,
+        link.contractId,
+        link.matchType,
+        endpointKey(link.from),
+        endpointKey(link.to),
+    ].join('\0');
+}
+export function dedupeContracts(items) {
+    const deduped = new Map();
+    for (const contract of items) {
+        const key = contractKey(contract);
+        const existing = deduped.get(key);
+        deduped.set(key, existing ? mergeContracts(existing, contract) : contract);
+    }
+    return [...deduped.values()];
+}
+export function dedupeCrossLinks(items) {
+    const deduped = new Map();
+    for (const link of items) {
+        const key = crossLinkKey(link);
+        const existing = deduped.get(key);
+        if (!existing) {
+            deduped.set(key, link);
+            continue;
+        }
+        const keepIncoming = link.confidence > existing.confidence;
+        const primary = keepIncoming ? link : existing;
+        const secondary = keepIncoming ? existing : link;
+        deduped.set(key, {
+            ...primary,
+            confidence: Math.max(existing.confidence, link.confidence),
+            from: mergeEndpoints(primary.from, secondary.from),
+            to: mergeEndpoints(primary.to, secondary.to),
+        });
+    }
+    return [...deduped.values()];
+}

package/dist/core/group/service-boundary-detector.d.ts

@@ -0,0 +1,8 @@
+export interface ServiceBoundary {
+    servicePath: string;
+    serviceName: string;
+    markers: string[];
+    confidence: number;
+}
+export declare function detectServiceBoundaries(repoPath: string): Promise<ServiceBoundary[]>;
+export declare function assignService(filePath: string, boundaries: ServiceBoundary[]): string | undefined;

package/dist/core/group/service-boundary-detector.js

@@ -0,0 +1,155 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+const SERVICE_MARKERS = [
+    'package.json',
+    'go.mod',
+    'Dockerfile',
+    'pom.xml',
+    'build.gradle',
+    'build.gradle.kts',
+    'Cargo.toml',
+    'pyproject.toml',
+    'requirements.txt',
+    'mix.exs',
+];
+const SOURCE_EXTENSIONS = new Set([
+    '.ts',
+    '.tsx',
+    '.js',
+    '.jsx',
+    '.mjs',
+    '.cjs',
+    '.go',
+    '.java',
+    '.kt',
+    '.kts',
+    '.py',
+    '.pyi',
+    '.rs',
+    '.c',
+    '.cpp',
+    '.h',
+    '.hpp',
+    '.cs',
+    '.rb',
+    '.php',
+    '.swift',
+    '.dart',
+    '.ex',
+    '.exs',
+    '.erl',
+    '.proto',
+]);
+const EXCLUDED_DIRS = new Set([
+    'node_modules',
+    'vendor',
+    'target',
+    'build',
+    'dist',
+    '__pycache__',
+    '.venv',
+    'venv',
+    '.tox',
+    '.mypy_cache',
+    '.gradle',
+    '.mvn',
+    'out',
+    'bin',
+]);
+export async function detectServiceBoundaries(repoPath) {
+    const boundaries = [];
+    await walkForBoundaries(repoPath, repoPath, boundaries);
+    return boundaries;
+}
+async function walkForBoundaries(dir, repoRoot, results) {
+    let entries;
+    try {
+        entries = await fs.readdir(dir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    const isRoot = path.resolve(dir) === path.resolve(repoRoot);
+    const foundMarkers = [];
+    let hasSourceFiles = false;
+    const subdirs = [];
+    for (const entry of entries) {
+        if (entry.name.startsWith('.') || EXCLUDED_DIRS.has(entry.name))
+            continue;
+        if (entry.isDirectory()) {
+            subdirs.push(path.join(dir, entry.name));
+        }
+        else if (entry.isFile()) {
+            if (SERVICE_MARKERS.includes(entry.name)) {
+                foundMarkers.push(entry.name);
+            }
+            const ext = path.extname(entry.name).toLowerCase();
+            if (SOURCE_EXTENSIONS.has(ext)) {
+                hasSourceFiles = true;
+            }
+        }
+    }
+    // Check subdirectories for source files if not found at this level
+    if (!hasSourceFiles && foundMarkers.length > 0) {
+        hasSourceFiles = await hasSourceFilesInSubdirs(subdirs);
+    }
+    if (!isRoot && foundMarkers.length >= 1 && hasSourceFiles) {
+        const relativePath = path.relative(repoRoot, dir).replace(/\\/g, '/');
+        const serviceName = path.basename(dir);
+        const confidence = computeConfidence(foundMarkers.length);
+        results.push({
+            servicePath: relativePath,
+            serviceName,
+            markers: foundMarkers,
+            confidence,
+        });
+    }
+    // Recurse into subdirectories
+    for (const subdir of subdirs) {
+        await walkForBoundaries(subdir, repoRoot, results);
+    }
+}
+async function hasSourceFilesInSubdirs(subdirs) {
+    for (const subdir of subdirs) {
+        let entries;
+        try {
+            entries = await fs.readdir(subdir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            if (entry.isFile()) {
+                const ext = path.extname(entry.name).toLowerCase();
+                if (SOURCE_EXTENSIONS.has(ext))
+                    return true;
+            }
+            if (entry.isDirectory() && !entry.name.startsWith('.') && !EXCLUDED_DIRS.has(entry.name)) {
+                const deeper = await hasSourceFilesInSubdirs([path.join(subdir, entry.name)]);
+                if (deeper)
+                    return true;
+            }
+        }
+    }
+    return false;
+}
+function computeConfidence(markerCount) {
+    if (markerCount >= 3)
+        return 1.0;
+    if (markerCount === 2)
+        return 0.9;
+    return 0.75;
+}
+export function assignService(filePath, boundaries) {
+    const normalized = filePath.replace(/\\/g, '/');
+    let bestMatch;
+    let bestLength = 0;
+    for (const boundary of boundaries) {
+        const prefix = boundary.servicePath + '/';
+        if (normalized.startsWith(prefix) && boundary.servicePath.length > bestLength) {
+            bestMatch = boundary;
+            bestLength = boundary.servicePath.length;
+        }
+    }
+    return bestMatch?.servicePath;
+}

package/dist/core/group/service.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Group orchestration shared by MCP (LocalBackend) and CLI.
+ * DB access is injected via GroupToolPort so this module stays free of LocalBackend private API.
+ */
+export interface GroupRepoHandle {
+    id: string;
+    name: string;
+    repoPath: string;
+    storagePath: string;
+    indexedAt?: string;
+    lastCommit?: string;
+}
+export interface GroupToolPort {
+    resolveRepo(repoParam?: string): Promise<GroupRepoHandle>;
+    impact(repo: GroupRepoHandle, params: {
+        target: string;
+        direction: 'upstream' | 'downstream';
+        maxDepth?: number;
+        relationTypes?: string[];
+        includeTests?: boolean;
+        minConfidence?: number;
+    }): Promise<unknown>;
+    query(repo: GroupRepoHandle, params: {
+        query: string;
+        task_context?: string;
+        goal?: string;
+        limit?: number;
+        max_symbols?: number;
+        include_content?: boolean;
+    }): Promise<unknown>;
+    impactByUid(repoId: string, uid: string, direction: string, opts: {
+        maxDepth: number;
+        relationTypes: string[];
+        minConfidence: number;
+        includeTests: boolean;
+    }): Promise<unknown | null>;
+}
+export declare class GroupService {
+    private readonly port;
+    constructor(port: GroupToolPort);
+    groupList(params: Record<string, unknown>): Promise<unknown>;
+    groupSync(params: Record<string, unknown>): Promise<unknown>;
+    groupContracts(params: Record<string, unknown>): Promise<unknown>;
+    groupQuery(params: Record<string, unknown>): Promise<unknown>;
+    groupStatus(params: Record<string, unknown>): Promise<unknown>;
+}

package/dist/core/group/service.js

@@ -0,0 +1,160 @@
+/**
+ * Group orchestration shared by MCP (LocalBackend) and CLI.
+ * DB access is injected via GroupToolPort so this module stays free of LocalBackend private API.
+ */
+import { checkStaleness } from '../git-staleness.js';
+import { loadGroupConfig } from './config-parser.js';
+import { getDefaultGitnexusDir, getGroupDir, listGroups, readContractRegistry } from './storage.js';
+import { syncGroup } from './sync.js';
+function repoInSubgroup(repoPath, subgroup) {
+    if (!subgroup?.trim())
+        return true;
+    const s = subgroup.replace(/\/+$/, '');
+    return repoPath === s || repoPath.startsWith(`${s}/`);
+}
+export class GroupService {
+    port;
+    constructor(port) {
+        this.port = port;
+    }
+    async groupList(params) {
+        const name = typeof params.name === 'string' ? params.name.trim() : '';
+        if (!name) {
+            const groups = await listGroups();
+            return { groups };
+        }
+        const groupDir = getGroupDir(getDefaultGitnexusDir(), name);
+        const config = await loadGroupConfig(groupDir);
+        return {
+            name: config.name,
+            description: config.description,
+            repos: config.repos,
+            links: config.links,
+        };
+    }
+    async groupSync(params) {
+        const name = String(params.name ?? '').trim();
+        if (!name)
+            return { error: 'name is required' };
+        const groupDir = getGroupDir(getDefaultGitnexusDir(), name);
+        const config = await loadGroupConfig(groupDir);
+        const result = await syncGroup(config, {
+            groupDir,
+            exactOnly: Boolean(params.exactOnly),
+            skipEmbeddings: Boolean(params.skipEmbeddings),
+            allowStale: Boolean(params.allowStale),
+            verbose: Boolean(params.verbose),
+        });
+        return {
+            contracts: result.contracts.length,
+            crossLinks: result.crossLinks.length,
+            unmatched: result.unmatched.length,
+            missingRepos: result.missingRepos,
+        };
+    }
+    async groupContracts(params) {
+        const name = String(params.name ?? '').trim();
+        if (!name)
+            return { error: 'name is required' };
+        const groupDir = getGroupDir(getDefaultGitnexusDir(), name);
+        const registry = await readContractRegistry(groupDir);
+        if (!registry) {
+            return { error: `No contracts.json for group "${name}". Run group_sync first.` };
+        }
+        let contracts = registry.contracts;
+        if (params.type)
+            contracts = contracts.filter((c) => c.type === params.type);
+        if (params.repo)
+            contracts = contracts.filter((c) => c.repo === params.repo);
+        if (params.unmatchedOnly) {
+            const matchedIds = new Set(registry.crossLinks.flatMap((l) => [
+                `${l.from.repo}::${l.contractId}`,
+                `${l.to.repo}::${l.contractId}`,
+            ]));
+            contracts = contracts.filter((c) => !matchedIds.has(`${c.repo}::${c.contractId}`));
+        }
+        return { contracts, crossLinks: registry.crossLinks };
+    }
+    async groupQuery(params) {
+        const name = String(params.name ?? '').trim();
+        const queryText = String(params.query ?? '').trim();
+        if (!name || !queryText)
+            return { error: 'name and query are required' };
+        const limit = typeof params.limit === 'number' && params.limit > 0 ? params.limit : 5;
+        const subgroup = typeof params.subgroup === 'string' ? params.subgroup : undefined;
+        const groupDir = getGroupDir(getDefaultGitnexusDir(), name);
+        const config = await loadGroupConfig(groupDir);
+        const perRepo = [];
+        for (const [repoPath, registryName] of Object.entries(config.repos)) {
+            if (!repoInSubgroup(repoPath, subgroup))
+                continue;
+            try {
+                const repoObj = await this.port.resolveRepo(registryName);
+                const queryResult = (await this.port.query(repoObj, {
+                    query: queryText,
+                    limit,
+                    max_symbols: 10,
+                    include_content: false,
+                }));
+                const processes = queryResult.processes || [];
+                const scored = processes.map((p, idx) => ({
+                    ...p,
+                    _rrf_score: 1 / (idx + 1 + 60),
+                    _repo: repoPath,
+                }));
+                perRepo.push({ repo: repoPath, score: 0, processes: scored });
+            }
+            catch {
+                perRepo.push({ repo: repoPath, score: 0, processes: [] });
+            }
+        }
+        const allProcesses = perRepo.flatMap((r) => r.processes);
+        allProcesses.sort((a, b) => b._rrf_score - a._rrf_score);
+        const topN = allProcesses.slice(0, limit);
+        return {
+            group: name,
+            query: queryText,
+            results: topN,
+            per_repo: perRepo.map((r) => ({ repo: r.repo, count: r.processes.length })),
+        };
+    }
+    async groupStatus(params) {
+        const name = String(params.name ?? '').trim();
+        if (!name)
+            return { error: 'name is required' };
+        const groupDir = getGroupDir(getDefaultGitnexusDir(), name);
+        const config = await loadGroupConfig(groupDir);
+        const registry = await readContractRegistry(groupDir);
+        const repoStatuses = {};
+        const fsp = await import('node:fs/promises');
+        const pathMod = await import('node:path');
+        for (const [repoPath, registryName] of Object.entries(config.repos)) {
+            try {
+                const repoObj = await this.port.resolveRepo(registryName);
+                const metaPath = pathMod.join(repoObj.storagePath, 'meta.json');
+                const metaRaw = await fsp.readFile(metaPath, 'utf-8').catch(() => '{}');
+                const meta = JSON.parse(metaRaw);
+                const staleness = meta.lastCommit
+                    ? checkStaleness(repoObj.repoPath, meta.lastCommit)
+                    : { isStale: true, commitsBehind: -1 };
+                const snapshot = registry?.repoSnapshots[repoPath];
+                const contractsStale = snapshot && meta.indexedAt ? snapshot.indexedAt !== meta.indexedAt : !snapshot;
+                repoStatuses[repoPath] = {
+                    indexStale: staleness.isStale,
+                    contractsStale: Boolean(contractsStale),
+                    missing: false,
+                    commitsBehind: staleness.commitsBehind,
+                };
+            }
+            catch {
+                repoStatuses[repoPath] = { indexStale: false, contractsStale: false, missing: true };
+            }
+        }
+        return {
+            group: name,
+            lastSync: registry?.generatedAt || null,
+            missingRepos: registry?.missingRepos || [],
+            repos: repoStatuses,
+        };
+    }
+}