gitnexus 1.6.3-rc.22 → 1.6.3-rc.23

package/dist/cli/ai-context.js

@@ -89,7 +89,7 @@ This project is indexed by GitNexus as **${projectName}**${noStats ? '' : ` (${s
 ${groupNames && groupNames.length > 0
         ? `## Cross-Repo Groups
 
-This repository is listed under GitNexus **group(s): ${groupNames.join(', ')}** (see \`~/.gitnexus/groups/\`). For blast radius across repository boundaries, use MCP tools \`group_impact\`, \`group_sync\`, \`group_query\`, \`group_contracts\`, \`group_status\`, and \`group_list\`. From the terminal: \`npx gitnexus group list\`, \`npx gitnexus group sync <name>\`, \`npx gitnexus group impact <name> --target <symbol> --repo <group-path>\`.
+This repository is listed under GitNexus **group(s): ${groupNames.join(', ')}** (see \`~/.gitnexus/groups/\`). For cross-repo analysis, use MCP tools \`impact\`, \`query\`, and \`context\` with \`repo\` set to \`@<groupName>\` or \`@<groupName>/<memberPath>\` (paths match keys in that group’s \`group.yaml\`). Use \`group_list\` / \`group_sync\` for membership and sync. From the terminal: \`npx gitnexus group list\`, \`npx gitnexus group sync <name>\`, \`npx gitnexus group impact <name> --target <symbol> --repo <group-path>\`.
 
 `
         : ''}## CLI

package/dist/cli/group.js

@@ -149,6 +149,79 @@ export function registerGroupCommands(program) {
             console.log(`\nWrote contracts.json (${result.contracts.length} contracts, ${result.crossLinks.length} cross-links)`);
         }
     });
+    group
+        .command('impact <name>')
+        .description('Cross-repo impact for a symbol in one member repo of a group')
+        .requiredOption('--target <symbol>', 'Symbol or file name to analyze')
+        .requiredOption('--repo <groupPath>', 'Member path from group.yaml (e.g. app/backend), not the indexed repo name')
+        .option('--direction <dir>', 'upstream or downstream', 'upstream')
+        .option('--service <path>', 'Optional monorepo service directory prefix (path filter)')
+        .option('--subgroup <path>', 'Optional prefix limiting which group repos participate in cross fan-out')
+        .option('--max-depth <n>', 'Max graph traversal depth')
+        .option('--cross-depth <n>', 'Cross-repository hop depth')
+        .option('--min-confidence <n>', 'Minimum relation confidence (0–1)')
+        .option('--include-tests', 'Include test files in traversal', false)
+        .option('--timeout-ms <n>', 'Phase-1 local impact wall time in milliseconds')
+        .option('--json', 'JSON output')
+        .action(async (name, opts) => {
+        const { LocalBackend } = await import('../mcp/local/local-backend.js');
+        const backend = new LocalBackend();
+        try {
+            await backend.init();
+            const payload = {
+                name,
+                repo: opts.repo,
+                target: opts.target,
+                direction: opts.direction || 'upstream',
+            };
+            if (opts.service)
+                payload.service = opts.service;
+            if (opts.subgroup)
+                payload.subgroup = opts.subgroup;
+            if (opts.maxDepth !== undefined && opts.maxDepth !== '') {
+                const n = parseInt(String(opts.maxDepth), 10);
+                if (!Number.isNaN(n))
+                    payload.maxDepth = n;
+            }
+            if (opts.crossDepth !== undefined && opts.crossDepth !== '') {
+                const n = parseInt(String(opts.crossDepth), 10);
+                if (!Number.isNaN(n))
+                    payload.crossDepth = n;
+            }
+            if (opts.minConfidence !== undefined && opts.minConfidence !== '') {
+                const n = parseFloat(String(opts.minConfidence));
+                if (!Number.isNaN(n))
+                    payload.minConfidence = n;
+            }
+            if (opts.timeoutMs !== undefined && opts.timeoutMs !== '') {
+                const n = parseInt(String(opts.timeoutMs), 10);
+                if (!Number.isNaN(n))
+                    payload.timeoutMs = n;
+            }
+            if (opts.includeTests)
+                payload.includeTests = true;
+            const raw = await backend.getGroupService().groupImpact(payload);
+            if (raw && typeof raw === 'object' && 'error' in raw) {
+                console.error(String(raw.error));
+                process.exitCode = 1;
+                return;
+            }
+            if (opts.json) {
+                console.log(JSON.stringify(raw, null, 2));
+            }
+            else {
+                const summary = raw?.summary;
+                const risk = raw?.risk;
+                console.log(`Group impact for "${name}" (${String(opts.repo)}): risk=${risk ?? '?'}`);
+                if (summary) {
+                    console.log(`  direct=${summary.direct ?? 0} processes=${summary.processes_affected ?? 0} cross=${summary.cross_repo_hits ?? 0}`);
+                }
+            }
+        }
+        finally {
+            await backend.dispose().catch(() => { });
+        }
+    });
     group
         .command('query <name> <query>')
         .description('Search execution flows across all repos in a group')

package/dist/core/group/cross-impact.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Cross-repo impact (Phase 1 local walk + Phase 2 bridge fan-out).
+ * All bridge Cypher for this feature lives in this module.
+ */
+import type { GroupImpactResult } from './types.js';
+import type { GroupToolPort } from './service.js';
+/** Cross-boundary hops beyond this value are clamped (multi-hop reserved for future work). */
+export declare const MAX_SUPPORTED_CROSS_DEPTH = 1;
+/** Default wall-clock budget for the Phase 1 `impact` leg when callers omit `timeoutMs`. */
+export declare const DEFAULT_LOCAL_IMPACT_TIMEOUT_MS = 30000;
+export interface RunGroupImpactDeps {
+    port: GroupToolPort;
+    gitnexusDir: string;
+}
+export declare function validateGroupImpactParams(params: Record<string, unknown>): {
+    ok: true;
+    name: string;
+    repoPath: string;
+    target: string;
+    direction: 'upstream' | 'downstream';
+    maxDepth: number;
+    crossDepth: number;
+    crossDepthWarning?: string;
+    relationTypes?: string[];
+    includeTests: boolean;
+    minConfidence: number;
+    service?: string;
+    subgroup?: string;
+    timeoutMs: number;
+} | {
+    ok: false;
+    error: string;
+};
+export declare function collectImpactSymbolUids(local: unknown, servicePrefix: string | undefined): {
+    uids: string[];
+    targetFilePath?: string;
+};
+export declare function runGroupImpact(deps: RunGroupImpactDeps, params: Record<string, unknown>): Promise<GroupImpactResult | {
+    error: string;
+}>;
+export { normalizeServicePrefix, fileMatchesServicePrefix } from './group-path-utils.js';

package/dist/core/group/cross-impact.js

@@ -0,0 +1,454 @@
+/**
+ * Cross-repo impact (Phase 1 local walk + Phase 2 bridge fan-out).
+ * All bridge Cypher for this feature lives in this module.
+ */
+import fsp from 'node:fs/promises';
+import path from 'node:path';
+import { loadGroupConfig } from './config-parser.js';
+import { fileMatchesServicePrefix, normalizeServicePrefix, repoInSubgroup, } from './group-path-utils.js';
+import { getGroupDir } from './storage.js';
+import { closeBridgeDb, openBridgeDbReadOnly, queryBridge, readBridgeMeta } from './bridge-db.js';
+import { BRIDGE_SCHEMA_VERSION } from './bridge-schema.js';
+/** Cross-boundary hops beyond this value are clamped (multi-hop reserved for future work). */
+export const MAX_SUPPORTED_CROSS_DEPTH = 1;
+/** Default wall-clock budget for the Phase 1 `impact` leg when callers omit `timeoutMs`. */
+export const DEFAULT_LOCAL_IMPACT_TIMEOUT_MS = 30_000;
+const CY_NEIGHBORS_UPSTREAM = `
+MATCH (consumer:Contract)-[l:ContractLink]->(provider:Contract)
+WHERE provider.repo = $localRepo
+  AND provider.symbolUid IN $uids
+  AND provider.role = 'provider'
+RETURN consumer.repo AS neighborRepo,
+       consumer.symbolUid AS neighborUid,
+       consumer.filePath AS neighborFilePath,
+       l.matchType AS matchType,
+       l.confidence AS confidence,
+       l.contractId AS contractId,
+       consumer.type AS contractType
+`;
+const CY_NEIGHBORS_DOWNSTREAM = `
+MATCH (consumer:Contract)-[l:ContractLink]->(provider:Contract)
+WHERE consumer.repo = $localRepo
+  AND consumer.symbolUid IN $uids
+  AND consumer.role = 'consumer'
+RETURN provider.repo AS neighborRepo,
+       provider.symbolUid AS neighborUid,
+       provider.filePath AS neighborFilePath,
+       l.matchType AS matchType,
+       l.confidence AS confidence,
+       l.contractId AS contractId,
+       provider.type AS contractType
+`;
+function parseDirection(raw) {
+    if (raw === 'upstream' || raw === 'downstream')
+        return raw;
+    return null;
+}
+function clampCrossDepth(raw) {
+    const n = typeof raw === 'number' && Number.isFinite(raw) ? Math.floor(raw) : 1;
+    const d = n < 1 ? 1 : n;
+    if (d > MAX_SUPPORTED_CROSS_DEPTH) {
+        return {
+            depth: MAX_SUPPORTED_CROSS_DEPTH,
+            warning: `crossDepth was ${d}; multi-hop cross-boundary traversal beyond ${MAX_SUPPORTED_CROSS_DEPTH} is not implemented yet. Using crossDepth ${MAX_SUPPORTED_CROSS_DEPTH}.`,
+        };
+    }
+    return { depth: d };
+}
+export function validateGroupImpactParams(params) {
+    const name = String(params.name ?? '').trim();
+    const repoPath = String(params.repo ?? '').trim();
+    const target = String(params.target ?? '').trim();
+    if (!name)
+        return { ok: false, error: 'name is required' };
+    if (!repoPath)
+        return { ok: false, error: 'repo is required (group repo path, e.g. app/backend)' };
+    if (!target)
+        return { ok: false, error: 'target is required' };
+    if (params.service !== undefined &&
+        params.service !== null &&
+        String(params.service).trim() === '') {
+        return { ok: false, error: 'service must not be an empty string' };
+    }
+    const direction = parseDirection(params.direction);
+    if (!direction)
+        return { ok: false, error: 'direction must be upstream or downstream' };
+    let maxDepth = typeof params.maxDepth === 'number' && params.maxDepth > 0 ? params.maxDepth : 3;
+    if (maxDepth > 32)
+        maxDepth = 32;
+    const { depth: crossDepth, warning: crossDepthWarning } = clampCrossDepth(params.crossDepth);
+    const relationTypes = Array.isArray(params.relationTypes)
+        ? params.relationTypes.filter((t) => typeof t === 'string')
+        : undefined;
+    const includeTests = Boolean(params.includeTests);
+    let minConfidence = typeof params.minConfidence === 'number' ? params.minConfidence : 0;
+    if (minConfidence < 0)
+        minConfidence = 0;
+    if (minConfidence > 1)
+        minConfidence = 1;
+    const service = normalizeServicePrefix(params.service);
+    const subgroup = typeof params.subgroup === 'string' ? params.subgroup : undefined;
+    let timeoutMs = typeof params.timeoutMs === 'number' && params.timeoutMs > 0
+        ? params.timeoutMs
+        : typeof params.timeout === 'number' && params.timeout > 0
+            ? params.timeout
+            : DEFAULT_LOCAL_IMPACT_TIMEOUT_MS;
+    if (timeoutMs > 3_600_000)
+        timeoutMs = 3_600_000;
+    return {
+        ok: true,
+        name,
+        repoPath,
+        target,
+        direction,
+        maxDepth,
+        crossDepth,
+        crossDepthWarning,
+        relationTypes,
+        includeTests,
+        minConfidence,
+        service,
+        subgroup,
+        timeoutMs,
+    };
+}
+async function resolveGroupRepo(port, config, repoPath) {
+    const registryName = config.repos[repoPath];
+    if (!registryName) {
+        return { error: `Unknown repo path "${repoPath}" in this group.` };
+    }
+    try {
+        return await port.resolveRepo(registryName);
+    }
+    catch (e) {
+        return { error: e instanceof Error ? e.message : String(e) };
+    }
+}
+async function safeLocalImpact(port, repo, impactParams, timeoutMs) {
+    let timer;
+    const impactP = port.impact(repo, impactParams).catch((err) => ({
+        error: err instanceof Error ? err.message : String(err),
+    }));
+    const timeoutP = new Promise((resolve) => {
+        timer = setTimeout(() => resolve('timeout'), timeoutMs);
+    });
+    const won = await Promise.race([
+        impactP.then((v) => ({ tag: 'impact', v })),
+        timeoutP.then(() => ({ tag: 'timeout' })),
+    ]);
+    if (timer !== undefined)
+        clearTimeout(timer);
+    if (won.tag === 'timeout') {
+        return {
+            value: { error: 'Local impact timed out', partial: true },
+            timedOut: true,
+        };
+    }
+    return { value: won.v, timedOut: false };
+}
+export function collectImpactSymbolUids(local, servicePrefix) {
+    const uids = new Set();
+    let targetFilePath;
+    const obj = local;
+    if (!obj || typeof obj !== 'object')
+        return { uids: [], targetFilePath };
+    const target = obj.target;
+    if (target?.id) {
+        targetFilePath = typeof target.filePath === 'string' ? target.filePath : undefined;
+        if (fileMatchesServicePrefix(targetFilePath, servicePrefix)) {
+            uids.add(String(target.id));
+        }
+    }
+    const byDepth = obj.byDepth;
+    if (byDepth && typeof byDepth === 'object') {
+        for (const items of Object.values(byDepth)) {
+            if (!Array.isArray(items))
+                continue;
+            for (const it of items) {
+                const row = it;
+                if (row?.id && fileMatchesServicePrefix(row.filePath, servicePrefix)) {
+                    uids.add(String(row.id));
+                }
+            }
+        }
+    }
+    return { uids: [...uids], targetFilePath };
+}
+function extractProcessNames(impact) {
+    const o = impact;
+    if (!o?.affected_processes)
+        return [];
+    return o.affected_processes.map((p) => String(p.name ?? '')).filter(Boolean);
+}
+function mergeRisk(localRisk, cross) {
+    const highConf = cross.some((c) => c.contract.confidence >= 0.85);
+    if (localRisk === 'CRITICAL')
+        return 'CRITICAL';
+    if (cross.length >= 3)
+        return 'CRITICAL';
+    if (highConf)
+        return 'HIGH';
+    if (cross.length > 0 && (localRisk === 'LOW' || localRisk === 'UNKNOWN'))
+        return 'MEDIUM';
+    return localRisk;
+}
+async function ensureBridgeReady(groupDir) {
+    const meta = await readBridgeMeta(groupDir);
+    if (meta.version > 0 && meta.version !== BRIDGE_SCHEMA_VERSION) {
+        return {
+            error: `Bridge schema version mismatch (meta.json has ${meta.version}, expected ${BRIDGE_SCHEMA_VERSION}). Run gitnexus group sync for this group.`,
+        };
+    }
+    const dbPath = path.join(groupDir, 'bridge.lbug');
+    try {
+        await fsp.access(dbPath);
+    }
+    catch {
+        return {
+            error: `No bridge.lbug in this group directory. Run gitnexus group sync (schema ${BRIDGE_SCHEMA_VERSION}).`,
+        };
+    }
+    const handle = await openBridgeDbReadOnly(groupDir);
+    if (!handle) {
+        return {
+            error: `Could not open bridge.lbug read-only (schema ${BRIDGE_SCHEMA_VERSION}). Run gitnexus group sync.`,
+        };
+    }
+    return { handle };
+}
+function rowToNeighbor(r) {
+    const neighborRepo = String(r.neighborRepo ?? r[0] ?? '');
+    const neighborUid = String(r.neighborUid ?? r[1] ?? '');
+    if (!neighborRepo || !neighborUid)
+        return null;
+    return {
+        neighborRepo,
+        neighborUid,
+        neighborFilePath: r.neighborFilePath !== undefined ? String(r.neighborFilePath) : String(r[2] ?? ''),
+        matchType: String(r.matchType ?? r[3] ?? 'exact'),
+        confidence: Number(r.confidence ?? r[4] ?? 0),
+        contractId: String(r.contractId ?? r[5] ?? ''),
+        contractType: String(r.contractType ?? r[6] ?? 'custom'),
+    };
+}
+export async function runGroupImpact(deps, params) {
+    const parsed = validateGroupImpactParams(params);
+    if (parsed.ok === false)
+        return { error: parsed.error };
+    const { name, repoPath, target, direction, maxDepth, crossDepth: _crossDepth, crossDepthWarning, relationTypes, includeTests, minConfidence, service: servicePrefix, subgroup, timeoutMs, } = parsed;
+    const groupDir = getGroupDir(deps.gitnexusDir, name);
+    let config;
+    try {
+        config = await loadGroupConfig(groupDir);
+    }
+    catch (e) {
+        return { error: e instanceof Error ? e.message : String(e) };
+    }
+    const resolved = await resolveGroupRepo(deps.port, config, repoPath);
+    if ('error' in resolved)
+        return { error: resolved.error };
+    const impactParams = {
+        target,
+        direction,
+        maxDepth,
+        relationTypes: relationTypes && relationTypes.length > 0 ? relationTypes : undefined,
+        includeTests,
+        minConfidence,
+    };
+    // Single shared deadline for Phase 1 (local walk) + Phase 2 (bridge fan-out).
+    // Phase 1 still gets the full budget; Phase 2 only uses whatever wall-clock
+    // time is left, so total work cannot exceed `timeoutMs`.
+    const deadline = Date.now() + Math.max(0, timeoutMs);
+    const { value: local, timedOut: localTimedOut } = await safeLocalImpact(deps.port, resolved, impactParams, timeoutMs);
+    if (localTimedOut) {
+        const base = local;
+        return {
+            local,
+            group: name,
+            cross: [],
+            outOfScope: [],
+            truncated: true,
+            truncatedRepos: [],
+            summary: {
+                direct: 0,
+                processes_affected: 0,
+                modules_affected: 0,
+                cross_repo_hits: 0,
+            },
+            risk: 'UNKNOWN',
+            timeoutMs,
+            truncationReason: 'timeout',
+            crossDepthWarning,
+        };
+    }
+    const localObj = local;
+    if (localObj?.error && typeof localObj.error === 'string') {
+        const empty = {
+            local,
+            group: name,
+            cross: [],
+            outOfScope: [],
+            truncated: false,
+            truncatedRepos: [],
+            summary: {
+                direct: 0,
+                processes_affected: 0,
+                modules_affected: 0,
+                cross_repo_hits: 0,
+            },
+            risk: 'UNKNOWN',
+            timeoutMs,
+            crossDepthWarning,
+        };
+        return empty;
+    }
+    if (servicePrefix) {
+        const tf = localObj?.target?.filePath;
+        if (!fileMatchesServicePrefix(tf, servicePrefix)) {
+            return {
+                local: {},
+                group: name,
+                cross: [],
+                outOfScope: [],
+                truncated: false,
+                truncatedRepos: [],
+                summary: {
+                    direct: 0,
+                    processes_affected: 0,
+                    modules_affected: 0,
+                    cross_repo_hits: 0,
+                },
+                risk: 'LOW',
+                timeoutMs,
+                crossDepthWarning,
+            };
+        }
+    }
+    const { uids } = collectImpactSymbolUids(local, servicePrefix);
+    if (uids.length === 0) {
+        const s = local?.summary || {};
+        return {
+            local,
+            group: name,
+            cross: [],
+            outOfScope: [],
+            truncated: Boolean(local.partial),
+            truncatedRepos: [],
+            summary: {
+                direct: s.direct ?? 0,
+                processes_affected: s.processes_affected ?? 0,
+                modules_affected: s.modules_affected ?? 0,
+                cross_repo_hits: 0,
+            },
+            risk: String(local.risk ?? 'LOW'),
+            timeoutMs,
+            truncationReason: local.partial ? 'partial' : undefined,
+            crossDepthWarning,
+        };
+    }
+    const bridgePrep = await ensureBridgeReady(groupDir);
+    if ('error' in bridgePrep)
+        return { error: bridgePrep.error };
+    const handle = bridgePrep.handle;
+    const cross = [];
+    const outOfScope = [];
+    const truncatedRepos = [];
+    try {
+        const cypher = direction === 'upstream' ? CY_NEIGHBORS_UPSTREAM : CY_NEIGHBORS_DOWNSTREAM;
+        const rows = await queryBridge(handle, cypher, {
+            localRepo: repoPath,
+            uids,
+        });
+        const neighbors = [];
+        for (const raw of rows) {
+            const n = rowToNeighbor(raw);
+            if (n)
+                neighbors.push(n);
+        }
+        neighbors.sort((a, b) => b.confidence - a.confidence);
+        const seen = new Set();
+        for (const n of neighbors) {
+            if (servicePrefix && !fileMatchesServicePrefix(n.neighborFilePath, servicePrefix)) {
+                continue;
+            }
+            if (!repoInSubgroup(n.neighborRepo, subgroup)) {
+                // CrossLink convention: consumer -> provider
+                outOfScope.push({
+                    from: direction === 'upstream' ? n.neighborRepo : repoPath,
+                    to: direction === 'upstream' ? repoPath : n.neighborRepo,
+                    contractId: n.contractId,
+                    confidence: n.confidence,
+                });
+                continue;
+            }
+            const key = `${n.neighborRepo}\0${n.neighborUid}\0${n.contractId}`;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            if (Date.now() > deadline) {
+                truncatedRepos.push(n.neighborRepo);
+                continue;
+            }
+            const regName = config.repos[n.neighborRepo];
+            if (!regName)
+                continue;
+            let neighborHandle;
+            try {
+                neighborHandle = await deps.port.resolveRepo(regName);
+            }
+            catch {
+                truncatedRepos.push(n.neighborRepo);
+                continue;
+            }
+            const fan = await deps.port.impactByUid(neighborHandle.id, n.neighborUid, direction, {
+                maxDepth,
+                relationTypes: relationTypes ?? [],
+                minConfidence,
+                includeTests,
+            });
+            if (fan == null) {
+                truncatedRepos.push(n.neighborRepo);
+                continue;
+            }
+            cross.push({
+                repo: regName,
+                repo_path: n.neighborRepo,
+                contract: {
+                    id: n.contractId,
+                    type: n.contractType,
+                    match_type: n.matchType || 'exact',
+                    confidence: n.confidence,
+                },
+                by_depth: (fan.byDepth ?? {}),
+                affected_processes: extractProcessNames(fan),
+            });
+        }
+    }
+    finally {
+        await closeBridgeDb(handle);
+    }
+    const localSum = local?.summary || {};
+    const localRisk = String(local.risk ?? 'LOW');
+    const localPartial = Boolean(local.partial);
+    const truncated = truncatedRepos.length > 0 || localPartial;
+    const result = {
+        local,
+        group: name,
+        cross,
+        outOfScope,
+        truncated,
+        truncatedRepos: [...new Set(truncatedRepos)],
+        summary: {
+            direct: localSum.direct ?? 0,
+            processes_affected: localSum.processes_affected ?? 0,
+            modules_affected: localSum.modules_affected ?? 0,
+            cross_repo_hits: cross.length,
+        },
+        risk: mergeRisk(localRisk, cross),
+        timeoutMs,
+        truncationReason: truncated ? 'partial' : undefined,
+        crossDepthWarning,
+    };
+    return result;
+}
+export { normalizeServicePrefix, fileMatchesServicePrefix } from './group-path-utils.js';

package/dist/core/group/group-path-utils.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Shared service-path normalization for group tools (`service` monorepo filter)
+ * and subgroup membership checks.
+ *
+ * Inputs may originate from tree-sitter, the OS file API, or user-supplied
+ * MCP arguments, so both `\` and `/` separators are accepted. Internally we
+ * normalize to POSIX-style `/` for case-sensitive segment comparisons.
+ */
+export declare function normalizeServicePrefix(service: unknown): string | undefined;
+export declare function fileMatchesServicePrefix(filePath: string | undefined, prefix: string | undefined): boolean;
+/**
+ * True if `repoPath` is at or beneath `subgroup` (member-path prefix in
+ * `group.yaml`). Empty / missing `subgroup` matches every repo.
+ *
+ * @param exact When set, requires an exact equality match (no descendant repos).
+ */
+export declare function repoInSubgroup(repoPath: string, subgroup?: string, exact?: boolean): boolean;

package/dist/core/group/group-path-utils.js

@@ -0,0 +1,40 @@
+/**
+ * Shared service-path normalization for group tools (`service` monorepo filter)
+ * and subgroup membership checks.
+ *
+ * Inputs may originate from tree-sitter, the OS file API, or user-supplied
+ * MCP arguments, so both `\` and `/` separators are accepted. Internally we
+ * normalize to POSIX-style `/` for case-sensitive segment comparisons.
+ */
+function toPosix(p) {
+    return p.replace(/\\/g, '/');
+}
+export function normalizeServicePrefix(service) {
+    if (service === undefined || service === null)
+        return undefined;
+    const s = toPosix(String(service)).trim().replace(/\/+$/, '');
+    return s.length > 0 ? s : undefined;
+}
+export function fileMatchesServicePrefix(filePath, prefix) {
+    if (!prefix)
+        return true;
+    if (!filePath)
+        return false;
+    const normalized = toPosix(filePath);
+    return normalized === prefix || normalized.startsWith(`${prefix}/`);
+}
+/**
+ * True if `repoPath` is at or beneath `subgroup` (member-path prefix in
+ * `group.yaml`). Empty / missing `subgroup` matches every repo.
+ *
+ * @param exact When set, requires an exact equality match (no descendant repos).
+ */
+export function repoInSubgroup(repoPath, subgroup, exact) {
+    if (!subgroup?.trim())
+        return true;
+    const s = toPosix(subgroup).replace(/\/+$/, '');
+    const r = toPosix(repoPath);
+    if (exact)
+        return r === s;
+    return r === s || r.startsWith(`${s}/`);
+}

package/dist/core/group/resolve-at-member.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Map MCP/CLI `@groupName` or `@groupName/memberPath` to a concrete member path in group.yaml.
+ */
+export declare function resolveAtGroupMemberRepoPath(groupName: string, explicitMemberPath: string | undefined): Promise<{
+    ok: true;
+    repoPath: string;
+} | {
+    ok: false;
+    error: string;
+}>;

package/dist/core/group/resolve-at-member.js

@@ -0,0 +1,31 @@
+/**
+ * Map MCP/CLI `@groupName` or `@groupName/memberPath` to a concrete member path in group.yaml.
+ */
+import { loadGroupConfig } from './config-parser.js';
+import { getDefaultGitnexusDir, getGroupDir } from './storage.js';
+export async function resolveAtGroupMemberRepoPath(groupName, explicitMemberPath) {
+    const trimmed = groupName.trim();
+    if (!trimmed)
+        return { ok: false, error: 'Group name is empty.' };
+    try {
+        const groupDir = getGroupDir(getDefaultGitnexusDir(), trimmed);
+        const config = await loadGroupConfig(groupDir);
+        const keys = Object.keys(config.repos).sort((a, b) => a.localeCompare(b));
+        if (keys.length === 0) {
+            return { ok: false, error: `Group "${trimmed}" has no repos in group.yaml.` };
+        }
+        if (explicitMemberPath !== undefined && explicitMemberPath !== '') {
+            if (!(explicitMemberPath in config.repos)) {
+                return {
+                    ok: false,
+                    error: `Unknown member path "${explicitMemberPath}" in group "${trimmed}". Known paths: ${keys.join(', ')}`,
+                };
+            }
+            return { ok: true, repoPath: explicitMemberPath };
+        }
+        return { ok: true, repoPath: keys[0] };
+    }
+    catch (e) {
+        return { ok: false, error: e instanceof Error ? e.message : String(e) };
+    }
+}