@jetecho/dsh-csv-and-image-preview 0.1.1 → 0.1.3

package/lib/store.js

@@ -0,0 +1,144 @@
+import { createHash, randomUUID } from 'node:crypto'
+import { mkdir, open, rename, unlink } from 'node:fs/promises'
+import { homedir } from 'node:os'
+import { join, resolve } from 'node:path'
+
+export const PREVIEW_ENDPOINT = 'csv-and-image-preview/get'
+export const MAX_INPUT_BYTES = 8 * 1024 * 1024
+const MAX_RECORD_BYTES = 16 * 1024 * 1024
+
+function defaultDirectory() {
+  let home = process.env.DSH_HOME?.trim() || join(homedir(), '.dsh')
+  if (home === '~') home = homedir()
+  else if (/^~[/\\]/.test(home)) home = join(homedir(), home.slice(2))
+  return resolve(home, 'storages', 'csv-and-image-preview')
+}
+
+/** Bound the allocation even when a source file grows after stat(). */
+export async function readBounded(path, limit = MAX_INPUT_BYTES, signal) {
+  signal?.throwIfAborted()
+  const file = await open(path, 'r')
+  try {
+    const info = await file.stat()
+    if (!info.isFile()) throw new Error('预览路径必须是普通文件。')
+    if (info.size > limit) throw new Error(`文件超过预览上限 ${limit / 1024 / 1024} MB。`)
+    const buffer = Buffer.alloc(Math.min(info.size + 1, limit + 1))
+    let length = 0
+    while (length < buffer.length) {
+      signal?.throwIfAborted()
+      const { bytesRead } = await file.read(buffer, length, buffer.length - length, null)
+      if (bytesRead === 0) break
+      length += bytesRead
+    }
+    signal?.throwIfAborted()
+    if (length > limit || length > info.size) throw new Error('文件在读取时变大，请重试预览。')
+    return buffer.subarray(0, length)
+  } finally {
+    await file.close()
+  }
+}
+
+function validIdentity(value) {
+  return typeof value === 'string' && value.length > 0 && value.length <= 512
+}
+
+export function validateRequest(request) {
+  if (!request || !validIdentity(request.sessionId) || !validIdentity(request.callId)
+    || !['preview_image', 'preview_csv'].includes(request.toolName)) {
+    throw new Error('无效的预览请求。')
+  }
+}
+
+export function executionIdentity(exec, toolName) {
+  const identity = { sessionId: exec?.agent?.session?.id, callId: exec?.callId, toolName }
+  validateRequest(identity)
+  return identity
+}
+
+/** Immutable per-call snapshots, outside model output and original workspace files. */
+export class PreviewStore {
+  constructor(directory = defaultDirectory()) { this.directory = resolve(directory) }
+
+  path(identity) {
+    validateRequest(identity)
+    const key = createHash('sha256').update(JSON.stringify([
+      identity.sessionId, identity.callId, identity.toolName,
+    ])).digest('hex')
+    return join(this.directory, `${key}.json`)
+  }
+
+  async put(identity, payload, signal) {
+    const target = this.path(identity)
+    const body = JSON.stringify({ version: 1, ...identity, payload })
+    if (Buffer.byteLength(body) > MAX_RECORD_BYTES) throw new Error('预览快照超过存储上限。')
+    signal?.throwIfAborted()
+    await mkdir(this.directory, { recursive: true })
+    const temporary = `${target}.${randomUUID()}.tmp`
+    try {
+      const file = await open(temporary, 'wx', 0o600)
+      try {
+        await file.writeFile(body, { encoding: 'utf8', signal })
+        await file.sync()
+      } finally { await file.close() }
+      signal?.throwIfAborted()
+      await rename(temporary, target)
+    } finally {
+      await unlink(temporary).catch(error => { if (error.code !== 'ENOENT') throw error })
+    }
+  }
+
+  async get(identity, signal) {
+    let bytes
+    try { bytes = await readBounded(this.path(identity), MAX_RECORD_BYTES, signal) }
+    catch (error) { if (error.code === 'ENOENT') return null; throw error }
+    const record = JSON.parse(bytes.toString('utf8'))
+    if (record.version !== 1 || record.sessionId !== identity.sessionId
+      || record.callId !== identity.callId || record.toolName !== identity.toolName) {
+      throw new Error('预览快照与当前会话不匹配。')
+    }
+    return record.payload
+  }
+}
+
+/** Connection applies browser authentication before this handler is invoked. */
+export function createPreviewHandler(store) {
+  return async (_endpoint, request, signal) => {
+    try { validateRequest(request) }
+    catch { return { ok: false, error: { code: 'preview/invalid', message: '无效的预览请求。', details: {} } } }
+    try {
+      const value = await store.get(request, signal)
+      if (value === null) return { ok: false, error: {
+        code: 'preview/missing', message: '未找到此调用的预览快照，旧版嵌套调用需要重新预览。', details: {},
+      } }
+      return { ok: true, value }
+    } catch {
+      return { ok: false, error: { code: 'preview/read', message: '读取预览快照失败，请重试。', details: {} } }
+    }
+  }
+}
+
+/** Own only this exact path. The single shared /api interceptor belongs to DSH's Gateway. */
+export function createPreviewRoute(store) {
+  const handle = createPreviewHandler(store)
+  return {
+    path: `/api/${PREVIEW_ENDPOINT}`,
+    methods: ['POST'],
+    requestBody: 'buffered',
+    async fetch(request) {
+      if (request.headers.get('content-type')?.split(';')[0].trim().toLowerCase() !== 'application/json') {
+        return new Response('content type must be application/json', { status: 415 })
+      }
+      let message
+      try { message = await request.json() }
+      catch { return new Response('invalid JSON', { status: 400 }) }
+      if (!message || message.type !== 'client-request' || !validIdentity(message.rpcId)
+        || message.method !== PREVIEW_ENDPOINT) {
+        return new Response('invalid preview RPC envelope', { status: 400 })
+      }
+      return Response.json({
+        type: 'server-response', rpcId: message.rpcId,
+        result: await handle(PREVIEW_ENDPOINT, message.payload, request.signal),
+      }, { headers: { 'Cache-Control': 'private, no-store' } })
+    },
+  }
+}

package/lib/types/index.d.ts

@@ -1,54 +1,68 @@
-/**
- * Public type surface for the dsh-csv-and-image-preview host half.
- * The runtime is plain JS; these declarations describe the cordis plugin
- * contract so TS consumers and the `.d.ts` re-export resolve cleanly.
+/**
+ * Public type surface for the dsh-csv-and-image-preview host half.
+ * The runtime is plain JS; these declarations describe the cordis plugin
+ * contract so TS consumers and the `.d.ts` re-export resolve cleanly.
  */
 
-/** The `preview_image` tool definition (a dsh ToolDefinition object). */
-export interface PreviewToolDefinition {
-  name: 'preview_image'
-  description: string
-  parameters: Record<string, unknown>
-  output: Record<string, unknown>
-  execute(args: unknown): Promise<string>
-  presentCall(args: unknown): { card: string; title: string; kind: string } | undefined
-  presentResult(args: unknown): { card: string; title: string } | undefined
+/** Execution identity supplied by DSH for native and run_code child calls. */
+export interface PreviewExecution {
+  callId: string
+  signal: AbortSignal
+  agent: { session: { id: string; header: { cwd?: string } } }
 }
 
-/** The `preview_csv` tool definition (a dsh ToolDefinition object). */
-export interface CsvToolDefinition {
-  name: 'preview_csv'
-  description: string
-  parameters: Record<string, unknown>
-  output: Record<string, unknown>
-  execute(args: unknown): Promise<string>
-  presentCall(args: unknown): { card: string; title: string; kind: string } | undefined
-  presentResult(args: unknown): { card: string; title: string } | undefined
+export interface PreviewSnapshotStore {
+  put(identity: { sessionId: string; callId: string; toolName: string }, payload: unknown, signal?: AbortSignal): Promise<void>
 }
-
-/** Cordis plugin exported by the host half (lib/index.js). */
-export interface ImagePreviewPlugin {
-  readonly name: 'csv-and-image-preview'
-  apply(ctx: unknown): void
-}
-
-/** A keyed display image payload carried on tool result meta. */
-export interface PreviewMeta {
-  src: string
-  mime: string
-  label: string
-}
-
-/** A keyed bounded table payload carried on tool result meta (rows[0] = header). */
-export interface CsvPreviewMeta {
-  label: string
-  delimiter: string
-  rows: string[][]
-  totalRows: number
-  totalCols: number
-  rowsShown: number
-  colsShown: number
-}
-
-declare const plugin: ImagePreviewPlugin
-export default plugin
+
+/** The `preview_image` tool definition (a dsh ToolDefinition object). */
+export interface PreviewToolDefinition {
+  name: 'preview_image'
+  description: string
+  parameters: Record<string, unknown>
+  output: Record<string, unknown>
+  execute(args: unknown, exec: PreviewExecution): Promise<string>
+  presentCall(args: unknown): { card: string; title: string; kind: string } | undefined
+  presentResult(args: unknown): { card: string; title: string } | undefined
+}
+
+/** The `preview_csv` tool definition (a dsh ToolDefinition object). */
+export interface CsvToolDefinition {
+  name: 'preview_csv'
+  description: string
+  parameters: Record<string, unknown>
+  output: Record<string, unknown>
+  execute(args: unknown, exec: PreviewExecution): Promise<string>
+  presentCall(args: unknown): { card: string; title: string; kind: string } | undefined
+  presentResult(args: unknown): { card: string; title: string } | undefined
+}
+
+/** Cordis plugin exported by the host half (lib/index.js). */
+export interface ImagePreviewPlugin {
+  readonly name: 'csv-and-image-preview'
+  apply(ctx: unknown): void
+}
+
+/** A keyed display image payload carried on tool result meta. */
+export interface PreviewMeta {
+  src: string
+  mime: string
+  label: string
+}
+
+/** A keyed bounded table payload carried on tool result meta (rows[0] = header). */
+export interface CsvPreviewMeta {
+  label: string
+  delimiter: string
+  rows: string[][]
+  totalRows: number
+  totalCols: number
+  rowsShown: number
+  colsShown: number
+}
+
+export declare const name: 'csv-and-image-preview'
+export declare const inject: string[]
+export declare function apply(ctx: unknown): void
+export declare function createPreviewTool(store?: PreviewSnapshotStore): PreviewToolDefinition
+export declare function createCsvTool(store?: PreviewSnapshotStore): CsvToolDefinition

package/package.json

@@ -1,67 +1,81 @@
-{
-  "name": "@jetecho/dsh-csv-and-image-preview",
-  "version": "0.1.1",
-  "description": "Preview images / SVG and CSV tables in the DeepSeek Harness chat, rendered as real browser <img> / <table> elements. Preview-first workflow: show the user the asset, wait for approval, then apply the real change.",
-  "type": "module",
-  "main": "lib/index.js",
-  "types": "lib/types/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./lib/types/index.d.ts",
-      "default": "./lib/index.js"
-    },
-    "./client": {
-      "default": "./lib/client.js"
-    },
-    "./package.json": "./package.json"
-  },
-  "files": [
-    "lib",
-    "cordis.patch.yml",
-    "README.md",
-    "README.en.md",
-    "Agent.md",
-    "LICENSE"
-  ],
-  "scripts": {
-    "build": "node scripts/build.mjs",
-    "prepack": "node scripts/prepack.mjs"
-  },
-  "dsh": {
-    "bundle": {
-      "patch": "./cordis.patch.yml"
-    },
-    "client": {
-      "inject": [],
-      "platform": "web"
-    }
-  },
-  "keywords": [
-    "dsh",
-    "deepseek-harness",
-    "dsh-plugin",
-    "image",
-    "svg",
-    "csv",
-    "table",
-    "preview",
-    "visual"
-  ],
-  "license": "MIT",
-  "author": "jetecho",
-  "publishConfig": {
-    "access": "public"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/jetecho/dsh-csv-and-image-preview.git"
-  },
-  "homepage": "https://github.com/jetecho/dsh-csv-and-image-preview#readme",
-  "peerDependencies": {
-    "@deepseek-ai/cordis": "^4.0.1",
-    "react": "^18.0.0 || ^19.0.0"
-  },
-  "dependencies": {
-    "react": "^18.3.1"
-  }
-}
+{
+  "name": "@jetecho/dsh-csv-and-image-preview",
+  "version": "0.1.3",
+  "description": "Preview images / SVG and CSV tables in the DeepSeek Harness chat, rendered as real browser <img> / <table> elements. Preview-first workflow: show the user the asset, wait for approval, then apply the real change.",
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./client": {
+      "default": "./lib/client.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "cordis.patch.yml",
+    "README.md",
+    "README.en.md",
+    "Agent.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test tests/*.test.mjs",
+    "preview:test": "node scripts/preview-test.mjs",
+    "build": "node scripts/build.mjs",
+    "prepack": "node scripts/prepack.mjs"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "inject": [
+        "@deepseek-ai/dsh-client-connection",
+        "@deepseek-ai/dsh-client-ui-renderer",
+        "@deepseek-ai/dsh-client-ui-conversation"
+      ],
+      "platform": "web"
+    }
+  },
+  "keywords": [
+    "dsh",
+    "deepseek-harness",
+    "dsh-plugin",
+    "image",
+    "svg",
+    "csv",
+    "table",
+    "preview",
+    "visual"
+  ],
+  "license": "MIT",
+  "author": "jetecho",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jetecho/dsh-csv-and-image-preview.git"
+  },
+  "homepage": "https://github.com/jetecho/dsh-csv-and-image-preview#readme",
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.2",
+    "react": "^18.0.0 || ^19.0.0"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-client-connection": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-client-store": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-client-ui-slots": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-tools": "0.1.5-rc.1",
+    "immer": "^10.2.0",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "react-test-renderer": "^18.3.1",
+    "zustand": "~4.4.7"
+  }
+}