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

package/lib/types/http/assets-routes.js

@@ -0,0 +1,169 @@
+/**
+ * Static plugin assets served on demand (docs/issue/0022 P3).
+ *
+ * The Univer engine chunk, the two xlsx workers and the standalone workbook
+ * page are all classic scripts or worker entry points the browser fetches after
+ * boot, so they are served from here rather than inlined into the client bundle.
+ * `univer-api.json` is the catalogue the Agent reads through its tool.
+ */
+import { createHash } from 'node:crypto';
+import { existsSync } from 'node:fs';
+import { readFile, stat } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { guardDataSheetRequest } from "./routes.js";
+/**
+ * The plugin directory, found by walking up to the `package.json` that owns
+ * this file.
+ *
+ * It used to be a pair of `new URL('../../lib/...', import.meta.url)` candidates
+ * because the path depth differs between `src/` and the emitted `lib/types/`,
+ * which meant every file move silently changed what those URLs pointed at. The
+ * walk is depth-independent, so moving this module cannot break it.
+ */
+function pluginRoot() {
+    let directory = dirname(fileURLToPath(import.meta.url));
+    for (let depth = 0; depth < 8; depth += 1) {
+        if (existsSync(join(directory, 'package.json')))
+            return directory;
+        const parent = dirname(directory);
+        if (parent === directory)
+            break;
+        directory = parent;
+    }
+    return dirname(fileURLToPath(import.meta.url));
+}
+/** Absolute path of one build artifact under `lib/`. */
+const artifact = (name) => join(pluginRoot(), 'lib', name);
+/** Last read per artifact name. The engine chunk is 13MB and changes only on rebuild. */
+const residentArtifacts = new Map();
+/**
+ * Read one `lib/` artifact, reusing the last read while the file is unchanged.
+ *
+ * The engine chunk used to be re-read from disk on every request, which was the
+ * only way to notice a rebuild. The `mtimeMs`/`size` identity notices the same
+ * rebuild without the disk read, and it is what lets the route answer the
+ * content-hash check below without hashing 13MB per request.
+ *
+ * @param name - file name under `lib/`.
+ * @returns the current bytes and content hash.
+ */
+async function readArtifact(name) {
+    const path = artifact(name);
+    const info = await stat(path);
+    const identity = `${info.mtimeMs}:${info.size}`;
+    const resident = residentArtifacts.get(name);
+    if (resident !== undefined && resident.identity === identity)
+        return resident;
+    const bytes = await readFile(path);
+    const next = { identity, bytes, hash: createHash('sha256').update(bytes).digest('hex').slice(0, 12) };
+    residentArtifacts.set(name, next);
+    return next;
+}
+/** Every static route this plugin serves. */
+export function assetRoutes() {
+    const routes = [];
+    routes.push({
+        kind: 'exact',
+        path: '/data-sheet/univer-client.js',
+        handler: async (req, res) => {
+            if (!guardDataSheetRequest(req, res))
+                return;
+            try {
+                const chunk = await readArtifact('univer-client.js');
+                // The loader asks for this file with its content hash in `?v=`. An exact
+                // match means the bytes cannot have changed, so the browser may keep them
+                // for a year and never ask again — which is the point: the chunk is 13MB
+                // and the sheet is opened in a fresh page constantly.
+                //
+                // Anything else — no `?v=` at all (the `/api/data-sheet?path=` transport mode
+                // drops the query), or a hash from a build that has since been replaced —
+                // is served `no-store`. A stale URL must never be able to pin different
+                // bytes, and that is exactly the failure the old unconditional `no-store`
+                // was there to prevent.
+                const requested = new URL(req.url ?? '/', 'http://x').searchParams.get('v');
+                const immutable = requested !== null && requested === chunk.hash;
+                res.writeHead(200, {
+                    'content-type': 'text/javascript; charset=utf-8',
+                    'cache-control': immutable ? 'public, max-age=31536000, immutable' : 'no-store, must-revalidate',
+                });
+                if (req.method === 'HEAD') {
+                    res.end();
+                    return;
+                }
+                res.end(chunk.bytes);
+            }
+            catch {
+                res.writeHead(404);
+                res.end();
+            }
+        },
+    });
+    // XLSX/CSV encoding is loaded only when the user exports. Keeping it in a
+    // worker prevents SheetJS serialization from blocking the Univer canvas.
+    routes.push({
+        kind: 'exact',
+        path: '/data-sheet/xlsx-export-worker.js',
+        handler: async (_req, res) => {
+            if (!guardDataSheetRequest(_req, res))
+                return;
+            try {
+                const body = await readFile(artifact('xlsx-export-worker.js'));
+                res.writeHead(200, {
+                    'content-type': 'text/javascript; charset=utf-8',
+                    'cache-control': 'no-cache',
+                });
+                res.end(body);
+            }
+            catch {
+                res.writeHead(404);
+                res.end();
+            }
+        },
+    });
+    routes.push({
+        kind: 'exact',
+        path: '/data-sheet/xlsx-import-worker.js',
+        handler: async (_req, res) => {
+            if (!guardDataSheetRequest(_req, res))
+                return;
+            try {
+                const body = await readFile(artifact('xlsx-import-worker.js'));
+                res.writeHead(200, {
+                    'content-type': 'text/javascript; charset=utf-8',
+                    'cache-control': 'no-cache',
+                });
+                res.end(body);
+            }
+            catch {
+                res.writeHead(404);
+                res.end();
+            }
+        },
+    });
+    // Standalone client bundle for the optional full-browser workbook page.
+    routes.push({
+        kind: 'exact',
+        path: '/data-sheet/workbook-page.js',
+        handler: async (_req, res) => {
+            if (!guardDataSheetRequest(_req, res))
+                return;
+            try {
+                const body = await readFile(artifact('workbook-page.js'));
+                res.writeHead(200, {
+                    'content-type': 'text/javascript; charset=utf-8',
+                    'cache-control': 'no-cache',
+                });
+                res.end(body);
+            }
+            catch {
+                res.writeHead(404);
+                res.end();
+            }
+        },
+    });
+    // Workbook catalog for the browser picker. Workbook content stays behind
+    // the per-workbook snapshot endpoint; this route returns names and sheet
+    // summaries and accepts the small lifecycle mutations used by the picker.
+    return routes;
+}

package/lib/types/http/collaboration.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The live collaboration stream (docs/issue/0022 P3).
+ *
+ * A server-sent event stream plus the presence beacon. This is a subscription
+ * protocol rather than request/response — the response stays open until the
+ * client goes away — which is why it is a module of its own.
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { type WorkbookRoute } from './routes.ts';
+export declare function handleCollaborationRoute(route: WorkbookRoute, req: IncomingMessage, res: ServerResponse, url: URL): Promise<boolean>;

package/lib/types/http/collaboration.js

@@ -0,0 +1,154 @@
+import { DataSheetError } from "../errors.js";
+import { publishWorkbookPresence, subscribeWorkbookCollaboration, subscribeWorkbookPresence } from "../collaboration-hub.js";
+import { readWorkbook } from "../workbook-manager.js";
+import { parseRevision, readJsonBody, requireDataSheetSession, writeOperationError } from "./routes.js";
+export async function handleCollaborationRoute(route, req, res, url) {
+    const id = route.id;
+    if (route.kind === 'presence' && req.method === 'POST') {
+        const sessionId = requireDataSheetSession(req, res, url);
+        if (sessionId === null)
+            return true;
+        let body;
+        try {
+            body = await readJsonBody(req);
+        }
+        catch (error) {
+            writeOperationError(res, error);
+            return true;
+        }
+        const kind = body.kind;
+        if (kind !== 'selection' && kind !== 'editing' && kind !== 'active-sheet') {
+            writeOperationError(res, new DataSheetError('VALIDATION_ERROR', 'presence.kind 必须是 selection、editing 或 active-sheet'));
+            return true;
+        }
+        const payload = body.payload;
+        if (typeof payload !== 'object' || payload === null || Array.isArray(payload)) {
+            writeOperationError(res, new DataSheetError('VALIDATION_ERROR', 'presence.payload 必须是对象'));
+            return true;
+        }
+        if (JSON.stringify(payload).length > 8192) {
+            writeOperationError(res, new DataSheetError('PAYLOAD_TOO_LARGE', 'presence.payload 不能超过 8 KiB', 413));
+            return true;
+        }
+        publishWorkbookPresence({ workbookId: id, sessionId, actor: 'user', kind, payload: payload, timestamp: new Date().toISOString() });
+        res.writeHead(202, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' });
+        res.end(JSON.stringify({ ok: true, workbookId: id }));
+        return true;
+    }
+    if (route.kind === 'collaboration' && req.method === 'GET') {
+        const sessionId = requireDataSheetSession(req, res, url);
+        if (sessionId === null)
+            return true;
+        const initialMeta = await readWorkbook(id);
+        if (initialMeta === null) {
+            res.writeHead(404);
+            res.end();
+            return true;
+        }
+        const after = parseRevision(url.searchParams.get('after'));
+        const operations = (initialMeta.operations ?? []).filter(operation => operation.revision > after);
+        const currentRevision = initialMeta.revision ?? 0;
+        const oldestRevision = operations[0]?.revision ?? currentRevision;
+        const requiresSnapshot = after < oldestRevision - 1;
+        const snapshot = requiresSnapshot
+            ? initialMeta.snapshot
+            : undefined;
+        const pendingEvents = [];
+        const pendingPresence = [];
+        let ready = false;
+        let closed = false;
+        const pendingWrites = [];
+        const flushWrites = () => {
+            while (!closed && pendingWrites.length > 0) {
+                const frame = pendingWrites.shift();
+                if (!res.write(frame))
+                    break;
+            }
+        };
+        const writeOperationEvent = (operation) => {
+            if (closed)
+                return;
+            const frame = `id: ${operation.revision}\nevent: operation\ndata: ${JSON.stringify({ workbookId: id, operation })}\n\n`;
+            if (pendingWrites.length > 0 || !res.write(frame)) {
+                if (pendingWrites.length >= 100) {
+                    res.destroy();
+                    return;
+                }
+                pendingWrites.push(frame);
+            }
+        };
+        const writePresenceEvent = (presence) => {
+            if (closed || presence.sessionId === sessionId)
+                return;
+            const frame = `id: ${Date.parse(presence.timestamp) || Date.now()}\nevent: presence\ndata: ${JSON.stringify({ workbookId: id, presence })}\n\n`;
+            if (pendingWrites.length > 0 || !res.write(frame)) {
+                if (pendingWrites.length >= 100) {
+                    res.destroy();
+                    return;
+                }
+                pendingWrites.push(frame);
+            }
+        };
+        let unsubscribe;
+        let unsubscribePresence;
+        try {
+            unsubscribe = subscribeWorkbookCollaboration(id, event => {
+                if (closed)
+                    return;
+                if (!ready) {
+                    pendingEvents.push(event);
+                    return;
+                }
+                writeOperationEvent(event.operation);
+            });
+            unsubscribePresence = subscribeWorkbookPresence(id, event => {
+                if (closed || event.presence.sessionId === sessionId)
+                    return;
+                if (!ready)
+                    pendingPresence.push(event);
+                else
+                    writePresenceEvent(event.presence);
+            });
+        }
+        catch (error) {
+            res.writeHead(429, { 'content-type': 'application/json; charset=utf-8', 'retry-after': '5' });
+            res.end(JSON.stringify({ ok: false, error: error instanceof Error ? error.message : String(error) }));
+            return true;
+        }
+        let heartbeat;
+        res.on('drain', flushWrites);
+        res.once('close', () => {
+            closed = true;
+            if (heartbeat !== undefined)
+                clearInterval(heartbeat);
+            unsubscribe?.();
+            unsubscribePresence?.();
+        });
+        heartbeat = setInterval(() => {
+            if (!closed)
+                res.write(': heartbeat\n\n');
+        }, 15000);
+        res.writeHead(200, {
+            'content-type': 'text/event-stream; charset=utf-8',
+            'cache-control': 'no-cache, no-transform',
+            connection: 'keep-alive',
+        });
+        res.write(`event: ready\ndata: ${JSON.stringify({
+            workbookId: id,
+            revision: currentRevision,
+            operations: requiresSnapshot ? [] : operations,
+            requiresSnapshot,
+            ...(snapshot === undefined ? {} : { snapshot }),
+        })}\n\n`);
+        ready = true;
+        for (const event of pendingEvents) {
+            if (event.operation.revision > currentRevision)
+                writeOperationEvent(event.operation);
+        }
+        for (const event of pendingPresence)
+            writePresenceEvent(event.presence);
+        await new Promise(resolve => res.once('close', resolve));
+        return true;
+    }
+    return false;
+}

package/lib/types/http/history.d.ts

@@ -0,0 +1,15 @@
+/**
+ * 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 WorkbookRoute } from './routes.ts';
+export declare function handleHistoryRoute(route: WorkbookRoute, req: IncomingMessage, res: ServerResponse, url: URL): Promise<boolean>;

package/lib/types/http/history.js

@@ -0,0 +1,134 @@
+import { DataSheetError } from "../errors.js";
+import { diffReachedLimit, diffWorkbookSnapshots } from "../version/diff.js";
+import { parseRevision } from "./routes.js";
+import { historyVersionsFromOperations } from "../version/grouping.js";
+import { activeHistoryRevisions, canReplayHistoryRevision, checkpointHasher, toVersionRecords } from "../version/records.js";
+import { settleIdleUserVersions } from "../version/session.js";
+import { readWorkbook, readWorkbookAtRevision, readWorkbookAtStep, readStepChanges } from "../workbook-manager.js";
+import { writeOperationError } from "./routes.js";
+import { operationSummary } from "../contract/operations.js";
+export async function handleHistoryRoute(route, req, res, url) {
+    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?.step,
+                stepCount: historical?.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) => 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/lib/types/http/project-files.d.ts

@@ -0,0 +1,79 @@
+import type { Context } from '@deepseek-ai/cordis';
+import { type LegacyRoute } from './routes.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[];
+}
+/**
+ * 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 declare function safeRelativeDirectory(raw: string): string;
+/**
+ * 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 declare function listProjectFiles(root: string, relativeDirectory: string): Promise<ProjectFileListing>;
+/** Largest file the chooser will hand back; matches the client's own import cap. */
+export declare const MAX_PICKED_BYTES: number;
+/**
+ * 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 declare function readProjectFile(root: string, relativePath: string, maxBytes?: number): Promise<{
+    name: string;
+    bytes: Buffer;
+}>;
+/**
+ * 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 declare function projectFiles(project: string | undefined, relativeDirectory: string): Promise<ProjectFileListing>;
+/**
+ * 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 declare function projectFileRoutes(ctx: Context): LegacyRoute[];