gitnexus 1.6.11-rc.8 → 1.6.11

package/dist/server/grep-params.js

@@ -0,0 +1,83 @@
+/**
+ * Query-parameter parsing for GET /api/grep.
+ *
+ * Extracted from api.ts so the contract is unit-testable without pulling
+ * Express + the LadybugDB native adapter into the test run (same rationale
+ * as the #2790 helper extraction).
+ *
+ * Contract fix (Patch 12): the grep tool schema in gitnexus-web has always
+ * promised regex search with an optional path-substring filter and
+ * case-sensitivity control, but the handler used to escapeRegExp() every
+ * pattern into a literal substring — an agent asking for "sign|Sign" got
+ * zero hits and concluded the code didn't exist, and the schema's own
+ * example ("console\.log") could never match. This restores the promised
+ * semantics. Matching runs in a worker_threads worker (`grep-worker.ts`) so
+ * `terminate()` can interrupt a catastrophic `regex.test()` when the
+ * wall-clock budget expires; the parent event loop stays responsive.
+ * Bounded mitigations:
+ *   - pattern length cap (200 chars, unchanged from the literal-only era)
+ *   - line-by-line matching (each regex.test call sees one source line)
+ *   - a wall-clock budget the parent enforces via worker terminate()
+ *   - result cap unchanged (limit, max 200)
+ *   - literal=1 opt-out restores the old escaped-substring immunity
+ */
+import { assertString, escapeRegExp, BadRequestError } from './validation.js';
+/** Hard cap on pattern length — unchanged from the literal-only era. */
+export const GREP_PATTERN_MAX_LENGTH = 200;
+/** Wall-clock budget for one /api/grep call; parent terminate()s the scan worker. */
+export const GREP_TIME_BUDGET_MS = 5_000;
+export const GREP_DEFAULT_LIMIT = 50;
+export const GREP_MAX_LIMIT = 200;
+const isFlagTrue = (value, name) => {
+    const s = assertString(value ?? '', name).toLowerCase();
+    return s === '1' || s === 'true';
+};
+/**
+ * Parse /api/grep query parameters into a ready-to-use regex + filters.
+ * Throws BadRequestError (mapped to HTTP 400 by statusFromError) on
+ * missing/over-long patterns or invalid regex syntax.
+ */
+export function parseGrepQuery(query) {
+    if (query.pattern === undefined) {
+        throw new BadRequestError('Missing "pattern" query parameter');
+    }
+    const pattern = assertString(query.pattern, 'pattern');
+    if (pattern.length === 0) {
+        throw new BadRequestError('Missing "pattern" query parameter');
+    }
+    if (pattern.length > GREP_PATTERN_MAX_LENGTH) {
+        throw new BadRequestError(`Pattern too long (max ${GREP_PATTERN_MAX_LENGTH} characters)`);
+    }
+    // Regex semantics by default — what the tool schema always promised.
+    // literal=1 opts back into the escaped-substring behaviour of the
+    // literal-only era for callers that want it verbatim.
+    const caseSensitive = isFlagTrue(query.caseSensitive, 'caseSensitive');
+    const flags = caseSensitive ? '' : 'i';
+    let regex;
+    try {
+        // Deliberately no 'g' flag: the handler tests line-by-line and a
+        // stateful lastIndex across lines would skip matches (the old handler
+        // had to reset it manually). No 'm' either: each test receives a
+        // single line, so ^/$ already anchor at string boundaries — 'm'
+        // would be a no-op.
+        if (isFlagTrue(query.literal, 'literal')) {
+            regex = new RegExp(escapeRegExp(pattern), flags);
+        }
+        else {
+            // Intentional: /api/grep advertises real regex (see file header + SECURITY.md).
+            // ReDoS is mitigated by running the scan in a worker and terminate()-ing it.
+            // codeql[js/regex-injection]
+            regex = new RegExp(pattern, flags);
+        }
+    }
+    catch {
+        throw new BadRequestError('Invalid regex pattern');
+    }
+    // Path-substring filter, case-insensitive ("Controller.java", "src/api").
+    const fileFilter = assertString(query.fileFilter ?? '', 'fileFilter').toLowerCase();
+    const parsedLimit = Number(query.limit ?? GREP_DEFAULT_LIMIT);
+    const limit = Number.isFinite(parsedLimit)
+        ? Math.max(1, Math.min(GREP_MAX_LIMIT, Math.trunc(parsedLimit)))
+        : GREP_DEFAULT_LIMIT;
+    return { regex, fileFilter, limit };
+}

package/dist/server/grep-scan.d.ts

@@ -0,0 +1,23 @@
+export interface GrepHit {
+    filePath: string;
+    line: number;
+    text: string;
+}
+export interface GrepScanInput {
+    repoRoot: string;
+    /** Repo-relative paths already filtered by fileFilter. */
+    filePaths: string[];
+    pattern: string;
+    flags: string;
+    limit: number;
+    /** Absolute Date.now() deadline. */
+    deadlineMs: number;
+}
+export interface GrepScanResult {
+    results: GrepHit[];
+    timedOut: boolean;
+}
+export type GrepProgress = (partial: GrepScanResult) => void;
+export declare function scanGrepFiles(input: GrepScanInput, onProgress?: GrepProgress): Promise<GrepScanResult>;
+export declare function grepWorkerPath(): string;
+export declare function runGrepScanInWorker(input: GrepScanInput): Promise<GrepScanResult>;

package/dist/server/grep-scan.js

@@ -0,0 +1,107 @@
+/**
+ * Filesystem grep scan used by GET /api/grep.
+ *
+ * Matching runs in a worker_threads worker (see grep-worker.ts) so a
+ * catastrophic `regex.test()` can be killed with terminate() when the
+ * wall-clock budget expires. The parent event loop stays responsive.
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { Worker } from 'node:worker_threads';
+export async function scanGrepFiles(input, onProgress) {
+    const regex = new RegExp(input.pattern, input.flags);
+    const results = [];
+    const repoRoot = path.resolve(input.repoRoot);
+    const safeRepoRoot = repoRoot.endsWith(path.sep) ? repoRoot : repoRoot + path.sep;
+    let timedOut = false;
+    files: for (const filePath of input.filePaths) {
+        if (results.length >= input.limit)
+            break;
+        if (Date.now() > input.deadlineMs) {
+            timedOut = true;
+            break;
+        }
+        const fullPath = path.resolve(repoRoot, filePath);
+        if (!fullPath.startsWith(safeRepoRoot) && fullPath !== repoRoot)
+            continue;
+        let content;
+        try {
+            content = await fs.readFile(fullPath, 'utf-8');
+        }
+        catch {
+            continue;
+        }
+        const lines = content.split('\n');
+        for (let i = 0; i < lines.length; i++) {
+            if (results.length >= input.limit)
+                break files;
+            if ((i & 255) === 0 && Date.now() > input.deadlineMs) {
+                timedOut = true;
+                break files;
+            }
+            regex.lastIndex = 0;
+            if (regex.test(lines[i])) {
+                results.push({ filePath, line: i + 1, text: lines[i].trim().slice(0, 200) });
+            }
+        }
+        onProgress?.({ results: results.slice(), timedOut });
+    }
+    return { results, timedOut };
+}
+const _require = createRequire(import.meta.url);
+export function grepWorkerPath() {
+    const callerPath = fileURLToPath(import.meta.url);
+    const isDev = callerPath.endsWith('.ts');
+    return path.join(path.dirname(callerPath), isDev ? 'grep-worker.ts' : 'grep-worker.js');
+}
+export function runGrepScanInWorker(input) {
+    const callerPath = fileURLToPath(import.meta.url);
+    const isDev = callerPath.endsWith('.ts');
+    const tsxHookArgs = isDev
+        ? ['--import', pathToFileURL(_require.resolve('tsx/esm')).href]
+        : [];
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        let latest = { results: [], timedOut: false };
+        const worker = new Worker(grepWorkerPath(), {
+            workerData: input,
+            execArgv: tsxHookArgs,
+        });
+        const finish = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            void worker.terminate();
+            resolve(result);
+        };
+        const remain = Math.max(1, input.deadlineMs - Date.now());
+        const timer = setTimeout(() => {
+            finish({ results: latest.results, timedOut: true });
+        }, remain);
+        worker.on('message', (msg) => {
+            if (msg.type === 'progress') {
+                latest = { results: msg.results, timedOut: msg.timedOut };
+                return;
+            }
+            if (msg.type === 'done') {
+                finish({ results: msg.results, timedOut: msg.timedOut });
+            }
+        });
+        worker.on('error', (err) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            void worker.terminate();
+            reject(err);
+        });
+        worker.on('exit', () => {
+            if (settled)
+                return;
+            finish({ results: latest.results, timedOut: true });
+        });
+    });
+}

package/dist/server/grep-worker.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/server/grep-worker.js

@@ -0,0 +1,12 @@
+import { parentPort, workerData } from 'node:worker_threads';
+if (!parentPort) {
+    throw new Error('grep-worker must run as a worker_threads worker');
+}
+const ext = import.meta.url.endsWith('.ts') ? '.ts' : '.js';
+const { scanGrepFiles } = await import(new URL(`./grep-scan${ext}`, import.meta.url).href);
+const port = parentPort;
+const input = workerData;
+const out = await scanGrepFiles(input, (partial) => {
+    port.postMessage({ type: 'progress', ...partial });
+});
+port.postMessage({ type: 'done', ...out });

package/dist/server/mcp-http.d.ts

@@ -9,4 +9,12 @@
  */
 import type { Express } from 'express';
 import type { LocalBackend } from '../mcp/local/local-backend.js';
+/**
+ * Protect serve's /api/mcp route when the shared MCP bearer token is configured.
+ *
+ * This middleware must be installed before Express's global JSON parser so an
+ * unauthenticated request body is rejected before it is parsed. The standalone
+ * `gitnexus mcp --http` server resolves the same environment variable.
+ */
+export declare function installServeMcpAuth(app: Express, env?: NodeJS.ProcessEnv): boolean;
 export declare function mountMCPEndpoints(app: Express, backend: LocalBackend): Promise<() => Promise<void>>;

package/dist/server/mcp-http.js

@@ -7,9 +7,24 @@
  *
  * Used by server/api.ts to wire up the full web server.
  */
-import { createStreamableHttpHandler } from '../mcp/http-transport.js';
+import { createAuthMiddleware, createStreamableHttpHandler, resolveAuthToken, } from '../mcp/http-transport.js';
 import { createMcpRepositoryPolicy } from '../mcp/repository-policy.js';
 import { logger } from '../core/logger.js';
+/**
+ * Protect serve's /api/mcp route when the shared MCP bearer token is configured.
+ *
+ * This middleware must be installed before Express's global JSON parser so an
+ * unauthenticated request body is rejected before it is parsed. The standalone
+ * `gitnexus mcp --http` server resolves the same environment variable.
+ */
+export function installServeMcpAuth(app, env = process.env) {
+    const authToken = resolveAuthToken(undefined, env);
+    if (!authToken)
+        return false;
+    app.use('/api/mcp', createAuthMiddleware(authToken));
+    logger.info('Bearer authentication enabled for serve /api/mcp');
+    return true;
+}
 export async function mountMCPEndpoints(app, backend) {
     const repositoryPolicy = await createMcpRepositoryPolicy(backend);
     const { handler, cleanup } = createStreamableHttpHandler(backend, { repositoryPolicy });

package/dist/server/update-controller.d.ts

@@ -0,0 +1,29 @@
+import { type UpdateState } from '../core/update-check.js';
+export interface ServerInfoResponse {
+    version: string;
+    launchContext: 'npx' | 'global' | 'local';
+    nodeVersion: string;
+    latestVersion?: string;
+    updateAvailable?: boolean;
+}
+interface ServeUpdateControllerDependencies {
+    evaluate: (options?: {
+        refreshIfStale?: boolean;
+    }) => Promise<UpdateState | null>;
+    armScheduler: (onState: (state: UpdateState | null) => void) => () => void;
+}
+export interface ServeUpdateController {
+    start: () => Promise<void>;
+    stop: () => void;
+    snapshot: () => UpdateState | null;
+}
+/**
+ * Own the update state for one `serve` process. The route reads snapshot()
+ * synchronously; all cache and network work stays on the startup/scheduler path.
+ */
+export declare const createServeUpdateController: (dependencies?: ServeUpdateControllerDependencies) => ServeUpdateController;
+export declare const buildServerInfo: (updateState: UpdateState | null) => ServerInfoResponse;
+export declare const bindServeUpdateControllerLifecycle: (server: {
+    once(event: "listening" | "close", listener: () => void): unknown;
+}, controller: ServeUpdateController) => void;
+export {};

package/dist/server/update-controller.js

@@ -0,0 +1,82 @@
+import { packageVersion } from '../core/package-version.js';
+import { armUpdateRefreshScheduler, evaluate } from '../core/update-check.js';
+/**
+ * Own the update state for one `serve` process. The route reads snapshot()
+ * synchronously; all cache and network work stays on the startup/scheduler path.
+ */
+export const createServeUpdateController = (dependencies = {
+    evaluate,
+    armScheduler: armUpdateRefreshScheduler,
+}) => {
+    let updateState = null;
+    let stopScheduler;
+    let started = false;
+    let stopped = false;
+    return {
+        start: async () => {
+            if (started || stopped)
+                return;
+            started = true;
+            try {
+                // Cache-only: the scheduler's first cycle owns any stale refresh.
+                updateState = await dependencies.evaluate({ refreshIfStale: false });
+            }
+            catch {
+                updateState = null;
+            }
+            if (stopped)
+                return;
+            try {
+                stopScheduler = dependencies.armScheduler((state) => {
+                    if (state?.updateAvailable !== updateState?.updateAvailable ||
+                        state?.latestVersion !== updateState?.latestVersion) {
+                        updateState = state;
+                    }
+                });
+            }
+            catch {
+                // Update checks are best-effort and never affect HTTP availability.
+            }
+        },
+        stop: () => {
+            if (stopped)
+                return;
+            stopped = true;
+            try {
+                stopScheduler?.();
+            }
+            catch {
+                // Shutdown must continue even if notifier cleanup unexpectedly fails.
+            }
+        },
+        snapshot: () => updateState,
+    };
+};
+export const buildServerInfo = (updateState) => {
+    const execPath = process.env.npm_execpath ?? '';
+    const argv0 = process.argv[1] ?? '';
+    let launchContext;
+    if (execPath.includes('npx') ||
+        argv0.includes('_npx') ||
+        process.env.npm_config_prefix?.includes('_npx')) {
+        launchContext = 'npx';
+    }
+    else if (argv0.includes('node_modules')) {
+        launchContext = 'local';
+    }
+    else {
+        launchContext = 'global';
+    }
+    return {
+        version: packageVersion(),
+        launchContext,
+        nodeVersion: process.version,
+        ...(updateState?.updateAvailable && updateState.latestVersion
+            ? { latestVersion: updateState.latestVersion, updateAvailable: true }
+            : {}),
+    };
+};
+export const bindServeUpdateControllerLifecycle = (server, controller) => {
+    server.once('listening', () => void controller.start());
+    server.once('close', controller.stop);
+};

package/dist/storage/file-lock.d.ts

@@ -0,0 +1,15 @@
+export interface FileLockOptions {
+    retries?: number;
+    retryDelayMs?: number;
+    pid?: number;
+    processStartTime?: string;
+    hostname?: string;
+    isProcessAlive?: (pid: number) => boolean;
+    readProcessStartTime?: (pid: number) => string | undefined;
+}
+export declare class FileLockBusyError extends Error {
+    readonly lockPath: string;
+    constructor(lockPath: string);
+}
+/** Acquire a recoverable cross-process mutex using an atomically published owner file. */
+export declare function acquireFileLock(lockPath: string, options?: FileLockOptions): Promise<() => Promise<void>>;

package/dist/storage/file-lock.js

@@ -0,0 +1,155 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { setTimeout as sleep } from 'node:timers/promises';
+import { isProcessAlive, readProcessStartTime } from '../utils/process-identity.js';
+const HOSTNAME = os.hostname();
+export class FileLockBusyError extends Error {
+    lockPath;
+    constructor(lockPath) {
+        super(`Lock is already held: ${lockPath}. Confirm no owner process is active, then remove it manually.`);
+        this.lockPath = lockPath;
+        this.name = 'FileLockBusyError';
+    }
+}
+/** Acquire a recoverable cross-process mutex using an atomically published owner file. */
+export async function acquireFileLock(lockPath, options = {}) {
+    const resolvedPath = path.resolve(lockPath);
+    const retries = options.retries ?? 0;
+    const retryDelayMs = options.retryDelayMs ?? 50;
+    const pid = options.pid ?? process.pid;
+    const owner = {
+        pid,
+        ownerId: crypto.randomUUID(),
+        processStartTime: options.processStartTime ?? (options.readProcessStartTime ?? readProcessStartTime)(pid) ?? '',
+        hostname: options.hostname ?? HOSTNAME,
+    };
+    if (!owner.processStartTime) {
+        throw new Error(`Unable to determine process start time for file lock owner pid ${owner.pid}.`);
+    }
+    await fs.mkdir(path.dirname(resolvedPath), { recursive: true });
+    const pendingPath = `${resolvedPath}.pending-${owner.ownerId}`;
+    await fs.writeFile(pendingPath, `${JSON.stringify(owner)}\n`, { encoding: 'utf-8', flag: 'wx' });
+    try {
+        for (let attempt = 0;; attempt += 1) {
+            try {
+                await fs.link(pendingPath, resolvedPath);
+                break;
+            }
+            catch (error) {
+                if (!(await isLockConflict(error, resolvedPath)))
+                    throw error;
+                if (await reclaimStaleLock(resolvedPath, owner, options.isProcessAlive ?? isProcessAlive, options.readProcessStartTime ?? readProcessStartTime)) {
+                    continue;
+                }
+                if (attempt >= retries)
+                    throw new FileLockBusyError(lockPath);
+                await sleep(retryDelayMs);
+            }
+        }
+    }
+    finally {
+        // The lock is already published by now, but the release closure below is
+        // not yet in the caller's hands. Letting a staging-file cleanup error
+        // escape would strand a lock nobody can release, so prefer leaking the
+        // pending file — its name is per-acquisition, so it can never block anyone.
+        await fs.rm(pendingPath, { force: true }).catch(() => { });
+    }
+    let releasePromise;
+    return () => (releasePromise ??= releaseOwnedLock(resolvedPath, owner.ownerId));
+}
+async function reclaimStaleLock(lockPath, guardOwner, ownerIsAlive, getProcessStartTime) {
+    const reclaimGuardPath = `${lockPath}.reclaim`;
+    let releaseReclaimGuard;
+    try {
+        releaseReclaimGuard = await acquireFileLock(reclaimGuardPath, {
+            pid: guardOwner.pid,
+            processStartTime: guardOwner.processStartTime,
+            hostname: guardOwner.hostname,
+            isProcessAlive: ownerIsAlive,
+            readProcessStartTime: getProcessStartTime,
+        });
+    }
+    catch (error) {
+        if (error instanceof FileLockBusyError)
+            return false;
+        throw error;
+    }
+    try {
+        const owner = await readOwner(lockPath);
+        if (!owner)
+            return false;
+        // A pid only means something on the machine that issued it. Asking this
+        // kernel about a holder on another host answers about an unrelated process
+        // — or nothing — and either way the answer is "stale", which would steal a
+        // live lock whenever GITNEXUS_HOME is a shared volume.
+        if (owner.hostname !== guardOwner.hostname)
+            return false;
+        if (ownerIsAlive(owner.pid)) {
+            const currentStartTime = getProcessStartTime(owner.pid);
+            if (!currentStartTime || currentStartTime === owner.processStartTime)
+                return false;
+        }
+        await fs.rm(lockPath, { force: true });
+        return true;
+    }
+    finally {
+        await releaseReclaimGuard();
+    }
+}
+async function releaseOwnedLock(lockPath, ownerId) {
+    const releasePath = `${lockPath}.release-${ownerId}-${crypto.randomUUID()}`;
+    if (!(await moveOwnedLock(lockPath, releasePath, ownerId)))
+        return;
+    await fs.rm(releasePath, { force: true });
+}
+async function moveOwnedLock(lockPath, destinationPath, ownerId) {
+    if ((await readOwner(lockPath))?.ownerId !== ownerId)
+        return false;
+    try {
+        await fs.rename(lockPath, destinationPath);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return false;
+        throw error;
+    }
+    if ((await readOwner(destinationPath))?.ownerId === ownerId)
+        return true;
+    await fs.rename(destinationPath, lockPath).catch(() => { });
+    return false;
+}
+async function readOwner(lockPath) {
+    try {
+        const parsed = JSON.parse(await fs.readFile(lockPath, 'utf-8'));
+        if (Number.isInteger(parsed.pid) &&
+            Number(parsed.pid) > 0 &&
+            typeof parsed.ownerId === 'string' &&
+            parsed.ownerId &&
+            typeof parsed.processStartTime === 'string' &&
+            parsed.processStartTime &&
+            typeof parsed.hostname === 'string' &&
+            parsed.hostname) {
+            return parsed;
+        }
+    }
+    catch {
+        // Invalid or legacy locks fail closed; only verified dead owners are reclaimed.
+    }
+    return undefined;
+}
+async function isLockConflict(error, lockPath) {
+    const code = error.code;
+    if (code === 'EEXIST')
+        return true;
+    if (code !== 'EPERM')
+        return false;
+    try {
+        await fs.access(lockPath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/storage/fs-atomic.d.ts

@@ -28,3 +28,27 @@ export declare function retryRename(src: string, dst: string, attempts?: number)
  * retry backoff (and, under a lock, make everyone else wait for it).
  */
 export declare function writeFileAtomic(targetPath: string, data: string, attempts?: number): Promise<void>;
+/**
+ * Publish `src` at `dst` without ever writing through the inode currently
+ * named by `dst` (#3090). Fast path is `fs.link`. Any failure (EEXIST, EXDEV,
+ * EPERM, unsupported hardlinks) copies into a unique sibling and
+ * {@link retryRename}s over `dst`. POSIX rename of a file over an existing
+ * file unlinks the old name; it does not open or truncate that inode.
+ *
+ * Invariant: may replace the destination directory entry; must never modify
+ * the inode that entry currently references. There is no dest unlink and no
+ * in-place `copyFile(src, dst)`.
+ */
+export declare function linkOrCopyFile(src: string, dst: string): Promise<void>;
+/**
+ * Binary sibling of {@link writeFileAtomic}. Same random tmp + `'wx'` + `0o600`
+ * + rename contract; used for optional V8 cache sidecars that cannot go through
+ * a UTF-8 `writeFile`.
+ */
+export declare function writeFileAtomicBytes(targetPath: string, data: Uint8Array, attempts?: number): Promise<void>;
+/**
+ * Sync binary publish for parse workers. Same exclusive-tmp + mode contract as
+ * {@link writeFileAtomicBytes}; rename is not retried (the worker is not the
+ * Windows multi-reader case `retryRename` exists for).
+ */
+export declare function writeFileAtomicBytesSync(targetPath: string, data: Uint8Array): void;