specrails-desktop 2.0.0

package/server/dist/code-explorer-router.js

@@ -0,0 +1,788 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createCodeExplorerRouter = createCodeExplorerRouter;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const child_process_1 = require("child_process");
+const express_1 = require("express");
+const feature_flags_1 = require("./feature-flags");
+const build_dirs_1 = require("./build-dirs");
+const file_provenance_1 = require("./file-provenance");
+const file_summary_manager_1 = require("./file-summary-manager");
+const MAX_TREE_PAGE = 2000;
+const MAX_FILE_BYTES = 2 * 1024 * 1024;
+const BINARY_PROBE_BYTES = 8 * 1024;
+// Hard-coded app deny-list (mirrors design D8). Dotfiles are excluded by name
+// prefix; build/dep dirs come from the shared BUILD_DIRS set (node_modules, dist,
+// build, out, coverage, target, vendor) so the on-demand tree walk skips the same
+// heavy trees the file-summary watcher prunes; extensions handled below.
+const DENY_EXTS = new Set(['.lock', '.log']);
+// Secret-bearing extensions/names blocked as defense-in-depth so credentials are
+// never served to the (non-developer) reader even if .gitignore is missing or git
+// is unavailable. Kept conservative to avoid hiding ordinary source files.
+const SECRET_EXTS = new Set(['.pem', '.key', '.p12', '.pfx', '.keystore', '.jks']);
+const SECRET_NAMES = new Set(['id_rsa', 'id_dsa', 'id_ecdsa', 'id_ed25519']);
+const DENY_NAMES = new Set(['package-lock.json', 'pnpm-lock.yaml', 'yarn.lock']);
+function isDenied(entryName) {
+    // Dotfiles (.env, .npmrc, .netrc, .git, …) are denied wholesale by prefix.
+    if (entryName.startsWith('.'))
+        return true;
+    // Case-insensitive for dir/lockfile names: macOS (APFS) and Windows (NTFS) are
+    // case-insensitive, so `Node_Modules` / `Package-Lock.json` resolve to the same
+    // denied path on disk and must not slip past the policy.
+    const lower = entryName.toLowerCase();
+    if (build_dirs_1.BUILD_DIRS.has(lower))
+        return true;
+    const ext = path_1.default.extname(lower);
+    if (DENY_EXTS.has(ext) || SECRET_EXTS.has(ext))
+        return true;
+    if (DENY_NAMES.has(lower) || SECRET_NAMES.has(lower))
+        return true;
+    return false;
+}
+// Apply the deny-list to ANY segment of a relative path so the policy is the
+// single source of truth across every surface (tree walk, touched-by-ai list,
+// and the content endpoints) — not just the top-level `all` walk.
+function isDeniedRelPath(rel) {
+    return rel.split(/[\\/]/).filter(Boolean).some(isDenied);
+}
+// Normalize a client-supplied relative path to POSIX separators so summary
+// (sha256 of relPath), provenance (git always emits '/'), and content lookups
+// all key off ONE canonical form regardless of the request's separator style.
+function normalizeRel(rel) {
+    return rel.split(/[\\/]/).filter((seg) => seg.length > 0).join('/');
+}
+// Return the subset of `relPaths` that git considers ignored (honours nested
+// .gitignore, excludes tracked files — exactly the set we must hide). One batched
+// `git check-ignore` spawn. Best-effort: any git failure (no repo, no git) → no
+// paths reported, so the deny-list remains the only filter. `check-ignore` exits
+// 1 ("none ignored") which execFileSync throws on — the matched list still lands
+// on stdout, so both branches read stdout.
+function gitIgnoredSet(projectPath, relPaths) {
+    if (relPaths.length === 0)
+        return new Set();
+    let out = '';
+    try {
+        out = (0, child_process_1.execFileSync)('git', ['check-ignore', '--stdin', '-z'], {
+            cwd: projectPath,
+            input: relPaths.join('\0') + '\0',
+            encoding: 'utf8',
+            stdio: ['pipe', 'pipe', 'ignore'],
+            maxBuffer: 16 * 1024 * 1024,
+            timeout: 15_000,
+        });
+    }
+    catch (err) {
+        out = (err.stdout ?? '').toString();
+    }
+    return new Set(out.split('\0').filter((p) => p.length > 0));
+}
+function isGitIgnored(projectPath, relPath) {
+    return gitIgnoredSet(projectPath, [relPath]).has(relPath);
+}
+function languageForExt(ext) {
+    const e = ext.toLowerCase();
+    switch (e) {
+        case '.ts':
+        case '.tsx':
+        case '.cts':
+        case '.mts': return 'typescript';
+        case '.js':
+        case '.jsx':
+        case '.mjs':
+        case '.cjs': return 'javascript';
+        case '.json': return 'json';
+        case '.md': return 'markdown';
+        case '.py': return 'python';
+        case '.rs': return 'rust';
+        case '.go': return 'go';
+        case '.css': return 'css';
+        case '.html': return 'html';
+        case '.yml':
+        case '.yaml': return 'yaml';
+        case '.sh': return 'shell';
+        case '.sql': return 'sql';
+        case '.toml': return 'toml';
+        default: return 'plaintext';
+    }
+}
+function decodeCursor(raw) {
+    if (!raw)
+        return { skip: 0 };
+    try {
+        const json = Buffer.from(raw, 'base64').toString('utf8');
+        const parsed = JSON.parse(json);
+        if (typeof parsed.skip === 'number' && parsed.skip >= 0)
+            return { skip: parsed.skip };
+    }
+    catch {
+        // fall through to default
+    }
+    return { skip: 0 };
+}
+function encodeCursor(skip) {
+    return Buffer.from(JSON.stringify({ skip }), 'utf8').toString('base64');
+}
+function rollupProvenance(rows) {
+    let createdByTicketId = null;
+    const modifiedSet = new Set();
+    // `rows` arrives ordered by `at DESC`. Walk oldest → newest so the earliest
+    // 'created' wins for createdByTicketId.
+    for (const r of [...rows].reverse()) {
+        if (r.ticket_id == null)
+            continue;
+        if (r.kind === 'created' && createdByTicketId == null) {
+            createdByTicketId = r.ticket_id;
+        }
+        else if (r.kind === 'modified') {
+            modifiedSet.add(r.ticket_id);
+        }
+    }
+    // Don't double-count the creating ticket in the modified chips list.
+    if (createdByTicketId != null)
+        modifiedSet.delete(createdByTicketId);
+    return {
+        createdByTicketId,
+        modifiedByTicketIds: [...modifiedSet],
+        latest: rows[0] ?? null,
+        touchedFileCount: 0,
+        rows,
+    };
+}
+function rollupDirectoryProvenance(rowsByPath, dirPath) {
+    const prefix = `${dirPath}/`;
+    const childRows = [];
+    let touchedFileCount = 0;
+    for (const [filePath, rows] of rowsByPath) {
+        if (!filePath.startsWith(prefix))
+            continue;
+        touchedFileCount += 1;
+        childRows.push(...rows);
+    }
+    childRows.sort((a, b) => b.at - a.at);
+    return {
+        ...rollupProvenance(childRows),
+        touchedFileCount,
+    };
+}
+function provenanceToJson(row) {
+    if (!row)
+        return null;
+    return {
+        path: row.file_path,
+        ticketId: row.ticket_id,
+        jobId: row.job_id,
+        kind: row.kind,
+        at: row.at,
+    };
+}
+function provenanceRowsToJson(rows) {
+    return rows.map((row) => ({
+        path: row.file_path,
+        ticketId: row.ticket_id,
+        jobId: row.job_id,
+        kind: row.kind,
+        at: row.at,
+    }));
+}
+function treeProvenanceToJson(provenance) {
+    return {
+        createdByTicketId: provenance.createdByTicketId,
+        modifiedByTicketIds: provenance.modifiedByTicketIds,
+        latest: provenanceToJson(provenance.latest),
+        touchedFileCount: provenance.touchedFileCount,
+        rows: provenanceRowsToJson(provenance.rows),
+    };
+}
+function parsePositiveInt(raw) {
+    if (typeof raw !== 'string' || raw.trim() === '')
+        return null;
+    const n = Number(raw);
+    return Number.isInteger(n) && n > 0 ? n : null;
+}
+function parseNonEmptyString(raw) {
+    return typeof raw === 'string' && raw.trim() !== '' ? raw.trim() : null;
+}
+function listTouchedRows(db, filters) {
+    const where = [];
+    const args = [];
+    if (filters.ticketId != null) {
+        where.push('ticket_id = ?');
+        args.push(filters.ticketId);
+    }
+    if (filters.jobId) {
+        where.push('job_id = ?');
+        args.push(filters.jobId);
+    }
+    if (filters.path) {
+        where.push('file_path = ?');
+        args.push(filters.path);
+    }
+    const whereSql = where.length > 0 ? `WHERE ${where.join(' AND ')}` : '';
+    return db.prepare(`SELECT id, file_path, ticket_id, job_id, kind, at
+     FROM file_provenance ${whereSql}
+     ORDER BY file_path ASC, at DESC`).all(...args);
+}
+function listAllEntries(projectPath) {
+    const out = [];
+    const stack = [projectPath];
+    while (stack.length > 0) {
+        const dir = stack.pop();
+        let entries;
+        try {
+            entries = fs_1.default.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            if (isDenied(entry.name))
+                continue;
+            const abs = path_1.default.join(dir, entry.name);
+            // Normalize to POSIX so provenance/summary lookups (which are '/'-keyed)
+            // match on Windows, where path.relative emits backslashes.
+            const rel = normalizeRel(path_1.default.relative(projectPath, abs));
+            if (entry.isDirectory()) {
+                out.push({ rel, isDir: true, size: null, mtime: null });
+                stack.push(abs);
+            }
+            else if (entry.isFile()) {
+                let size = null;
+                let mtime = null;
+                try {
+                    const st = fs_1.default.statSync(abs);
+                    size = st.size;
+                    mtime = st.mtimeMs;
+                }
+                catch {
+                    // ignore
+                }
+                out.push({ rel, isDir: false, size, mtime });
+            }
+        }
+    }
+    // Drop gitignored files (honours the documented .gitignore-respect contract).
+    // Directories are kept — git can't report an ignored dir without its files, and
+    // an empty dir node is harmless; its ignored children are already filtered.
+    const files = out.filter((e) => !e.isDir).map((e) => e.rel);
+    const ignored = gitIgnoredSet(projectPath, files);
+    const filtered = ignored.size > 0 ? out.filter((e) => e.isDir || !ignored.has(e.rel)) : out;
+    filtered.sort((a, b) => a.rel.localeCompare(b.rel));
+    return filtered;
+}
+function listTouchedEntries(projectPath, rowsByPath) {
+    const seen = new Set();
+    const out = [];
+    for (const filePath of rowsByPath.keys()) {
+        // Keep touched-by-ai consistent with the `all` tree (and never surface
+        // secrets like .env that an AI job happened to touch).
+        if (isDeniedRelPath(filePath))
+            continue;
+        const parts = filePath.split('/').filter(Boolean);
+        for (let i = 1; i < parts.length; i += 1) {
+            const dirRel = parts.slice(0, i).join('/');
+            if (!seen.has(dirRel)) {
+                seen.add(dirRel);
+                out.push({ rel: dirRel, isDir: true, size: null, mtime: null });
+            }
+        }
+        if (seen.has(filePath))
+            continue;
+        seen.add(filePath);
+        const abs = path_1.default.join(projectPath, filePath);
+        let size = null;
+        let mtime = null;
+        try {
+            const st = fs_1.default.statSync(abs);
+            size = st.size;
+            mtime = st.mtimeMs;
+        }
+        catch {
+            // file may have been deleted after provenance was recorded
+        }
+        out.push({ rel: filePath, isDir: false, size, mtime });
+    }
+    out.sort((a, b) => {
+        const byPath = a.rel.localeCompare(b.rel);
+        if (byPath !== 0)
+            return byPath;
+        return Number(b.isDir) - Number(a.isDir);
+    });
+    return out;
+}
+// Set of summary file basenames (without `.json`), i.e. the path-hash of every
+// file that currently has a summary on disk. One readdir replaces a per-entry
+// readSummary disk hit during the tree walk.
+function readSummaryHashSet(projectPath) {
+    const set = new Set();
+    let files;
+    try {
+        files = fs_1.default.readdirSync((0, file_summary_manager_1.summariesDir)(projectPath));
+    }
+    catch {
+        return set;
+    }
+    for (const f of files) {
+        if (f.endsWith('.json'))
+            set.add(f.slice(0, -'.json'.length));
+    }
+    return set;
+}
+function createCodeExplorerRouter(deps) {
+    const router = (0, express_1.Router)({ mergeParams: true });
+    const listByPath = deps.listProvenanceByPath ?? file_provenance_1.listProvenanceByPath;
+    const listByTicket = deps.listProvenanceByTicket ?? file_provenance_1.listProvenanceByTicket;
+    // Short-TTL per-project cache so paginating a large `all` tree reuses ONE
+    // synchronous filesystem walk instead of re-walking (and re-statting) on every
+    // page — the cursor only slices an already-materialized array. Also caches the
+    // one-readdir summary-hash set. 5s is long enough for a pagination burst and
+    // short enough that tree edits surface promptly.
+    const WALK_CACHE_TTL_MS = 5000;
+    let allEntriesCache = null;
+    let summaryHashCache = null;
+    const nowMs = () => Date.now();
+    function getAllEntriesCached() {
+        if (allEntriesCache && nowMs() - allEntriesCache.at < WALK_CACHE_TTL_MS)
+            return allEntriesCache.entries;
+        const entries = listAllEntries(deps.projectPath);
+        allEntriesCache = { at: nowMs(), entries };
+        return entries;
+    }
+    function getSummaryHashesCached() {
+        if (summaryHashCache && nowMs() - summaryHashCache.at < WALK_CACHE_TTL_MS)
+            return summaryHashCache.set;
+        const set = readSummaryHashSet(deps.projectPath);
+        summaryHashCache = { at: nowMs(), set };
+        return set;
+    }
+    // Feature-flag gate — entire prefix returns 404 when disabled.
+    router.use((_req, res, next) => {
+        if (!(0, feature_flags_1.isCodeExplorerEnabled)()) {
+            res.status(404).end();
+            return;
+        }
+        // Lazily attach the file-summary watcher on first Code-Explorer use. It is
+        // not attached at registry load (that recursive watcher caused the fd leak
+        // that broke terminals); attachWatcher is idempotent, so this is cheap on
+        // every subsequent request.
+        try {
+            deps.fileSummaryManager.attachWatcher(deps.projectId, deps.projectPath);
+        }
+        catch { /* non-fatal */ }
+        next();
+    });
+    router.get('/tree', (req, res) => {
+        const filter = req.query.filter ?? 'touched-by-ai';
+        const withProvenance = req.query.withProvenance === '1' || req.query.withProvenance === 'true';
+        const { skip } = decodeCursor(req.query.cursor);
+        const ticketId = parsePositiveInt(req.query.ticketId);
+        const jobId = parseNonEmptyString(req.query.jobId);
+        let entries;
+        const touchedRowsByPath = new Map();
+        if (filter === 'touched-by-ai') {
+            const rows = listTouchedRows(deps.db, { ticketId, jobId });
+            for (const row of rows) {
+                const existing = touchedRowsByPath.get(row.file_path);
+                if (existing)
+                    existing.push(row);
+                else
+                    touchedRowsByPath.set(row.file_path, [row]);
+            }
+            entries = listTouchedEntries(deps.projectPath, touchedRowsByPath);
+        }
+        else {
+            entries = getAllEntriesCached();
+            // Batch-load ALL provenance once instead of a per-entry SQL query (N+1).
+            if (withProvenance) {
+                for (const row of listTouchedRows(deps.db, {})) {
+                    const existing = touchedRowsByPath.get(row.file_path);
+                    if (existing)
+                        existing.push(row);
+                    else
+                        touchedRowsByPath.set(row.file_path, [row]);
+                }
+            }
+        }
+        const page = entries.slice(skip, skip + MAX_TREE_PAGE);
+        const nextCursor = skip + page.length < entries.length ? encodeCursor(skip + page.length) : null;
+        // Read the summaries dir ONCE into a Set of path-hashes instead of opening +
+        // parsing a JSON file per entry just to test existence (cached per project).
+        const summaryHashes = getSummaryHashesCached();
+        const out = page.map((e) => {
+            const isTouchedDir = filter === 'touched-by-ai' && e.isDir;
+            const rawRows = withProvenance && !isTouchedDir ? (touchedRowsByPath.get(e.rel) ?? []) : [];
+            const provenance = withProvenance && isTouchedDir
+                ? rollupDirectoryProvenance(touchedRowsByPath, e.rel)
+                : rollupProvenance(rawRows);
+            return {
+                path: e.rel,
+                kind: e.isDir ? 'dir' : 'file',
+                sizeBytes: e.size,
+                hasSummary: !e.isDir && summaryHashes.has((0, file_summary_manager_1.pathHash)(e.rel)),
+                provenance,
+                lastModifiedAt: e.mtime,
+            };
+        });
+        res.json({
+            entries: out.map((entry) => ({
+                ...entry,
+                provenance: treeProvenanceToJson(entry.provenance),
+            })),
+            nextCursor,
+        });
+    });
+    router.get('/file', async (req, res) => {
+        const relRaw = req.query.path;
+        if (!relRaw || typeof relRaw !== 'string') {
+            res.status(400).json({ error: 'path query parameter is required' });
+            return;
+        }
+        const guard = resolveSafePath(deps.projectPath, relRaw);
+        if (!guard) {
+            res.status(400).json({ error: 'path traversal not allowed' });
+            return;
+        }
+        if (isDeniedRelPath(relRaw)) {
+            res.status(403).json({ error: 'path is excluded by the code-explorer deny-list' });
+            return;
+        }
+        // Canonical POSIX form for all summary/provenance/hash lookups.
+        const rel = normalizeRel(relRaw);
+        if (isGitIgnored(deps.projectPath, rel)) {
+            res.status(403).json({ error: 'path is gitignored' });
+            return;
+        }
+        const abs = guard;
+        let stat;
+        try {
+            stat = fs_1.default.statSync(abs);
+        }
+        catch {
+            // Honour the staleness scenario: even if content is unavailable, return
+            // the existing summary so the client can render a "not found" banner.
+            const summary = (0, file_summary_manager_1.readSummary)(deps.projectPath, rel);
+            const provenance = listByPath(deps.db, deps.projectId, rel);
+            if (summary || provenance.length > 0) {
+                res.json({
+                    content: null,
+                    reason: 'not-found',
+                    summary,
+                    summaryStale: true,
+                    provenance: provenanceRowsToJson(provenance),
+                });
+                return;
+            }
+            res.status(404).json({ error: 'file not found' });
+            return;
+        }
+        if (!stat.isFile()) {
+            res.status(400).json({ error: 'path is not a regular file' });
+            return;
+        }
+        if (stat.size > MAX_FILE_BYTES) {
+            res.json({
+                tooLarge: true,
+                sizeBytes: stat.size,
+                provenance: provenanceRowsToJson(listByPath(deps.db, deps.projectId, rel)),
+                summary: (0, file_summary_manager_1.readSummary)(deps.projectPath, rel),
+                absolutePath: abs,
+            });
+            return;
+        }
+        // Binary detection: read first 8 KB, scan for NUL.
+        let head;
+        try {
+            const fd = fs_1.default.openSync(abs, 'r');
+            try {
+                head = Buffer.alloc(Math.min(BINARY_PROBE_BYTES, stat.size));
+                fs_1.default.readSync(fd, head, 0, head.length, 0);
+            }
+            finally {
+                fs_1.default.closeSync(fd);
+            }
+        }
+        catch {
+            res.status(500).json({ error: 'failed to read file' });
+            return;
+        }
+        if (head.includes(0)) {
+            res.json({
+                binary: true,
+                sizeBytes: stat.size,
+                mime: 'application/octet-stream',
+                provenance: provenanceRowsToJson(listByPath(deps.db, deps.projectId, rel)),
+                summary: (0, file_summary_manager_1.readSummary)(deps.projectPath, rel),
+                absolutePath: abs,
+            });
+            return;
+        }
+        let content;
+        try {
+            content = fs_1.default.readFileSync(abs, 'utf8');
+        }
+        catch {
+            res.status(500).json({ error: 'failed to read file' });
+            return;
+        }
+        const summary = (0, file_summary_manager_1.readSummary)(deps.projectPath, rel);
+        const summaryStale = await computeStaleness(abs, summary);
+        res.json({
+            content,
+            encoding: 'utf-8',
+            language: languageForExt(path_1.default.extname(rel)),
+            provenance: provenanceRowsToJson(listByPath(deps.db, deps.projectId, rel)),
+            summary,
+            summaryStale,
+            absolutePath: abs,
+        });
+    });
+    router.get('/summary', async (req, res) => {
+        const relRaw = req.query.path;
+        if (!relRaw || typeof relRaw !== 'string') {
+            res.status(400).json({ error: 'path query parameter is required' });
+            return;
+        }
+        const guard = resolveSafePath(deps.projectPath, relRaw);
+        if (!guard) {
+            res.status(400).json({ error: 'path traversal not allowed' });
+            return;
+        }
+        if (isDeniedRelPath(relRaw)) {
+            res.status(403).json({ error: 'path is excluded by the code-explorer deny-list' });
+            return;
+        }
+        const rel = normalizeRel(relRaw);
+        if (isGitIgnored(deps.projectPath, rel)) {
+            res.status(403).json({ error: 'path is gitignored' });
+            return;
+        }
+        const summary = (0, file_summary_manager_1.readSummary)(deps.projectPath, rel);
+        if (!summary) {
+            res.json({ summary: null });
+            return;
+        }
+        let summaryStale = false;
+        try {
+            summaryStale = await computeStaleness(guard, summary);
+        }
+        catch {
+            summaryStale = true;
+        }
+        res.json({ summary, summaryStale });
+    });
+    router.post('/file/regenerate-summary', async (req, res) => {
+        const relRaw = req.query.path;
+        if (!relRaw || typeof relRaw !== 'string') {
+            res.status(400).json({ error: 'path query parameter is required' });
+            return;
+        }
+        const guard = resolveSafePath(deps.projectPath, relRaw);
+        if (!guard) {
+            res.status(400).json({ error: 'path traversal not allowed' });
+            return;
+        }
+        if (isDeniedRelPath(relRaw)) {
+            res.status(403).json({ error: 'path is excluded by the code-explorer deny-list' });
+            return;
+        }
+        const rel = normalizeRel(relRaw);
+        if (isGitIgnored(deps.projectPath, rel)) {
+            res.status(403).json({ error: 'path is gitignored' });
+            return;
+        }
+        let stat;
+        try {
+            stat = fs_1.default.statSync(guard);
+        }
+        catch {
+            res.status(404).json({ skipped: 'not-found' });
+            return;
+        }
+        if (!stat.isFile()) {
+            res.status(400).json({ skipped: 'not-file' });
+            return;
+        }
+        if (stat.size > MAX_FILE_BYTES) {
+            res.status(413).json({ skipped: 'too-large' });
+            return;
+        }
+        try {
+            const fd = fs_1.default.openSync(guard, 'r');
+            try {
+                const head = Buffer.alloc(Math.min(BINARY_PROBE_BYTES, stat.size));
+                fs_1.default.readSync(fd, head, 0, head.length, 0);
+                if (head.includes(0)) {
+                    res.status(415).json({ skipped: 'binary' });
+                    return;
+                }
+            }
+            finally {
+                fs_1.default.closeSync(fd);
+            }
+        }
+        catch {
+            res.status(500).json({ error: 'failed to inspect file' });
+            return;
+        }
+        const body = (req.body ?? {});
+        try {
+            // force: true — an explicit "Regenerate" click should re-summarise even if
+            // the content hash is unchanged (e.g. after an app language switch).
+            const result = await deps.fileSummaryManager.enqueue({
+                projectPath: deps.projectPath,
+                projectId: deps.projectId,
+                projectSlug: deps.projectId,
+                relPath: rel,
+                triggeredBy: { kind: 'user', id: 'manual', ticketId: null },
+                overrideBudget: body.overrideBudget === true,
+                force: true,
+            });
+            // Surface the enqueue outcome so the client's budget-override prompt is
+            // reachable. 200 (not 4xx) keeps res.ok true so the client reads `skipped`.
+            if (result === 'skipped:budget') {
+                res.status(200).json({ skipped: 'budget' });
+                return;
+            }
+            if (result === 'skipped:per-job-cap') {
+                res.status(200).json({ skipped: 'per-job-cap' });
+                return;
+            }
+            // TTL-dropped (queue saturated >5min) and not-found (file vanished between
+            // the stat above and the worker) must NOT masquerade as a 202 success —
+            // surface them so the client toasts "try again" instead of silently
+            // clearing the spinner with no summary.
+            if (result === 'skipped:ttl') {
+                res.status(200).json({ skipped: 'ttl' });
+                return;
+            }
+            if (result === 'skipped:not-found') {
+                res.status(200).json({ skipped: 'not-found' });
+                return;
+            }
+            if (result === 'failed') {
+                res.status(500).json({ error: 'summary generation failed' });
+                return;
+            }
+            res.status(202).json({ enqueued: true });
+        }
+        catch (err) {
+            console.error('[code-explorer-router] enqueue failed:', err);
+            res.status(500).json({ error: 'enqueue failed', message: err.message });
+        }
+    });
+    router.get('/provenance', (req, res) => {
+        const ticketId = parsePositiveInt(req.query.ticketId);
+        const jobId = parseNonEmptyString(req.query.jobId);
+        const relPath = parseNonEmptyString(req.query.path);
+        if (relPath) {
+            const guard = resolveSafePath(deps.projectPath, relPath);
+            if (!guard) {
+                res.status(400).json({ error: 'path traversal not allowed' });
+                return;
+            }
+            // Mirror the content endpoints: never leak even the metadata (which ticket/
+            // job touched it, when) of a denied/secret file.
+            if (isDeniedRelPath(relPath)) {
+                res.status(403).json({ error: 'path is excluded by the code-explorer deny-list' });
+                return;
+            }
+        }
+        if (ticketId == null && !jobId && !relPath) {
+            res.status(400).json({ error: 'ticketId, jobId, or path query parameter is required' });
+            return;
+        }
+        if (req.query.ticketId != null && ticketId == null) {
+            res.status(400).json({ error: 'ticketId must be a positive integer' });
+            return;
+        }
+        const rows = ticketId != null && !jobId && !relPath
+            ? listByTicket(deps.db, deps.projectId, ticketId)
+            : listTouchedRows(deps.db, { ticketId, jobId, path: relPath ? normalizeRel(relPath) : relPath });
+        res.json(provenanceRowsToJson(rows));
+    });
+    router.get('/diff', (req, res) => {
+        const jobId = parseNonEmptyString(req.query.jobId);
+        const relPath = parseNonEmptyString(req.query.path);
+        if (!jobId || !relPath) {
+            res.status(400).json({ error: 'jobId and path query parameters are required' });
+            return;
+        }
+        const guard = resolveSafePath(deps.projectPath, relPath);
+        if (!guard) {
+            res.status(400).json({ error: 'path traversal not allowed' });
+            return;
+        }
+        const diff = (0, file_provenance_1.getProvenanceDiff)(deps.db, deps.projectId, jobId, normalizeRel(relPath));
+        if (!diff) {
+            res.status(404).json({ error: 'diff not available' });
+            return;
+        }
+        res.json(diff);
+    });
+    return router;
+}
+function resolveSafePath(projectPath, relPath) {
+    // Reject absolute paths and any path with explicit traversal segments before
+    // we ever hit the filesystem. resolve() can collapse `..` legally so we still
+    // verify the prefix below.
+    if (path_1.default.isAbsolute(relPath))
+        return null;
+    const resolved = path_1.default.resolve(projectPath, relPath);
+    const root = projectPath.endsWith(path_1.default.sep) ? projectPath : projectPath + path_1.default.sep;
+    if (resolved !== projectPath && !resolved.startsWith(root))
+        return null;
+    // Symlink hardening: the lexical check above is defeated by an in-tree symlink
+    // whose target escapes the project (e.g. `link -> /etc/passwd`). Verify the
+    // REAL path stays under the REAL project root. Walk up to the nearest existing
+    // ancestor (so not-yet-created paths — used by the not-found banner and the
+    // regenerate endpoint — still validate), realpath it, then re-append the
+    // missing suffix.
+    let realRoot;
+    try {
+        realRoot = fs_1.default.realpathSync.native(projectPath);
+    }
+    catch {
+        // Project root itself is uncanonicalisable — fail CLOSED. Returning the
+        // lexical path here would silently drop the symlink-escape hardening (the
+        // lexical check alone is defeatable by an in-tree symlink pointing outside
+        // the project). Reading any file is pointless if the root can't resolve.
+        return null;
+    }
+    const realRootWithSep = realRoot.endsWith(path_1.default.sep) ? realRoot : realRoot + path_1.default.sep;
+    let probe = resolved;
+    const suffix = [];
+    for (;;) {
+        try {
+            const realProbe = fs_1.default.realpathSync.native(probe);
+            const realFull = suffix.length > 0
+                ? path_1.default.join(realProbe, ...suffix.slice().reverse())
+                : realProbe;
+            if (realFull !== realRoot && !realFull.startsWith(realRootWithSep))
+                return null;
+            return resolved;
+        }
+        catch (err) {
+            if (err.code !== 'ENOENT')
+                return null;
+            const parent = path_1.default.dirname(probe);
+            if (parent === probe)
+                return null; // hit filesystem root without resolving
+            suffix.push(path_1.default.basename(probe));
+            probe = parent;
+        }
+    }
+}
+async function computeStaleness(abs, summary) {
+    if (!summary)
+        return false;
+    try {
+        const currentHash = await (0, file_summary_manager_1.computeFileHash)(abs);
+        return currentHash !== summary.fileHash;
+    }
+    catch {
+        return true;
+    }
+}