arceus-s 1.6.4

package/dist/core/group/service.js

@@ -0,0 +1,395 @@
+/**
+ * Group orchestration shared by MCP (LocalBackend) and CLI.
+ * DB access is injected via GroupToolPort so this module stays free of LocalBackend private API.
+ */
+import fsp from 'node:fs/promises';
+import path from 'node:path';
+import { checkStaleness } from '../git-staleness.js';
+import { GroupNotFoundError, loadGroupConfig } from './config-parser.js';
+import { fileMatchesServicePrefix, normalizeServicePrefix, repoInSubgroup, } from './group-path-utils.js';
+import { getDefaultArceusDir, getGroupDir, listGroups, readContractRegistry } from './storage.js';
+import { syncGroup } from './sync.js';
+import { logger } from '../logger.js';
+function isStoredContract(raw) {
+    if (!raw || typeof raw !== 'object')
+        return false;
+    const o = raw;
+    return (typeof o.contractId === 'string' &&
+        typeof o.type === 'string' &&
+        typeof o.repo === 'string' &&
+        typeof o.role === 'string' &&
+        (o.role === 'provider' || o.role === 'consumer') &&
+        typeof o.symbolUid === 'string' &&
+        typeof o.symbolName === 'string' &&
+        typeof o.confidence === 'number' &&
+        o.meta !== undefined &&
+        typeof o.meta === 'object' &&
+        o.meta !== null &&
+        o.symbolRef !== undefined &&
+        typeof o.symbolRef === 'object' &&
+        o.symbolRef !== null &&
+        typeof o.symbolRef.filePath === 'string' &&
+        typeof o.symbolRef.name === 'string');
+}
+function filterQueryByServicePrefix(queryResult, servicePrefix) {
+    const symbols = (queryResult.process_symbols || []).filter((s) => fileMatchesServicePrefix(typeof s.filePath === 'string' ? s.filePath : undefined, servicePrefix));
+    const allowed = new Set(symbols.map((s) => String(s.process_id ?? '')).filter(Boolean));
+    const processes = (queryResult.processes || []).filter((p) => allowed.has(String(p.id)));
+    return { processes, process_symbols: symbols };
+}
+function isCrossLink(raw) {
+    if (!raw || typeof raw !== 'object')
+        return false;
+    const o = raw;
+    const from = o.from;
+    const to = o.to;
+    if (!from || !to)
+        return false;
+    if (typeof from.repo !== 'string' || typeof to.repo !== 'string')
+        return false;
+    return typeof o.contractId === 'string' && typeof o.type === 'string';
+}
+async function loadContractRegistryResilient(groupDir) {
+    const filePath = path.join(groupDir, 'contracts.json');
+    let raw;
+    try {
+        raw = await fsp.readFile(filePath, 'utf-8');
+    }
+    catch (e) {
+        if (e.code === 'ENOENT') {
+            return { ok: false, error: `No contracts.json for this group. Run group_sync first.` };
+        }
+        return { ok: false, error: e instanceof Error ? e.message : String(e) };
+    }
+    let root;
+    try {
+        root = JSON.parse(raw);
+    }
+    catch {
+        return { ok: false, error: 'contracts.json is not valid JSON' };
+    }
+    if (!root || typeof root !== 'object' || Array.isArray(root)) {
+        return { ok: false, error: 'contracts.json has an invalid root object' };
+    }
+    const base = root;
+    const contractsRaw = base.contracts;
+    const crossRaw = base.crossLinks;
+    let skippedCorrupt = 0;
+    const contracts = [];
+    if (Array.isArray(contractsRaw)) {
+        for (const row of contractsRaw) {
+            try {
+                if (isStoredContract(row)) {
+                    contracts.push(row);
+                }
+                else {
+                    skippedCorrupt++;
+                    logger.warn('[group] skipping corrupt contract row in contracts.json');
+                }
+            }
+            catch {
+                skippedCorrupt++;
+                logger.warn('[group] skipping corrupt contract row in contracts.json');
+            }
+        }
+    }
+    const crossLinks = [];
+    if (Array.isArray(crossRaw)) {
+        for (const row of crossRaw) {
+            try {
+                if (isCrossLink(row)) {
+                    crossLinks.push(row);
+                }
+                else {
+                    skippedCorrupt++;
+                    logger.warn('[group] skipping corrupt crossLinks row in contracts.json');
+                }
+            }
+            catch {
+                skippedCorrupt++;
+                logger.warn('[group] skipping corrupt crossLinks row in contracts.json');
+            }
+        }
+    }
+    const registry = {
+        version: typeof base.version === 'number' ? base.version : 0,
+        generatedAt: typeof base.generatedAt === 'string' ? base.generatedAt : '',
+        repoSnapshots: base.repoSnapshots && typeof base.repoSnapshots === 'object' && base.repoSnapshots !== null
+            ? base.repoSnapshots
+            : {},
+        missingRepos: Array.isArray(base.missingRepos) ? base.missingRepos : [],
+        contracts,
+        crossLinks,
+    };
+    return { ok: true, registry, skippedCorrupt };
+}
+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(getDefaultArceusDir(), name);
+        let config;
+        try {
+            config = await loadGroupConfig(groupDir);
+        }
+        catch (err) {
+            if (err instanceof GroupNotFoundError)
+                return { error: `Group "${name}" not found. Run group_list to see configured groups.` };
+            throw err;
+        }
+        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(getDefaultArceusDir(), name);
+        let config;
+        try {
+            config = await loadGroupConfig(groupDir);
+        }
+        catch (err) {
+            if (err instanceof GroupNotFoundError)
+                return { error: `Group "${name}" not found. Run group_list to see configured groups.` };
+            throw err;
+        }
+        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(getDefaultArceusDir(), name);
+        const loaded = await loadContractRegistryResilient(groupDir);
+        if (loaded.ok === false) {
+            if (loaded.error.includes('No contracts.json')) {
+                return { error: `No contracts.json for group "${name}". Run group_sync first.` };
+            }
+            return { error: loaded.error };
+        }
+        const { registry, skippedCorrupt } = loaded;
+        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}`));
+        }
+        const out = { contracts, crossLinks: registry.crossLinks };
+        if (skippedCorrupt > 0)
+            out.skippedCorrupt = skippedCorrupt;
+        return out;
+    }
+    async groupImpact(params) {
+        const { runGroupImpact } = await import('./cross-impact.js');
+        return runGroupImpact({ port: this.port, arcDir: getDefaultArceusDir() }, params);
+    }
+    async groupContext(params) {
+        const name = String(params.name ?? '').trim();
+        const target = typeof params.target === 'string' ? params.target.trim() : '';
+        const uid = typeof params.uid === 'string' ? params.uid.trim() : undefined;
+        const file_path = typeof params.file_path === 'string' ? params.file_path : undefined;
+        const include_content = Boolean(params.include_content);
+        if (params.service !== undefined &&
+            params.service !== null &&
+            String(params.service).trim() === '') {
+            return { group: name || '', error: 'service must not be an empty string', results: [] };
+        }
+        const servicePrefix = normalizeServicePrefix(params.service);
+        const subgroup = typeof params.subgroup === 'string' ? params.subgroup : undefined;
+        const subgroupExact = params.subgroupExact === true;
+        if (!name) {
+            return { group: '', error: 'name is required', results: [] };
+        }
+        if (!uid && !target) {
+            return { group: name, error: 'target or uid is required', results: [] };
+        }
+        const groupDir = getGroupDir(getDefaultArceusDir(), name);
+        let config;
+        try {
+            config = await loadGroupConfig(groupDir);
+        }
+        catch (e) {
+            if (e instanceof GroupNotFoundError)
+                return {
+                    group: name,
+                    target: target || uid,
+                    service: servicePrefix,
+                    error: `Group "${name}" not found. Run group_list to see configured groups.`,
+                    results: [],
+                };
+            return {
+                group: name,
+                target: target || uid,
+                service: servicePrefix,
+                error: e instanceof Error ? e.message : String(e),
+                results: [],
+            };
+        }
+        const memberEntries = Object.entries(config.repos).filter(([repoPath]) => repoInSubgroup(repoPath, subgroup, subgroupExact));
+        const results = await Promise.all(memberEntries.map(async ([repoPath, registryName]) => {
+            try {
+                const repoObj = await this.port.resolveRepo(registryName);
+                const payload = await this.port.context(repoObj, {
+                    name: target || undefined,
+                    uid,
+                    file_path,
+                    include_content,
+                });
+                if (servicePrefix) {
+                    const st = payload?.status;
+                    const sym = payload?.symbol;
+                    if (st === 'found' && !fileMatchesServicePrefix(sym?.filePath, servicePrefix)) {
+                        return { repoPath, registryName, payload: {} };
+                    }
+                }
+                return { repoPath, registryName, payload };
+            }
+            catch (e) {
+                return {
+                    repoPath,
+                    registryName,
+                    payload: { error: e instanceof Error ? e.message : String(e) },
+                };
+            }
+        }));
+        return {
+            group: name,
+            target: target || uid,
+            service: servicePrefix,
+            results,
+        };
+    }
+    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' };
+        if (params.service !== undefined &&
+            params.service !== null &&
+            String(params.service).trim() === '') {
+            return { error: 'service must not be an empty string' };
+        }
+        const servicePrefix = normalizeServicePrefix(params.service);
+        const limit = typeof params.limit === 'number' && params.limit > 0 ? params.limit : 5;
+        const subgroup = typeof params.subgroup === 'string' ? params.subgroup : undefined;
+        const subgroupExact = params.subgroupExact === true;
+        const groupDir = getGroupDir(getDefaultArceusDir(), name);
+        let config;
+        try {
+            config = await loadGroupConfig(groupDir);
+        }
+        catch (err) {
+            if (err instanceof GroupNotFoundError)
+                return { error: `Group "${name}" not found. Run group_list to see configured groups.` };
+            throw err;
+        }
+        const memberEntries = Object.entries(config.repos).filter(([repoPath]) => repoInSubgroup(repoPath, subgroup, subgroupExact));
+        const perRepo = await Promise.all(memberEntries.map(async ([repoPath, registryName]) => {
+            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 = servicePrefix
+                    ? filterQueryByServicePrefix(queryResult, servicePrefix).processes
+                    : queryResult.processes || [];
+                const scored = processes.map((p, idx) => ({
+                    ...p,
+                    _rrf_score: 1 / (idx + 1 + 60),
+                    _repo: repoPath,
+                }));
+                return { repo: repoPath, score: 0, processes: scored };
+            }
+            catch {
+                return { 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(getDefaultArceusDir(), name);
+        let config;
+        try {
+            config = await loadGroupConfig(groupDir);
+        }
+        catch (err) {
+            if (err instanceof GroupNotFoundError)
+                return { error: `Group "${name}" not found. Run group_list to see configured groups.` };
+            throw err;
+        }
+        const registry = await readContractRegistry(groupDir);
+        const repoStatuses = {};
+        for (const [repoPath, registryName] of Object.entries(config.repos)) {
+            try {
+                const repoObj = await this.port.resolveRepo(registryName);
+                const metaPath = path.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,
+        };
+    }
+}

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

@@ -0,0 +1,9 @@
+import type { ContractRegistry } from './types.js';
+export declare function getDefaultArceusDir(): string;
+export declare function getGroupsBaseDir(arcDir?: string): string;
+export declare function validateGroupName(name: string): void;
+export declare function getGroupDir(arcDir: string, groupName: string): string;
+export declare function writeContractRegistry(groupDir: string, registry: ContractRegistry): Promise<void>;
+export declare function readContractRegistry(groupDir: string): Promise<ContractRegistry | null>;
+export declare function listGroups(arcDir?: string): Promise<string[]>;
+export declare function createGroupDir(arcDir: string, groupName: string, force?: boolean): Promise<string>;

package/dist/core/group/storage.js

@@ -0,0 +1,157 @@
+import * as fs from 'node:fs';
+import * as fsp from 'node:fs/promises';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import { randomBytes } from 'node:crypto';
+import { retryRename } from './bridge-db.js';
+/**
+ * Build an unpredictable suffix for atomic-write tmp files. Replaces the
+ * previous `Date.now()` pattern which CodeQL flagged as
+ * js/insecure-temporary-file: a guessable suffix in a writable directory
+ * lets a co-located attacker pre-create or symlink the tmp path before the
+ * write lands.
+ */
+const tmpSuffix = () => randomBytes(8).toString('hex');
+const CONTRACTS_FILE = 'contracts.json';
+export function getDefaultArceusDir() {
+    return process.env.ARC_HOME || path.join(os.homedir(), '.arc');
+}
+export function getGroupsBaseDir(arcDir) {
+    return path.join(arcDir || getDefaultArceusDir(), 'groups');
+}
+const GROUP_NAME_RE = /^[a-zA-Z0-9][a-zA-Z0-9_-]*$/;
+export function validateGroupName(name) {
+    if (!GROUP_NAME_RE.test(name)) {
+        throw new Error(`Invalid group name "${name}". Names must start with a letter or digit and contain only [a-zA-Z0-9_-].`);
+    }
+}
+export function getGroupDir(arcDir, groupName) {
+    validateGroupName(groupName);
+    return path.join(arcDir, 'groups', groupName);
+}
+export async function writeContractRegistry(groupDir, registry) {
+    const targetPath = path.join(groupDir, CONTRACTS_FILE);
+    const tmpPath = `${targetPath}.tmp.${tmpSuffix()}`;
+    // O_EXCL via `'wx'` flag + explicit `0o600` mode — closes both halves
+    // of the CodeQL js/insecure-temporary-file finding: `'wx'` rejects a
+    // pre-planted symlink at the path, and `0o600` (user-only) prevents
+    // the file from being created group/world readable while it briefly
+    // contains contract data en route to the rename. The query's
+    // `isSecureMode` predicate inspects ONLY the mode argument, not the
+    // flags, so the explicit mode is what credits the fix.
+    const handle = await fsp.open(tmpPath, 'wx', 0o600);
+    try {
+        await handle.writeFile(JSON.stringify(registry, null, 2), 'utf-8');
+    }
+    finally {
+        await handle.close();
+    }
+    // retryRename absorbs the documented Windows EPERM/EBUSY/EACCES race that
+    // fires when AV scanners or another concurrent rename briefly hold the
+    // destination handle between rename calls. Same helper bridge-db.ts uses
+    // (lines 304, 583, 587, 595, 605, 677) for the bridge.lbug atomic swap —
+    // single source of truth for the Windows-rename pattern across the group
+    // package.
+    await retryRename(tmpPath, targetPath);
+}
+export async function readContractRegistry(groupDir) {
+    const filePath = path.join(groupDir, CONTRACTS_FILE);
+    try {
+        const content = await fsp.readFile(filePath, 'utf-8');
+        return JSON.parse(content);
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return null;
+        throw err;
+    }
+}
+export async function listGroups(arcDir) {
+    const groupsDir = getGroupsBaseDir(arcDir);
+    try {
+        const entries = await fsp.readdir(groupsDir, { withFileTypes: true });
+        const names = [];
+        for (const entry of entries) {
+            if (entry.isDirectory()) {
+                const yamlPath = path.join(groupsDir, entry.name, 'group.yaml');
+                if (fs.existsSync(yamlPath)) {
+                    names.push(entry.name);
+                }
+            }
+        }
+        return names;
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return [];
+        throw err;
+    }
+}
+export async function createGroupDir(arcDir, groupName, force = false) {
+    const groupDir = getGroupDir(arcDir, groupName);
+    if (fs.existsSync(path.join(groupDir, 'group.yaml')) && !force) {
+        throw new Error(`Group "${groupName}" already exists. Use --force to overwrite.`);
+    }
+    await fsp.mkdir(groupDir, { recursive: true });
+    const template = `version: 1
+name: ${groupName}
+description: ""
+
+repos: {}
+
+links: []
+
+packages: {}
+
+detect:
+  http: true
+  grpc: true
+  topics: true
+  shared_libs: true
+  embedding_fallback: true
+
+matching:
+  bm25_threshold: 0.7
+  embedding_threshold: 0.65
+  max_candidates_per_step: 3
+  # exclude_links_paths: [/ping, /health, /healthcheck]
+  # exclude_links_param_only_paths: false
+`;
+    // Always write group.yaml with O_EXCL via `fsp.open(..., 'wx')` —
+    // refuses to follow a pre-planted symlink at the target path, closing
+    // the TOCTOU window between the existence check (line ~98) and the
+    // write that CodeQL js/insecure-temporary-file flags. Under
+    // `force=true` we unlink the existing file first (best-effort, no-op
+    // when absent) so the subsequent O_EXCL open succeeds AND the same
+    // symlink-rejection guarantee holds — this is strictly safer than
+    // the previous `flag: force ? 'w' : 'wx'` shape, which silently
+    // followed symlinks under force. CodeQL's rule does not recognize
+    // the `writeFile(path, content, { flag: 'wx' })` shape as O_EXCL;
+    // the explicit open() handle below is what credits the mitigation.
+    const yamlPath = path.join(groupDir, 'group.yaml');
+    if (force) {
+        try {
+            await fsp.unlink(yamlPath);
+        }
+        catch (err) {
+            // ENOENT (file absent) is expected on first run; rethrow anything
+            // else so we don't silently mask permission/EBUSY failures.
+            if (err.code !== 'ENOENT')
+                throw err;
+        }
+    }
+    // `'wx'` rejects a pre-planted symlink at the path; `0o600` is
+    // user-only (no group/world bits) — arc storage is per-user
+    // (`~/.arc/...`), so any "other user wants to read this" case is
+    // a misconfiguration, not a feature. Keeping the file user-only also
+    // satisfies CodeQL's `isSecureMode` predicate (low 6 bits == 0) and
+    // closes the js/insecure-temporary-file alert at this site.
+    const handle = await fsp.open(yamlPath, 'wx', 0o600);
+    try {
+        await handle.writeFile(template, 'utf-8');
+    }
+    finally {
+        await handle.close();
+    }
+    return groupDir;
+}

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

@@ -0,0 +1,21 @@
+import { type RegistryEntry } from '../../storage/repo-manager.js';
+import type { GroupConfig, RepoHandle, RepoSnapshot, StoredContract, CrossLink } from './types.js';
+export interface SyncOptions {
+    extractorOverride?: ((repo: RepoHandle) => Promise<StoredContract[]>) | (() => Promise<StoredContract[]>);
+    resolveRepoHandle?: (registryName: string, groupPath: string) => Promise<RepoHandle | null>;
+    skipWrite?: boolean;
+    groupDir?: string;
+    allowStale?: boolean;
+    verbose?: boolean;
+    exactOnly?: boolean;
+    skipEmbeddings?: boolean;
+}
+export interface SyncResult {
+    contracts: StoredContract[];
+    crossLinks: CrossLink[];
+    unmatched: StoredContract[];
+    missingRepos: string[];
+    repoSnapshots: Record<string, RepoSnapshot>;
+}
+export declare function stableRepoPoolId(entry: RegistryEntry, allEntries: RegistryEntry[]): string;
+export declare function syncGroup(config: GroupConfig, opts?: SyncOptions): Promise<SyncResult>;