gitnexus 1.6.8-rc.8 → 1.6.8

package/dist/server/analyze-upload.js

@@ -0,0 +1,123 @@
+/**
+ * POST /api/analyze/upload — analyze a browser folder upload.
+ *
+ * Securely ingests the multipart upload into a sandbox (upload-ingest.ts),
+ * promotes it to a persistent app-controlled directory, and analyzes it via
+ * the same job/worker machinery as a git clone — never returning a server
+ * path to the client. Factored as a dependency-injected handler so the job
+ * machinery (createJob + the worker launcher) can be mocked in unit tests.
+ */
+import path from 'path';
+import fsp from 'fs/promises';
+import { ingestUpload } from './upload-ingest.js';
+import { UPLOAD_ROOT, getUploadDir, deriveUploadName } from './upload-paths.js';
+import { BadRequestError } from './validation.js';
+/** Cap on collision-suffix attempts when allocating an upload dir name. */
+const MAX_NAME_COLLISION_TRIES = 100;
+/**
+ * Find an available upload directory name, appending `-2`, `-3`, … on
+ * collision with an existing upload. Bounded to avoid an unbounded scan.
+ */
+async function pickAvailableName(base) {
+    for (let i = 0; i < MAX_NAME_COLLISION_TRIES; i++) {
+        const name = i === 0 ? base : `${base}-${i + 1}`;
+        let dir;
+        try {
+            dir = getUploadDir(name);
+        }
+        catch {
+            continue;
+        }
+        try {
+            await fsp.access(dir);
+            // exists → try the next suffix
+        }
+        catch {
+            return name; // ENOENT → available
+        }
+    }
+    throw new BadRequestError(`Could not allocate an upload directory after ${MAX_NAME_COLLISION_TRIES} attempts`, 409);
+}
+export function createAnalyzeUploadHandler(deps) {
+    const ingest = deps.ingest ?? ingestUpload;
+    return async function handleAnalyzeUploadRequest(req, res) {
+        let stageRoot;
+        let promotedDir;
+        let createdJobId;
+        let launched = false;
+        try {
+            const result = await ingest(req);
+            stageRoot = result.stageRoot;
+            const baseName = deriveUploadName(result.topLevelName);
+            if (!baseName) {
+                throw new BadRequestError('Uploaded folder has no usable name');
+            }
+            // webkitRelativePath prefixes every entry with the picked folder, so the
+            // real repo root is stageRoot/<topLevelName>. Validate it is a directory
+            // BEFORE taking the single analysis slot — a malformed (non-folder)
+            // upload must not be able to occupy the slot.
+            const innerRoot = path.join(result.stageRoot, result.topLevelName);
+            let innerIsDir = false;
+            try {
+                innerIsDir = (await fsp.stat(innerRoot)).isDirectory();
+            }
+            catch {
+                innerIsDir = false;
+            }
+            if (!innerIsDir) {
+                throw new BadRequestError('Upload must be a folder');
+            }
+            const finalName = await pickAvailableName(baseName);
+            const finalDir = getUploadDir(finalName);
+            // createJob occupies the single analysis slot (throws 'already in
+            // progress' → 409). From here on, ANY error before launch MUST release
+            // the slot via failJob in the catch, or the server wedges all analyses.
+            let job;
+            try {
+                job = deps.createJob({ repoPath: finalDir });
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : '';
+                if (msg.includes('already in progress')) {
+                    throw new BadRequestError(msg, 409);
+                }
+                throw err;
+            }
+            createdJobId = job.id;
+            // Promote staging → persistent upload dir. Both live under UPLOAD_ROOT's
+            // filesystem, so this rename stays atomic (no EXDEV).
+            await fsp.mkdir(UPLOAD_ROOT, { recursive: true });
+            await fsp.rename(innerRoot, finalDir);
+            promotedDir = finalDir;
+            const oldStage = stageRoot;
+            stageRoot = undefined;
+            await fsp.rm(oldStage, { recursive: true, force: true }).catch(() => { });
+            // Drop any crafted index the upload may have carried (a `.gitnexus`
+            // segment passes containment); the worker will build a fresh one.
+            await fsp
+                .rm(path.join(finalDir, '.gitnexus'), { recursive: true, force: true })
+                .catch(() => { });
+            deps.launch(job, finalDir, { registryName: finalName });
+            launched = true;
+            res.status(202).json({ jobId: job.id, status: job.status });
+        }
+        catch (err) {
+            // Release the single analysis slot if a job was created but never
+            // launched — otherwise the leaked queued job blocks all future analyses.
+            if (createdJobId && !launched) {
+                deps.failJob(createdJobId, err instanceof Error ? err.message : 'Upload failed');
+            }
+            if (stageRoot) {
+                await fsp.rm(stageRoot, { recursive: true, force: true }).catch(() => { });
+            }
+            if (promotedDir && !launched) {
+                await fsp.rm(promotedDir, { recursive: true, force: true }).catch(() => { });
+            }
+            if (err instanceof BadRequestError) {
+                res.status(err.status).json({ error: err.message });
+                return;
+            }
+            res.status(500).json({ error: 'Upload failed' });
+        }
+    };
+}

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

@@ -0,0 +1,58 @@
+/**
+ * JSON-safe projection of `AnalyzeResult` for the analyze-worker → parent IPC
+ * boundary (#2112 boundary audit; #2135).
+ *
+ * The forked analyze worker (`analyze-worker.ts`) reports completion to the
+ * parent over `child_process` IPC, which uses Node's DEFAULT `'json'`
+ * serialization — `api.ts` forks the worker with no `serialization:` option, so
+ * the channel runs `JSON.stringify`/`JSON.parse`, NOT V8 structured clone.
+ *
+ * `AnalyzeResult.pipelineResult` is populated on every successful analysis
+ * (`run-analyze.ts`) and carries `pipelineResult.graph` — the live
+ * `KnowledgeGraph` closure object. Sending the raw result across this channel is
+ * wrong three ways:
+ *   1. Waste — the graph's `nodes`/`relationships` getters force-materialize the
+ *      ENTIRE graph into two arrays, then JSON-stringify them, on every analyze.
+ *      On a large repo (the #2112 scenario) that is a multi-hundred-MB
+ *      stringify+parse whose result is immediately discarded.
+ *   2. Silent corruption — the graph's methods are own function properties;
+ *      `JSON.stringify` drops them with no error, so a `pipelineResult.graph`
+ *      that survived the wire is a data-only husk whose `forEachNode(...)` throws
+ *      "is not a function" far from the cause.
+ *   3. Conditional crash — a BigInt or circular reference anywhere in the
+ *      payload makes `process.send` throw `TypeError` synchronously; the throw is
+ *      caught in the worker and re-sent as `{type:'error'}`, turning a
+ *      SUCCESSFUL analysis (DB already written) into a reported FAILURE. This is
+ *      the #2112 failure family on the server path, and — unlike the parse-worker
+ *      result boundary — it has no clone-safety net.
+ *
+ * The parent (`api.ts`) reads only `result.repoName`; `pipelineResult`'s real
+ * consumers (CLI skill generation) call `runFullAnalysis` in-process and never
+ * cross this fork. So the worker sends an explicit allowlist of the scalar
+ * fields, JSON-safe by construction.
+ */
+import type { AnalyzeResult } from '../core/run-analyze.js';
+/**
+ * The JSON-safe subset of `AnalyzeResult` that crosses the analyze-worker IPC
+ * boundary. A `Pick` allowlist — NOT `Omit<…, 'pipelineResult'>`. With `Pick`
+ * the allowlist IS the type, so the projection is exhaustive by construction:
+ * `projectAnalyzeResultForIpc`'s return literal must name exactly these keys
+ * (omitting one is a compile error), and a new field added to `AnalyzeResult`
+ * is simply absent from the wire until it is *deliberately* added here. `Omit`
+ * couldn't give that guarantee — it kept every other field, including OPTIONAL
+ * ones (e.g. `isPrimaryBranch?`), so an optional non-serializable field could be
+ * advertised by the type yet silently dropped by the runtime allowlist.
+ *
+ * `isPrimaryBranch` is intentionally excluded: the parent (`api.ts`) reads only
+ * `repoName`, and nothing consumes `isPrimaryBranch` across this fork (its CLI
+ * consumer calls `runFullAnalysis` in-process). Add a field here only when a
+ * server-side IPC consumer actually needs it — and only if it is JSON-safe.
+ */
+export type AnalyzeResultIpc = Pick<AnalyzeResult, 'repoName' | 'repoPath' | 'stats' | 'alreadyUpToDate' | 'ftsRepairedOnly' | 'ftsSkipped'>;
+/**
+ * Project an `AnalyzeResult` down to the JSON-safe fields the parent consumes,
+ * dropping `pipelineResult` (the live `KnowledgeGraph`) and any other field not
+ * in the `AnalyzeResultIpc` allowlist. The return literal is exhaustive over
+ * `AnalyzeResultIpc` (a missing key is a compile error).
+ */
+export declare function projectAnalyzeResultForIpc(result: AnalyzeResult): AnalyzeResultIpc;

package/dist/server/analyze-worker-ipc.js

@@ -0,0 +1,16 @@
+/**
+ * Project an `AnalyzeResult` down to the JSON-safe fields the parent consumes,
+ * dropping `pipelineResult` (the live `KnowledgeGraph`) and any other field not
+ * in the `AnalyzeResultIpc` allowlist. The return literal is exhaustive over
+ * `AnalyzeResultIpc` (a missing key is a compile error).
+ */
+export function projectAnalyzeResultForIpc(result) {
+    return {
+        repoName: result.repoName,
+        repoPath: result.repoPath,
+        stats: result.stats,
+        alreadyUpToDate: result.alreadyUpToDate,
+        ftsRepairedOnly: result.ftsRepairedOnly,
+        ftsSkipped: result.ftsSkipped,
+    };
+}

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

@@ -10,4 +10,20 @@
  *   Child -> Parent: { type: 'complete', result: AnalyzeResult }
  *   Child -> Parent: { type: 'error', message: string }
  */
-export {};
+import { type AnalyzeResultIpc } from './analyze-worker-ipc.js';
+export interface ProgressMessage {
+    type: 'progress';
+    phase: string;
+    percent: number;
+    message: string;
+}
+export interface CompleteMessage {
+    type: 'complete';
+    result: AnalyzeResultIpc;
+}
+export interface ErrorMessage {
+    type: 'error';
+    message: string;
+}
+/** Child → parent IPC messages. Shared with the parent-side launcher. */
+export type WorkerMessage = ProgressMessage | CompleteMessage | ErrorMessage;

package/dist/server/analyze-worker.js

@@ -11,6 +11,7 @@
  *   Child -> Parent: { type: 'error', message: string }
  */
 import { runFullAnalysis } from '../core/run-analyze.js';
+import { projectAnalyzeResultForIpc } from './analyze-worker-ipc.js';
 import { closeLbug } from '../core/lbug/lbug-adapter.js';
 function send(msg) {
     process.send?.(msg);
@@ -48,7 +49,12 @@ process.on('message', async (msg) => {
                 send({ type: 'progress', phase: 'log', percent: -1, message });
             },
         });
-        send({ type: 'complete', result });
+        // Send a JSON-safe projection, NOT the raw result: the IPC channel is
+        // default-JSON serialization and `result.pipelineResult` carries the live
+        // KnowledgeGraph (wasteful to materialize, silently corrupted by JSON, and
+        // a BigInt/circular value would throw and mis-report this success as a
+        // failure). See analyze-worker-ipc.ts.
+        send({ type: 'complete', result: projectAnalyzeResultForIpc(result) });
     }
     catch (err) {
         send({ type: 'error', message: err?.message || 'Analysis failed' });

package/dist/server/api.d.ts

@@ -72,5 +72,22 @@ export declare const handleFileRequest: (req: {
 export declare const handleQueryRequest: (req: express.Request, res: express.Response, resolveRepo: (repoName?: string) => Promise<{
     storagePath: string;
 } | undefined>) => Promise<void>;
+/**
+ * Validate the optional `token` field of POST /api/analyze. Returns an
+ * { status, error } to send, or null when the token is absent or valid.
+ *
+ * The token is a GitHub PAT: charset-restricted (blocks CRLF header
+ * smuggling), length-bounded (1–256), and bound to github.com using the SAME
+ * GITHUB_TOKEN_HOSTS allowlist + hostname parse as resolveGitCredential, so a
+ * token the API accepts is exactly the one buildGitEnv will inject — and one
+ * it rejects is never sent off github.com.
+ *
+ * Exported for unit tests (the route validation is otherwise only reachable
+ * by booting the server).
+ */
+export declare function validateAnalyzeToken(repoToken: unknown, repoUrl: unknown): {
+    status: number;
+    error: string;
+} | null;
 export declare const createServer: (port: number, host?: string) => Promise<void>;
 export {};