@restregular/dsh-notepad 0.0.0-stage → 0.1.0

package/cordis.patch.yml

@@ -0,0 +1,9 @@
+# dsh-notepad bundle patch: inserts the Host plugin (the loopback note store
+# route under /dsh-notepad/api) and the Client plugin (the floating notepad
+# registered into the shell.overlay slot).
+#
+# `name` must be byte-for-byte the package.json name: the client module graph
+# locates the package by the Loader row name.
+- insert:
+    - id: dsh-notepad
+      name: '@restregular/dsh-notepad'

package/icon.svg

@@ -0,0 +1,19 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="256" height="256" viewBox="0 0 256 256" fill="none">
+  <defs>
+    <linearGradient id="bg" x1="32" y1="24" x2="224" y2="232" gradientUnits="userSpaceOnUse">
+      <stop stop-color="#4D6BFE"/>
+      <stop offset="1" stop-color="#2E3FCB"/>
+    </linearGradient>
+    <linearGradient id="paper" x1="72" y1="64" x2="176" y2="208" gradientUnits="userSpaceOnUse">
+      <stop stop-color="#FFFFFF"/>
+      <stop offset="1" stop-color="#E8ECFF"/>
+    </linearGradient>
+  </defs>
+  <rect x="16" y="16" width="224" height="224" rx="56" fill="url(#bg)"/>
+  <path d="M78 66h100a18 18 0 0 1 18 18v102a18 18 0 0 1-18 18H78a18 18 0 0 1-18-18V84a18 18 0 0 1 18-18Z" fill="url(#paper)"/>
+  <path d="M88 96h56" stroke="#9AA9FF" stroke-width="12" stroke-linecap="round"/>
+  <path d="M88 128h72" stroke="#9AA9FF" stroke-width="12" stroke-linecap="round"/>
+  <path d="M88 160h40" stroke="#9AA9FF" stroke-width="12" stroke-linecap="round"/>
+  <path d="m178.5 96.5 17 17a10 10 0 0 1 0 14.1l-44.3 44.3-22.9 6.3a5 5 0 0 1-6.2-6.2l6.3-22.9 44.3-44.3a10 10 0 0 1 14.1 0Z" fill="#FFB020" stroke="#2E3FCB" stroke-width="6" stroke-linejoin="round"/>
+  <path d="m166.5 108.5 17 17" stroke="#2E3FCB" stroke-width="6" stroke-linecap="round"/>
+</svg>

package/index.js

@@ -0,0 +1,266 @@
+/**
+ * dsh-notepad — Host half.
+ *
+ * Stores one plain-text note per workspace in `<workspace>/.dsh/notepad.json`
+ * and exposes it to the same-origin browser overlay through the loopback route
+ * `/dsh-notepad/api/note`.
+ *
+ * Security:
+ *   - only loopback requests with a same-origin (or absent) Origin are served;
+ *   - the resolved root must be a registered workspace or the exact cwd of the
+ *     requesting session;
+ *   - the file path itself is fixed (`.dsh/notepad.json`), so the route cannot
+ *     be used to read or write arbitrary workspace files.
+ *
+ * @module dsh-notepad
+ */
+
+import path from 'node:path';
+import {
+  DEFAULT_MAX_BYTES,
+  NOTE_VERSION,
+  NoteStoreError,
+  readNote,
+  writeNote,
+} from './lib/note-store.js';
+
+/** Loopback route prefix. */
+const ROUTE = '/dsh-notepad/api';
+
+/** Plugin version mirrored in package.json. */
+const VERSION = '0.1.0';
+
+/** Request body cap. */
+const BODY_LIMIT = 1024 * 1024;
+
+// ---------------------------------------------------------------------------
+// HTTP helpers
+// ---------------------------------------------------------------------------
+
+/** @param {import('node:http').ServerResponse} res */
+function sendJson(res, payload, status = 200) {
+  const body = JSON.stringify(payload);
+  res.writeHead(status, {
+    'Content-Type': 'application/json; charset=utf-8',
+    'Cache-Control': 'no-store',
+  });
+  res.end(body);
+}
+
+/**
+ * Read and parse a JSON object body.
+ * @param {import('node:http').IncomingMessage} req
+ * @param {number} limit
+ */
+function readJsonBody(req, limit = BODY_LIMIT) {
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    let total = 0;
+    req.on('data', (chunk) => {
+      total += chunk.length;
+      if (total > limit) {
+        reject(new NoteStoreError('too-large', 'Request body is too large.'));
+        req.destroy();
+        return;
+      }
+      chunks.push(chunk);
+    });
+    req.on('end', () => {
+      try {
+        const text = Buffer.concat(chunks).toString('utf8');
+        const value = text === '' ? {} : JSON.parse(text);
+        if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+          throw new Error('not an object');
+        }
+        resolve(value);
+      } catch {
+        reject(new NoteStoreError('bad-input', 'Request body is not a JSON object.'));
+      }
+    });
+    req.on('error', reject);
+  });
+}
+
+/** Only the same machine may drive the route. */
+function isLoopback(req) {
+  const address = req.socket?.remoteAddress ?? '';
+  return (
+    address === '127.0.0.1' ||
+    address === '::1' ||
+    address.startsWith('::ffff:127.') ||
+    address === ''
+  );
+}
+
+/** Reject cross-origin form posts; the page is served from the same origin. */
+function sameOrigin(req) {
+  const origin = req.headers.origin;
+  if (typeof origin !== 'string' || origin === '') return true;
+  try {
+    return new URL(origin).host === req.headers.host;
+  } catch {
+    return false;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Workspace validation
+// ---------------------------------------------------------------------------
+
+/** Case-insensitive path equality (Windows) with lexical normalization. */
+function samePath(a, b) {
+  if (typeof a !== 'string' || typeof b !== 'string') return false;
+  const norm = (value) => {
+    let out = value.replace(/[\\/]+/gu, '/').replace(/\/+$/u, '');
+    if (process.platform === 'win32') out = out.toLowerCase();
+    return out;
+  };
+  return norm(a) === norm(b);
+}
+
+/**
+ * Resolve the workspace root a request is allowed to touch.
+ * @param {import('@deepseek-ai/cordis').Context} ctx
+ * @param {Record<string, unknown>} args
+ * @returns {Promise<string>}
+ */
+async function resolveRequestRoot(ctx, args) {
+  const requested = typeof args.root === 'string' ? args.root : '';
+  if (requested === '') {
+    throw new NoteStoreError('bad-root', 'root is required.');
+  }
+  const root = path.resolve(requested);
+  if (await isKnownRoot(ctx, root, typeof args.sessionId === 'string' ? args.sessionId : '')) {
+    return root;
+  }
+  throw new NoteStoreError('unknown-workspace', 'This directory is not a registered workspace.');
+}
+
+/**
+ * A root is allowed when it is a registered workspace or the exact working
+ * directory of the requesting session.
+ * @param {import('@deepseek-ai/cordis').Context} ctx
+ * @param {string} root
+ * @param {string} sessionId
+ */
+async function isKnownRoot(ctx, root, sessionId) {
+  const registry = ctx.get('workspaceRegistry');
+  if (registry !== undefined && typeof registry.list === 'function') {
+    const known = registry.list();
+    if (Array.isArray(known) && known.some((workspace) => samePath(workspace?.path, root))) return true;
+  }
+  if (sessionId !== '') {
+    const agent = ctx.get('agents')?.get?.(sessionId);
+    const cwd = agent?.session?.header?.cwd;
+    if (samePath(cwd, root)) return true;
+  }
+  return false;
+}
+
+// ---------------------------------------------------------------------------
+// Route
+// ---------------------------------------------------------------------------
+
+/**
+ * Handle one API request. Exported for route tests.
+ * @param {import('@deepseek-ai/cordis').Context} ctx
+ * @param {import('node:http').IncomingMessage} req
+ * @param {import('node:http').ServerResponse} res
+ */
+export async function handleRequest(ctx, req, res) {
+  try {
+    await dispatchRequest(ctx, req, res);
+  } catch (error) {
+    if (error instanceof NoteStoreError) {
+      const status = error.code === 'unknown-workspace' || error.code === 'bad-root' ? 403 : 400;
+      sendJson(res, { ok: false, code: error.code, error: error.message }, status);
+      return;
+    }
+    ctx.logger?.warn?.(`dsh-notepad: ${error?.stack ?? error}`);
+    sendJson(res, { ok: false, code: 'internal', error: String(error?.message ?? error) }, 500);
+  }
+}
+
+/**
+ * Dispatch one already-authenticated API request.
+ * @param {import('@deepseek-ai/cordis').Context} ctx
+ * @param {import('node:http').IncomingMessage} req
+ * @param {import('node:http').ServerResponse} res
+ */
+async function dispatchRequest(ctx, req, res) {
+  if (!isLoopback(req) || !sameOrigin(req)) {
+    sendJson(res, { ok: false, code: 'forbidden', error: 'Forbidden.' }, 403);
+    return;
+  }
+  const url = new URL(req.url ?? '/', 'http://localhost');
+  if (!url.pathname.startsWith(ROUTE)) {
+    sendJson(res, { ok: false, code: 'not-found', error: 'Not found.' }, 404);
+    return;
+  }
+  const action = url.pathname.slice(ROUTE.length).replace(/^\/+|\/+$/gu, '');
+  if (action === 'ping') {
+    sendJson(res, { ok: true, plugin: 'dsh-notepad', version: VERSION, noteVersion: NOTE_VERSION });
+    return;
+  }
+  if (action !== 'note') {
+    sendJson(res, { ok: false, code: 'not-found', error: `Unknown endpoint "${action}".` }, 404);
+    return;
+  }
+  if (req.method === 'GET') {
+    const root = await resolveRequestRoot(ctx, {
+      root: url.searchParams.get('root') ?? '',
+      sessionId: url.searchParams.get('sessionId') ?? '',
+    });
+    const note = await readNote(root);
+    sendJson(res, { ok: true, root, ...note });
+    return;
+  }
+  if (req.method === 'PUT') {
+    const body = await readJsonBody(req);
+    const root = await resolveRequestRoot(ctx, body);
+    const note = await writeNote(root, body.text, { maxBytes: DEFAULT_MAX_BYTES });
+    sendJson(res, { ok: true, root, ...note });
+    return;
+  }
+  sendJson(res, { ok: false, code: 'method', error: 'Use GET or PUT.' }, 405);
+}
+
+/**
+ * Mount the loopback route.
+ * @param {import('@deepseek-ai/cordis').Context} ctx
+ */
+function mountRoutes(ctx) {
+  const webServer = ctx.webServer ?? ctx.get('webServer');
+  if (webServer === undefined) return;
+  ctx.effect(
+    () =>
+      webServer.register({
+        kind: 'prefix',
+        path: ROUTE,
+        async handler(req, res) {
+          try {
+            await handleRequest(ctx, req, res);
+          } catch (error) {
+            ctx.logger?.warn?.(`dsh-notepad: ${error?.stack ?? error}`);
+          }
+        },
+      }),
+    'dsh-notepad: loopback note route',
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Plugin body
+// ---------------------------------------------------------------------------
+
+/** Loader identity of the Host half. */
+export const name = 'dsh-notepad';
+
+/**
+ * Mount the note route. Without `webServer` the overlay degrades to an
+ * in-memory note for the lifetime of the page.
+ * @param {import('@deepseek-ai/cordis').Context} ctx
+ */
+export function apply(ctx) {
+  ctx.inject(['webServer'], (scoped) => mountRoutes(scoped));
+}

package/lib/note-store.js

@@ -0,0 +1,138 @@
+/**
+ * dsh-notepad — workspace note storage.
+ *
+ * One plain-text note per workspace, kept at `<workspace>/.dsh/notepad.json`.
+ * The JSON envelope lets the file carry its own `updatedAt` while still
+ * degrading gracefully: if the file is not JSON (a user or another tool
+ * edited it by hand), the raw bytes are returned as the note text instead of
+ * losing the content.
+ *
+ * @module dsh-notepad/lib/note-store
+ */
+
+import { randomBytes } from 'node:crypto';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+/** Directory under the workspace root. */
+export const NOTE_DIR = '.dsh';
+
+/** File name inside {@link NOTE_DIR}. */
+export const NOTE_FILE = 'notepad.json';
+
+/** Default maximum note size (UTF-8 bytes). */
+export const DEFAULT_MAX_BYTES = 512 * 1024;
+
+/** Storage envelope version. */
+export const NOTE_VERSION = 1;
+
+/** A note-store failure with a stable machine-readable code. */
+export class NoteStoreError extends Error {
+  /**
+   * @param {string} code
+   * @param {string} message
+   */
+  constructor(code, message) {
+    super(message);
+    this.name = 'NoteStoreError';
+    this.code = code;
+  }
+}
+
+/**
+ * Absolute path of the note file.
+ * @param {string} root workspace root
+ */
+export function notePath(root) {
+  return path.join(root, NOTE_DIR, NOTE_FILE);
+}
+
+/**
+ * Decode a stored note file.
+ * @param {string} raw file contents
+ * @param {number | undefined} mtimeMs
+ */
+export function parseNote(raw, mtimeMs) {
+  let text = raw;
+  let updatedAt;
+  try {
+    const parsed = JSON.parse(raw);
+    if (parsed !== null && typeof parsed === 'object' && typeof parsed.text === 'string') {
+      text = parsed.text;
+      if (typeof parsed.updatedAt === 'string') updatedAt = parsed.updatedAt;
+    }
+  } catch {
+    /* Not our envelope: keep the raw text. */
+  }
+  return {
+    text,
+    updatedAt: updatedAt ?? (typeof mtimeMs === 'number' ? new Date(mtimeMs).toISOString() : null),
+    mtimeMs: typeof mtimeMs === 'number' ? mtimeMs : null,
+    exists: true,
+    size: Buffer.byteLength(raw, 'utf8'),
+  };
+}
+
+/**
+ * Read one workspace note. A missing file is an empty note, not an error.
+ * @param {string} root workspace root
+ * @returns {Promise<{text: string, updatedAt: string | null, mtimeMs: number | null, exists: boolean, size: number}>}
+ */
+export async function readNote(root) {
+  const file = notePath(root);
+  let raw;
+  try {
+    raw = await fs.readFile(file, 'utf8');
+  } catch (error) {
+    if (error?.code === 'ENOENT') {
+      return { text: '', updatedAt: null, mtimeMs: null, exists: false, size: 0 };
+    }
+    throw error;
+  }
+  let mtimeMs;
+  try {
+    const stat = await fs.stat(file);
+    mtimeMs = stat.mtimeMs;
+  } catch {
+    mtimeMs = undefined;
+  }
+  return parseNote(raw, mtimeMs);
+}
+
+/**
+ * Replace one workspace note atomically.
+ * @param {string} root workspace root
+ * @param {string} text note body
+ * @param {{ maxBytes?: number }} [options]
+ */
+export async function writeNote(root, text, options = {}) {
+  if (typeof text !== 'string') {
+    throw new NoteStoreError('bad-input', 'Note text must be a string.');
+  }
+  const maxBytes = Number.isFinite(options.maxBytes) ? options.maxBytes : DEFAULT_MAX_BYTES;
+  const size = Buffer.byteLength(text, 'utf8');
+  if (size > maxBytes) {
+    throw new NoteStoreError('too-large', `Note is too large (${size} bytes; limit ${maxBytes} bytes).`);
+  }
+  const dir = path.join(root, NOTE_DIR);
+  const file = path.join(dir, NOTE_FILE);
+  await fs.mkdir(dir, { recursive: true });
+  const updatedAt = new Date().toISOString();
+  const payload = `${JSON.stringify({ version: NOTE_VERSION, text, updatedAt }, null, 2)}\n`;
+  const tmp = path.join(dir, `.${NOTE_FILE}.${process.pid}.${randomBytes(4).toString('hex')}.tmp`);
+  await fs.writeFile(tmp, payload, 'utf8');
+  try {
+    await fs.rename(tmp, file);
+  } catch (error) {
+    await fs.rm(tmp, { force: true }).catch(() => {});
+    throw error;
+  }
+  const stat = await fs.stat(file);
+  return {
+    text,
+    updatedAt,
+    mtimeMs: stat.mtimeMs,
+    exists: true,
+    size: stat.size,
+  };
+}

package/locale/en.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Notepad",
+    "description": "A per-workspace floating notepad in the session view: jot down problems and next steps, insert the note into the composer with one click, drag, minimize, and hide."
+  }
+}

package/locale/zh.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "记事本",
+    "description": "在会话界面显示一个按工作区共享的文本浮窗：记录问题与下一步，一键插入输入框，支持拖拽、最小化和快捷键隐藏。"
+  }
+}

package/package.json

@@ -1,6 +1,71 @@
 {
   "name": "@restregular/dsh-notepad",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Notepad — a per-workspace floating note window in the DeepSeek Harness session view: jot down problems and next steps, insert the note into the composer with one click, drag, minimize, and hide. · 记事本 — 在 DeepSeek Harness 会话界面显示一个按工作区共享的文本浮窗：记录问题与下一步，一键插入输入框，支持拖拽、最小化和快捷键隐藏。",
+  "icon": "./icon.svg",
+  "type": "module",
+  "main": "index.js",
+  "exports": {
+    ".": "./index.js",
+    "./client": "./client.js",
+    "./locale/*.json": "./locale/*.json",
+    "./icon": "./icon.svg",
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "index.js",
+    "client.js",
+    "lib/",
+    "locale/*.json",
+    "cordis.patch.yml",
+    "icon.svg",
+    "README.md",
+    "LICENSE"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "inject": [
+        "@deepseek-ai/dsh-client-locale",
+        "@deepseek-ai/dsh-client-ui-layout",
+        "@deepseek-ai/dsh-api-session-controller",
+        "@deepseek-ai/dsh-client-ui-session",
+        "@deepseek-ai/dsh-client-ui-conversation"
+      ]
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/RestRegular/dsh-notepad.git"
+  },
+  "homepage": "https://github.com/RestRegular/dsh-notepad#readme",
+  "bugs": {
+    "url": "https://github.com/RestRegular/dsh-notepad/issues"
+  },
+  "keywords": [
+    "dsh-plugin",
+    "deepseek-harness",
+    "deepseek",
+    "notepad",
+    "notes",
+    "scratchpad",
+    "workspace",
+    "floating"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "engines": {
+    "node": ">=22.13.0"
+  },
+  "license": "MIT",
+  "author": "RestRegular",
+  "scripts": {
+    "test": "node test/note-store.test.mjs && node test/route.test.mjs && node test/client-smoke.mjs && node test/package.test.mjs"
+  }
+}