dsh-file-activity 0.5.3 → 0.5.4

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 本文件记录 dsh-file-activity 的所有版本变更。格式遵循 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)，版本号遵循 [语义化版本](https://semver.org/lang/zh-CN/)。
 
+## [0.5.4] - 2026-09-01
+
+### 变更
+
+- fix(file-activity): 浮窗预览优雅降级与工作区外文本读取（issue #68）
+
 ## [0.5.3] - 2026-09-01
 
 ### 变更

package/lib/client.js

@@ -86,6 +86,9 @@ const strings = {
   loading: () => (isZh() ? '加载中…' : 'Loading…'),
   previewUnsupported: () => (isZh() ? '该文件类型暂不支持预览' : 'This file type cannot be previewed yet'),
   previewFailed: () => (isZh() ? '预览加载失败' : 'Preview failed to load'),
+  fileMissing: () => (isZh() ? '文件不存在或已被删除' : 'This file no longer exists'),
+  fileOutside: () =>
+    isZh() ? '文件位于工作区外，暂无法读取内容' : 'The file is outside the workspace and cannot be read',
   downloadToView: () => (isZh() ? '下载查看' : 'download to view'),
 }
 
@@ -266,6 +269,11 @@ function mediaUrlOf(sessionId, path) {
   return `/file-activity/file?${new URLSearchParams({ sessionId, path })}`
 }
 
+/** Plugin text route URL (`as=text`): fs.read-shaped JSON for recorded text. */
+function textUrlOf(sessionId, path) {
+  return `/file-activity/file?${new URLSearchParams({ sessionId, path, as: 'text' })}`
+}
+
     // ── fetch interception: sidebar file operations ───────────────────────
 function methodOf(init) {
   return (init?.method ?? 'GET').toUpperCase()
@@ -1154,14 +1162,26 @@ function isFsReadOk(json) {
   return json !== null && typeof json === 'object' && json.ok === true && typeof json.value?.content === 'string'
 }
 
-/** Error load state from an fs.read API response (or a generic message). */
+/** Error load state from an fs.read API response (or a generic message).
+ *  Raw system errors are translated to friendly, locale-aware messages
+ *  (issue #68): deleted files and workspace-fenced paths must never surface
+ *  ENOENT / "is outside workspace" verbatim. */
 function fsReadError(json, viewer) {
-  return { status: 'error', viewer, message: json?.error?.message ?? strings.previewFailed() }
+  const raw = json?.error?.message ?? ''
+  let message
+  if (raw === '') message = strings.previewFailed()
+  else if (/ENOENT|no such file|does not exist|cannot resolve/i.test(raw)) message = strings.fileMissing()
+  else if (/outside workspace/i.test(raw)) message = strings.fileOutside()
+  else message = raw
+  return { status: 'error', viewer, message }
 }
 
 /**
  * Load fsRead content through the sidebar API and resolve the viewer's
- * load state (ready with text, or error with the API message).
+ * load state (ready with text, or error with the API message). When the
+ * sidebar refuses a recorded path (its workspace fence, e.g. agent-read
+ * files under ~/.dsh), fall back to the plugin's own text route, which
+ * authorizes exactly the paths this session recorded (issue #68).
  */
 async function loadFsReadContent(viewer, path, scope, sessionId) {
   const target = resolvePath(path, scope?.cwd ?? '')
@@ -1172,9 +1192,22 @@ async function loadFsReadContent(viewer, path, scope, sessionId) {
   })
   const json = await response.json()
   if (isFsReadOk(json)) return { status: 'ready', viewer, content: json.value.content }
+  // The sidebar refused — try OUR recorded-path text route before giving up.
+  const textJson = await fetchTextContent(sessionId, path)
+  if (isFsReadOk(textJson)) return { status: 'ready', viewer, content: textJson.value.content }
   return fsReadError(json, viewer)
 }
 
+/** Plugin text route (fs.read-shaped JSON), or null on any failure. */
+async function fetchTextContent(sessionId, path) {
+  try {
+    const response = await fetch(textUrlOf(sessionId, path))
+    return await response.json()
+  } catch {
+    return null
+  }
+}
+
 /**
  * Fetch the bytes the viewer's fetchStrategy needs (fsRead text /
  * mediaUrl / customData) and resolve its load state.
@@ -1450,6 +1483,10 @@ exports.apply = function apply(ctx) {
   ctx.effect(() => installAutoOpen(ctx, TAB_ID), 'dsh-file-activity: auto-open')
 }
 
+// Internal functions exposed for the render-path test suite only; inert in
+// the browser bundle (plain properties on the exports object).
+exports.__test = { loadFsReadContent, fsReadError, fetchTextContent, textUrlOf, strings }
+
 
     return module.exports
   },

package/lib/media-route.js

@@ -1,12 +1,17 @@
 /**
- * /file-activity/file media route: serves recorded file bytes (images / PDFs)
- * for the floating preview. The sidebar's own /sidebar/file route refuses
- * every path outside the session working directory (isWithin(cwd, …)), but
- * file activity records files the agent touched ANYWHERE — /tmp scratch files,
- * sibling repos, … — so images/PDFs outside the workspace resolve to a broken
- * <img>. This route serves the bytes with the same trust fence, swapping the
- * "inside the session cwd" boundary for "paths this session actually
- * recorded".
+ * /file-activity/file media route: serves recorded file bytes (images / PDFs
+ * AND, with `as=text`, text content) for the floating preview. The sidebar's
+ * own /sidebar/file route refuses every path outside the session working
+ * directory (isWithin(cwd, …)), but file activity records files the agent
+ * touched ANYWHERE — /tmp scratch files, sibling repos, … — so images/PDFs
+ * outside the workspace resolve to a broken <img>. This route serves the
+ * bytes with the same trust fence, swapping the "inside the session cwd"
+ * boundary for "paths this session actually recorded".
+ *
+ * `as=text` (issue #68): the floating preview's text path first asks the
+ * sidebar fs.read API; when the sidebar refuses a recorded file (workspace
+ * fence), the client falls back to this route and receives an fs.read-shaped
+ * JSON payload ({ ok, value: { content } }) so the viewer mounts unchanged.
  */
 import { readFile, stat } from 'node:fs/promises'
 import { basename, isAbsolute, join } from 'node:path'
@@ -17,6 +22,9 @@ import { isRecordedPath } from './state.js'
 /** Cap for the plugin's own media route (bytes): images / PDFs only. */
 const MEDIA_LIMIT = 64 * 1024 * 1024
 
+/** Cap for `as=text` payloads (characters): text previews, not archives. */
+const TEXT_LIMIT = 2 * 1024 * 1024
+
 /** Content types served by /file-activity/file (mirrors the sidebar's set). */
 const MEDIA_TYPES = {
   '.png': 'image/png',
@@ -55,14 +63,7 @@ export function createMediaHandler({ ctx, store, fence }) {
       return
     }
     try {
-      const url = new URL(request.url ?? '/', 'http://dsh.internal')
-      const sessionId = url.searchParams.get('sessionId')
-      const raw = url.searchParams.get('path')
-      assertMediaParams(sessionId, raw)
-      if (!isRecordedPath(store.state, sessionId, raw))
-        throw mediaError(403, "path is not in this session's file activity")
-      const abs = isAbsolute(raw) ? raw : join(sessionCwdOf(ctx, sessionId), raw)
-      await serveMedia(response, abs, url)
+      await serveRecordedFile(request, response, ctx, store)
     } catch (error) {
       const status = typeof error?.status === 'number' ? error.status : 400
       writeJson(response, status, {
@@ -73,6 +74,26 @@ export function createMediaHandler({ ctx, store, fence }) {
   }
 }
 
+/**
+ * Resolve a recorded path (authorized per session) and serve it: bytes
+ * (images / PDFs, `download=1` supported) or, with `as=text`, an
+ * fs.read-shaped JSON payload for the floating preview's text fallback.
+ */
+async function serveRecordedFile(request, response, ctx, store) {
+  const url = new URL(request.url ?? '/', 'http://dsh.internal')
+  const sessionId = url.searchParams.get('sessionId')
+  const raw = url.searchParams.get('path')
+  assertMediaParams(sessionId, raw)
+  if (!isRecordedPath(store.state, sessionId, raw))
+    throw mediaError(403, "path is not in this session's file activity")
+  const abs = isAbsolute(raw) ? raw : join(sessionCwdOf(ctx, sessionId), raw)
+  if (url.searchParams.get('as') === 'text') {
+    await serveText(response, abs)
+    return
+  }
+  await serveMedia(response, abs, url)
+}
+
 /** Both query parameters are required for a media request. */
 function assertMediaParams(sessionId, raw) {
   if (sessionId === null || raw === null || raw === '') throw mediaError(400, 'sessionId and path are required')
@@ -96,3 +117,23 @@ async function serveMedia(response, abs, url) {
   response.writeHead(200, headers)
   response.end(body)
 }
+
+/**
+ * `as=text` mode: serve a recorded file's text content as an fs.read-shaped
+ * JSON payload ({ ok, value: { content } }) so the floating preview's text
+ * viewers mount unchanged even when the sidebar fs.read refuses the path
+ * (workspace fence — issue #68). Same authorization as bytes serving:
+ * recorded paths only.
+ */
+async function serveText(response, abs) {
+  let info
+  try {
+    info = await stat(abs)
+  } catch {
+    throw mediaError(404, 'file not found')
+  }
+  if (!info.isFile()) throw mediaError(400, 'not a file')
+  if (info.size > TEXT_LIMIT) throw mediaError(413, 'file too large')
+  const content = await readFile(abs, 'utf8')
+  writeJson(response, 200, { ok: true, value: { content } })
+}

package/lib/parts/api.part.js

@@ -43,3 +43,8 @@ function postClear(sessionId) {
 function mediaUrlOf(sessionId, path) {
   return `/file-activity/file?${new URLSearchParams({ sessionId, path })}`
 }
+
+/** Plugin text route URL (`as=text`): fs.read-shaped JSON for recorded text. */
+function textUrlOf(sessionId, path) {
+  return `/file-activity/file?${new URLSearchParams({ sessionId, path, as: 'text' })}`
+}

package/lib/parts/apply.part.js

@@ -83,3 +83,7 @@ exports.apply = function apply(ctx) {
   // auto-open once per session (default on)
   ctx.effect(() => installAutoOpen(ctx, TAB_ID), 'dsh-file-activity: auto-open')
 }
+
+// Internal functions exposed for the render-path test suite only; inert in
+// the browser bundle (plain properties on the exports object).
+exports.__test = { loadFsReadContent, fsReadError, fetchTextContent, textUrlOf, strings }

package/lib/parts/i18n.part.js

@@ -38,5 +38,8 @@ const strings = {
   loading: () => (isZh() ? '加载中…' : 'Loading…'),
   previewUnsupported: () => (isZh() ? '该文件类型暂不支持预览' : 'This file type cannot be previewed yet'),
   previewFailed: () => (isZh() ? '预览加载失败' : 'Preview failed to load'),
+  fileMissing: () => (isZh() ? '文件不存在或已被删除' : 'This file no longer exists'),
+  fileOutside: () =>
+    isZh() ? '文件位于工作区外，暂无法读取内容' : 'The file is outside the workspace and cannot be read',
   downloadToView: () => (isZh() ? '下载查看' : 'download to view'),
 }

package/lib/parts/preview.part.js

@@ -12,14 +12,26 @@ function isFsReadOk(json) {
   return json !== null && typeof json === 'object' && json.ok === true && typeof json.value?.content === 'string'
 }
 
-/** Error load state from an fs.read API response (or a generic message). */
+/** Error load state from an fs.read API response (or a generic message).
+ *  Raw system errors are translated to friendly, locale-aware messages
+ *  (issue #68): deleted files and workspace-fenced paths must never surface
+ *  ENOENT / "is outside workspace" verbatim. */
 function fsReadError(json, viewer) {
-  return { status: 'error', viewer, message: json?.error?.message ?? strings.previewFailed() }
+  const raw = json?.error?.message ?? ''
+  let message
+  if (raw === '') message = strings.previewFailed()
+  else if (/ENOENT|no such file|does not exist|cannot resolve/i.test(raw)) message = strings.fileMissing()
+  else if (/outside workspace/i.test(raw)) message = strings.fileOutside()
+  else message = raw
+  return { status: 'error', viewer, message }
 }
 
 /**
  * Load fsRead content through the sidebar API and resolve the viewer's
- * load state (ready with text, or error with the API message).
+ * load state (ready with text, or error with the API message). When the
+ * sidebar refuses a recorded path (its workspace fence, e.g. agent-read
+ * files under ~/.dsh), fall back to the plugin's own text route, which
+ * authorizes exactly the paths this session recorded (issue #68).
  */
 async function loadFsReadContent(viewer, path, scope, sessionId) {
   const target = resolvePath(path, scope?.cwd ?? '')
@@ -30,9 +42,22 @@ async function loadFsReadContent(viewer, path, scope, sessionId) {
   })
   const json = await response.json()
   if (isFsReadOk(json)) return { status: 'ready', viewer, content: json.value.content }
+  // The sidebar refused — try OUR recorded-path text route before giving up.
+  const textJson = await fetchTextContent(sessionId, path)
+  if (isFsReadOk(textJson)) return { status: 'ready', viewer, content: textJson.value.content }
   return fsReadError(json, viewer)
 }
 
+/** Plugin text route (fs.read-shaped JSON), or null on any failure. */
+async function fetchTextContent(sessionId, path) {
+  try {
+    const response = await fetch(textUrlOf(sessionId, path))
+    return await response.json()
+  } catch {
+    return null
+  }
+}
+
 /**
  * Fetch the bytes the viewer's fetchStrategy needs (fsRead text /
  * mediaUrl / customData) and resolve its load state.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-file-activity",
-  "version": "0.5.3",
+  "version": "0.5.4",
   "description": "DSH 侧边栏文件活动插件：按 LRU 记录文件读取/新增/修改事件（最近访问），按绝对路径树形统计（文件统计），点击文件浮窗预览（代码高亮/Markdown/图片/PDF）。DSH web plugin: file activity tracker — LRU recent-access list plus per-file read/create/modify counts in a folder tree, with floating preview.",
   "type": "module",
   "main": "lib/index.js",