@codragraph/cli 1.6.2

package/dist/server/git-clone.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Git Clone Utility
+ *
+ * Shallow-clones repositories into ~/.codragraph/repos/{name}/.
+ * If already cloned, does git pull instead.
+ */
+/** Extract the repository name from a git URL (HTTPS or SSH). */
+export declare function extractRepoName(url: string): string;
+/** Get the clone target directory for a repo name. */
+export declare function getCloneDir(repoName: string): string;
+/**
+ * Validate a git URL to prevent SSRF attacks.
+ * Only allows https:// and http:// schemes. Blocks private/internal addresses,
+ * IPv6 private ranges, cloud metadata hostnames, and numeric IP encodings.
+ */
+export declare function validateGitUrl(url: string): void;
+export interface CloneProgress {
+    phase: 'cloning' | 'pulling';
+    message: string;
+}
+/**
+ * Clone or pull a git repository.
+ * If targetDir doesn't exist: git clone --depth 1
+ * If targetDir exists with .git: git pull --ff-only
+ */
+export declare function cloneOrPull(url: string, targetDir: string, onProgress?: (progress: CloneProgress) => void): Promise<string>;

package/dist/server/git-clone.js

@@ -0,0 +1,184 @@
+/**
+ * Git Clone Utility
+ *
+ * Shallow-clones repositories into ~/.codragraph/repos/{name}/.
+ * If already cloned, does git pull instead.
+ */
+import { spawn } from 'child_process';
+import path from 'path';
+import os from 'os';
+import fs from 'fs/promises';
+import { isIP } from 'net';
+/** Extract the repository name from a git URL (HTTPS or SSH). */
+export function extractRepoName(url) {
+    const cleaned = url.replace(/\/+$/, '');
+    const lastSegment = cleaned.split(/[/:]/).pop() || 'unknown';
+    return lastSegment.replace(/\.git$/, '');
+}
+/** Get the clone target directory for a repo name. */
+export function getCloneDir(repoName) {
+    return path.join(os.homedir(), '.codragraph', 'repos', repoName);
+}
+// Cloud metadata hostnames that must never be reachable via user-supplied URLs
+const BLOCKED_HOSTNAMES = new Set([
+    'localhost',
+    'metadata.google.internal',
+    'metadata.azure.com',
+    'metadata.internal',
+]);
+/**
+ * Validate a git URL to prevent SSRF attacks.
+ * Only allows https:// and http:// schemes. Blocks private/internal addresses,
+ * IPv6 private ranges, cloud metadata hostnames, and numeric IP encodings.
+ */
+export function validateGitUrl(url) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        throw new Error('Invalid URL');
+    }
+    if (!['https:', 'http:'].includes(parsed.protocol)) {
+        throw new Error('Only https:// and http:// git URLs are allowed');
+    }
+    const host = parsed.hostname.toLowerCase();
+    // Block known dangerous hostnames (cloud metadata services)
+    if (BLOCKED_HOSTNAMES.has(host)) {
+        throw new Error('Cloning from private/internal addresses is not allowed');
+    }
+    // Strip IPv6 brackets if present (URL parser behavior varies across Node versions)
+    let normalizedHost = host;
+    if (host.startsWith('[') && host.endsWith(']')) {
+        normalizedHost = host.slice(1, -1);
+    }
+    // Check if this is an IPv6 address
+    // Use manual colon detection as fallback since isIP may return 0 for some
+    // normalized IPv6 forms (e.g. ::ffff:7f00:1)
+    const isIPv6 = isIP(normalizedHost) === 6 || normalizedHost.includes(':');
+    if (isIPv6) {
+        assertNotPrivateIPv6(normalizedHost);
+        return;
+    }
+    // Check if this is an IPv4 address (including numeric encodings)
+    if (isIP(normalizedHost) === 4) {
+        assertNotPrivateIPv4(normalizedHost);
+        return;
+    }
+    // For non-IP hostnames, check for numeric IP tricks
+    // Decimal encoding: 2130706433 = 127.0.0.1
+    // Hex encoding: 0x7f000001 = 127.0.0.1
+    if (/^\d+$/.test(host) || /^0x[0-9a-f]+$/i.test(host)) {
+        throw new Error('Cloning from private/internal addresses is not allowed');
+    }
+    // Standard IPv4 regex checks for dotted notation
+    if (/^127\./.test(host) ||
+        /^10\./.test(host) ||
+        /^172\.(1[6-9]|2\d|3[01])\./.test(host) ||
+        /^192\.168\./.test(host) ||
+        /^169\.254\./.test(host) ||
+        /^0\./.test(host) ||
+        host === '0.0.0.0' ||
+        /^100\.(6[4-9]|[7-9]\d|1[01]\d|12[0-7])\./.test(host) ||
+        /^198\.1[89]\./.test(host)) {
+        throw new Error('Cloning from private/internal addresses is not allowed');
+    }
+}
+function assertNotPrivateIPv6(ip) {
+    // Expand common compressed forms for comparison
+    const lower = ip.toLowerCase();
+    // IPv6 loopback
+    if (lower === '::1' || lower === '0:0:0:0:0:0:0:1') {
+        throw new Error('Cloning from private/internal addresses is not allowed');
+    }
+    // Unspecified address
+    if (lower === '::' || lower === '0:0:0:0:0:0:0:0') {
+        throw new Error('Cloning from private/internal addresses is not allowed');
+    }
+    // IPv6 Unique Local Address (fc00::/7 = fc and fd prefixes)
+    if (lower.startsWith('fc') || lower.startsWith('fd')) {
+        throw new Error('Cloning from private/internal addresses is not allowed');
+    }
+    // IPv6 link-local (fe80::/10)
+    if (lower.startsWith('fe80') ||
+        lower.startsWith('fe8') ||
+        lower.startsWith('fe9') ||
+        lower.startsWith('fea') ||
+        lower.startsWith('feb')) {
+        throw new Error('Cloning from private/internal addresses is not allowed');
+    }
+    // IPv4-mapped IPv6 (::ffff:x.x.x.x or ::ffff:hex:hex)
+    // Node may normalize ::ffff:127.0.0.1 to ::ffff:7f00:1
+    if (lower.startsWith('::ffff:')) {
+        throw new Error('Cloning from private/internal addresses is not allowed');
+    }
+    // Also catch the expanded form: 0:0:0:0:0:ffff:
+    if (lower.includes(':ffff:')) {
+        throw new Error('Cloning from private/internal addresses is not allowed');
+    }
+}
+function assertNotPrivateIPv4(ip) {
+    const parts = ip.split('.').map(Number);
+    const [a, b] = parts;
+    if (a === 127 ||
+        a === 10 ||
+        (a === 172 && b >= 16 && b <= 31) ||
+        (a === 192 && b === 168) ||
+        (a === 169 && b === 254) ||
+        a === 0 ||
+        (a === 100 && b >= 64 && b <= 127) ||
+        (a === 198 && (b === 18 || b === 19))) {
+        throw new Error('Cloning from private/internal addresses is not allowed');
+    }
+}
+/**
+ * Clone or pull a git repository.
+ * If targetDir doesn't exist: git clone --depth 1
+ * If targetDir exists with .git: git pull --ff-only
+ */
+export async function cloneOrPull(url, targetDir, onProgress) {
+    const exists = await fs.access(path.join(targetDir, '.git')).then(() => true, () => false);
+    if (exists) {
+        onProgress?.({ phase: 'pulling', message: 'Pulling latest changes...' });
+        await runGit(['pull', '--ff-only'], targetDir);
+    }
+    else {
+        validateGitUrl(url);
+        await fs.mkdir(path.dirname(targetDir), { recursive: true });
+        onProgress?.({ phase: 'cloning', message: `Cloning ${url}...` });
+        await runGit(['clone', '--depth', '1', url, targetDir]);
+    }
+    return targetDir;
+}
+function runGit(args, cwd) {
+    return new Promise((resolve, reject) => {
+        const proc = spawn('git', args, {
+            cwd,
+            stdio: ['ignore', 'pipe', 'pipe'],
+            env: {
+                ...process.env,
+                // Prevent git from prompting for credentials (hangs the process)
+                GIT_TERMINAL_PROMPT: '0',
+                // Ensure no credential helper tries to open a GUI prompt
+                GIT_ASKPASS: process.platform === 'win32' ? 'echo' : '/bin/true',
+            },
+        });
+        let stderr = '';
+        proc.stderr.on('data', (chunk) => {
+            stderr += chunk;
+        });
+        proc.on('close', (code) => {
+            if (code === 0)
+                resolve();
+            else {
+                // Log full stderr internally but don't expose it to API callers (SSRF mitigation)
+                if (stderr.trim())
+                    console.error(`git ${args[0]} stderr: ${stderr.trim()}`);
+                reject(new Error(`git ${args[0]} failed (exit code ${code})`));
+            }
+        });
+        proc.on('error', (err) => {
+            reject(new Error(`Failed to spawn git: ${err.message}`));
+        });
+    });
+}

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

@@ -0,0 +1,13 @@
+/**
+ * MCP over HTTP
+ *
+ * Mounts the CodraGraph MCP server on Express using StreamableHTTP transport.
+ * Each connecting client gets its own stateful session; the LocalBackend
+ * is shared across all sessions (thread-safe — lazy LadybugDB per repo).
+ *
+ * Sessions are cleaned up on explicit close or after SESSION_TTL_MS of inactivity
+ * (guards against network drops that never trigger onclose).
+ */
+import type { Express } from 'express';
+import type { LocalBackend } from '../mcp/local/local-backend.js';
+export declare function mountMCPEndpoints(app: Express, backend: LocalBackend): () => Promise<void>;

package/dist/server/mcp-http.js

@@ -0,0 +1,100 @@
+/**
+ * MCP over HTTP
+ *
+ * Mounts the CodraGraph MCP server on Express using StreamableHTTP transport.
+ * Each connecting client gets its own stateful session; the LocalBackend
+ * is shared across all sessions (thread-safe — lazy LadybugDB per repo).
+ *
+ * Sessions are cleaned up on explicit close or after SESSION_TTL_MS of inactivity
+ * (guards against network drops that never trigger onclose).
+ */
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { createMCPServer } from '../mcp/server.js';
+import { randomUUID } from 'crypto';
+/** Idle sessions are evicted after 30 minutes */
+const SESSION_TTL_MS = 30 * 60 * 1000;
+/** Cleanup sweep runs every 5 minutes */
+const CLEANUP_INTERVAL_MS = 5 * 60 * 1000;
+export function mountMCPEndpoints(app, backend) {
+    const sessions = new Map();
+    // Periodic cleanup of idle sessions (guards against network drops)
+    const cleanupTimer = setInterval(() => {
+        const now = Date.now();
+        for (const [id, session] of sessions) {
+            if (now - session.lastActivity > SESSION_TTL_MS) {
+                try {
+                    session.server.close();
+                }
+                catch { }
+                sessions.delete(id);
+            }
+        }
+    }, CLEANUP_INTERVAL_MS);
+    if (cleanupTimer && typeof cleanupTimer === 'object' && 'unref' in cleanupTimer) {
+        cleanupTimer.unref();
+    }
+    const handleMcpRequest = async (req, res) => {
+        const sessionId = req.headers['mcp-session-id'];
+        if (sessionId && sessions.has(sessionId)) {
+            // Existing session — delegate to its transport
+            const session = sessions.get(sessionId);
+            session.lastActivity = Date.now();
+            await session.transport.handleRequest(req, res, req.body);
+        }
+        else if (sessionId) {
+            // Unknown/expired session ID — tell client to re-initialize (per MCP spec)
+            res.status(404).json({
+                jsonrpc: '2.0',
+                error: { code: -32001, message: 'Session not found. Re-initialize.' },
+                id: null,
+            });
+        }
+        else if (req.method === 'POST') {
+            // No session ID — new client initializing
+            const transport = new StreamableHTTPServerTransport({
+                sessionIdGenerator: () => randomUUID(),
+            });
+            const server = createMCPServer(backend);
+            await server.connect(transport);
+            await transport.handleRequest(req, res, req.body);
+            if (transport.sessionId) {
+                sessions.set(transport.sessionId, { server, transport, lastActivity: Date.now() });
+                transport.onclose = () => {
+                    sessions.delete(transport.sessionId);
+                };
+            }
+        }
+        else {
+            res.status(400).json({
+                jsonrpc: '2.0',
+                error: { code: -32000, message: 'No valid session. Send a POST to initialize.' },
+                id: null,
+            });
+        }
+    };
+    app.all('/api/mcp', (req, res) => {
+        void handleMcpRequest(req, res).catch((err) => {
+            console.error('MCP HTTP request failed:', err);
+            if (res.headersSent)
+                return;
+            res.status(500).json({
+                jsonrpc: '2.0',
+                error: { code: -32000, message: 'Internal MCP server error' },
+                id: null,
+            });
+        });
+    });
+    const cleanup = async () => {
+        clearInterval(cleanupTimer);
+        const closers = [...sessions.values()].map(async (session) => {
+            try {
+                await Promise.resolve(session.server.close());
+            }
+            catch { }
+        });
+        sessions.clear();
+        await Promise.allSettled(closers);
+    };
+    console.log('MCP HTTP endpoints mounted at /api/mcp');
+    return cleanup;
+}

package/dist/storage/git.d.ts

@@ -0,0 +1,80 @@
+export declare const isGitRepo: (repoPath: string) => boolean;
+export declare const getCurrentCommit: (repoPath: string) => string;
+/**
+ * Get a stable canonical identifier for the repo's `origin` remote, if any.
+ *
+ * Used to fingerprint two on-disk clones as the same logical repository
+ * (issue #XXX — silent graph drift across sibling clones). `path` alone
+ * is unreliable: worktrees, "clean clone for indexing" hygiene, and
+ * multi-agent workspaces routinely have the same repo at multiple
+ * absolute paths. The remote URL is the only on-disk signal that
+ * survives those conventions.
+ *
+ * Normalisation strategy:
+ *   - Strip a trailing `.git` so `https://x/y` and `https://x/y.git` collapse.
+ *   - Strip a trailing `/` for the same reason.
+ *   - `git@github.com:foo/bar` and `https://github.com/foo/bar` are
+ *     intentionally NOT collapsed — they are different remotes from
+ *     git's perspective and we don't want to assert equivalence.
+ *   - Lower-case the host portion so `GitHub.com` and `github.com`
+ *     don't desync; preserves case in path because some hosts
+ *     (Bitbucket Server) treat repo paths case-sensitively.
+ *
+ * Returns `undefined` when there is no origin remote, the directory
+ * isn't a git repo, or git itself isn't available.
+ */
+export declare const getRemoteUrl: (repoPath: string) => string | undefined;
+/**
+ * Find the git repository root from any path inside the repo
+ */
+export declare const getGitRoot: (fromPath: string) => string | null;
+/**
+ * Check whether a directory contains a .git entry (file or folder).
+ *
+ * This is intentionally a simple filesystem check rather than running
+ * `git rev-parse`, so it works even when git is not installed or when
+ * the directory is a git-worktree root (which has a .git file, not a
+ * directory).  Use `isGitRepo` for a definitive git answer.
+ *
+ * @param dirPath - Absolute path to the directory to inspect.
+ * @returns `true` when `.git` is present, `false` otherwise.
+ */
+export declare const hasGitDir: (dirPath: string) => boolean;
+/**
+ * Read `remote.origin.url` from a git repository, or `null` if not a
+ * git repo, has no `origin` remote, or git is unavailable.
+ *
+ * Used by the registry-name inference path (#979) to recover a
+ * meaningful repo name when `path.basename(repoPath)` is generic
+ * (e.g. monorepo subprojects, git worktrees, Gas-Town-style
+ * `<rig>/refinery/rig/` layouts).
+ */
+export declare const getRemoteOriginUrl: (repoPath: string) => string | null;
+/**
+ * Parse a repository name out of a git remote URL. Handles the common
+ * SSH (`git@host:owner/repo.git`), HTTPS (`https://host/owner/repo.git`),
+ * `git://`, `ssh://`, and `file://` shapes. Returns `null` for empty /
+ * unparseable input.
+ *
+ * The heuristic: strip a trailing `.git` and trailing slashes, then
+ * take the segment after the last `/` or `:`.
+ */
+export declare const parseRepoNameFromUrl: (url: string | null | undefined) => string | null;
+/**
+ * Convenience wrapper: derive a registry-friendly name from the repo's
+ * `origin` remote, or `null` when it cannot be inferred.
+ */
+export declare const getInferredRepoName: (repoPath: string) => string | null;
+export interface DiffHunk {
+    startLine: number;
+    endLine: number;
+}
+export interface FileDiff {
+    filePath: string;
+    hunks: DiffHunk[];
+}
+/**
+ * Parse unified diff output (with -U0) into per-file hunk ranges.
+ * Extracts the new-file line ranges from @@ hunk headers.
+ */
+export declare function parseDiffHunks(diffOutput: string): FileDiff[];

package/dist/storage/git.js

@@ -0,0 +1,190 @@
+import { execSync } from 'child_process';
+import { statSync } from 'fs';
+import path from 'path';
+// Git utilities for repository detection, commit tracking, and diff analysis
+export const isGitRepo = (repoPath) => {
+    try {
+        execSync('git rev-parse --is-inside-work-tree', { cwd: repoPath, stdio: 'ignore' });
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+export const getCurrentCommit = (repoPath) => {
+    try {
+        return execSync('git rev-parse HEAD', { cwd: repoPath }).toString().trim();
+    }
+    catch {
+        return '';
+    }
+};
+/**
+ * Get a stable canonical identifier for the repo's `origin` remote, if any.
+ *
+ * Used to fingerprint two on-disk clones as the same logical repository
+ * (issue #XXX — silent graph drift across sibling clones). `path` alone
+ * is unreliable: worktrees, "clean clone for indexing" hygiene, and
+ * multi-agent workspaces routinely have the same repo at multiple
+ * absolute paths. The remote URL is the only on-disk signal that
+ * survives those conventions.
+ *
+ * Normalisation strategy:
+ *   - Strip a trailing `.git` so `https://x/y` and `https://x/y.git` collapse.
+ *   - Strip a trailing `/` for the same reason.
+ *   - `git@github.com:foo/bar` and `https://github.com/foo/bar` are
+ *     intentionally NOT collapsed — they are different remotes from
+ *     git's perspective and we don't want to assert equivalence.
+ *   - Lower-case the host portion so `GitHub.com` and `github.com`
+ *     don't desync; preserves case in path because some hosts
+ *     (Bitbucket Server) treat repo paths case-sensitively.
+ *
+ * Returns `undefined` when there is no origin remote, the directory
+ * isn't a git repo, or git itself isn't available.
+ */
+export const getRemoteUrl = (repoPath) => {
+    let raw;
+    try {
+        raw = execSync('git config --get remote.origin.url', {
+            cwd: repoPath,
+            stdio: ['ignore', 'pipe', 'ignore'],
+        })
+            .toString()
+            .trim();
+    }
+    catch {
+        return undefined;
+    }
+    if (!raw)
+        return undefined;
+    let normalised = raw.replace(/\/$/, '').replace(/\.git$/, '');
+    // Lower-case the host segment of `scheme://[user@]host[:port]/...`
+    // and the host segment of `git@host:owner/repo` SCP form.
+    // SSH user-segment regex deliberately accepts the common
+    // `git@`/`<alnum>-_@` cases. Less common usernames (e.g. with
+    // dots) fall through to the URL-form branch — they will simply
+    // not get host-case normalisation, which is acceptable: the raw
+    // `git config` output is still a valid fingerprint, just slightly
+    // less collapsible across host casings.
+    const sshMatch = normalised.match(/^(git@|[a-zA-Z0-9_-]+@)([^:/]+)(:.+)$/);
+    if (sshMatch) {
+        normalised = `${sshMatch[1]}${sshMatch[2].toLowerCase()}${sshMatch[3]}`;
+    }
+    else {
+        const urlMatch = normalised.match(/^([a-zA-Z][a-zA-Z0-9+.-]*:\/\/)([^/]+)(\/.*)?$/);
+        if (urlMatch) {
+            normalised = `${urlMatch[1]}${urlMatch[2].toLowerCase()}${urlMatch[3] ?? ''}`;
+        }
+    }
+    return normalised;
+};
+/**
+ * Find the git repository root from any path inside the repo
+ */
+export const getGitRoot = (fromPath) => {
+    try {
+        const raw = execSync('git rev-parse --show-toplevel', { cwd: fromPath }).toString().trim();
+        // On Windows, git returns /d/Projects/Foo — path.resolve normalizes to D:\Projects\Foo
+        return path.resolve(raw);
+    }
+    catch {
+        return null;
+    }
+};
+/**
+ * Check whether a directory contains a .git entry (file or folder).
+ *
+ * This is intentionally a simple filesystem check rather than running
+ * `git rev-parse`, so it works even when git is not installed or when
+ * the directory is a git-worktree root (which has a .git file, not a
+ * directory).  Use `isGitRepo` for a definitive git answer.
+ *
+ * @param dirPath - Absolute path to the directory to inspect.
+ * @returns `true` when `.git` is present, `false` otherwise.
+ */
+export const hasGitDir = (dirPath) => {
+    try {
+        statSync(path.join(dirPath, '.git'));
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+/**
+ * Read `remote.origin.url` from a git repository, or `null` if not a
+ * git repo, has no `origin` remote, or git is unavailable.
+ *
+ * Used by the registry-name inference path (#979) to recover a
+ * meaningful repo name when `path.basename(repoPath)` is generic
+ * (e.g. monorepo subprojects, git worktrees, Gas-Town-style
+ * `<rig>/refinery/rig/` layouts).
+ */
+export const getRemoteOriginUrl = (repoPath) => {
+    try {
+        const url = execSync('git config --get remote.origin.url', {
+            cwd: repoPath,
+            stdio: ['ignore', 'pipe', 'ignore'],
+        })
+            .toString()
+            .trim();
+        return url || null;
+    }
+    catch {
+        return null;
+    }
+};
+/**
+ * Parse a repository name out of a git remote URL. Handles the common
+ * SSH (`git@host:owner/repo.git`), HTTPS (`https://host/owner/repo.git`),
+ * `git://`, `ssh://`, and `file://` shapes. Returns `null` for empty /
+ * unparseable input.
+ *
+ * The heuristic: strip a trailing `.git` and trailing slashes, then
+ * take the segment after the last `/` or `:`.
+ */
+export const parseRepoNameFromUrl = (url) => {
+    if (!url)
+        return null;
+    const trimmed = url.trim();
+    if (!trimmed)
+        return null;
+    // Strip `.git` suffix (case-insensitive) and any trailing slashes.
+    const withoutSuffix = trimmed.replace(/\.git\/*$/i, '').replace(/\/+$/, '');
+    // Last path segment, splitting on either `/` or `:` (covers SSH form).
+    const m = withoutSuffix.match(/[/:]([^/:]+)$/);
+    const candidate = m ? m[1] : withoutSuffix;
+    return candidate || null;
+};
+/**
+ * Convenience wrapper: derive a registry-friendly name from the repo's
+ * `origin` remote, or `null` when it cannot be inferred.
+ */
+export const getInferredRepoName = (repoPath) => {
+    return parseRepoNameFromUrl(getRemoteOriginUrl(repoPath));
+};
+/**
+ * Parse unified diff output (with -U0) into per-file hunk ranges.
+ * Extracts the new-file line ranges from @@ hunk headers.
+ */
+export function parseDiffHunks(diffOutput) {
+    const files = [];
+    let current = null;
+    for (const line of diffOutput.split('\n')) {
+        if (line.startsWith('+++ b/')) {
+            current = { filePath: line.slice(6), hunks: [] };
+            files.push(current);
+        }
+        else if (line.startsWith('@@') && current) {
+            const match = line.match(/@@ -\d+(?:,\d+)? \+(\d+)(?:,(\d+))? @@/);
+            if (match) {
+                const start = parseInt(match[1], 10);
+                const count = match[2] !== undefined ? parseInt(match[2], 10) : 1;
+                if (count > 0) {
+                    current.hunks.push({ startLine: start, endLine: start + count - 1 });
+                }
+            }
+        }
+    }
+    return files;
+}