dsh-gitnexus-plus 0.0.0-stage → 0.1.2

package/lib/index.js

@@ -0,0 +1,252 @@
+/**
+ * dsh-gitnexus-plus —host half.
+ *
+ * Registers one read-only tool and one loopback HTTP route over the coverage
+ * engine in `./gitnexus/`. Both answer the same question —"what did this index
+ * leave out?" —for the two callers that need it: the model, and a browser half
+ * that will render it.
+ *
+ * The read path is still never allowed to change anything: a status check must not
+ * start a 30-second rebuild. The two mutating capabilities are separate routes with
+ * their own guards, and both go through the host's shell executor rather than
+ * spawning from the read path. Keyword search is a third read-only route over the
+ * graph itself; the tool above stays read-only.
+ */
+import { fileURLToPath } from 'node:url';
+import Schema from '@deepseek-ai/schemastery';
+import { defineTool } from '@deepseek-ai/dsh-tools';
+import { analyzeCoverage } from './gitnexus/coverage.js';
+import { formatReport } from './gitnexus/format.js';
+import { commandRationale, defaultGitnexusHome, effectiveSkipFts, maintenanceCommands, } from './gitnexus/commands.js';
+import { mountCoverageRoute } from './routes/coverage.js';
+import { mountAnalyzeRoute } from './routes/analyze.js';
+import { mountInstallRoute } from './routes/install.js';
+import { mountSearchRoute } from './routes/search.js';
+import { searchWithFallback } from './gitnexus/search.js';
+import { createAnalyzeRunner } from './gitnexus/analyze.js';
+import { createInstallRunner, defaultInstallPrefix } from './gitnexus/install.js';
+/**
+ * Whether a service resolved from the context has the shape the runner needs.
+ *
+ * `ctx.get` is untyped here —the DSH packages ship no declarations, so the service
+ * arrives as `unknown`. Checking the two methods the runner actually calls is the
+ * narrowest claim that can be made: asserting the full `ctx.shell` contract from this
+ * side would be a guess, and a wrong guess fails at the first click rather than here.
+ */
+function isShellLike(value) {
+    if (value === null || typeof value !== 'object')
+        return false;
+    const candidate = value;
+    return typeof candidate.resolve === 'function' && typeof candidate.execute === 'function';
+}
+export const name = 'gitnexus-plus';
+/**
+ * Only `tools` is required. `webServer` is reached through `ctx.inject` because a
+ * headless profile has no HTTP carrier at all —naming it here would leave the
+ * plugin permanently pending there, and the tool would never register.
+ */
+export const inject = ['tools'];
+export const Config = Schema.object({
+    scanDefaultCapKb: Schema.natural().default(512),
+    minifiedSampleLimit: Schema.natural().default(40),
+    serveRoutes: Schema.boolean().default(true),
+    skipFts: Schema.boolean().default(false),
+    memoryOff: Schema.boolean().default(true),
+    analyzeHeapMb: Schema.natural().default(8192),
+    analyzeTimeoutMs: Schema.natural().default(600000),
+    gitnexusInstallDir: Schema.string().default(''),
+    installTimeoutMs: Schema.natural().default(1200000),
+    gitnexusHome: Schema.string().default(''),
+});
+const configShapeMatches = true;
+void configShapeMatches;
+export function apply(ctx, config) {
+    const cache = new Map();
+    const CACHE_TTL_MS = 15_000;
+    /**
+     * The one install location, resolved once and shared by every path that needs to
+     * know it. This was the broken link in "install, then initialize": the installer
+     * wrote a plugin-owned tree under DSH_HOME, while the coverage engine and the
+     * analyze runner probed only PATH and the declared dependency. On a machine with
+     * no global GitNexus the install succeeded and then *nothing used it* — the panel
+     * still reported "absent" and the refresh still said "no CLI". Passing the same
+     * prefix to all three (reader, language detector, runner) is what makes the
+     * install a prerequisite rather than an isolated side effect.
+     */
+    const installPrefix = config.gitnexusInstallDir === '' ? defaultInstallPrefix() : config.gitnexusInstallDir;
+    const managedToolchain = { managedPrefix: installPrefix };
+    // Resolved at boot so a search never depends on the host's working directory. The
+    // file is run by the system Node (see `searchViaHelper`); this process only names it.
+    const searchHelperPath = fileURLToPath(new URL('./bin/search-helper.js', import.meta.url));
+    /**
+     * Resolve a coverage report, from cache when it is recent enough.
+     *
+     * Scan results are pure functions of the working tree, so a short TTL removes the
+     * repeated cost of a 28k-file walk without ever showing a stale verdict to a caller
+     * who just changed something.
+     *
+     * `fresh` bypasses the TTL. A manual refresh is an explicit instruction from a
+     * person who believes the numbers may have moved, and answering it with a cached
+     * copy makes the control look broken —which is exactly how it was reported. A
+     * background poll is the case the TTL exists for; a click is not.
+     */
+    const coverageFor = async (repoPath, options = {}) => {
+        const key = String(repoPath);
+        if (options.fresh !== true) {
+            const hit = cache.get(key);
+            if (hit !== undefined && Date.now() - hit.at < CACHE_TTL_MS)
+                return hit.report;
+        }
+        const report = await analyzeCoverage(key, {
+            minifiedSampleLimit: config.minifiedSampleLimit,
+            toolchain: managedToolchain,
+        });
+        cache.set(key, { at: Date.now(), report });
+        return report;
+    };
+    /**
+     * The maintenance commands, resolved at the boundary rather than inside
+     * `analyzeCoverage`: they depend on this plugin's config, and the report is a
+     * pure function of the repository.
+     */
+    const maintenanceFor = (repoPath) => {
+        const options = {
+            // `skipFts: false` means automatic, not "attempt FTS": if the index has no FTS,
+            // attempting the install dies with `spawn EPERM` in a confined host.
+            skipFts: effectiveSkipFts(repoPath, config.skipFts),
+            memoryOff: config.memoryOff,
+            // Default to a plugin-owned home inside the project so the global registry
+            // write stays within the workspace. The explicit config still wins.
+            gitnexusHome: config.gitnexusHome === '' ? defaultGitnexusHome(repoPath) : config.gitnexusHome,
+        };
+        return {
+            commands: maintenanceCommands(repoPath, options),
+            rationale: commandRationale(options),
+            supportsForce: true,
+        };
+    };
+    ctx.tools.register(defineTool({
+        name: 'gitnexus_coverage',
+        description: 'Report what a GitNexus index omitted for a repository: files skipped for exceeding the ' +
+            'size cap, oversized generated/minified output that inflates a language share, and files ' +
+            'a fresh scan would select but the index does not cover. Read-only; never triggers a ' +
+            're-index. Use it to judge how much of a repository the index actually represents before ' +
+            'trusting graph queries.',
+        parameters: {
+            repo: {
+                type: 'string',
+                required: true,
+                description: 'Absolute path to the repository root (the directory containing .gitnexus).',
+            },
+            includeLanguages: {
+                type: 'boolean',
+                description: 'Include the per-language byte breakdown in the result. Defaults to true.',
+            },
+        },
+        output: {
+            schema: {
+                type: 'object',
+                additionalProperties: true,
+                properties: {
+                    // `required: true` per property, never `required: [...]`. The DSL's
+                    // compiler rejects the array form outright —it collects these marks
+                    // into the JSON Schema `required` list itself.
+                    text: { type: 'string', required: true },
+                    indexed: { type: 'boolean', required: true },
+                    largeFileCount: { type: 'integer', required: true },
+                    largeBytes: { type: 'integer', required: true },
+                    warnings: { type: 'array' },
+                },
+            },
+            render: (_args, value) => [{ type: 'text', text: value.text }],
+        },
+        async execute(args) {
+            const report = await coverageFor(args.repo);
+            return {
+                text: formatReport(report, args.includeLanguages !== false),
+                indexed: report.repo.indexed,
+                largeFileCount: report.totals.large,
+                largeBytes: report.totals.largeBytes,
+                warnings: report.warnings.map((w) => ({ level: w.level, code: w.code, message: w.message })),
+            };
+        },
+        presentCall: (args) => ({
+            card: 'generic',
+            title: `GitNexus coverage 路 ${String(args.repo).split(/[\\/]/).pop()}`,
+            kind: 'read',
+        }),
+    }));
+    if (config.serveRoutes) {
+        // Optional carrier: absent on headless profiles, so the tool above still works.
+        ctx.inject(['webServer'], (svcCtx) => {
+            // Read through `ctx.get` rather than injecting, because `shell` is optional here
+            // and `inject` would make the whole route block wait for a service a headless
+            // deployment never provides. `null` is handed to the runner, which reports
+            // `unavailable` and tells the operator to run the command themselves —the
+            // read-only half of the panel keeps working either way.
+            const shellRaw = svcCtx.get('shell');
+            const searchShell = isShellLike(shellRaw) ? shellRaw : null;
+            const analyze = createAnalyzeRunner({
+                shell: searchShell,
+                timeoutMs: config.analyzeTimeoutMs,
+                toolchain: managedToolchain,
+                // The runner must read the same config as the command text it confirms,
+                // otherwise the dialog describes a command the run does not execute. It
+                // resolves `false` per repository (automatic), and defaults to the
+                // project-local `GITNEXUS_HOME` when the config leaves it empty.
+                skipFts: config.skipFts,
+                gitnexusHome: config.gitnexusHome === '' ? null : config.gitnexusHome,
+            });
+            // GitNexus is what produces the index this plugin reads, so a machine without it
+            // has nothing to display and no way to change that from here. This runner is the
+            // way out: it installs a plugin-owned copy so the operator does not have to work
+            // out a package manager, a registry, or a global prefix themselves.
+            const install = createInstallRunner({
+                shell: isShellLike(shellRaw) ? shellRaw : null,
+                prefix: installPrefix,
+                timeoutMs: config.installTimeoutMs,
+            });
+            const disposers = [
+                mountCoverageRoute(svcCtx.webServer, {
+                    get: (repoPath, options) => coverageFor(repoPath, options),
+                    maintenance: (repoPath) => maintenanceFor(repoPath),
+                }),
+                mountAnalyzeRoute(svcCtx.webServer, {
+                    start: (repoPath, options) => analyze.start(repoPath, options),
+                    status: (repoPath) => analyze.status(repoPath),
+                    cancel: (repoPath) => analyze.cancel(repoPath),
+                }),
+                mountInstallRoute(svcCtx.webServer, {
+                    start: () => install.start(),
+                    status: () => install.status(),
+                    cancel: () => install.cancel(),
+                    cliPath: () => install.cliPath(),
+                }),
+                mountSearchRoute(svcCtx.webServer, {
+                    search: (repoPath, query, options) => searchWithFallback(repoPath, query, {
+                        shell: searchShell,
+                        helperPath: searchHelperPath,
+                        limit: options?.limit,
+                        managedPrefix: installPrefix,
+                    }),
+                }),
+            ];
+            ctx.effect(() => () => {
+                for (const dispose of disposers)
+                    dispose();
+                // Abort before clearing, so a run in flight is stopped rather than orphaned
+                // holding a handle onto a server that no longer exists.
+                analyze.dispose();
+                install.dispose();
+                cache.clear();
+            }, 'gitnexus-plus: HTTP routes');
+        });
+    }
+}
+/**
+ * Human-readable rendering lives in `./gitnexus/format.js` —free of DSH imports
+ * so it can be tested without a host. Re-exported here for callers that already
+ * hold the plugin module.
+ */
+export { formatReport } from './gitnexus/format.js';
+//# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/lib/routes/analyze.d.ts

@@ -0,0 +1,41 @@
+/**
+ * The one endpoint that changes something.
+ *
+ * Everything else this plugin serves is a reading of the working tree; this route
+ * starts `gitnexus analyze --index-only` through the host's shell executor. It is a
+ * separate module from `coverage.ts` rather than another branch inside it, so the
+ * read-only half keeps a guard set that cannot mutate and this half can be reviewed
+ * on its own.
+ *
+ * THREE METHODS, THREE MEANINGS
+ * -----------------------------
+ * `POST` starts a run, `GET` reports where it got to, `DELETE` asks it to stop. They
+ * are one endpoint because the run is one resource and the panel polls the same URL it
+ * started, which removes the id bookkeeping a separate status route would need.
+ *
+ * WHAT THIS ROUTE DOES NOT DO
+ * ---------------------------
+ * It does not escalate. The runner never sets `sandboxPolicy`, so the process is
+ * confined exactly as the deployment confines every other command. A refusal comes
+ * back as `denied` and is not retried wider — see `gitnexus/analyze.ts`, which is
+ * where that decision lives and is tested.
+ */
+import type { WebServerService } from '@deepseek-ai/cordis';
+import type { AnalyzeStatus } from '../gitnexus/analyze.js';
+export interface AnalyzeRouteDeps {
+    /**
+     * Begin a run, or return the one already in flight for this repository.
+     * `force` selects the destructive full rebuild; it is passed through, never
+     * inferred from the method or the route.
+     */
+    start: (repoPath: string, options?: {
+        force?: boolean;
+    }) => AnalyzeStatus;
+    status: (repoPath: string) => AnalyzeStatus | null;
+    cancel: (repoPath: string) => boolean;
+}
+/**
+ * @returns disposer that unregisters the route
+ */
+export declare function mountAnalyzeRoute(webServer: WebServerService, deps: AnalyzeRouteDeps): () => void;
+//# sourceMappingURL=analyze.d.ts.map

package/lib/routes/analyze.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"analyze.d.ts","sourceRoot":"","sources":["../../src/routes/analyze.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAIH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAC5D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAQ5D,MAAM,WAAW,gBAAgB;IAC/B;;;;OAIG;IACH,KAAK,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,KAAK,aAAa,CAAC;IAC1E,MAAM,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,aAAa,GAAG,IAAI,CAAC;IACnD,MAAM,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC;CACvC;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,gBAAgB,EAAE,IAAI,EAAE,gBAAgB,GAAG,MAAM,IAAI,CA2CjG"}

package/lib/routes/analyze.js

@@ -0,0 +1,75 @@
+/**
+ * The one endpoint that changes something.
+ *
+ * Everything else this plugin serves is a reading of the working tree; this route
+ * starts `gitnexus analyze --index-only` through the host's shell executor. It is a
+ * separate module from `coverage.ts` rather than another branch inside it, so the
+ * read-only half keeps a guard set that cannot mutate and this half can be reviewed
+ * on its own.
+ *
+ * THREE METHODS, THREE MEANINGS
+ * -----------------------------
+ * `POST` starts a run, `GET` reports where it got to, `DELETE` asks it to stop. They
+ * are one endpoint because the run is one resource and the panel polls the same URL it
+ * started, which removes the id bookkeeping a separate status route would need.
+ *
+ * WHAT THIS ROUTE DOES NOT DO
+ * ---------------------------
+ * It does not escalate. The runner never sets `sandboxPolicy`, so the process is
+ * confined exactly as the deployment confines every other command. A refusal comes
+ * back as `denied` and is not retried wider — see `gitnexus/analyze.ts`, which is
+ * where that decision lives and is tested.
+ */
+import path from 'node:path';
+import { guardHandler, passGuard, passWriteGuard, answerHead, sendJson } from './guard.js';
+/**
+ * The methods this route answers. A wider set than the coverage route's on purpose:
+ * the difference between the two routes *is* their method policy.
+ */
+const ANALYZE_METHODS = new Set(['GET', 'HEAD', 'POST', 'DELETE']);
+/**
+ * @returns disposer that unregisters the route
+ */
+export function mountAnalyzeRoute(webServer, deps) {
+    const handler = guardHandler(async (req, res) => {
+        if (!passGuard(req, res, ANALYZE_METHODS))
+            return;
+        const url = new URL(req.url ?? '/', 'http://127.0.0.1');
+        const repo = url.searchParams.get('repo');
+        if (repo === null || repo.trim() === '') {
+            sendJson(res, 400, { ok: false, code: 'missing-repo', message: 'repo query parameter is required' });
+            return;
+        }
+        const absRepo = path.resolve(repo);
+        if (answerHead(req, res))
+            return;
+        if (req.method === 'POST') {
+            // The only mutating verb here, so the only one that takes the write guard. A
+            // cross-origin page can reach loopback; `Origin` is what separates it from the
+            // desktop shell's own fetch.
+            if (!passWriteGuard(req, res))
+                return;
+            // `force=1` is the full rebuild. It is an explicit query flag rather than a
+            // body field because the panel's only other POST parameter is the repo, and a
+            // flag in the URL is visible in the run's own command and in a log.
+            const force = url.searchParams.get('force') === '1';
+            sendJson(res, 200, { ok: true, run: deps.start(absRepo, { force }) });
+            return;
+        }
+        if (req.method === 'DELETE') {
+            if (!passWriteGuard(req, res))
+                return;
+            const cancelled = deps.cancel(absRepo);
+            // Cancelling nothing is not an error worth a 404: the caller's intent — "this
+            // repository should not be analysing" — already holds.
+            sendJson(res, 200, { ok: true, cancelled, run: deps.status(absRepo) });
+            return;
+        }
+        const run = deps.status(absRepo);
+        // `null` means nothing has run here in this host's lifetime, which is a state the
+        // panel renders ("尚未运行"), not a failure.
+        sendJson(res, 200, { ok: true, run });
+    });
+    return webServer.register({ kind: 'prefix', path: '/api/gitnexus/analyze', handler });
+}
+//# sourceMappingURL=analyze.js.map

package/lib/routes/analyze.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"analyze.js","sourceRoot":"","sources":["../../src/routes/analyze.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,cAAc,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAI3F;;;GAGG;AACH,MAAM,eAAe,GAAwB,IAAI,GAAG,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAC;AAaxF;;GAEG;AACH,MAAM,UAAU,iBAAiB,CAAC,SAA2B,EAAE,IAAsB;IACnF,MAAM,OAAO,GAAG,YAAY,CAAC,KAAK,EAAE,GAAG,EAAE,GAAG,EAAE,EAAE;QAC9C,IAAI,CAAC,SAAS,CAAC,GAAG,EAAE,GAAG,EAAE,eAAe,CAAC;YAAE,OAAO;QAElD,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,GAAG,IAAI,GAAG,EAAE,kBAAkB,CAAC,CAAC;QACxD,MAAM,IAAI,GAAG,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QAC1C,IAAI,IAAI,KAAK,IAAI,IAAI,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;YACxC,QAAQ,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,cAAc,EAAE,OAAO,EAAE,kCAAkC,EAAE,CAAC,CAAC;YACrG,OAAO;QACT,CAAC;QACD,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QAEnC,IAAI,UAAU,CAAC,GAAG,EAAE,GAAG,CAAC;YAAE,OAAO;QAEjC,IAAI,GAAG,CAAC,MAAM,KAAK,MAAM,EAAE,CAAC;YAC1B,6EAA6E;YAC7E,+EAA+E;YAC/E,6BAA6B;YAC7B,IAAI,CAAC,cAAc,CAAC,GAAG,EAAE,GAAG,CAAC;gBAAE,OAAO;YACtC,4EAA4E;YAC5E,8EAA8E;YAC9E,oEAAoE;YACpE,MAAM,KAAK,GAAG,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,OAAO,CAAC,KAAK,GAAG,CAAC;YACpD,QAAQ,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE,EAAE,EAAE,IAAI,EAAE,GAAG,EAAE,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC,CAAC;YACtE,OAAO;QACT,CAAC;QAED,IAAI,GAAG,CAAC,MAAM,KAAK,QAAQ,EAAE,CAAC;YAC5B,IAAI,CAAC,cAAc,CAAC,GAAG,EAAE,GAAG,CAAC;gBAAE,OAAO;YACtC,MAAM,SAAS,GAAG,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;YACvC,8EAA8E;YAC9E,uDAAuD;YACvD,QAAQ,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,GAAG,EAAE,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;YACvE,OAAO;QACT,CAAC;QAED,MAAM,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QACjC,kFAAkF;QAClF,yCAAyC;QACzC,QAAQ,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE,EAAE,EAAE,IAAI,EAAE,GAAG,EAAE,CAAC,CAAC;IACxC,CAAC,CAAC,CAAC;IAEH,OAAO,SAAS,CAAC,QAAQ,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,uBAAuB,EAAE,OAAO,EAAE,CAAC,CAAC;AACxF,CAAC"}

package/lib/routes/coverage.d.ts

@@ -0,0 +1,52 @@
+/**
+ * `GET /api/gitnexus/coverage?repo=<project>` — the panel's data source.
+ *
+ * Route shape follows the community convention (`/api/<plugin-slug>/…`) and the
+ * carrier contract in `@deepseek-ai/dsh-host-webserver`: bare `node:http`, no
+ * Express, exact-then-longest-prefix matching, and a disposer for teardown.
+ *
+ * THE BOUND IS "IS A PROJECT ROOT", NOT "IS IN THE REGISTRY"
+ * ----------------------------------------------------------
+ * An earlier revision accepted only paths present in `~/.gitnexus/registry.json`.
+ * That was wrong for the panel's actual job: it shows the project the user is
+ * *in*, and a working directory the global registry has never heard of — a fresh
+ * clone, an index built with `GITNEXUS_HOME` redirected — is exactly the case the
+ * panel exists to report on. Refusing it would have been a correctness bug wearing
+ * a security costume.
+ *
+ * A later revision required an index. That was also wrong, for the same reason at a
+ * different state: a project with no index yet still has a readable working tree,
+ * and the engine already builds a useful scan-only report for it. The bound is now a
+ * project root (`.gitnexus` or `.git`), which still refuses arbitrary directories.
+ *
+ * The route still refuses to describe arbitrary directories: the path must be a
+ * project root — carrying `.gitnexus/gitnexus.json`, `.gitnexus/meta.json`, or a
+ * `.git` marker — so a caller cannot use it to enumerate a filesystem. An index is
+ * no longer required: the engine's scan-only report is what makes the "no index
+ * yet" state informative instead of an empty command. Loopback and method guards
+ * live in `./guard.js`.
+ */
+import type { WebServerService } from '@deepseek-ai/cordis';
+import type { CoverageReport } from '../gitnexus/coverage.js';
+import type { MaintenanceInfo } from '../index.js';
+/**
+ * What the route needs from the host half.
+ *
+ * Injected rather than imported so the route stays testable without a GitNexus
+ * install: the engine arrives as two functions, and a test supplies stubs.
+ */
+export interface CoverageRouteDeps {
+    /**
+     * `fresh` asks the engine to skip its short-lived cache. A manual refresh carries
+     * it; a background poll does not, which is the case the cache exists for.
+     */
+    get: (repoPath: string, options?: {
+        fresh?: boolean;
+    }) => Promise<CoverageReport>;
+    maintenance?: (repoPath: string) => MaintenanceInfo;
+}
+/**
+ * @returns disposer that unregisters the route
+ */
+export declare function mountCoverageRoute(webServer: WebServerService, deps: CoverageRouteDeps): () => void;
+//# sourceMappingURL=coverage.d.ts.map

package/lib/routes/coverage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"coverage.d.ts","sourceRoot":"","sources":["../../src/routes/coverage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAKH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAC5D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAC9D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAEnD;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;OAGG;IACH,GAAG,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,KAAK,OAAO,CAAC,cAAc,CAAC,CAAC;IAClF,WAAW,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,eAAe,CAAC;CACrD;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,gBAAgB,EAAE,IAAI,EAAE,iBAAiB,GAAG,MAAM,IAAI,CAgDnG"}

package/lib/routes/coverage.js

@@ -0,0 +1,81 @@
+/**
+ * `GET /api/gitnexus/coverage?repo=<project>` — the panel's data source.
+ *
+ * Route shape follows the community convention (`/api/<plugin-slug>/…`) and the
+ * carrier contract in `@deepseek-ai/dsh-host-webserver`: bare `node:http`, no
+ * Express, exact-then-longest-prefix matching, and a disposer for teardown.
+ *
+ * THE BOUND IS "IS A PROJECT ROOT", NOT "IS IN THE REGISTRY"
+ * ----------------------------------------------------------
+ * An earlier revision accepted only paths present in `~/.gitnexus/registry.json`.
+ * That was wrong for the panel's actual job: it shows the project the user is
+ * *in*, and a working directory the global registry has never heard of — a fresh
+ * clone, an index built with `GITNEXUS_HOME` redirected — is exactly the case the
+ * panel exists to report on. Refusing it would have been a correctness bug wearing
+ * a security costume.
+ *
+ * A later revision required an index. That was also wrong, for the same reason at a
+ * different state: a project with no index yet still has a readable working tree,
+ * and the engine already builds a useful scan-only report for it. The bound is now a
+ * project root (`.gitnexus` or `.git`), which still refuses arbitrary directories.
+ *
+ * The route still refuses to describe arbitrary directories: the path must be a
+ * project root — carrying `.gitnexus/gitnexus.json`, `.gitnexus/meta.json`, or a
+ * `.git` marker — so a caller cannot use it to enumerate a filesystem. An index is
+ * no longer required: the engine's scan-only report is what makes the "no index
+ * yet" state informative instead of an empty command. Loopback and method guards
+ * live in `./guard.js`.
+ */
+import path from 'node:path';
+import { isProjectRoot } from '../gitnexus/index-meta.js';
+import { guardHandler, passGuard, answerHead, sendJson } from './guard.js';
+/**
+ * @returns disposer that unregisters the route
+ */
+export function mountCoverageRoute(webServer, deps) {
+    const handler = guardHandler(async (req, res) => {
+        if (!passGuard(req, res))
+            return;
+        const url = new URL(req.url ?? '/', 'http://127.0.0.1');
+        const repo = url.searchParams.get('repo');
+        if (repo === null || repo.trim() === '') {
+            sendJson(res, 400, {
+                ok: false,
+                code: 'missing-repo',
+                message: 'repo query parameter is required',
+            });
+            return;
+        }
+        const absRepo = path.resolve(repo);
+        // The bound changed from "is a GitNexus index" to "is a project root": a
+        // directory with neither an index nor a `.git` marker is still refused, so the
+        // route cannot be used to enumerate a filesystem. A git repository without an
+        // index is the state the panel's initialize action exists for, and the engine
+        // already produces a useful scan-only report for it (file counts, bytes,
+        // languages, the size cap). Refusing that state was hiding data, not protecting
+        // anything — the route only answers loopback callers.
+        if (!(await isProjectRoot(absRepo))) {
+            sendJson(res, 404, {
+                ok: false,
+                code: 'not-a-project',
+                message: 'directory is neither a GitNexus index nor a git repository root',
+            });
+            return;
+        }
+        if (answerHead(req, res))
+            return;
+        // `refresh=1` comes from the panel's manual refresh control. A background poll
+        // omits it and gets the cached copy, which is what the TTL is for.
+        const fresh = url.searchParams.get('refresh') === '1';
+        const report = await deps.get(absRepo, { fresh });
+        // The maintenance commands ride along with the report because they are
+        // config-derived and only meaningful next to the index they would rebuild.
+        const maintenance = typeof deps.maintenance === 'function' ? deps.maintenance(absRepo) : null;
+        // `readAt` is what makes a refresh visible: without it two reads of an unchanged
+        // repository are byte-identical on screen, so the control looks inert even when
+        // it did exactly what it was asked.
+        sendJson(res, 200, { ok: true, report, maintenance, readAt: new Date().toISOString() });
+    });
+    return webServer.register({ kind: 'prefix', path: '/api/gitnexus/coverage', handler });
+}
+//# sourceMappingURL=coverage.js.map

package/lib/routes/coverage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"coverage.js","sourceRoot":"","sources":["../../src/routes/coverage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAC1D,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAoB3E;;GAEG;AACH,MAAM,UAAU,kBAAkB,CAAC,SAA2B,EAAE,IAAuB;IACrF,MAAM,OAAO,GAAG,YAAY,CAAC,KAAK,EAAE,GAAG,EAAE,GAAG,EAAE,EAAE;QAC9C,IAAI,CAAC,SAAS,CAAC,GAAG,EAAE,GAAG,CAAC;YAAE,OAAO;QAEjC,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,GAAG,IAAI,GAAG,EAAE,kBAAkB,CAAC,CAAC;QACxD,MAAM,IAAI,GAAG,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QAC1C,IAAI,IAAI,KAAK,IAAI,IAAI,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;YACxC,QAAQ,CAAC,GAAG,EAAE,GAAG,EAAE;gBACjB,EAAE,EAAE,KAAK;gBACT,IAAI,EAAE,cAAc;gBACpB,OAAO,EAAE,kCAAkC;aAC5C,CAAC,CAAC;YACH,OAAO;QACT,CAAC;QAED,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QACnC,yEAAyE;QACzE,+EAA+E;QAC/E,8EAA8E;QAC9E,8EAA8E;QAC9E,yEAAyE;QACzE,gFAAgF;QAChF,sDAAsD;QACtD,IAAI,CAAC,CAAC,MAAM,aAAa,CAAC,OAAO,CAAC,CAAC,EAAE,CAAC;YACpC,QAAQ,CAAC,GAAG,EAAE,GAAG,EAAE;gBACjB,EAAE,EAAE,KAAK;gBACT,IAAI,EAAE,eAAe;gBACrB,OAAO,EAAE,iEAAiE;aAC3E,CAAC,CAAC;YACH,OAAO;QACT,CAAC;QAED,IAAI,UAAU,CAAC,GAAG,EAAE,GAAG,CAAC;YAAE,OAAO;QAEjC,+EAA+E;QAC/E,mEAAmE;QACnE,MAAM,KAAK,GAAG,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,SAAS,CAAC,KAAK,GAAG,CAAC;QACtD,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;QAClD,uEAAuE;QACvE,2EAA2E;QAC3E,MAAM,WAAW,GAAG,OAAO,IAAI,CAAC,WAAW,KAAK,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;QAC9F,iFAAiF;QACjF,gFAAgF;QAChF,oCAAoC;QACpC,QAAQ,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC;IAC1F,CAAC,CAAC,CAAC;IAEH,OAAO,SAAS,CAAC,QAAQ,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,wBAAwB,EAAE,OAAO,EAAE,CAAC,CAAC;AACzF,CAAC"}

package/lib/routes/guard.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Shared guards for this plugin's HTTP routes.
+ *
+ * Extracted because two routes now need identical treatment, and a guard that is
+ * copy-pasted stops being a guard the first time one copy is edited.
+ *
+ * WHY THE GUARD EXISTS AT ALL
+ * ---------------------------
+ * On a bare `dsh web` profile a third-party named route is unauthenticated: the
+ * carrier owns no TLS, authentication, or Origin policy, and the Host/Origin
+ * checks that do exist belong to `client/connection` and cover only the routes it
+ * registers itself. The Desktop carrier adds its own gate (an
+ * `x-dsh-desktop-renderer` token; unauthenticated requests get 403), but a route
+ * that is safe only on one carrier is not safe.
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { RequestHandler } from '@deepseek-ai/cordis';
+/** This plugin only ever answers reads. */
+export declare const ALLOWED_METHODS: Set<string>;
+/**
+ * @param {import('node:http').IncomingMessage} req
+ * @returns {boolean} whether the peer is this machine
+ */
+export declare function isLoopback(req: IncomingMessage): boolean;
+/**
+ * @param {import('node:http').ServerResponse} res
+ * @param {number} status
+ * @param {unknown} body
+ * @param {Record<string, string>} [headers]
+ */
+export declare function sendJson(res: ServerResponse, status: number, body: unknown, headers?: Record<string, string>): void;
+/**
+ * Run the shared pre-checks, answering the request when one fails.
+ *
+ * `methods` exists because the default set is the read-only one: the coverage route
+ * answers GET and HEAD and nothing else, and giving it POST would widen it by accident.
+ * A route that legitimately mutates passes its own set, so the method policy is stated
+ * at the route rather than inferred from what the guard happens to allow.
+ *
+ * @param {import('node:http').IncomingMessage} req
+ * @param {import('node:http').ServerResponse} res
+ * @param methods the methods this route accepts
+ * @returns `true` when the caller may continue handling the request
+ */
+export declare function passGuard(req: IncomingMessage, res: ServerResponse, methods?: ReadonlySet<string>): boolean;
+/**
+ * Answer a HEAD request with headers only, or report that the caller should
+ * continue and send the body.
+ *
+ * @returns `true` when the request was fully answered
+ */
+export declare function answerHead(req: IncomingMessage, res: ServerResponse): boolean;
+/**
+ * Wrap a handler so no failure escapes as an unhandled rejection on the carrier.
+ *
+ * `Promise.resolve` around the call is not decoration: `RequestHandler` may return
+ * `void`, and calling `.catch` on `void` is a runtime `TypeError`. The shape the
+ * carrier actually uses is "sync throw or async rejection", and only the resolved
+ * form covers both.
+ */
+export declare function guardHandler(handler: RequestHandler): RequestHandler;
+/**
+ * Extra guard for routes that *change* something.
+ *
+ * The loopback check alone is not enough for a mutation: any page the operator
+ * visits can issue a request to `127.0.0.1`, and a cross-origin `POST` needs no
+ * preflight when it uses a simple content type. `Origin` is the discriminator —
+ * a malicious page always sends its own origin, and it will not match this host.
+ *
+ * A request with NO `Origin` is allowed through, and that is deliberate rather
+ * than lazy: a same-origin `fetch` from the desktop shell, and any local tool
+ * (including this repository's own tests), legitimately send none. The remaining
+ * gates — loopback peer, and the Desktop carrier's renderer token — still apply,
+ * so an absent header is not by itself a way in.
+ *
+ * @param {import('node:http').IncomingMessage} req
+ * @param {import('node:http').ServerResponse} res
+ * @returns {boolean} `true` when the caller may proceed
+ */
+export declare function passWriteGuard(req: IncomingMessage, res: ServerResponse): boolean;
+/**
+ * Read a JSON body with a hard byte cap.
+ *
+ * Bounded because the cap is the only thing standing between a malformed client
+ * and unbounded host memory — and this plugin's bodies are at most a few fields.
+ *
+ * @param {import('node:http').IncomingMessage} req
+ * @param {number} [maxBytes]
+ * @returns {Promise<Record<string, unknown>>}
+ */
+export declare function readJsonBody(req: IncomingMessage, maxBytes?: number): Promise<unknown>;
+//# sourceMappingURL=guard.d.ts.map

package/lib/routes/guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guard.d.ts","sourceRoot":"","sources":["../../src/routes/guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AACjE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAE1D,2CAA2C;AAC3C,eAAO,MAAM,eAAe,aAA2B,CAAC;AAExD;;;GAGG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,eAAe,GAAG,OAAO,CASxD;AAED;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,cAAc,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAM,QAShH;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,SAAS,CACvB,GAAG,EAAE,eAAe,EACpB,GAAG,EAAE,cAAc,EACnB,OAAO,GAAE,WAAW,CAAC,MAAM,CAAmB,GAC7C,OAAO,CAUT;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,eAAe,EAAE,GAAG,EAAE,cAAc,GAAG,OAAO,CAM7E;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,cAAc,GAAG,cAAc,CAcpE;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,eAAe,EAAE,GAAG,EAAE,cAAc,GAAG,OAAO,CAmBjF;AAED;;;;;;;;;GASG;AACH,wBAAsB,YAAY,CAAC,GAAG,EAAE,eAAe,EAAE,QAAQ,SAAW,GAAG,OAAO,CAAC,OAAO,CAAC,CA4B9F"}