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

package/src/request-params.ts

@@ -0,0 +1,92 @@
+/**
+ * Request vocabulary shared by both transports (docs/issue/0022 P3).
+ *
+ * The browser posts a JSON body and the Agent passes tool arguments, but both
+ * have to become the same `WorkbookOperationPayload`. These parsers are that
+ * translation, and they are validation-first: each one rejects what it cannot
+ * represent instead of coercing it.
+ *
+ * They live here rather than in `http/` because the Agent tools need exactly the
+ * same conversions, and a tool importing from the HTTP layer would make the two
+ * transports depend on each other.
+ */
+import {
+  type WorkbookOperationPayload,
+  type WorkbookOperationType,
+  type WorkbookRange,
+} from './types.ts'
+import { validateRange } from './contract/snapshots.ts'
+
+export function parseIndex(value: unknown, label: string): number {
+  if (typeof value !== 'number' || !Number.isInteger(value) || value < 0) throw new Error(`${label} 必须是大于等于 0 的整数`)
+  return value
+}
+
+export function optionalRevision(value: unknown): number | undefined {
+  if (value === undefined || value === null) return undefined
+  return parseIndex(value, 'baseRevision')
+}
+
+export function isOperationType(value: unknown): value is WorkbookOperationType {
+  return value === 'update_cells' || value === 'clear_range' || value === 'delete_cells'
+    || value === 'insert_rows' || value === 'delete_rows' || value === 'insert_columns'
+    || value === 'delete_columns' || value === 'create_sheet' || value === 'delete_sheet'
+    || value === 'rename_sheet' || value === 'append_rows' || value === 'format_cells'
+    || value === 'merge_cells' || value === 'unmerge_cells' || value === 'freeze_panes'
+    || value === 'set_column_width' || value === 'set_row_height' || value === 'sort_range'
+    || value === 'set_hyperlink' || value === 'remove_hyperlink'
+    || value === 'remove_duplicates'
+    || value === 'batch' || value === 'snapshot_replace'
+}
+
+export function asOperationPayload(value: unknown): WorkbookOperationPayload {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) throw new Error('operation payload 必须是对象')
+  return value as WorkbookOperationPayload
+}
+
+export function parseRange(value: unknown): WorkbookRange {
+  if (typeof value === 'string') return parseA1Range(value)
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) throw new Error('range 必须是对象')
+  const raw = value as Record<string, unknown>
+  const range = {
+    startRow: parseIndex(raw.startRow, 'range.startRow'),
+    startColumn: parseIndex(raw.startColumn, 'range.startColumn'),
+    endRow: parseIndex(raw.endRow, 'range.endRow'),
+    endColumn: parseIndex(raw.endColumn, 'range.endColumn'),
+  }
+  // One validator, not two opinions. This checked only the span, so a range far
+  // past the end of any sheet (`startRow: 9e8`) was accepted here and rejected
+  // later by whichever mutator happened to consult the absolute bound — with a
+  // different message. `parseA1Range` reaches this through the object branch, so
+  // both spellings of a range are now validated identically.
+  validateRange(range)
+  return range
+}
+
+export function a1ColumnIndex(value: string): number {
+  let result = 0
+  for (const character of value.toUpperCase()) result = result * 26 + character.charCodeAt(0) - 64
+  return result - 1
+}
+
+export function parseA1Range(value: string): WorkbookRange {
+  const match = /^\s*([A-Za-z]+)(\d+)(?::([A-Za-z]+)(\d+))?\s*$/.exec(value)
+  if (match === null) throw new Error('range 必须是 0-based 对象，或类似 A1:D4 的范围字符串')
+  const startColumn = a1ColumnIndex(match[1] as string)
+  const startRow = Number(match[2]) - 1
+  const endColumn = match[3] === undefined ? startColumn : a1ColumnIndex(match[3])
+  const endRow = match[4] === undefined ? startRow : Number(match[4]) - 1
+  return parseRange({ startRow, startColumn, endRow, endColumn })
+}
+
+export function normalizeValueMatrix(value: unknown): unknown[][] {
+  if (!Array.isArray(value) || value.length === 0) throw new Error('values 必须是非空二维数组')
+  const rows = value.every(item => !Array.isArray(item)) ? [value] : value
+  if (!rows.every(item => Array.isArray(item))) throw new Error('values 必须是二维数组')
+  const width = Math.max(...rows.map(item => (item as unknown[]).length))
+  if (width === 0) throw new Error('values 不能包含空行')
+  // Ragged model-generated matrices are padded instead of rejected. This
+  // makes a four-row write safe when one row has a missing trailing field.
+  return rows.map(item => Array.from({ length: width }, (_value, index) => (item as unknown[])[index] ?? null))
+}
+

package/src/store/paths.ts

@@ -0,0 +1,165 @@
+/**
+ * Where a workbook's files live in the DSH home (docs/issue/0022 P1).
+ *
+ * The single choke point every read and write goes through, which is why the
+ * one-time `data-sheet` → `data-table` rename is performed here rather than at
+ * a call site. Nothing else in the plugin may build a storage path.
+ */
+import { existsSync, mkdirSync, renameSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { dirname, join, resolve } from 'node:path'
+import { normalizeWorkbookId, normalizeWorktreeId } from '../contract/ids.ts'
+import { currentProjectRoot, projectStoragesRoot } from './project.ts'
+
+/**
+ * The home the migration has already been attempted for, and what happened.
+ *
+ * Keyed by the resolved home rather than a bare boolean: `$DSH_HOME` is read on
+ * every call, and the previous process-wide flag meant a home that changed
+ * mid-process was never migrated at all — it returned the *other* home's
+ * outcome. The memo exists to avoid re-stat-ing on every operation, which keying
+ * by home still does.
+ */
+let storageMigrationHome: string | null = null
+let storageMigrationOutcome: WorkbookStorageMigration = 'no-legacy'
+
+
+/** Resolve the DSH home, honoring $DSH_HOME (mirror of dsh-home-paths). */
+export function dshHome(): string {
+  const env = process.env.DSH_HOME
+  const home = env !== undefined && env.trim().length > 0 ? env : join(homedir(), '.dsh')
+  return resolve(home)
+}
+
+/**
+ * Repository root for this plugin.
+ *
+ * Two answers, and the difference is which project the call belongs to:
+ *
+ *  - **inside a Session** (an HTTP route or a tool call, which establish the
+ *    scope — see `./project.ts`): `<project>/storages/data-table`, so a
+ *    project directory is self-contained.
+ *  - **outside one** (a script, a test, an un-migrated caller): the pre-project
+ *    per-user location, unchanged. Answering that case with `process.cwd()`
+ *    would silently start a *new* store for a caller that was reading the old
+ *    one, which is worse than keeping it.
+ *
+ * `data-sheet` → `data-table` renamed that per-user root; resolving the root is
+ * the single choke point every read and write goes through, so the one-time
+ * migration runs here and is memoized afterwards.
+ */
+export function workbookRoot(): string {
+  migrateLegacyWorkbookStorage()
+  const project = currentProjectRoot()
+  return project === undefined ? globalWorkbookRoot() : projectStoragesRoot(project)
+}
+
+/**
+ * The pre-project, per-user storage root.
+ *
+ * Named rather than inlined because it is read by more than the fallback: the
+ * workbook list offers its contents as "from the old location" for a user who
+ * has workbooks there and none here yet.
+ */
+export function globalWorkbookRoot(): string {
+  return join(dshHome(), 'storages', 'data-table')
+}
+
+/** Storage root used before the data-sheet → data-table rename. */
+export function legacyWorkbookRoot(): string {
+  return join(dshHome(), 'storages', 'data-sheet')
+}
+
+/**
+ * Move `<dshHome>/storages/data-sheet` to `storages/data-table` exactly once.
+ *
+ * Idempotent and safe to call from every read/write path: the old root is only
+ * moved when the new root does not exist yet, so a second call is a no-op and
+ * two populated roots are never merged (the legacy files are left untouched
+ * rather than deleted).
+ * @returns the outcome of the first migration attempt.
+ */
+export function migrateLegacyWorkbookStorage(): WorkbookStorageMigration {
+  const home = dshHome()
+  if (storageMigrationHome === home) return storageMigrationOutcome
+  storageMigrationHome = home
+  const legacy = legacyWorkbookRoot()
+  const target = workbookRootWithoutMigration()
+  try {
+    if (legacy === target || !existsSync(legacy)) return (storageMigrationOutcome = 'no-legacy')
+    if (existsSync(target)) return (storageMigrationOutcome = 'target-exists')
+    mkdirSync(dirname(target), { recursive: true })
+    renameSync(legacy, target)
+    return (storageMigrationOutcome = 'migrated')
+  } catch {
+    // A failed rename must never take the plugin down; the legacy root stays
+    // where it is and the next call retries.
+    storageMigrationHome = null
+    return (storageMigrationOutcome = 'failed')
+  }
+}
+
+/** Current root without triggering the migration (avoids recursion). */
+/**
+ * Where oversized tool results are spilled.
+ *
+ * Under the storage root, and here rather than in the module that writes them:
+ * what a spilled result *is* belongs to the tool presentation, but where plugin
+ * data lives is the store's business — and so is what to do when there is too
+ * much of it.
+ */
+export function toolOutputRoot(): string {
+  return join(workbookRoot(), 'tool-output')
+}
+
+export function workbookRootWithoutMigration(): string {
+  return join(dshHome(), 'storages', 'data-table')
+}
+
+/** Absolute snapshot path for one workbook. */
+export function workbookPath(id: string): string {
+  // Keep this boundary safe even for callers outside the tool/HTTP adapters.
+  // Those adapters already normalize ids, but this exported repository helper
+  // must not allow `../` segments to escape the Datasheet storage directory.
+  return join(workbookRoot(), `${normalizeWorkbookId(id)}.json`)
+}
+
+/** Lightweight metadata path used by polling, workbook lists, and history. */
+export function workbookIndexPath(id: string): string {
+  return join(workbookRoot(), `${normalizeWorkbookId(id)}.index.json`)
+}
+
+export function workbookSnapshotPath(id: string): string {
+  return join(workbookRoot(), `${normalizeWorkbookId(id)}.snapshot.json`)
+}
+
+export function workbookCheckpointsPath(id: string): string {
+  return join(workbookRoot(), `${normalizeWorkbookId(id)}.checkpoints.json`)
+}
+
+/** Full operation log is kept out of the workbook metadata file. */
+export function workbookOperationsPath(id: string): string {
+  return join(workbookRoot(), `${normalizeWorkbookId(id)}.operations.json`)
+}
+
+/** Pending proposals (which may contain a full preview snapshot) are sidecar data. */
+export function workbookProposalsPath(id: string): string {
+  return join(workbookRoot(), `${normalizeWorkbookId(id)}.proposals.json`)
+}
+
+export function workbookTransactionPath(id: string): string {
+  return join(workbookRoot(), `${normalizeWorkbookId(id)}.transaction.json`)
+}
+
+/** Isolated review worktrees live below the workbook repository and never
+ * participate in the trunk workbook catalog. */
+export function workbookWorktreeDirectory(workbookId: string): string {
+  return join(workbookRoot(), '.worktrees', normalizeWorkbookId(workbookId))
+}
+
+export function workbookWorktreePath(workbookId: string, worktreeId: string): string {
+  return join(workbookWorktreeDirectory(workbookId), `${normalizeWorktreeId(worktreeId)}.json`)
+}
+
+/** Outcome of {@link migrateLegacyWorkbookStorage}. */
+export type WorkbookStorageMigration = 'no-legacy' | 'migrated' | 'target-exists' | 'failed'

package/src/store/project.ts

@@ -0,0 +1,137 @@
+/**
+ * Which project a store call belongs to (project-local storage, 2026-09-25).
+ *
+ * A workbook used to live in one per-user directory (`~/.dsh/storages/data-table`)
+ * shared by every Session. It now lives in the project it belongs to —
+ * `<project>/storages/data-table` — so copying a project directory copies its
+ * workbooks, and deleting one leaves nothing behind in the user's home.
+ *
+ * The store modules are called from three places that do **not** share a call
+ * shape: HTTP route handlers (which name a Session id), Agent tool executions
+ * (which carry the calling Agent), and plain scripts and tests (which have
+ * neither). Rather than thread a root parameter through every read and write —
+ * `workbookRoot()` is the single choke point they all pass through — the project
+ * travels in an async context for the duration of one request or tool call.
+ * `AsyncLocalStorage` rather than a module variable because one Host process
+ * serves several Sessions at once: a global would let two projects' writes
+ * interleave into the wrong directory, which is the one failure this must not
+ * have.
+ *
+ * The three callers converge on one question, asked in one place:
+ * {@link projectScopeOf} turns "this Session" into "this project directory" by
+ * looking the Session up in the Host's registry and reading its **header**. A
+ * tool and a browser request naming the same Session therefore mean the same
+ * directory by construction rather than by both computing it the same way.
+ *
+ * @module dsh-data-table/store/project
+ */
+import { AsyncLocalStorage } from 'node:async_hooks'
+import { join } from 'node:path'
+import { STORAGES_DIRECTORY, isProjectDirectory } from '#contracts'
+
+/** This plugin's directory inside a project's `storages/`. */
+export const PLUGIN_DIRECTORY = 'data-table'
+
+const scope = new AsyncLocalStorage<string>()
+
+/**
+ * Run one unit of work with a project root in scope.
+ *
+ * @param root - Absolute project directory.
+ * @param body - The work; may be async, and keeps the scope across its awaits.
+ * @returns whatever `body` returns.
+ */
+export function runInProject<T>(root: string, body: () => T): T {
+  return scope.run(root, body)
+}
+
+/**
+ * The project root in scope, when there is one.
+ *
+ * `undefined` means "no project": a script, a test, or a caller that has not been
+ * migrated. `workbookRoot()` answers that case with the pre-project location
+ * rather than inventing a project, so an un-migrated caller keeps reading and
+ * writing where it always did instead of quietly starting a new store.
+ */
+export function currentProjectRoot(): string | undefined {
+  return scope.getStore()
+}
+
+/**
+ * The bits of DSH's Session registry this module reads.
+ *
+ * Read structurally — it arrives from the Host, and a caller may run without it
+ * (a test harness, an embedding with no Host services).
+ */
+export interface SessionRegistry {
+  /** Look one Session up by id; `undefined` when no such Session is live. */
+  get?: (id: string) => { readonly header?: { readonly cwd?: unknown } } | undefined
+}
+
+/**
+ * The project directory one Session's store calls belong to, or `undefined` for
+ * "no project".
+ *
+ * The Session **header** is the only source, and it is read through the Host's
+ * registry (`ctx.sessions.get(id)`) rather than off the calling Agent's own
+ * Session object. That is the fix for a real bug (2026-10-02): the tools read
+ * `agent.session.cwd`, a field a Session does not have — a Session carries its
+ * directory at `session.header.cwd` — so every tool call answered "no project"
+ * and wrote to the per-user store while the browser panel wrote to
+ * `<project>/storages/data-table`. The Agent and the open Table were editing two
+ * different sets of workbooks, and neither could see the other's.
+ *
+ * Reading the registry also makes the two transports agree by construction: an
+ * HTTP request names a Session id, a tool call names the same id through its
+ * Agent, and both are answered by the same header. `data-excalidraw` resolves its
+ * scene directory the same way, for the same reason.
+ *
+ * The Host's sandbox policy is deliberately *not* consulted: a plugin context
+ * cannot read it (see `src/index.ts`), and the one attempt to use it as a
+ * fallback turned every workbook list into a bodyless 400.
+ *
+ * `undefined` is a real answer and not a failure: it means the caller named no
+ * Session, so nobody has said which project this is. The two ways to get it
+ * wrong are both worse than a missing project — `process.cwd()` would silently
+ * start a *new* per-project store for a caller that was reading the old per-user
+ * one (a test, a script, an older client), and a shared per-process default
+ * would mix two Sessions' writes. Callers therefore leave the scope unset, and
+ * `workbookRoot()` answers with the pre-project location it always used.
+ *
+ * @param sessions - DSH's Session registry, from the injected `sessions` service.
+ * @param sessionId - The Session naming the project; `undefined` or empty for a
+ *   caller that named none.
+ * @returns an absolute project directory, or `undefined` when nothing named one.
+ */
+export function projectScopeOf(sessions: SessionRegistry | undefined, sessionId: string | undefined): string | undefined {
+  if (sessionId === undefined || sessionId.length === 0) return undefined
+  const cwd = sessions?.get?.(sessionId)?.header?.cwd
+  // A filesystem root counts as "not named": treating `/` as a project root
+  // meant creating `/storages/data-table`.
+  return isProjectDirectory(cwd) ? cwd : undefined
+}
+
+/**
+ * This plugin's storage inside one project.
+ *
+ * @param root - Project directory.
+ * @returns `<root>/storages/data-table`, which may not exist yet.
+ */
+export function projectStoragesRoot(root: string): string {
+  return join(root, STORAGES_DIRECTORY, PLUGIN_DIRECTORY)
+}
+
+/**
+ * The project's storage container, shared by every plugin.
+ *
+ * The file chooser lists this directory rather than the project root: it is
+ * where a project's data lives, and it is what a copy of the project directory
+ * carries. A user who wants a file from elsewhere uses the "从项目外导入" path,
+ * which is deliberately unrestricted.
+ *
+ * @param root - Project directory.
+ * @returns `<root>/storages`, which may not exist yet.
+ */
+export function projectStoragesDirectory(root: string): string {
+  return join(root, STORAGES_DIRECTORY)
+}