dsh-gitnexus-plus 0.0.0-stage → 0.1.2

package/lib/routes/guard.js

@@ -0,0 +1,187 @@
+/**
+ * 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.
+ */
+/** This plugin only ever answers reads. */
+export const ALLOWED_METHODS = new Set(['GET', 'HEAD']);
+/**
+ * @param {import('node:http').IncomingMessage} req
+ * @returns {boolean} whether the peer is this machine
+ */
+export function isLoopback(req) {
+    const address = req.socket?.remoteAddress ?? '';
+    return (address === '127.0.0.1' ||
+        address === '::1' ||
+        address === '::ffff:127.0.0.1' ||
+        // Node reports an absent family as an empty string for unix sockets.
+        address === '');
+}
+/**
+ * @param {import('node:http').ServerResponse} res
+ * @param {number} status
+ * @param {unknown} body
+ * @param {Record<string, string>} [headers]
+ */
+export function sendJson(res, status, body, headers = {}) {
+    const payload = JSON.stringify(body, null, 2);
+    res.statusCode = status;
+    res.setHeader('content-type', 'application/json; charset=utf-8');
+    res.setHeader('cache-control', 'no-store');
+    res.setHeader('x-content-type-options', 'nosniff');
+    res.setHeader('referrer-policy', 'no-referrer');
+    for (const [name, value] of Object.entries(headers))
+        res.setHeader(name, value);
+    res.end(payload);
+}
+/**
+ * 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 function passGuard(req, res, methods = ALLOWED_METHODS) {
+    if (!isLoopback(req)) {
+        sendJson(res, 403, { ok: false, code: 'forbidden', message: 'loopback only' });
+        return false;
+    }
+    if (!methods.has(req.method ?? '')) {
+        sendJson(res, 405, { ok: false, code: 'method-not-allowed' }, { allow: [...methods].join(', ') });
+        return false;
+    }
+    return true;
+}
+/**
+ * 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 function answerHead(req, res) {
+    if (req.method !== 'HEAD')
+        return false;
+    res.statusCode = 200;
+    res.setHeader('content-type', 'application/json; charset=utf-8');
+    res.end();
+    return true;
+}
+/**
+ * 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 function guardHandler(handler) {
+    return (req, res) => {
+        Promise.resolve(handler(req, res)).catch((error) => {
+            if (res.headersSent) {
+                res.end();
+                return;
+            }
+            sendJson(res, 500, {
+                ok: false,
+                code: 'internal-error',
+                message: error instanceof Error ? error.message : String(error),
+            });
+        });
+    };
+}
+/**
+ * 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 function passWriteGuard(req, res) {
+    const origin = req.headers.origin;
+    if (typeof origin !== 'string' || origin === '')
+        return true;
+    const host = req.headers.host;
+    if (typeof host === 'string' && host !== '') {
+        try {
+            if (new URL(origin).host === host)
+                return true;
+        }
+        catch {
+            /* malformed origin falls through to the refusal below */
+        }
+    }
+    sendJson(res, 403, {
+        ok: false,
+        code: 'cross-origin-write',
+        message: 'this endpoint changes state and refuses cross-origin requests',
+    });
+    return false;
+}
+/**
+ * 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 async function readJsonBody(req, maxBytes = 8 * 1024) {
+    return new Promise((resolve, reject) => {
+        let size = 0;
+        const chunks = [];
+        req.on('data', (chunk) => {
+            size += chunk.length;
+            if (size > maxBytes) {
+                reject(new Error('request body too large'));
+                req.destroy();
+                return;
+            }
+            chunks.push(chunk);
+        });
+        req.on('end', () => {
+            const raw = Buffer.concat(chunks).toString('utf8').trim();
+            if (raw === '') {
+                resolve({});
+                return;
+            }
+            try {
+                const parsed = JSON.parse(raw);
+                resolve(parsed !== null && typeof parsed === 'object' ? parsed : {});
+            }
+            catch (error) {
+                reject(new Error(`invalid JSON body: ${error instanceof Error ? error.message : String(error)}`));
+            }
+        });
+        req.on('error', reject);
+    });
+}
+//# sourceMappingURL=guard.js.map

package/lib/routes/guard.js.map

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

package/lib/routes/install.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The endpoint that installs GitNexus on this machine.
+ *
+ * Its own route rather than a branch in `analyze.ts`, because it is a different kind of
+ * action: `analyze` reads and writes an index that already exists, while this downloads
+ * several hundred megabytes and runs the package's build scripts. Separating them keeps
+ * the cheap, frequent operation from being reviewed alongside the expensive, rare one.
+ *
+ * `POST` starts, `GET` reports, `DELETE` cancels — the same shape as the analyze route,
+ * for the same reason: the panel polls the URL it started.
+ */
+import type { WebServerService } from '@deepseek-ai/cordis';
+import type { InstallStatus } from '../gitnexus/install.js';
+export interface InstallRouteDeps {
+    start: () => InstallStatus;
+    status: () => InstallStatus | null;
+    cancel: () => boolean;
+    /** Where a successful install puts the CLI, so the panel can show it. */
+    cliPath: () => string;
+}
+/**
+ * @returns disposer that unregisters the route
+ */
+export declare function mountInstallRoute(webServer: WebServerService, deps: InstallRouteDeps): () => void;
+/** Narrow a repo path for the panel's benefit; unused by the route itself. */
+export declare function projectName(repoPath: string): string;
+//# sourceMappingURL=install.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"install.d.ts","sourceRoot":"","sources":["../../src/routes/install.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAC5D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAI5D,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,MAAM,aAAa,CAAC;IAC3B,MAAM,EAAE,MAAM,aAAa,GAAG,IAAI,CAAC;IACnC,MAAM,EAAE,MAAM,OAAO,CAAC;IACtB,yEAAyE;IACzE,OAAO,EAAE,MAAM,MAAM,CAAC;CACvB;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,gBAAgB,EAAE,IAAI,EAAE,gBAAgB,GAAG,MAAM,IAAI,CAuBjG;AAED,8EAA8E;AAC9E,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAEpD"}

package/lib/routes/install.js

@@ -0,0 +1,46 @@
+/**
+ * The endpoint that installs GitNexus on this machine.
+ *
+ * Its own route rather than a branch in `analyze.ts`, because it is a different kind of
+ * action: `analyze` reads and writes an index that already exists, while this downloads
+ * several hundred megabytes and runs the package's build scripts. Separating them keeps
+ * the cheap, frequent operation from being reviewed alongside the expensive, rare one.
+ *
+ * `POST` starts, `GET` reports, `DELETE` cancels — the same shape as the analyze route,
+ * for the same reason: the panel polls the URL it started.
+ */
+import path from 'node:path';
+import { guardHandler, passGuard, passWriteGuard, answerHead, sendJson } from './guard.js';
+const INSTALL_METHODS = new Set(['GET', 'HEAD', 'POST', 'DELETE']);
+/**
+ * @returns disposer that unregisters the route
+ */
+export function mountInstallRoute(webServer, deps) {
+    const handler = guardHandler(async (req, res) => {
+        if (!passGuard(req, res, INSTALL_METHODS))
+            return;
+        if (answerHead(req, res))
+            return;
+        if (req.method === 'POST') {
+            // Installing runs arbitrary build scripts from the dependency tree, so this is the
+            // most privileged verb this plugin exposes and takes the cross-origin write guard.
+            if (!passWriteGuard(req, res))
+                return;
+            sendJson(res, 200, { ok: true, run: deps.start(), cliPath: deps.cliPath() });
+            return;
+        }
+        if (req.method === 'DELETE') {
+            if (!passWriteGuard(req, res))
+                return;
+            sendJson(res, 200, { ok: true, cancelled: deps.cancel(), run: deps.status() });
+            return;
+        }
+        sendJson(res, 200, { ok: true, run: deps.status(), cliPath: deps.cliPath() });
+    });
+    return webServer.register({ kind: 'prefix', path: '/api/gitnexus/install', handler });
+}
+/** Narrow a repo path for the panel's benefit; unused by the route itself. */
+export function projectName(repoPath) {
+    return path.basename(repoPath);
+}
+//# sourceMappingURL=install.js.map

package/lib/routes/install.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"install.js","sourceRoot":"","sources":["../../src/routes/install.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,cAAc,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAI3F,MAAM,eAAe,GAAwB,IAAI,GAAG,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAC;AAUxF;;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;QAClD,IAAI,UAAU,CAAC,GAAG,EAAE,GAAG,CAAC;YAAE,OAAO;QAEjC,IAAI,GAAG,CAAC,MAAM,KAAK,MAAM,EAAE,CAAC;YAC1B,mFAAmF;YACnF,mFAAmF;YACnF,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,EAAE,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;YAC7E,OAAO;QACT,CAAC;QAED,IAAI,GAAG,CAAC,MAAM,KAAK,QAAQ,EAAE,CAAC;YAC5B,IAAI,CAAC,cAAc,CAAC,GAAG,EAAE,GAAG,CAAC;gBAAE,OAAO;YACtC,QAAQ,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,CAAC,MAAM,EAAE,EAAE,GAAG,EAAE,IAAI,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;YAC/E,OAAO;QACT,CAAC;QAED,QAAQ,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE,EAAE,EAAE,IAAI,EAAE,GAAG,EAAE,IAAI,CAAC,MAAM,EAAE,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;IAChF,CAAC,CAAC,CAAC;IAEH,OAAO,SAAS,CAAC,QAAQ,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,uBAAuB,EAAE,OAAO,EAAE,CAAC,CAAC;AACxF,CAAC;AAED,8EAA8E;AAC9E,MAAM,UAAU,WAAW,CAAC,QAAgB;IAC1C,OAAO,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;AACjC,CAAC"}

package/lib/routes/search.d.ts

@@ -0,0 +1,27 @@
+/**
+ * `GET /api/gitnexus/search?repo=<project>&q=<keyword>` — keyword search.
+ *
+ * The fourth route, and the first that is neither a reading of the index manifest
+ * nor a maintenance action: it queries the graph's symbol names and file paths.
+ * It is read-only in the strongest sense this plugin can offer — the engine opens
+ * LadybugDB with `readOnly: true` and takes no write lock — so the method policy is
+ * the read-only one (GET/HEAD), not the analyze route's wider set.
+ *
+ * The bound is the same project-root check the coverage route uses: a directory
+ * that is neither indexed nor a `.git` root is refused, so the route cannot be used
+ * to enumerate a filesystem. Search itself additionally requires a complete index
+ * store and returns a typed error when the graph is missing.
+ */
+import type { WebServerService } from '@deepseek-ai/cordis';
+import { type SearchReport } from '../gitnexus/search.js';
+export interface SearchRouteDeps {
+    /** Run one keyword search. Errors are `SearchError` instances when typed. */
+    search: (repoPath: string, query: string, options?: {
+        limit?: number;
+    }) => Promise<SearchReport>;
+}
+/**
+ * @returns disposer that unregisters the route
+ */
+export declare function mountSearchRoute(webServer: WebServerService, deps: SearchRouteDeps): () => void;
+//# sourceMappingURL=search.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../../src/routes/search.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAE5D,OAAO,EAAe,KAAK,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAIvE,MAAM,WAAW,eAAe;IAC9B,6EAA6E;IAC7E,MAAM,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,KAAK,OAAO,CAAC,YAAY,CAAC,CAAC;CAClG;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,gBAAgB,EAAE,IAAI,EAAE,eAAe,GAAG,MAAM,IAAI,CAwD/F"}

package/lib/routes/search.js

@@ -0,0 +1,77 @@
+/**
+ * `GET /api/gitnexus/search?repo=<project>&q=<keyword>` — keyword search.
+ *
+ * The fourth route, and the first that is neither a reading of the index manifest
+ * nor a maintenance action: it queries the graph's symbol names and file paths.
+ * It is read-only in the strongest sense this plugin can offer — the engine opens
+ * LadybugDB with `readOnly: true` and takes no write lock — so the method policy is
+ * the read-only one (GET/HEAD), not the analyze route's wider set.
+ *
+ * The bound is the same project-root check the coverage route uses: a directory
+ * that is neither indexed nor a `.git` root is refused, so the route cannot be used
+ * to enumerate a filesystem. Search itself additionally requires a complete index
+ * store and returns a typed error when the graph is missing.
+ */
+import path from 'node:path';
+import { guardHandler, passGuard, answerHead, sendJson } from './guard.js';
+import { isProjectRoot } from '../gitnexus/index-meta.js';
+import { SearchError } from '../gitnexus/search.js';
+const SEARCH_METHODS = new Set(['GET', 'HEAD']);
+/**
+ * @returns disposer that unregisters the route
+ */
+export function mountSearchRoute(webServer, deps) {
+    const handler = guardHandler(async (req, res) => {
+        if (!passGuard(req, res, SEARCH_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 query = url.searchParams.get('q');
+        if (query === null || query.trim() === '') {
+            sendJson(res, 400, { ok: false, code: 'missing-query', message: 'q query parameter is required' });
+            return;
+        }
+        const absRepo = path.resolve(repo);
+        // The same boundary as the coverage route: a search must not become a way to
+        // ask whether an arbitrary directory exists. The engine repeats this check for
+        // direct callers; at the HTTP edge it saves opening a database to say no.
+        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;
+        // `limit` is optional; the engine clamps it. A malformed value is treated as
+        // absent rather than as an error — the search itself does not depend on it.
+        const rawLimit = url.searchParams.get('limit');
+        const parsed = rawLimit === null ? Number.NaN : Number.parseInt(rawLimit, 10);
+        const limit = Number.isFinite(parsed) ? parsed : undefined;
+        try {
+            const report = await deps.search(absRepo, query, { limit });
+            sendJson(res, 200, {
+                ok: true,
+                ...report,
+                readAt: new Date().toISOString(),
+            });
+        }
+        catch (error) {
+            if (error instanceof SearchError) {
+                sendJson(res, error.status, { ok: false, code: error.code, message: error.message });
+                return;
+            }
+            // `guardHandler` turns anything else into a 500; rethrow so its single error
+            // path stays the only place that formats an unexpected failure.
+            throw error;
+        }
+    });
+    return webServer.register({ kind: 'prefix', path: '/api/gitnexus/search', handler });
+}
+//# sourceMappingURL=search.js.map

package/lib/routes/search.js.map

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

package/package.json

@@ -1,6 +1,89 @@
 {
   "name": "dsh-gitnexus-plus",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.2",
+  "description": "DSH plugin: visualize a GitNexus project index, search its symbols by keyword, report what it left out, and run its incremental refresh from a sidebar panel — including detecting a missing GitNexus and installing one on request.",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Moowningstar/gitnexus-plus.git"
+  },
+  "homepage": "https://github.com/Moowningstar/gitnexus-plus#readme",
+  "bugs": {
+    "url": "https://github.com/Moowningstar/gitnexus-plus/issues"
+  },
+  "keywords": [
+    "dsh",
+    "dsh-plugin",
+    "gitnexus",
+    "code-index",
+    "code-graph",
+    "coverage"
+  ],
+  "main": "./lib/index.js",
+  "types": "./lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./client": "./lib/client.js",
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "dsh-gitnexus-coverage": "./lib/bin/gitnexus-coverage.js"
+  },
+  "files": [
+    "lib",
+    "scripts/link-runtime.mjs",
+    "cordis.patch.yml",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22",
+    "dsh": ">=0.2.0-rc.2 <0.3.0"
+  },
+  "scripts": {
+    "clean": "node scripts/clean.mjs",
+    "build": "npm run clean && tsc -p tsconfig.host.json && node scripts/build-client.mjs",
+    "prepare": "npm run build",
+    "postinstall": "node scripts/link-runtime.mjs",
+    "check": "tsc -p tsconfig.json && tsc -p tsconfig.scripts.json && tsc -p tsconfig.client.json",
+    "coverage": "node lib/bin/gitnexus-coverage.js",
+    "test": "npm run build && node test/run.mjs && node test/plugin.mjs && node test/client.mjs"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web"
+    }
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.2",
+    "@deepseek-ai/dsh-tools": ">=0.2.0-rc.2 <0.3.0-0",
+    "@deepseek-ai/schemastery": ">=3.0.0 <4.0.0",
+    "gitnexus": ">=1.6.0 <2.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@deepseek-ai/cordis": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-tools": {
+      "optional": true
+    },
+    "@deepseek-ai/schemastery": {
+      "optional": true
+    },
+    "gitnexus": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^26.6.5",
+    "@types/react": "^19.3.0",
+    "typescript": "^5.9.3"
+  }
+}

package/scripts/link-runtime.mjs

@@ -0,0 +1,146 @@
+#!/usr/bin/env node
+/**
+ * Re-link the DSH runtime packages into `node_modules`.
+ *
+ * The host half imports `@deepseek-ai/schemastery`, `@deepseek-ai/dsh-tools` and
+ * `@deepseek-ai/cordis`; the client half is built against `react` and
+ * `@deepseek-ai/dsh-client-ui-primitives`. In a real install these arrive as
+ * ordinary dependencies, but during development they are taken from the DSH
+ * installation that is already on this machine rather than fetched from a registry
+ * — the primitives package in particular ships no `lib/` on npm; its JavaScript
+ * lives inside the web app bundle, and the published README states that plugins
+ * must share it rather than bundle their own copy.
+ *
+ * WHY THIS IS A SCRIPT AND NOT A ONE-OFF
+ * --------------------------------------
+ * `npm install` prunes anything in `node_modules` it does not recognise, so a
+ * hand-made junction survives exactly until the next dependency change. Twice
+ * during development that silently broke the test suite — the failure looked like
+ * a missing module, not like a pruned link. Wiring this to `postinstall` makes the
+ * links a property of the project instead of a property of the machine.
+ *
+ * It never fails the install: on a machine without DSH, or on a published package
+ * where the real dependencies are present, there is nothing to do.
+ */
+
+import { existsSync, mkdirSync, rmSync, symlinkSync, statSync } from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+
+/** Packages the project needs, mapped to their location under a DSH install. */
+const PACKAGES = [
+  '@deepseek-ai/schemastery',
+  '@deepseek-ai/dsh-tools',
+  '@deepseek-ai/cordis',
+  '@deepseek-ai/dsh-client-ui-primitives',
+  'react',
+];
+
+/** Where a DSH installation keeps its `node_modules`, most specific first. */
+function candidateRoots() {
+  const roots = [];
+  const fromEnv = process.env.DSH_RUNTIME_ROOT;
+  if (typeof fromEnv === 'string' && fromEnv !== '') roots.push(fromEnv);
+
+  if (process.platform === 'win32') {
+    const local = process.env.LOCALAPPDATA;
+    if (typeof local === 'string' && local !== '') {
+      roots.push(path.join(local, 'Programs', 'DSH Desktop', 'resources', 'app', 'node_modules'));
+    }
+  }
+  // A source checkout, for developers running DSH from a repository.
+  roots.push(path.resolve(import.meta.dirname, '..', '..', 'deepseek-harness', 'node_modules'));
+  return roots;
+}
+
+function findRuntimeRoot() {
+  for (const root of candidateRoots()) {
+    if (existsSync(path.join(root, '@deepseek-ai', 'dsh-tools'))) return root;
+  }
+  return null;
+}
+
+/**
+ * Whether this run is the project's own checkout rather than an installed copy.
+ *
+ * `postinstall` runs on **every** install, including when this package is a
+ * dependency inside someone else's tree. Linking the host's runtime packages into
+ * that tree is not ours to do, and a reviewer reading a plugin for "surprising
+ * install-time behaviour" would be right to flag a postinstall that walks PATH,
+ * probes for a DSH installation and rewrites `node_modules`. Installed copies live
+ * under `node_modules/`, so that is the test.
+ */
+function isOwnCheckout() {
+  return !/(^|[\\/])node_modules([\\/]|$)/.test(process.cwd());
+}
+
+function main() {
+  if (!isOwnCheckout()) return;
+
+  const runtime = findRuntimeRoot();
+  if (runtime === null) {
+    // Expected on a machine without DSH: nothing to link from.
+    return;
+  }
+
+  const linked = [];
+  const skipped = [];
+  for (const name of PACKAGES) {
+    const target = path.join(runtime, name);
+    if (!existsSync(target)) {
+      skipped.push(name);
+      continue;
+    }
+
+    const link = path.join(process.cwd(), 'node_modules', name);
+    // A real installation already satisfies this; leave it alone.
+    if (existsSync(link)) {
+      let isLink = false;
+      try {
+        isLink = statSync(link).isDirectory() && existsSync(path.join(link, 'package.json'));
+      } catch {
+        isLink = false;
+      }
+      const pointsHere = (() => {
+        try {
+          return path.resolve(link, '..', '..') === path.resolve(target, '..', '..');
+        } catch {
+          return false;
+        }
+      })();
+      if (isLink && !pointsHere) {
+        skipped.push(`${name} (already present)`);
+        continue;
+      }
+    }
+
+    mkdirSync(path.dirname(link), { recursive: true });
+    if (existsSync(link)) rmSync(link, { recursive: true, force: true });
+    try {
+      symlinkSync(target, link, process.platform === 'win32' ? 'junction' : 'dir');
+      linked.push(name);
+    } catch (cause) {
+      // `cause` is `unknown` at this boundary. `ErrnoException` rather than `Error`
+      // because `code` lives on the former — an fs failure is what is expected here,
+      // and reading `.code` off a plain `Error` is not a thing that exists.
+      /** @type {string} */
+      let detail;
+      if (cause instanceof Error) {
+        const code = /** @type {NodeJS.ErrnoException} */ (cause).code;
+        detail = typeof code === 'string' ? code : cause.message;
+      } else {
+        detail = String(cause);
+      }
+      skipped.push(`${name} (${detail})`);
+    }
+  }
+
+  if (linked.length > 0) {
+    console.log(`[link-runtime] linked ${linked.length} package(s) from ${runtime}`);
+  }
+  if (skipped.length > 0 && process.env.DSH_LINK_VERBOSE === '1') {
+    console.log(`[link-runtime] skipped: ${skipped.join(', ')}`);
+  }
+}
+
+main();