arceus-s 1.6.4

package/dist/server/analyze-job.js

@@ -0,0 +1,150 @@
+/**
+ * Analyze Job Manager
+ *
+ * Tracks server-side analysis jobs with:
+ * - In-memory Map storage
+ * - Single-slot concurrency (one active job at a time)
+ * - Same-repo deduplication (returns existing job)
+ * - Progress event emission for SSE relay
+ * - 1-hour TTL cleanup for completed/failed jobs
+ */
+import { randomUUID } from 'crypto';
+import { EventEmitter } from 'events';
+const JOB_TTL_MS = 60 * 60 * 1000; // 1 hour
+const CLEANUP_INTERVAL_MS = 5 * 60 * 1000; // 5 minutes
+const JOB_TIMEOUT_MS = 30 * 60 * 1000; // 30 minutes
+export class JobManager {
+    jobs = new Map();
+    children = new Map();
+    timeouts = new Map();
+    emitter = new EventEmitter();
+    cleanupTimer;
+    constructor() {
+        this.cleanupTimer = setInterval(() => this.cleanup(), CLEANUP_INTERVAL_MS);
+    }
+    /** Create a new job, or return existing active job for the same repo. */
+    createJob(params) {
+        // Dedup: return existing active job for the same repo (by URL or path)
+        for (const job of this.jobs.values()) {
+            if (!this.isTerminal(job.status)) {
+                const isSameRepo = (params.repoUrl && job.repoUrl === params.repoUrl) ||
+                    (params.repoPath && job.repoPath === params.repoPath);
+                if (isSameRepo) {
+                    return job;
+                }
+            }
+        }
+        // Single-slot: reject if another job is active (different repo)
+        for (const job of this.jobs.values()) {
+            if (!this.isTerminal(job.status)) {
+                throw new Error(`Analysis already in progress (job ${job.id})`);
+            }
+        }
+        const job = {
+            id: randomUUID(),
+            status: 'queued',
+            repoUrl: params.repoUrl,
+            repoPath: params.repoPath,
+            progress: { phase: 'queued', percent: 0, message: 'Waiting to start...' },
+            startedAt: Date.now(),
+            retryCount: 0,
+        };
+        this.jobs.set(job.id, job);
+        return job;
+    }
+    getJob(id) {
+        return this.jobs.get(id);
+    }
+    /** Return a snapshot of all tracked jobs for inspection. */
+    listJobs() {
+        return Array.from(this.jobs.values());
+    }
+    updateJob(id, update) {
+        const job = this.jobs.get(id);
+        if (!job)
+            return;
+        Object.assign(job, update);
+        if (this.isTerminal(job.status)) {
+            job.completedAt = job.completedAt ?? Date.now();
+        }
+        // Emit exactly one event per updateJob call to prevent SSE double-write
+        if (update.status === 'complete' || update.status === 'failed') {
+            // Terminal event takes precedence — don't also emit the progress event
+            this.emitter.emit(`progress:${id}`, {
+                phase: update.status,
+                percent: update.status === 'complete' ? 100 : job.progress.percent,
+                message: update.status === 'complete' ? 'Complete' : update.error || 'Failed',
+            });
+        }
+        else if (update.progress) {
+            this.emitter.emit(`progress:${id}`, update.progress);
+        }
+    }
+    /** Register a child process for a job — enables cancellation and timeout. */
+    registerChild(jobId, child) {
+        this.children.set(jobId, child);
+        // 30-minute timeout
+        const timer = setTimeout(() => {
+            const job = this.jobs.get(jobId);
+            if (job && !this.isTerminal(job.status)) {
+                this.cancelJob(jobId, 'Analysis timed out (30 minute limit)');
+            }
+        }, JOB_TIMEOUT_MS);
+        this.timeouts.set(jobId, timer);
+        // Clean up tracking when child exits
+        child.on('exit', () => {
+            this.children.delete(jobId);
+            const t = this.timeouts.get(jobId);
+            if (t) {
+                clearTimeout(t);
+                this.timeouts.delete(jobId);
+            }
+        });
+    }
+    /** Cancel a running job — sends SIGTERM to child process. */
+    cancelJob(jobId, reason) {
+        const job = this.jobs.get(jobId);
+        if (!job || this.isTerminal(job.status))
+            return false;
+        const child = this.children.get(jobId);
+        if (child) {
+            child.kill('SIGTERM');
+        }
+        this.updateJob(jobId, {
+            status: 'failed',
+            error: reason || 'Analysis cancelled',
+        });
+        return true;
+    }
+    /** Subscribe to progress events for a job. Returns unsubscribe function. */
+    onProgress(jobId, listener) {
+        const event = `progress:${jobId}`;
+        this.emitter.on(event, listener);
+        return () => this.emitter.off(event, listener);
+    }
+    dispose() {
+        // Kill all active child processes
+        for (const child of this.children.values()) {
+            child.kill('SIGTERM');
+        }
+        this.children.clear();
+        // Clear all timeouts
+        for (const timer of this.timeouts.values()) {
+            clearTimeout(timer);
+        }
+        this.timeouts.clear();
+        clearInterval(this.cleanupTimer);
+        this.emitter.removeAllListeners();
+    }
+    isTerminal(status) {
+        return status === 'complete' || status === 'failed';
+    }
+    cleanup() {
+        const now = Date.now();
+        for (const [id, job] of this.jobs) {
+            if (this.isTerminal(job.status) && job.completedAt && now - job.completedAt > JOB_TTL_MS) {
+                this.jobs.delete(id);
+            }
+        }
+    }
+}

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

@@ -0,0 +1,13 @@
+/**
+ * Analyze Worker — Forked Child Process
+ *
+ * This file is the entry point for `child_process.fork()`.
+ * It runs runFullAnalysis in an isolated process with 8GB heap.
+ *
+ * IPC Protocol:
+ *   Parent -> Child: { type: 'start', repoPath: string, options: AnalyzeOptions }
+ *   Child -> Parent: { type: 'progress', phase: string, percent: number, message: string }
+ *   Child -> Parent: { type: 'complete', result: AnalyzeResult }
+ *   Child -> Parent: { type: 'error', message: string }
+ */
+export {};

package/dist/server/analyze-worker.js

@@ -0,0 +1,59 @@
+/**
+ * Analyze Worker — Forked Child Process
+ *
+ * This file is the entry point for `child_process.fork()`.
+ * It runs runFullAnalysis in an isolated process with 8GB heap.
+ *
+ * IPC Protocol:
+ *   Parent -> Child: { type: 'start', repoPath: string, options: AnalyzeOptions }
+ *   Child -> Parent: { type: 'progress', phase: string, percent: number, message: string }
+ *   Child -> Parent: { type: 'complete', result: AnalyzeResult }
+ *   Child -> Parent: { type: 'error', message: string }
+ */
+import { runFullAnalysis } from '../core/run-analyze.js';
+import { closeLbug } from '../core/lbug/lbug-adapter.js';
+function send(msg) {
+    process.send?.(msg);
+}
+// Catch uncaught exceptions and unhandled rejections — report to parent
+process.on('uncaughtException', (err) => {
+    send({ type: 'error', message: err?.message || 'Uncaught exception in worker' });
+    setTimeout(() => process.exit(1), 500);
+});
+process.on('unhandledRejection', (reason) => {
+    send({ type: 'error', message: reason?.message || 'Unhandled rejection in worker' });
+    setTimeout(() => process.exit(1), 500);
+});
+// Handle graceful shutdown — notify parent before exit
+process.on('SIGTERM', async () => {
+    send({ type: 'error', message: 'Analysis cancelled (worker received SIGTERM)' });
+    try {
+        await closeLbug();
+    }
+    catch { }
+    process.exit(0);
+});
+// Listen for start command from parent — guarded against re-entry
+let started = false;
+process.on('message', async (msg) => {
+    if (msg.type !== 'start' || started)
+        return;
+    started = true;
+    try {
+        const result = await runFullAnalysis(msg.repoPath, msg.options, {
+            onProgress: (phase, percent, message) => {
+                send({ type: 'progress', phase, percent, message });
+            },
+            onLog: (message) => {
+                send({ type: 'progress', phase: 'log', percent: -1, message });
+            },
+        });
+        send({ type: 'complete', result });
+    }
+    catch (err) {
+        send({ type: 'error', message: err?.message || 'Analysis failed' });
+    }
+    // LadybugDB's native module prevents clean exit — force it
+    // (same reason the CLI uses process.exit(0))
+    setTimeout(() => process.exit(0), 500);
+});

package/dist/server/api.d.ts

@@ -0,0 +1,72 @@
+/**
+ * HTTP API Server
+ *
+ * REST API for browser-based clients to query the local .arc/ index.
+ * Also hosts the MCP server over StreamableHTTP for remote AI tool access.
+ *
+ * Security: binds to localhost by default (use --host to override).
+ * CORS is restricted to localhost, private/LAN networks, and the deployed site.
+ */
+import express from 'express';
+import { type GraphNode, type GraphRelationship } from '../_shared/index.js';
+/**
+ * Determine whether an HTTP Origin header value is allowed by CORS policy.
+ *
+ * Permitted origins:
+ * - No origin (non-browser requests such as curl or server-to-server calls)
+ * - http://localhost:<port> — local development
+ * - http://127.0.0.1:<port> — loopback alias
+ * - RFC 1918 private/LAN networks (any port):
+ *     10.0.0.0/8      → 10.x.x.x
+ *     172.16.0.0/12   → 172.16.x.x – 172.31.x.x
+ *     192.168.0.0/16  → 192.168.x.x
+ * - https://arc.vercel.app — the deployed Arceus web UI
+ *
+ * @param origin - The value of the HTTP `Origin` request header, or `undefined`
+ *                 when the header is absent (non-browser request).
+ * @returns `true` if the origin is allowed, `false` otherwise.
+ */
+export declare const isAllowedOrigin: (origin: string | undefined) => boolean;
+type GraphStreamRecord = {
+    type: 'node';
+    data: GraphNode;
+} | {
+    type: 'relationship';
+    data: GraphRelationship;
+} | {
+    type: 'error';
+    error: string;
+};
+export declare class ClientDisconnectedError extends Error {
+    constructor();
+}
+export declare const isIgnorableGraphQueryError: (err: unknown) => boolean;
+export declare const SPA_FALLBACK_REGEX: RegExp;
+export declare const resolveWebDistDir: (primaryDir: string, fallbackDir: string) => Promise<string | null>;
+export declare const landingPageHtml: () => string;
+export declare const staticCacheControlSetHeaders: (res: express.Response, filePath: string) => void;
+export declare const registerWebUI: (app: express.Express, staticDir: string | null) => void;
+export declare const writeNdjsonRecord: (res: express.Response, record: GraphStreamRecord, signal?: AbortSignal) => Promise<void>;
+export declare const streamGraphNdjson: (res: express.Response, includeContent?: boolean, signal?: AbortSignal) => Promise<void>;
+/**
+ * Handle a GET /api/file request body. Extracted from createServer's route
+ * registration so it can be unit-tested without spinning up an HTTP server
+ * — calling app.get(...) inside a test triggers CodeQL's
+ * js/missing-rate-limiting query, which is appropriate for production
+ * route handlers but a false positive for tests of the handler logic.
+ *
+ * The function takes the express req and res (typed loosely so test code
+ * can pass minimal mocks) plus the resolved repo path. All path-traversal
+ * containment is done inline at the readFile sink with the canonical
+ * path.relative idiom for CodeQL js/path-injection recognition.
+ */
+export declare const handleFileRequest: (req: {
+    query: any;
+}, res: {
+    status: (code: number) => {
+        json: (body: any) => void;
+    };
+    json: (body: any) => void;
+}, repoPath: string) => Promise<void>;
+export declare const createServer: (port: number, host?: string) => Promise<void>;
+export {};