dsh-gitnexus-plus 0.0.0-stage → 0.1.1

package/lib/index.d.ts

@@ -0,0 +1,79 @@
+/**
+ * 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.
+ *
+ * Deliberately read-only. Nothing here triggers `analyze`, writes to `.gitnexus/`,
+ * or takes the index lock; driving updates is a separate concern with its own
+ * safety story, and mixing the two would mean a status check could start a
+ * 30-second rebuild.
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import { type MaintenanceCommand } from './gitnexus/commands.js';
+export declare 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 declare const inject: readonly ["tools"];
+/** The shape `Schema.object` infers below, named for use in signatures. */
+export interface PluginConfig {
+    scanDefaultCapKb: number;
+    minifiedSampleLimit: number;
+    serveRoutes: boolean;
+    /**
+     * Shapes the maintenance commands the panel hands to the operator. The defaults
+     * are the values measured to work inside a confined DSH process; a deployment
+     * that is not sandboxed can turn them off to get keyword search and a
+     * self-managed heap.
+     */
+    skipFts: boolean;
+    memoryOff: boolean;
+    analyzeHeapMb: number;
+    /**
+     * Wall-clock ceiling for a run this plugin starts.
+     *
+     * Ten minutes, because the escape hatch this panel offers is a full rebuild and
+     * those are measured in minutes on a large repository. Too short a ceiling turns
+     * the feature into "it always times out on the repos that need it most"; the run
+     * is cancellable, so the cost of it being generous is bounded by the operator.
+     */
+    analyzeTimeoutMs: number;
+    /**
+     * Where the plugin installs GitNexus when asked. Empty means the default,
+     * `$DSH_HOME/gitnexus-plus/gitnexus`.
+     */
+    gitnexusInstallDir: string;
+    /** Wall-clock ceiling for that install. Compiling native modules is slow. */
+    installTimeoutMs: number;
+    gitnexusHome: string;
+}
+export declare const Config: import("@deepseek-ai/schemastery").SchemaLike<{
+    scanDefaultCapKb: number;
+    minifiedSampleLimit: number;
+    serveRoutes: boolean;
+    skipFts: boolean;
+    memoryOff: boolean;
+    analyzeHeapMb: number;
+    analyzeTimeoutMs: number;
+    gitnexusInstallDir: string;
+    installTimeoutMs: number;
+    gitnexusHome: string;
+}>;
+/** The maintenance payload the panel renders alongside a report. */
+export interface MaintenanceInfo {
+    commands: MaintenanceCommand[];
+    rationale: string[];
+}
+export declare function apply(ctx: Context, config: PluginConfig): void;
+/**
+ * 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.d.ts.map

package/lib/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAKnD,OAAO,EAAyC,KAAK,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAqBxG,eAAO,MAAM,IAAI,kBAAkB,CAAC;AAEpC;;;;GAIG;AACH,eAAO,MAAM,MAAM,oBAAqB,CAAC;AAEzC,2EAA2E;AAC3E,MAAM,WAAW,YAAY;IAC3B,gBAAgB,EAAE,MAAM,CAAC;IACzB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,WAAW,EAAE,OAAO,CAAC;IACrB;;;;;OAKG;IACH,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,EAAE,OAAO,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;IACtB;;;;;;;OAOG;IACH,gBAAgB,EAAE,MAAM,CAAC;IACzB;;;OAGG;IACH,kBAAkB,EAAE,MAAM,CAAC;IAC3B,6EAA6E;IAC7E,gBAAgB,EAAE,MAAM,CAAC;IACzB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,eAAO,MAAM,MAAM;;;;;;;;;;;EAWjB,CAAC;AAqBH,oEAAoE;AACpE,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,kBAAkB,EAAE,CAAC;IAC/B,SAAS,EAAE,MAAM,EAAE,CAAC;CACrB;AAiBD,wBAAgB,KAAK,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,YAAY,GAAG,IAAI,CAuJ9D;AAED;;;;GAIG;AACH,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC"}

package/lib/index.js

@@ -0,0 +1,211 @@
+/**
+ * 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.
+ *
+ * Deliberately read-only. Nothing here triggers `analyze`, writes to `.gitnexus/`,
+ * or takes the index lock; driving updates is a separate concern with its own
+ * safety story, and mixing the two would mean a status check could start a
+ * 30-second rebuild.
+ */
+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 { maintenanceCommands, commandRationale } from './gitnexus/commands.js';
+import { mountCoverageRoute } from './routes/coverage.js';
+import { mountAnalyzeRoute } from './routes/analyze.js';
+import { mountInstallRoute } from './routes/install.js';
+import { createAnalyzeRunner } from './gitnexus/analyze.js';
+import { createInstallRunner } 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(true),
+    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;
+    /**
+     * 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,
+        });
+        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: config.skipFts,
+            memoryOff: config.memoryOff,
+            gitnexusHome: config.gitnexusHome === '' ? null : config.gitnexusHome,
+        };
+        return {
+            commands: maintenanceCommands(repoPath, options),
+            rationale: commandRationale(options),
+        };
+    };
+    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 analyze = createAnalyzeRunner({
+                shell: isShellLike(shellRaw) ? shellRaw : null,
+                timeoutMs: config.analyzeTimeoutMs,
+            });
+            // 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: config.gitnexusInstallDir === '' ? undefined : config.gitnexusInstallDir,
+                timeoutMs: config.installTimeoutMs,
+            });
+            const disposers = [
+                mountCoverageRoute(svcCtx.webServer, {
+                    get: (repoPath, options) => coverageFor(repoPath, options),
+                    maintenance: (repoPath) => maintenanceFor(repoPath),
+                }),
+                mountAnalyzeRoute(svcCtx.webServer, {
+                    start: (repoPath) => analyze.start(repoPath),
+                    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(),
+                }),
+            ];
+            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,35 @@
+/**
+ * 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. */
+    start: (repoPath: string) => 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,4EAA4E;IAC5E,KAAK,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,aAAa,CAAC;IAC3C,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,CAuCjG"}

package/lib/routes/analyze.js

@@ -0,0 +1,71 @@
+/**
+ * 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;
+            sendJson(res, 200, { ok: true, run: deps.start(absRepo) });
+            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;AASxF;;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,QAAQ,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE,EAAE,EAAE,IAAI,EAAE,GAAG,EAAE,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;YAC3D,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,44 @@
+/**
+ * `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 GITNEXUS INDEX", 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.
+ *
+ * The route still refuses to describe arbitrary directories: the path must already
+ * contain `.gitnexus/gitnexus.json` or `.gitnexus/meta.json`, so a caller cannot
+ * use it to enumerate a filesystem. 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;;;;;;;;;;;;;;;;;;;GAmBG;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,CA2CnG"}

package/lib/routes/coverage.js

@@ -0,0 +1,68 @@
+/**
+ * `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 GITNEXUS INDEX", 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.
+ *
+ * The route still refuses to describe arbitrary directories: the path must already
+ * contain `.gitnexus/gitnexus.json` or `.gitnexus/meta.json`, so a caller cannot
+ * use it to enumerate a filesystem. Loopback and method guards live in `./guard.js`.
+ */
+import path from 'node:path';
+import { hasIndex } 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);
+        if (!(await hasIndex(absRepo))) {
+            // Not an error the caller should retry: this directory simply has no index
+            // yet, which is the state the panel's initialize action exists for.
+            sendJson(res, 404, {
+                ok: false,
+                code: 'not-indexed',
+                message: 'directory has no GitNexus index (.gitnexus/gitnexus.json or meta.json)',
+            });
+            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;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AACrD,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,IAAI,CAAC,CAAC,MAAM,QAAQ,CAAC,OAAO,CAAC,CAAC,EAAE,CAAC;YAC/B,2EAA2E;YAC3E,oEAAoE;YACpE,QAAQ,CAAC,GAAG,EAAE,GAAG,EAAE;gBACjB,EAAE,EAAE,KAAK;gBACT,IAAI,EAAE,aAAa;gBACnB,OAAO,EAAE,wEAAwE;aAClF,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"}