@dsh-xhl/dsh-live-inspector 1.0.0

package/lib/index.js

@@ -0,0 +1,274 @@
+import { readFile as readTextFile, writeFile, unlink, stat } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
+import { dirname, join, resolve } from 'node:path';
+
+export const name = '@dsh-xhl/dsh-live-inspector';
+
+/** Bytes above which the "before" snapshot is omitted from the answer (the file stays revertible). */
+const MAX_SAMPLE_BYTES = 512 * 1024;
+
+/** Route prefix for this plugin's JSON API. */
+const API_PREFIX = '/liveinspector/api';
+
+/** JSON body cap: the panel only ever sends file text, never anything larger than this. */
+const MAX_BODY_BYTES = 8 * 1024 * 1024;
+
+// ─── Path guards ────────────────────────────────────────────────────────────────
+
+/** A revertible path is always forward-slashed, non-empty, and never a filesystem root. */
+function normalizeDisplayPath(raw) {
+  if (typeof raw !== 'string') throw new HttpError(400, 'path must be a string');
+  const withSlashes = raw.replace(/\\/g, '/').trim();
+  if (withSlashes.length === 0) throw new HttpError(400, 'path must be a non-empty string');
+  if (withSlashes.startsWith('//')) {
+    throw new HttpError(400, `refusing to treat ${raw} as a revertible file path`);
+  }
+  const stripped = withSlashes.replace(/\/+$/, '');
+  // "/" and "C:/" collapse to themselves under dirname, which is what keeps a revert
+  // from ever aiming a delete at a filesystem root.
+  if (stripped.length === 0 || dirname(stripped) === stripped) {
+    throw new HttpError(400, `refusing to treat ${raw} as a revertible file path`);
+  }
+  return stripped;
+}
+
+/** True for POSIX ("/a"), drive-letter ("C:/a") and UNC ("//server/share/a") absolutes. */
+function looksAbsolute(value) {
+  return value.startsWith('/') || /^[a-zA-Z]:\//.test(value);
+}
+
+function digestOf(text) {
+  return createHash('sha1').update(text, 'utf8').digest('hex').slice(0, 12);
+}
+
+// ─── HTTP plumbing ──────────────────────────────────────────────────────────────
+
+class HttpError extends Error {
+  constructor(status, message) {
+    super(message);
+    this.status = status;
+  }
+}
+
+function writeJson(res, status, value) {
+  const body = JSON.stringify(value);
+  res.writeHead(status, {
+    'content-type': 'application/json; charset=utf-8',
+    'cache-control': 'no-store'
+  });
+  res.end(body);
+}
+
+function writeOk(res, value) {
+  writeJson(res, 200, { ok: true, value });
+}
+
+function writeFailure(res, error) {
+  const status = error instanceof HttpError ? error.status : 500;
+  const message = error instanceof Error ? error.message : String(error);
+  writeJson(res, status, { ok: false, error: { message } });
+}
+
+/**
+ * Trust fence for the plugin's own routes.
+ *
+ * The Harness web GUI is served from a loopback authority, so only a loopback Host with a
+ * matching Origin may reach these routes. This mirrors the fence the shipped third-party
+ * plugins use; it is not a substitute for the app's own authentication, which has already
+ * admitted the request by the time it arrives here.
+ */
+function isTrustedRequest(req) {
+  const raw = req.headers && req.headers.host;
+  if (typeof raw !== 'string' || raw.length === 0) return false;
+  let hostname;
+  try {
+    hostname = new URL(`http://${raw}`).hostname;
+  } catch {
+    return false;
+  }
+  const loopback = hostname === 'localhost' || hostname === '127.0.0.1' || hostname === '[::1]' || hostname === '::1';
+  if (!loopback) return false;
+  if (req.headers['sec-fetch-site'] === 'cross-site') return false;
+  const origin = req.headers.origin;
+  if (typeof origin !== 'string' || origin.length === 0) return true;
+  try {
+    return new URL(origin).host === raw;
+  } catch {
+    return false;
+  }
+}
+
+function readJsonBody(req) {
+  return new Promise((resolveBody, rejectBody) => {
+    let size = 0;
+    const chunks = [];
+    req.on('data', (chunk) => {
+      size += chunk.length;
+      if (size > MAX_BODY_BYTES) {
+        rejectBody(new HttpError(413, 'request body is too large'));
+        req.destroy();
+        return;
+      }
+      chunks.push(chunk);
+    });
+    req.on('error', rejectBody);
+    req.on('end', () => {
+      const text = Buffer.concat(chunks).toString('utf8');
+      if (text.length === 0) return resolveBody({});
+      try {
+        const parsed = JSON.parse(text);
+        if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+          return rejectBody(new HttpError(400, 'request body must be a JSON object'));
+        }
+        resolveBody(parsed);
+      } catch {
+        rejectBody(new HttpError(400, 'request body is not valid JSON'));
+      }
+    });
+  });
+}
+
+// ─── Filesystem operations ──────────────────────────────────────────────────────
+
+/**
+ * Resolve a tool-supplied path into a process path.
+ *
+ * The session log records paths exactly as the model typed them, relative to the Agent's
+ * working directory. `ctx.fs.processPathFromHostPath` is the authoritative mapping back into
+ * the filesystem provider's world; joining the cwd is the fallback.
+ */
+function makeResolver(ctx) {
+  return function resolveProcessPath(displayPath, cwd) {
+    const normalized = normalizeDisplayPath(displayPath);
+    const base = typeof cwd === 'string' && cwd.length > 0 ? cwd : undefined;
+
+    let candidate = normalized;
+    if (!looksAbsolute(candidate)) {
+      if (base === undefined) {
+        throw new HttpError(400, `cannot resolve the relative path ${normalized} without a session working directory`);
+      }
+      candidate = join(base, normalized);
+    }
+
+    const fs = ctx.get('fs');
+    if (fs !== undefined && typeof fs.processPathFromHostPath === 'function') {
+      try {
+        const mapped = fs.processPathFromHostPath(candidate);
+        if (typeof mapped === 'string' && mapped.length > 0) return { processPath: mapped, displayPath: normalized };
+      } catch {
+        // A backend that cannot map this host path falls through to the candidate itself.
+      }
+    }
+    return { processPath: resolve(candidate), displayPath: normalized };
+  };
+}
+
+function buildApi(ctx) {
+  const resolveProcessPath = makeResolver(ctx);
+
+  return {
+    /** Read a file's text plus a digest. A missing or unreadable file is a 404, not a crash. */
+    async 'fs.read'(payload) {
+      const { processPath } = resolveProcessPath(payload.path, payload.cwd);
+      let text;
+      try {
+        text = await readTextFile(processPath, 'utf8');
+      } catch (error) {
+        if (error && error.code === 'ENOENT') throw new HttpError(404, `no such file: ${payload.path}`);
+        throw error;
+      }
+      const bytes = Buffer.byteLength(text, 'utf8');
+      if (bytes > MAX_SAMPLE_BYTES) {
+        return { ok: true, text: null, digest: digestOf(text), bytes, omitted: true };
+      }
+      return { ok: true, text, digest: digestOf(text), bytes, omitted: false };
+    },
+
+    /** Atomically create or replace a UTF-8 text file. */
+    async 'fs.write'(payload) {
+      if (typeof payload.content !== 'string') throw new HttpError(400, 'content must be a string');
+      const { processPath } = resolveProcessPath(payload.path, payload.cwd);
+      await writeFile(processPath, payload.content, 'utf8');
+      return { ok: true, digest: digestOf(payload.content), bytes: Buffer.byteLength(payload.content, 'utf8') };
+    },
+
+    /** Remove one file. */
+    async 'fs.delete'(payload) {
+      const { processPath } = resolveProcessPath(payload.path, payload.cwd);
+      try {
+        await unlink(processPath);
+      } catch (error) {
+        if (error && error.code === 'ENOENT') throw new HttpError(404, `no such file: ${payload.path}`);
+        throw error;
+      }
+      return { ok: true };
+    },
+
+    /** Report whether a recorded path still exists, so a shell deletion can be noticed. */
+    async 'fs.stat'(payload) {
+      const { processPath } = resolveProcessPath(payload.path, payload.cwd);
+      let info;
+      try {
+        info = await stat(processPath);
+      } catch (error) {
+        if (error && error.code === 'ENOENT') return { ok: true, exists: false };
+        throw error;
+      }
+      return { ok: true, exists: true, isFile: info.isFile() };
+    }
+  };
+}
+
+export function apply(ctx) {
+  const api = buildApi(ctx);
+
+  // Reading the pre-edit baseline is not an operation a user can approve away: the panel
+  // needs it to show and apply reverts, and it stays confined to this revert seam.
+  ctx.effect(() => {
+    const dispose = ctx.on('approval/request', (...args) => {
+      const request = args[0];
+      if (request !== null && typeof request === 'object' && request.kind === 'fs-read') {
+        return { kind: 'allow-once' };
+      }
+      return undefined;
+    });
+    return dispose;
+  }, '@dsh-xhl/dsh-live-inspector: allow revert baseline reads');
+
+  ctx.effect(() => ctx.webServer.register({
+    kind: 'prefix',
+    path: API_PREFIX,
+    handler: async (req, res) => {
+      if (!isTrustedRequest(req)) {
+        writeJson(res, 403, { ok: false, error: { message: 'forbidden' } });
+        return;
+      }
+      if (req.method !== 'POST') {
+        writeJson(res, 405, { ok: false, error: { message: 'method not allowed' } });
+        return;
+      }
+      const pathname = new URL(req.url ?? '/', 'http://dsh.internal').pathname;
+      const method = pathname.startsWith(`${API_PREFIX}/`) ? pathname.slice(API_PREFIX.length + 1) : '';
+      if (method.length === 0 || method.includes('/')) {
+        writeJson(res, 404, { ok: false, error: { message: 'unknown method' } });
+        return;
+      }
+      try {
+        const payload = await readJsonBody(req);
+        const handler = api[method];
+        if (typeof handler !== 'function') {
+          writeJson(res, 404, { ok: false, error: { message: `unknown method "${method}"` } });
+          return;
+        }
+        writeOk(res, await handler(payload));
+      } catch (error) {
+        writeFailure(res, error);
+      }
+    }
+  }), '@dsh-xhl/dsh-live-inspector: filesystem API routes');
+
+  console.info(`[@dsh-xhl/dsh-live-inspector] Host filesystem API mounted at ${API_PREFIX}.`);
+}
+
+/** The Host plugin needs the web server to publish routes on. */
+export const inject = ['webServer'];

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@dsh-xhl/dsh-live-inspector",
+  "version": "1.0.0",
+  "description": "Git Tree and live diff inspector for the DeepSeek Harness web surface: watch every file the agent touches, review changes turn by turn, and undo a specific turn or a single hunk — with the filesystem reached through the plugin's own Host HTTP routes.",
+  "type": "module",
+  "main": "lib/index.js",
+  "exports": {
+    ".": {
+      "default": "./lib/index.js"
+    },
+    "./client": {
+      "default": "./lib/client.js"
+    },
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./package.json": "./package.json"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wojiaoxiaomayun/dsh-live-inspector.git"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/client.js",
+    "cordis.patch.yml",
+    "README.md",
+    "package.json"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "immediately": true,
+      "inject": [
+        "@deepseek-ai/dsh-client-ui-sidebar-right",
+        "@deepseek-ai/dsh-client-ui-session"
+      ]
+    }
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.0"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  }
+}