@tita-agent/dsh-data-table 0.0.0-stage → 0.2.0

package/src/http/history.ts

@@ -0,0 +1,151 @@
+/**
+ * Version history over HTTP (docs/issue/0022 P3).
+ *
+ * The list, one historical snapshot or Step, and the diff between two revisions.
+ * The list is also where an abandoned editing session becomes observable:
+ * reading it is what settles it into a saved Version (PRD v3.3 D21).
+ *
+ * The Version record's wire shape comes from `version/records.ts`, which this
+ * endpoint answers with but does not define. It said the opposite — that the
+ * shape lived here and the model knew nothing about HTTP — while importing
+ * `toVersionRecords` from there on the next line.
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http'
+
+import type { VersionRecord } from '#contracts'
+import { DataSheetError } from '../errors.ts'
+import { diffReachedLimit, diffWorkbookSnapshots } from '../version/diff.ts'
+import { parseRevision } from './routes.ts'
+import { historyVersionsFromOperations } from '../version/grouping.ts'
+import { activeHistoryRevisions, canReplayHistoryRevision, checkpointHasher, toVersionRecords } from '../version/records.ts'
+import { settleIdleUserVersions } from '../version/session.ts'
+import { readWorkbook, readWorkbookAtRevision, readWorkbookAtStep, readStepChanges } from '../workbook-manager.ts'
+import { writeOperationError, type WorkbookRoute } from './routes.ts'
+import type { WorkbookCheckpoint, WorkbookHistoryVersion, WorkbookOperation } from '../types.ts'
+import { operationSummary } from '../contract/operations.ts'
+
+export async function handleHistoryRoute(route: WorkbookRoute, req: IncomingMessage, res: ServerResponse, url: URL): Promise<boolean> {
+  const id = route.id
+
+  if (route.kind === 'history-diff' && req.method === 'GET') {
+    const fromRaw = url.searchParams.get('from')
+    const toRaw = url.searchParams.get('to')
+    // `parseRevision` rather than a bare `Number()`: the sibling endpoints use it
+    // for the same kind of cursor, and `Number()` also accepts `0x10`, `1e3` and
+    // `5.0` — a revision is a decimal integer. The defaults differ (`to` falls
+    // back to the current revision), so only the parsing is shared.
+    const from = parseRevision(fromRaw)
+    const currentMeta = await readWorkbook(id)
+    if (currentMeta === null) { writeOperationError(res, new DataSheetError('WORKBOOK_NOT_FOUND', '工作簿不存在', 404)); return true }
+    const to = toRaw === null ? currentMeta.revision ?? 0 : parseRevision(toRaw)
+    if (!Number.isInteger(from) || from < 0 || !Number.isInteger(to) || to < 0 || from > to) {
+      writeOperationError(res, new DataSheetError('VALIDATION_ERROR', 'from/to 必须是非负整数，且 from 不得大于 to'))
+      return true
+    }
+    const left = await readWorkbookAtRevision(id, from)
+    const right = await readWorkbookAtRevision(id, to)
+    if (left === null || right === null) {
+      // User-facing copy: this is the panel's notice text, so it says what
+      // happened and what still works, not which revision number failed.
+      writeOperationError(res, new DataSheetError('REVISION_UNAVAILABLE', '这两版之间的历史记录已被压缩，无法重建内容快照，因此不能比较。更早的版本仍然可以恢复。', 409, { from, to }))
+      return true
+    }
+    res.writeHead(200, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-cache' })
+    // `truncated` rather than nothing: the client renders these counts, and a
+    // capped list would otherwise read as the whole comparison.
+    const changes = diffWorkbookSnapshots(left.snapshot, right.snapshot)
+    res.end(JSON.stringify({ ok: true, workbookId: id, from, to, changes, truncated: diffReachedLimit(changes) }))
+    return true
+  }
+
+  if (route.kind === 'history' && req.method === 'GET') {
+    // Reading the list is the moment "stopped typing ten minutes ago"
+    // becomes observable, so that is where an abandoned session is settled
+    // into a saved Version (PRD v3.3 D21). Idempotent and cheap.
+    await settleIdleUserVersions(id).catch(() => 0)
+    const meta = await readWorkbook(id, { includeCheckpoints: true })
+    if (meta === null) {
+      res.writeHead(404)
+      res.end()
+      return true
+    }
+    const currentRevision = meta.revision ?? 0
+    const requested = url.searchParams.get('revision')
+    if (requested !== null) {
+      const targetRevision = Number(requested)
+      if (!Number.isInteger(targetRevision) || targetRevision < 0) {
+        res.writeHead(400, { 'content-type': 'application/json; charset=utf-8' })
+        res.end(JSON.stringify({ ok: false, error: 'revision 必须是大于等于 0 的整数' }))
+        return true
+      }
+      const stepRaw = url.searchParams.get('step')
+      if (stepRaw !== null) {
+        const step = Number(stepRaw)
+        if (!Number.isInteger(step) || step < 0) {
+          res.writeHead(400, { 'content-type': 'application/json; charset=utf-8' })
+          res.end(JSON.stringify({ ok: false, error: 'step 必须是大于等于 0 的整数' }))
+          return true
+        }
+      }
+      const historical = stepRaw === null
+        ? await readWorkbookAtRevision(id, targetRevision)
+        : await readWorkbookAtStep(id, targetRevision, Number(stepRaw))
+      if (historical === null) {
+        res.writeHead(409, { 'content-type': 'application/json; charset=utf-8' })
+        res.end(JSON.stringify({ ok: false, error: '该版本的历史记录已被压缩，无法重建内容快照，因此不能预览。它仍然可以被恢复。', revision: currentRevision }))
+        return true
+      }
+      res.writeHead(200, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-cache' })
+      // A Step preview also returns what that Step changed, so the canvas
+      // can scroll to and tint the cells (PRD v3.3 §7.2).
+      const stepChanges = stepRaw === null ? null : await readStepChanges(id, targetRevision, Number(stepRaw))
+      const stepResult = stepRaw === null ? {} : {
+        step: (historical as Awaited<ReturnType<typeof readWorkbookAtStep>>)?.step,
+        stepCount: (historical as Awaited<ReturnType<typeof readWorkbookAtStep>>)?.stepCount,
+        changes: stepChanges ?? [],
+        // A Step can be a batch, so this list is bounded the same way the diff
+        // list is and has to say so when it stops.
+        truncated: stepChanges === null ? false : diffReachedLimit(stepChanges),
+      }
+      res.end(JSON.stringify({
+        ok: true,
+        workbookId: id,
+        revision: historical.revision,
+        snapshot: historical.snapshot,
+        ...stepResult,
+      }))
+      return true
+    }
+    const operations = (meta.operations ?? []).slice().sort((left, right) => left.revision - right.revision)
+    const rawCheckpoints = meta?.checkpoints ?? []
+    const checkpoints = rawCheckpoints.map(checkpoint => checkpoint.revision).sort((left, right) => left - right)
+    const operationByRevision = new Map(operations.map(operation => [operation.revision, operation]))
+    const activeRevisions = activeHistoryRevisions(currentRevision, operationByRevision)
+    const canReplay = (targetRevision: number): boolean => canReplayHistoryRevision(targetRevision, currentRevision, checkpoints, operationByRevision)
+    const entries = operations.map(operation => ({
+      opId: operation.opId,
+      revision: operation.revision,
+      parentRevision: operation.parentRevision ?? Math.max(0, operation.revision - 1),
+      actor: operation.actor,
+      type: operation.type,
+      timestamp: operation.timestamp,
+      summary: operationSummary(operation),
+      canPreview: canReplay(operation.revision),
+    }))
+    const versions = historyVersionsFromOperations(operations, canReplay, activeRevisions)
+    res.writeHead(200, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-cache' })
+    res.end(JSON.stringify({
+      ok: true,
+      workbookId: id,
+      revision: currentRevision,
+      entries,
+      versions,
+      // Unified cross-plugin model (PRD §7.1); `versions` stays for compatibility.
+      versionRecords: toVersionRecords(versions, id, checkpointHasher(rawCheckpoints)),
+      checkpoints,
+    }))
+    return true
+  }
+
+  return false
+}

package/src/http/project-files.ts

@@ -0,0 +1,227 @@
+/**
+ * The project file chooser's data source.
+ *
+ * The browser's own file dialog cannot do the two things this plugin needs: it
+ * shows no creation date, and it can browse the whole disk, which is the wrong
+ * default for a project that keeps its data in `<project>/storages`. This route
+ * lists one directory of that container instead, with each entry's size and its
+ * creation and modification times.
+ *
+ * Two properties are deliberate:
+ *
+ *  - **Contained.** `dir` is a relative path inside `<project>/storages`, and
+ *    anything that resolves outside it is refused. The chooser is not a general
+ *    filesystem browser.
+ *  - **Not the only way in.** Importing from outside the project stays possible
+ *    (the OS dialog the client already had): containment is about where a
+ *    project's files *live*, not about what a user may read.
+ *
+ * @module dsh-data-table/http/project-files
+ */
+import { readFile, readdir, stat } from 'node:fs/promises'
+import { join, resolve, sep } from 'node:path'
+import type { Context } from '@deepseek-ai/cordis'
+import { projectFor, sessionIdOf } from './project-scope.ts'
+import { guardDataSheetRequest, type LegacyRoute } from './routes.ts'
+import { projectStoragesDirectory, runInProject } from '../store/project.ts'
+
+/** One entry of the chooser's listing. */
+export interface ProjectFileEntry {
+  /** Basename inside the listed directory. */
+  readonly name: string
+  /** Path relative to `<project>/storages`, `/`-separated; empty at the root. */
+  readonly path: string
+  readonly type: 'file' | 'directory'
+  /** Bytes, for a regular file. */
+  readonly size: number
+  /** Filesystem creation time, ISO; empty when the platform does not report one. */
+  readonly createdAt: string
+  /** Last modification time, ISO. */
+  readonly modifiedAt: string
+}
+
+/** One directory of the project's storage, as the chooser renders it. */
+export interface ProjectFileListing {
+  /** The listed directory, relative to `<project>/storages`; empty at the root. */
+  readonly directory: string
+  /** How many entries were dropped by the cap. */
+  readonly truncated: number
+  readonly entries: readonly ProjectFileEntry[]
+}
+
+/** Cap on one page; a chooser that renders ten thousand rows helps nobody. */
+const MAX_ENTRIES = 500
+
+/**
+ * Normalize the requested directory to a relative path inside the storage root.
+ *
+ * @param raw - What the client sent: `''`, `data-table/`.
+ * @returns a `/`-separated relative path with no traversal.
+ * @throws when the path escapes the storage container.
+ */
+export function safeRelativeDirectory(raw: string): string {
+  // A leading separator or a `..` segment is refused rather than normalized
+  // away: `/etc` silently becoming `etc` would list a *different* directory than
+  // the caller asked for, and a caller that sends one is wrong about something.
+  const cleaned = raw.replace(/\\/g, '/').replace(/\/+$/, '')
+  if (cleaned.length === 0) return ''
+  if (cleaned.startsWith('/')) throw new Error('目录必须是 storages 内的相对路径')
+  const segments = cleaned.split('/')
+  if (segments.some(segment => segment === '' || segment === '.' || segment === '..')) {
+    throw new Error('目录必须是 storages 内的相对路径')
+  }
+  return segments.join('/')
+}
+
+/** ISO creation and modification times of one entry, best effort. */
+function times(entry: { birthtimeMs: number; mtimeMs: number }): { createdAt: string; modifiedAt: string } {
+  // `birthtimeMs` is 0 on filesystems that do not record a creation time; an
+  // empty string is honest there, while `0` would render as 1970.
+  const created = Number.isFinite(entry.birthtimeMs) && entry.birthtimeMs > 0 ? new Date(entry.birthtimeMs) : null
+  return {
+    createdAt: created === null ? '' : created.toISOString(),
+    modifiedAt: new Date(entry.mtimeMs).toISOString(),
+  }
+}
+
+/**
+ * List one page of a storage container rooted at `root`.
+ *
+ * `root` is the project directory, and the container is `<root>/storages`; the
+ * parameter exists so tests can point at a temporary tree without a Session.
+ */
+export async function listProjectFiles(root: string, relativeDirectory: string): Promise<ProjectFileListing> {
+  const directory = safeRelativeDirectory(relativeDirectory)
+  const target = join(projectStoragesDirectory(root), ...(directory === '' ? [] : directory.split('/')))
+  const containment = resolve(projectStoragesDirectory(root))
+  const resolved = resolve(target)
+  if (resolved !== containment && !resolved.startsWith(containment + sep)) {
+    throw new Error('目录必须是 storages 内的相对路径')
+  }
+  const dirents = await readdir(resolved, { withFileTypes: true }).catch(() => [])
+  const entries: ProjectFileEntry[] = []
+  for (const dirent of dirents) {
+    const absolute = join(resolved, dirent.name)
+    const info = await stat(absolute).catch(() => null)
+    if (info === null) continue
+    const isDirectory = info.isDirectory()
+    if (!isDirectory && !info.isFile()) continue
+    entries.push({
+      name: dirent.name,
+      path: directory === '' ? dirent.name : `${directory}/${dirent.name}`,
+      type: isDirectory ? 'directory' : 'file',
+      size: isDirectory ? 0 : info.size,
+      ...times(info),
+    })
+  }
+  entries.sort((left, right) => {
+    if (left.type !== right.type) return left.type === 'directory' ? -1 : 1
+    return left.name.localeCompare(right.name)
+  })
+  return { directory, truncated: Math.max(0, entries.length - MAX_ENTRIES), entries: entries.slice(0, MAX_ENTRIES) }
+}
+
+/** Largest file the chooser will hand back; matches the client's own import cap. */
+export const MAX_PICKED_BYTES = 25 * 1024 * 1024
+
+/**
+ * Read one file from the storage container.
+ *
+ * The browser cannot open a path itself, so a choice made in the chooser comes
+ * back through here. Contained exactly like the listing — the same root, the
+ * same refusal — and capped, because the import pipeline caps at the same size
+ * and a truncated workbook is worse than a clear refusal.
+ *
+ * @param root - Project directory.
+ * @param relativePath - File path relative to `<project>/storages`.
+ * @param maxBytes - Cap, defaulting to {@link MAX_PICKED_BYTES}.
+ * @returns the file's bytes and its basename.
+ * @throws when the path escapes the container, is a directory, or is too large.
+ */
+export async function readProjectFile(root: string, relativePath: string, maxBytes = MAX_PICKED_BYTES): Promise<{ name: string; bytes: Buffer }> {
+  const container = resolve(projectStoragesDirectory(root))
+  const cleaned = safeRelativeDirectory(relativePath)
+  if (cleaned === '') throw new Error('请选择一个文件')
+  const resolved = resolve(join(container, ...cleaned.split('/')))
+  if (!resolved.startsWith(container + sep)) throw new Error('文件必须在 storages 内')
+  const info = await stat(resolved).catch(() => null)
+  if (info === null || !info.isFile()) throw new Error('文件不存在')
+  if (info.size > maxBytes) throw new Error(`文件过大（最大 ${Math.floor(maxBytes / (1024 * 1024))} MB）`)
+  return { name: cleaned.split('/').pop() ?? cleaned, bytes: await readFile(resolved) }
+}
+
+/**
+ * The chooser's listing for one request.
+ *
+ * @param project - Absolute project directory, or `undefined` when none was named.
+ * @param relativeDirectory - Directory relative to the storage container.
+ * @returns the listing; empty when there is no project or no storage yet.
+ * @throws when the path escapes the container.
+ */
+export async function projectFiles(project: string | undefined, relativeDirectory: string): Promise<ProjectFileListing> {
+  if (project === undefined) return { directory: safeRelativeDirectory(relativeDirectory), truncated: 0, entries: [] }
+  return runInProject(project, async () => listProjectFiles(project, relativeDirectory))
+}
+
+/**
+ * The chooser's two routes: the listing, and one file's bytes.
+ *
+ * They live here rather than in the plugin body because the body has a 200-line
+ * budget — it assembles routes, it does not implement them (the same reason
+ * `assetRoutes()` is a module).
+ *
+ * @param ctx - Host context, read for the Session registry.
+ * @returns the routes to register.
+ */
+export function projectFileRoutes(ctx: Context): LegacyRoute[] {
+  /** The project this request belongs to, resolved once per request. */
+  const projectOf = (req: Parameters<NonNullable<LegacyRoute['handler']>>[0], url: URL): string | undefined =>
+    projectFor(ctx, sessionIdOf(req.headers as Record<string, unknown>, url))
+
+  return [{
+    kind: 'exact',
+    path: '/data-sheet/project-files.json',
+    handler: async (req, res) => {
+      if (!guardDataSheetRequest(req, res)) return
+      const url = new URL(req.url ?? '/', 'http://x')
+      try {
+        const listing = await projectFiles(projectOf(req, url), url.searchParams.get('dir') ?? '')
+        res.writeHead(200, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-cache' })
+        res.end(JSON.stringify({ ok: true, ...listing }))
+      } catch (error) {
+        // A path outside the container is the caller's mistake, not a crash.
+        res.writeHead(400, { 'content-type': 'application/json; charset=utf-8' })
+        res.end(JSON.stringify({ ok: false, error: error instanceof Error ? error.message : String(error) }))
+      }
+    },
+  }, {
+    // One file's bytes, so a choice made in the chooser can reach the import
+    // pipeline: the browser cannot open a path by itself.
+    kind: 'exact',
+    path: '/data-sheet/project-file.json',
+    handler: async (req, res) => {
+      if (!guardDataSheetRequest(req, res)) return
+      const url = new URL(req.url ?? '/', 'http://x')
+      const project = projectOf(req, url)
+      if (project === undefined) {
+        res.writeHead(400, { 'content-type': 'application/json; charset=utf-8' })
+        res.end(JSON.stringify({ ok: false, error: '无法确定项目目录' }))
+        return
+      }
+      try {
+        const file = await readProjectFile(project, url.searchParams.get('path') ?? '')
+        res.writeHead(200, {
+          'content-type': 'application/octet-stream',
+          'content-length': String(file.bytes.byteLength),
+          // The chooser showed this name; the client keeps using it.
+          'x-file-name': encodeURIComponent(file.name),
+          'cache-control': 'no-cache',
+        })
+        res.end(file.bytes)
+      } catch (error) {
+        res.writeHead(400, { 'content-type': 'application/json; charset=utf-8' })
+        res.end(JSON.stringify({ ok: false, error: error instanceof Error ? error.message : String(error) }))
+      }
+    },
+  }]
+}

package/src/http/project-scope.ts

@@ -0,0 +1,77 @@
+/**
+ * Which project a browser request writes into.
+ *
+ * The workbook routes are declared in `index.ts` and dispatched to the domain
+ * handlers in `http/`, so the decision "this request belongs to that project"
+ * has to be made once, before the dispatch — but the plugin body has a 200-line
+ * budget precisely so that decisions with a home live in it. This is that home.
+ *
+ * @module dsh-data-table/http/project-scope
+ */
+import type { Context } from '@deepseek-ai/cordis'
+import { projectScopeOf, runInProject, type SessionRegistry } from '../store/project.ts'
+
+/**
+ * The Host fields the project scope is derived from.
+ *
+ * Read structurally rather than injected: both are Host services a plugin may
+ * run without, and refusing to load over a missing optional service would be a
+ * worse failure than the fallbacks below.
+ */
+interface HostScope {
+  /** Session registry, read for the header's working directory. */
+  sessions?: SessionRegistry
+}
+
+/**
+ * The Session a browser request belongs to.
+ *
+ * The header first, because that is one line in the client's single transport
+ * (`requestJson` sets it on every call); the query parameter second, because an
+ * `EventSource` cannot set headers and the live collaboration stream is the one
+ * route that needs the fallback.
+ *
+ * @param headers - Node request headers.
+ * @param url - Parsed request URL.
+ * @returns the Session id, or `undefined` for a caller that named none.
+ */
+export function sessionIdOf(headers: Record<string, unknown>, url: URL): string | undefined {
+  const header = headers['x-dsh-session']
+  const value = Array.isArray(header) ? header[0] : header
+  if (typeof value === 'string' && value.length > 0) return value
+  const query = url.searchParams.get('sessionId')
+  return query !== null && query.length > 0 ? query : undefined
+}
+
+/**
+ * The project directory one browser request writes into.
+ *
+ * A Session's header carries its working directory, and the registry is where
+ * that header is read — the same lookup the Agent tools make for the same
+ * Session id, so a panel and a tool call cannot mean two directories. `undefined`
+ * means **no project**: nobody named one, so the store keeps its pre-project
+ * location rather than inventing a project from the process directory — one Host
+ * serves several projects at once, and a shared fallback would mix them.
+ *
+ * @param ctx - Host context.
+ * @param sessionId - Session named by the request, when it named one.
+ * @returns an absolute project directory, or `undefined`.
+ */
+export function projectFor(ctx: Context, sessionId: string | undefined): string | undefined {
+  const scope = ctx as unknown as HostScope
+  return projectScopeOf(scope.sessions, sessionId)
+}
+
+/**
+ * Run one request's store work inside `project`, when there is one.
+ *
+ * A missing project is not a failure: the body runs unscoped and the store
+ * answers with the location it used before projects existed.
+ *
+ * @param project - Project directory, or `undefined` for "nobody named one".
+ * @param body - The request's store work.
+ * @returns whatever `body` returns.
+ */
+export function runForProject<T>(project: string | undefined, body: () => Promise<T>): Promise<T> {
+  return project === undefined ? body() : runInProject(project, body)
+}