dsh-file-activity 0.4.6

package/lib/state.js

@@ -0,0 +1,140 @@
+/**
+ * State model + persistence for file activity.
+ *
+ * State (recent history + per-file counts) is kept per session and persisted
+ * to $DSH_HOME/file-activity.json (atomic tmp+rename, debounced). Loading is
+ * defensive: missing / corrupt / wrong-version files degrade to fresh state.
+ */
+import { readFile } from 'node:fs/promises'
+import { homedir } from 'node:os'
+
+/** How many recent entries to keep per session (LRU: one entry per path). */
+const RECENT_LIMIT = 5
+
+/** State file: $DSH_HOME/file-activity.json (fallback: ~/.dsh/file-activity.json). */
+export function stateFile() {
+  const home = process.env.DSH_HOME
+  if (typeof home === 'string' && home !== '') return `${home}/file-activity.json`
+  return `${homedir()}/.dsh/file-activity.json`
+}
+
+/** Empty state document. */
+export function createState() {
+  return { version: 1, sessions: {} }
+}
+
+/** Load persisted state (missing/corrupt file → fresh state). */
+export async function loadState(file) {
+  try {
+    const raw = await readFile(file, 'utf8')
+    const parsed = JSON.parse(raw)
+    if (parsed !== null && typeof parsed === 'object' && parsed.version === 1) return parsed
+  } catch {
+    // first run or unreadable file: start fresh
+  }
+  return createState()
+}
+
+/** Map a raw operation kind (tool name or client op) to 'read' | 'write' | 'edit'. */
+export function mapOp(op) {
+  switch (op) {
+    case 'write': return 'write'
+    case 'edit':
+    case 'str_replace_editor': return 'edit'
+    case 'read':
+    case 'read_image':
+    default: return 'read'
+  }
+}
+
+/**
+ * Fold one observed operation into the state.
+ * 'write' is classified create vs modify through the per-session known-file
+ * registry (first contact = create, later writes = modify); edits are always
+ * modifies. Each file's counters also track firstSeen (first contact time,
+ * i.e. creation time) and lastSeen (most recent activity time).
+ * Returns true when a record was produced.
+ */
+export function applyRecord(state, sessionId, path, op, time) {
+  if (!isValidRecordTarget(sessionId, path)) return false
+  const session = state.sessions[sessionId] ?? (state.sessions[sessionId] = { known: {}, counts: {}, recent: [] })
+  const timestamp = typeof time === 'number' ? time : Date.now()
+  const firstSeen = typeof session.known[path] === 'number' ? session.known[path] : timestamp
+  const finalOp = classifyOp(op, session.known[path])
+  session.known[path] = firstSeen
+  const counts = session.counts[path] ?? (session.counts[path] = { read: 0, create: 0, modify: 0 })
+  bumpCount(counts, finalOp, firstSeen, timestamp)
+  // Newest-first LRU history: revisiting a path moves it to the front
+  // instead of appending a duplicate; cap at RECENT_LIMIT entries.
+  const existing = session.recent.findIndex((entry) => entry.path === path)
+  if (existing !== -1) session.recent.splice(existing, 1)
+  session.recent.unshift({ path, op: finalOp, time: timestamp })
+  if (session.recent.length > RECENT_LIMIT) session.recent.length = RECENT_LIMIT
+  return true
+}
+
+/** A record target is valid when both ids are non-empty strings (no NUL). */
+function isValidRecordTarget(sessionId, path) {
+  return typeof sessionId === 'string' && sessionId !== ''
+    && typeof path === 'string' && path !== '' && !path.includes('\0')
+}
+
+/** 'write' → create/modify by the known-file registry; 'edit' → modify; else read. */
+function classifyOp(op, knownTime) {
+  if (op === 'write') return knownTime ? 'modify' : 'create'
+  if (op === 'edit') return 'modify'
+  return 'read'
+}
+
+/** Increment the matching counter and refresh firstSeen/lastSeen. */
+function bumpCount(counts, finalOp, firstSeen, timestamp) {
+  if (finalOp === 'create') counts.create += 1
+  else if (finalOp === 'modify') counts.modify += 1
+  else counts.read += 1
+  counts.firstSeen = firstSeen
+  counts.lastSeen = timestamp
+}
+
+/**
+ * Normalize + trim a loaded state document in place: null/absent sessions are
+ * reset to {}, pre-existing history is deduped by path and capped at
+ * RECENT_LIMIT (LRU semantics: one entry per path, newest occurrence wins —
+ * the array is newest-first, so the first occurrence of each path is kept).
+ * Returns { state, trimmed } where trimmed reports whether anything changed.
+ */
+export function trimLoadedState(loaded) {
+  if (loaded.sessions === undefined || loaded.sessions === null || typeof loaded.sessions !== 'object') loaded.sessions = {}
+  let trimmed = false
+  for (const session of Object.values(loaded.sessions)) {
+    if (Array.isArray(session.recent)) {
+      const seen = new Set()
+      const deduped = session.recent.filter((entry) => {
+        if (typeof entry?.path !== 'string' || entry.path === '') return false
+        if (seen.has(entry.path)) return false
+        seen.add(entry.path)
+        return true
+      })
+      if (deduped.length !== session.recent.length) trimmed = true
+      session.recent = deduped
+      if (session.recent.length > RECENT_LIMIT) {
+        session.recent.length = RECENT_LIMIT
+        trimmed = true
+      }
+    }
+  }
+  return { state: loaded, trimmed }
+}
+
+/**
+ * Whether `path` appears in this session's recorded file activity (counts or
+ * recent). The media route authorizes EXACTLY these paths — the record itself
+ * is the permission: the agent actually touched the file, so previewing it is
+ * expected, while arbitrary unrecorded paths stay refused.
+ */
+export function isRecordedPath(state, sessionId, path) {
+  const session = state.sessions[sessionId]
+  if (session === undefined) return false
+  if (session.counts !== undefined && typeof session.counts[path] === 'object' && session.counts[path] !== null) return true
+  if (Array.isArray(session.recent)) return session.recent.some((entry) => entry.path === path)
+  return false
+}

package/lib/store.js

@@ -0,0 +1,92 @@
+/**
+ * Store lifecycle for file activity: async state load with buffering of
+ * records that arrive before it completes, debounced atomic persistence
+ * (tmp+rename) and a teardown flush. The exposed store object carries a live
+ * `state` reference so route handlers always read the current document.
+ */
+import { rename, writeFile } from 'node:fs/promises'
+import { applyRecord, createState, loadState, mapOp, stateFile, trimLoadedState } from './state.js'
+
+/** Build the per-apply store: { state, record, schedulePersist, dispose }. */
+export function createStore(ctx) {
+  const store = { state: createState() }
+  const handle = {
+    ctx,
+    file: stateFile(),
+    store,
+    pending: [],
+    ready: false,
+    persistTimer: null,
+    dirtyChain: Promise.resolve(),
+  }
+  handle.persistNow = () => persistNow(handle)
+  handle.persistSoon = () => persistSoon(handle)
+  store.record = (sessionId, path, op, time) => record(handle, sessionId, path, op, time)
+  store.schedulePersist = () => persistSoon(handle)
+  store.dispose = () => dispose(handle)
+  void loadState(handle.file).then((loaded) => onLoaded(handle, loaded))
+  return store
+}
+
+/** Write the current state atomically (serialized through dirtyChain). */
+function persistNow(handle) {
+  const snapshot = JSON.stringify(handle.store.state)
+  const tmp = `${handle.file}.tmp-${process.pid}`
+  handle.dirtyChain = handle.dirtyChain.then(async () => {
+    try {
+      await writeFile(tmp, snapshot, 'utf8')
+      await rename(tmp, handle.file)
+    } catch (error) {
+      handle.ctx.logger?.warn(`[dsh-file-activity] persist failed: ${error instanceof Error ? error.message : String(error)}`)
+    }
+  }).catch(() => {})
+}
+
+/** Debounced (500ms) schedule of a persist. */
+function persistSoon(handle) {
+  if (handle.persistTimer !== null) return
+  handle.persistTimer = setTimeout(() => {
+    handle.persistTimer = null
+    persistNow(handle)
+  }, 500)
+}
+
+/** State loaded: normalize/trim, mark ready, drain buffered records. */
+function onLoaded(handle, loaded) {
+  const result = trimLoadedState(loaded)
+  handle.store.state = result.state
+  handle.ready = true
+  if (drainPending(handle) || result.trimmed) persistSoon(handle)
+}
+
+/** Apply every record buffered before the state load finished. */
+function drainPending(handle) {
+  const drained = handle.pending.splice(0)
+  for (const item of drained) {
+    applyRecord(handle.store.state, item.sessionId, item.path, mapOp(item.op), item.time)
+  }
+  return drained.length > 0
+}
+
+/** Record an operation once state is loaded (buffered before that). */
+function record(handle, sessionId, path, op, time) {
+  if (!handle.ready) {
+    handle.pending.push({ sessionId, path, op, time })
+    return true
+  }
+  if (applyRecord(handle.store.state, sessionId, path, op, time)) {
+    persistSoon(handle)
+    return true
+  }
+  return false
+}
+
+/** Tear down on unload: flush pending persistence. */
+function dispose(handle) {
+  if (handle.persistTimer !== null) {
+    clearTimeout(handle.persistTimer)
+    handle.persistTimer = null
+  }
+  persistNow(handle)
+  void handle.dirtyChain
+}

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "dsh-file-activity",
+  "version": "0.4.6",
+  "description": "DSH web plugin: file activity tracker for dsh-better-sidebar — recent file access history plus create/modify/read counts grouped by folder (dotted multi-level paths), opening files in the sidebar's built-in native preview (syntax highlighting / Markdown rendering / images / PDF) and auto-open.",
+  "type": "module",
+  "main": "lib/index.js",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/baosfeng/my-dsh-plugins"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "test": "npx vitest run --coverage && cucumber-js test/features --import 'test/features/steps/*.mjs'"
+  },
+  "exports": {
+    ".": {
+      "default": "./lib/index.js"
+    },
+    "./client": {
+      "default": "./lib/client.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "cordis.patch.yml",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE",
+    "assets"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "inject": [
+        "@deepseek-ai/dsh-client-runtime"
+      ]
+    }
+  },
+  "peerDependencies": {
+    "cordis": "^4.0.0-rc.8",
+    "dsh-better-sidebar": "^0.14.0",
+    "react": "^18.2.0"
+  },
+  "peerDependenciesMeta": {
+    "dsh-better-sidebar": {
+      "optional": true
+    },
+    "cordis": {
+      "optional": true
+    }
+  },
+  "license": "MIT"
+}