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

package/lib/types/store/write.js

@@ -0,0 +1,210 @@
+/**
+ * The only module that replaces a workbook's bytes (docs/issue/0022 P1).
+ *
+ * Every commit is a write-ahead journal plus temp-file renames, so an
+ * interrupted save is finished by the next read rather than leaving half a
+ * workbook on disk. It takes the journal lock from `store/read.ts` so a commit
+ * can never interleave with the recovery of another.
+ */
+import { mkdir, rename, rm, unlink, writeFile } from 'node:fs/promises';
+import { randomUUID } from 'node:crypto';
+import { DEFAULT_WORKBOOK } from "../types.js";
+import { normalizeWorkbookId, normalizeWorktreeId } from "../contract/ids.js";
+import { PROPOSAL_LOG_LIMIT, operationSummary } from "../contract/operations.js";
+import { validateSnapshotBounds } from "../contract/mutations.js";
+import { cloneSnapshot, normalizeSnapshotName } from "../contract/snapshots.js";
+import { workbookCheckpointsPath, workbookIndexPath, workbookOperationsPath, workbookPath, workbookProposalsPath, workbookRoot, workbookSnapshotPath, workbookTransactionPath, workbookWorktreeDirectory, workbookWorktreePath, } from "./paths.js";
+import { fileExists, readWorkbook, recoverWorkbookTransactionNow, summarize, withWorkbookTransactionQueue, workbookCache, } from "./read.js";
+/** Write one workbook meta atomically (creates the repo root on demand). */
+export async function writeWorkbook(meta, options = {}) {
+    const normalizedId = normalizeWorkbookId(meta.id);
+    await withWorkbookTransactionQueue(normalizedId, async () => {
+        await mkdir(workbookRoot(), { recursive: true });
+        await recoverWorkbookTransactionNow(normalizedId);
+        // The DSH metadata name is the user-facing workbook name. Keep the Univer
+        // snapshot name aligned so exports and other consumers use the same name.
+        const normalizedMeta = { ...meta, id: normalizedId, snapshot: normalizeSnapshotName(meta.snapshot, meta.name) };
+        validateSnapshotBounds(normalizedMeta.snapshot);
+        const operationLog = normalizedMeta.operations ?? [];
+        const proposalLog = normalizedMeta.proposals ?? [];
+        // Versions are the durable audit trail. Keep the append-only operation log
+        // instead of truncating it to a recent tail so old versions can be replayed.
+        normalizedMeta.operations = operationLog;
+        // The single place this bound is applied, since every write comes through here.
+        normalizedMeta.proposals = proposalLog.slice(-PROPOSAL_LOG_LIMIT);
+        const snapshotExists = await fileExists(workbookSnapshotPath(normalizedId));
+        const persistSnapshot = options.persistSnapshot === true || !snapshotExists;
+        const checkpointsExist = await fileExists(workbookCheckpointsPath(normalizedId));
+        const snapshotRevision = persistSnapshot
+            ? normalizedMeta.revision ?? 0
+            : (typeof normalizedMeta.snapshotRevision === 'number' ? normalizedMeta.snapshotRevision : 0);
+        const { snapshot: _snapshot, checkpoints: _checkpoints, operations: _operations, proposals: _proposals, ...metadata } = normalizedMeta;
+        const metadataWithSnapshotRevision = { ...metadata, snapshotRevision };
+        const files = [
+            { target: workbookOperationsPath(normalizedId), value: normalizedMeta.operations ?? [] },
+            { target: workbookProposalsPath(normalizedId), value: normalizedMeta.proposals ?? [] },
+            { target: workbookPath(normalizedId), value: metadataWithSnapshotRevision },
+            { target: workbookIndexPath(normalizedId), value: buildWorkbookIndex(normalizedMeta) },
+        ];
+        if (persistSnapshot)
+            files.unshift({ target: workbookSnapshotPath(normalizedId), value: { revision: normalizedMeta.revision ?? 0, snapshot: normalizedMeta.snapshot } });
+        if (options.persistCheckpoints === true || !checkpointsExist)
+            files.splice(persistSnapshot ? 1 : 0, 0, { target: workbookCheckpointsPath(normalizedId), value: { checkpoints: normalizedMeta.checkpoints ?? [] } });
+        await commitWorkbookTransaction(normalizedId, files, normalizedMeta.revision ?? 0);
+        workbookCache.set(normalizedId, {
+            meta: { ...normalizedMeta, snapshotRevision, checkpoints: normalizedMeta.checkpoints ?? [] },
+            checkpointsLoaded: options.persistCheckpoints === true || !checkpointsExist,
+        });
+    });
+}
+export async function writeJsonAtomically(path, value) {
+    const tempPath = `${path}.${process.pid}.${randomUUID()}.tmp`;
+    try {
+        await writeFile(tempPath, JSON.stringify(value, null, 2), 'utf8');
+        await rename(tempPath, path);
+    }
+    finally {
+        try {
+            await unlink(tempPath);
+        }
+        catch { /* rename already removed it */ }
+    }
+}
+export async function commitWorkbookTransaction(id, files, revision) {
+    const transactionId = randomUUID();
+    const journalPath = workbookTransactionPath(id);
+    const prepared = files.map(file => ({ target: file.target, temp: `${file.target}.${transactionId}.tmp` }));
+    let journalWritten = false;
+    try {
+        for (const [index, file] of files.entries()) {
+            await writeFile(prepared[index].temp, JSON.stringify(file.value, null, 2), 'utf8');
+        }
+        await writeJsonAtomically(journalPath, { revision, files: prepared });
+        journalWritten = true;
+        for (const file of prepared)
+            await rename(file.temp, file.target);
+        await unlink(journalPath);
+    }
+    catch (error) {
+        // Once the journal exists, its prepared files are intentionally retained
+        // so the next read can complete the commit. Before that point cleanup is
+        // safe because no target has been replaced.
+        if (!journalWritten) {
+            await Promise.all(prepared.map(file => unlink(file.temp).catch(() => undefined)));
+        }
+        throw error;
+    }
+}
+export async function writeWorktree(worktree) {
+    await mkdir(workbookWorktreeDirectory(worktree.workbookId), { recursive: true });
+    await writeJsonAtomically(workbookWorktreePath(worktree.workbookId, worktree.id), worktree);
+}
+export function buildWorkbookIndex(meta) {
+    const summary = summarize(meta);
+    return {
+        id: summary.id,
+        name: summary.name,
+        sheetOrder: summary.sheets.map(sheet => sheet.id),
+        sheets: summary.sheets,
+        updatedAt: summary.updatedAt,
+        revision: meta.revision ?? 0,
+        operations: (meta.operations ?? []).map(operation => ({
+            opId: operation.opId,
+            workbookId: operation.workbookId,
+            revision: operation.revision,
+            actor: operation.actor,
+            type: operation.type,
+            timestamp: operation.timestamp,
+            summary: operationSummary(operation),
+        })),
+        proposals: (meta.proposals ?? []).map(({ snapshot: _snapshot, ...proposal }) => proposal),
+    };
+}
+/**
+ * Delete a workbook and all of its Datasheet sidecars. `main` is the stable
+ * default workbook and is intentionally protected from accidental deletion.
+ * The queue makes deletion serialize with an in-flight save for the same id.
+ */
+export async function deleteWorkbook(id) {
+    const normalizedId = normalizeWorkbookId(id);
+    if (normalizedId === DEFAULT_WORKBOOK)
+        throw new Error('默认工作簿 main 不能删除');
+    await withWorkbookQueue(normalizedId, async () => {
+        workbookCache.delete(normalizedId);
+        const paths = [
+            workbookPath(normalizedId),
+            workbookIndexPath(normalizedId),
+            workbookSnapshotPath(normalizedId),
+            workbookCheckpointsPath(normalizedId),
+            workbookOperationsPath(normalizedId),
+            workbookProposalsPath(normalizedId),
+            workbookTransactionPath(normalizedId),
+        ];
+        for (const path of paths) {
+            try {
+                await unlink(path);
+            }
+            catch (error) {
+                if (error.code !== 'ENOENT')
+                    throw error;
+            }
+        }
+        await rm(workbookWorktreeDirectory(normalizedId), { recursive: true, force: true });
+    });
+}
+/** Rename the user-facing workbook label without changing its stable id or
+ * history. The snapshot name is kept in sync by `writeWorkbook`. */
+export async function renameWorkbook(id, name) {
+    const normalizedId = normalizeWorkbookId(id);
+    const normalizedName = name.trim();
+    if (normalizedName.length === 0)
+        throw new Error('工作簿名称不能为空');
+    return withWorkbookQueue(normalizedId, async () => {
+        const existing = await readWorkbook(normalizedId);
+        if (existing === null)
+            throw new Error(`工作簿不存在：${id}`);
+        const meta = cloneSnapshot(existing);
+        meta.name = normalizedName;
+        meta.updatedAt = new Date().toISOString();
+        await writeWorkbook(meta);
+        return meta;
+    });
+}
+/** Serialize mutations (and worktree writes) per id.
+ * `deleteWorkbook` and `renameWorkbook` take the same lock as `mutateWorkbook`,
+ * so a delete can never interleave with an in-flight save. The manager imports
+ * them from here rather than owning them, because the store must not depend on
+ * its callers. */
+const mutationQueues = new Map();
+const worktreeQueues = new Map();
+export async function withWorkbookQueue(id, task) {
+    const previous = mutationQueues.get(id) ?? Promise.resolve();
+    let release;
+    const current = new Promise(resolveRelease => { release = resolveRelease; });
+    mutationQueues.set(id, current);
+    await previous;
+    try {
+        return await task();
+    }
+    finally {
+        release();
+        if (mutationQueues.get(id) === current)
+            mutationQueues.delete(id);
+    }
+}
+export async function withWorktreeQueue(workbookId, worktreeId, task) {
+    const key = `${normalizeWorkbookId(workbookId)}:${normalizeWorktreeId(worktreeId)}`;
+    const previous = worktreeQueues.get(key) ?? Promise.resolve();
+    let release;
+    const current = new Promise(resolveRelease => { release = resolveRelease; });
+    worktreeQueues.set(key, current);
+    await previous;
+    try {
+        return await task();
+    }
+    finally {
+        release();
+        if (worktreeQueues.get(key) === current)
+            worktreeQueues.delete(key);
+    }
+}

package/lib/types/tools/arguments.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Reading tool arguments (docs/issue/0022 P3b).
+ *
+ * The Agent hands a tool an untyped record; every field has to be validated
+ * before it can become part of an operation. These are the conversions several
+ * tools share — the ones only one tool needs live in that tool.
+ */
+import { type WorkbookCellDeleteShift } from '../types.ts';
+export type ToolArguments = Record<string, unknown>;
+export declare function asToolArguments(value: unknown, label?: string): ToolArguments;
+/** Validate and normalize a workbook id argument. There is no implicit
+ * `main`: every Agent call must identify the workbook it intends to change. */
+export declare function workbookIdOf(raw: unknown): string;
+/** ISO timestamp helper. */
+export declare function now(): string;
+export declare function optionalIntent(value: unknown, name?: string): string | undefined;
+export declare function optionalAuditText(value: unknown, name: string, maxLength: number): string | undefined;
+export declare function optionalString(value: unknown): string | undefined;
+export declare function parseCount(value: unknown): number;
+/**
+ * `verifyHeader` defaults to true because comparing header labels is the only
+ * guard that catches a column order or rename mistake before rows are written.
+ * Only an explicit `false` relaxes it.
+ */
+export declare function parseHeaderVerification(value: unknown, label: string): boolean;
+export declare function parseCellDeleteShift(value: unknown): WorkbookCellDeleteShift;
+export declare function commandPayload(raw: ToolArguments): ToolArguments;
+/**
+ * Accept the vocabulary used by both the public Agent tool and the Univer
+ * facade. Older callers use `sheet`, while generated calls often use the
+ * persisted field name `sheetId` or the human-facing `sheetName`.
+ */
+export declare function sheetRefFromArguments(raw: ToolArguments, label?: string): string | undefined;
+/** Resolve an optional Agent sheet reference. A missing reference is safe only
+ * when the workbook has one sheet; otherwise returning the first sheet would
+ * make a write silently target the wrong tab. */
+export declare function sheetRefForSnapshot(snapshot: unknown, raw: ToolArguments, label: string): string;
+export declare function commandSheet(raw: ToolArguments, index: number, _optional?: boolean): string | undefined;
+export declare function commandIndex(raw: ToolArguments, index: number, field: 'index' | 'startRow' | 'startColumn'): number;
+export declare function parseNonEmptyString(value: unknown, label: string): string;

package/lib/types/tools/arguments.js

@@ -0,0 +1,130 @@
+/**
+ * Reading tool arguments (docs/issue/0022 P3b).
+ *
+ * The Agent hands a tool an untyped record; every field has to be validated
+ * before it can become part of an operation. These are the conversions several
+ * tools share — the ones only one tool needs live in that tool.
+ */
+import { SHEET_MAX_ROWS } from "../types.js";
+import { normalizeWorkbookId } from "../contract/ids.js";
+import { parseIndex } from "../request-params.js";
+export function asToolArguments(value, label = '参数') {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        throw new Error(label + '必须是对象');
+    return value;
+}
+/** Validate and normalize a workbook id argument. There is no implicit
+ * `main`: every Agent call must identify the workbook it intends to change. */
+export function workbookIdOf(raw) {
+    if (typeof raw !== 'string' || raw.trim().length === 0) {
+        throw new Error('必须明确指定 workbookId；请先调用 workbook_catalog(action=list) 获取工作簿 id');
+    }
+    return normalizeWorkbookId(raw);
+}
+/** ISO timestamp helper. */
+export function now() {
+    return new Date().toISOString();
+}
+export function optionalIntent(value, name = 'intent') {
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value !== 'string' || value.trim().length === 0 || value.trim().length > 280)
+        throw new Error(`${name} 必须是 1 到 280 字符的字符串`);
+    return value.trim();
+}
+export function optionalAuditText(value, name, maxLength) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value !== 'string' || value.trim().length === 0 || value.trim().length > maxLength)
+        throw new Error(`${name} 必须是 1 到 ${maxLength} 字符的字符串`);
+    return value.trim();
+}
+export function optionalString(value) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value !== 'string' || value.trim().length === 0)
+        throw new Error('opId 必须是非空字符串');
+    return value.trim();
+}
+export function parseCount(value) {
+    const count = parseIndex(value, 'count');
+    if (count < 1 || count > SHEET_MAX_ROWS)
+        throw new Error(`count 必须是 1 到 ${SHEET_MAX_ROWS} 之间的整数`);
+    return count;
+}
+/**
+ * `verifyHeader` defaults to true because comparing header labels is the only
+ * guard that catches a column order or rename mistake before rows are written.
+ * Only an explicit `false` relaxes it.
+ */
+export function parseHeaderVerification(value, label) {
+    if (value === undefined || value === null)
+        return true;
+    if (typeof value !== 'boolean')
+        throw new Error(`${label} 必须是布尔值`);
+    return value;
+}
+export function parseCellDeleteShift(value) {
+    if (value === undefined || value === null || value === '')
+        return 'clear';
+    if (value === 'clear' || value === 'left' || value === 'up')
+        return value;
+    throw new Error('shift 必须是 clear、left 或 up');
+}
+export function commandPayload(raw) {
+    const nested = raw.payload;
+    if (nested === undefined || nested === null)
+        return raw;
+    if (typeof nested !== 'object' || Array.isArray(nested))
+        throw new Error('command.payload 必须是对象');
+    // Permit callers to send the durable { type, payload } shape while keeping
+    // the documented flat command shape. Explicit top-level fields win.
+    return { ...nested, ...raw };
+}
+/**
+ * Accept the vocabulary used by both the public Agent tool and the Univer
+ * facade. Older callers use `sheet`, while generated calls often use the
+ * persisted field name `sheetId` or the human-facing `sheetName`.
+ */
+export function sheetRefFromArguments(raw, label = 'sheet') {
+    const candidates = ['sheet', 'sheetId', 'sheetName', 'sheet_id', 'sheet_name']
+        .filter(key => raw[key] !== undefined && raw[key] !== null && raw[key] !== '');
+    if (candidates.length === 0)
+        return undefined;
+    const refs = candidates.map(key => parseNonEmptyString(raw[key], `${label}.${key}`));
+    const first = refs[0];
+    if (refs.some(ref => ref !== first))
+        throw new Error(`${label}、sheetId、sheetName 只能指定同一个 sheet`);
+    return first;
+}
+/** Resolve an optional Agent sheet reference. A missing reference is safe only
+ * when the workbook has one sheet; otherwise returning the first sheet would
+ * make a write silently target the wrong tab. */
+export function sheetRefForSnapshot(snapshot, raw, label) {
+    const explicit = sheetRefFromArguments(raw, label);
+    if (explicit !== undefined)
+        return explicit;
+    const root = asToolArguments(snapshot, 'workbook snapshot');
+    const order = Array.isArray(root.sheetOrder) ? root.sheetOrder.filter(item => typeof item === 'string') : [];
+    if (order.length === 1 && order[0] !== undefined)
+        return order[0];
+    const sheets = typeof root.sheets === 'object' && root.sheets !== null && !Array.isArray(root.sheets)
+        ? Object.entries(root.sheets).map(([id, value]) => {
+            const sheet = value !== null && typeof value === 'object' && !Array.isArray(value) ? value : {};
+            return `${id}${typeof sheet.name === 'string' ? `（${sheet.name}）` : ''}`;
+        })
+        : [];
+    throw new Error(`${label} 缺少 sheet；当前工作簿有多个 sheet，请使用 sheetId 或 sheetName：${sheets.join('、')}`);
+}
+export function commandSheet(raw, index, _optional = false) {
+    return sheetRefFromArguments(raw, 'commands[' + index + '].sheet');
+}
+export function commandIndex(raw, index, field) {
+    const value = raw[field] ?? (field === 'startRow' ? raw.index : field === 'startColumn' ? raw.index : undefined);
+    return parseIndex(value, 'commands[' + index + '].' + field);
+}
+export function parseNonEmptyString(value, label) {
+    if (typeof value !== 'string' || value.trim().length === 0)
+        throw new Error(`${label} 必须是非空字符串`);
+    return value.trim();
+}

package/lib/types/tools/cells.d.ts

@@ -0,0 +1,50 @@
+import { type SheetColumn, type SheetColumnType, type WorkbookCellUpdate, type WorkbookOperationPayload, type WorkbookRange } from '../types.ts';
+import { type ToolArguments } from './arguments.ts';
+export declare function parseCells(value: unknown): WorkbookCellUpdate[];
+/**
+ * Resolve `cells[].valueFromFile` into a literal value (docs/issue/0011 I4 / T7).
+ *
+ * Long text had to be inlined into the tool call, and the same SQL was retyped
+ * into every workbook that needed it. A cell may now name a local text file
+ * instead. The content is read here and handed to the ordinary `parseCells`
+ * validation, so nothing bypasses the existing cell limits.
+ */
+export declare function resolveCellFileValues(value: unknown[], label: string): Promise<unknown[]>;
+/**
+ * Resolve the target range of a value matrix.
+ *
+ * The matrix size is unambiguous, so it is the authority: `range` only needs
+ * to anchor the write, and a `range` whose declared end disagrees with
+ * `values` is corrected and reported as a warning instead of failing a large
+ * batch. End coordinates are inclusive, which the tool description now states.
+ */
+export declare function parseValueRange(value: unknown, matrix: unknown[][], label: string, warnings?: string[]): WorkbookRange;
+export declare function parseApiValues(matrix: unknown[][], range: WorkbookRange): WorkbookCellUpdate[];
+/** A single cell of long text (typically a SQL body) read from a local file. */
+export declare const TEXT_CELL_MAX_BYTES: number;
+export declare function parseFreeze(value: unknown): NonNullable<WorkbookOperationPayload['freeze']>;
+export declare function parseSort(value: unknown): NonNullable<WorkbookOperationPayload['sort']>;
+export interface ValidatedSheet {
+    name?: string;
+    columns: SheetColumn[];
+    rows: Array<Record<string, unknown>>;
+}
+export declare function cellValue(type: SheetColumnType, value: unknown): number | string | boolean;
+/** Validate one sheet argument; throws a model-facing message on bad input. */
+export declare function validateSheet(args: {
+    name: unknown;
+    columns?: unknown;
+    rows: unknown;
+}): ValidatedSheet;
+export declare function chunkRows(rows: Array<Record<string, unknown>>, size: number): Array<Array<Record<string, unknown>>>;
+export declare function dimensionRange(index: number, dimension: 'row' | 'column'): WorkbookRange;
+/**
+ * Row/column structural commands accept either an explicit `range` (matching
+ * the documented command vocabulary) or the older `index`/`startRow` +
+ * `count` pair. Missing position arguments report the full accepted contract
+ * instead of the single `startRow` field the old implementation demanded.
+ */
+export declare function dimensionCommandRange(raw: ToolArguments, index: number, dimension: 'row' | 'column'): WorkbookRange;
+export declare function parseFiniteNumber(value: unknown, label: string): number;
+export declare function parseHyperlink(value: unknown): string;
+export declare function parseHyperlinkLabel(value: unknown): string;