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

package/lib/types/http/project-files.js

@@ -0,0 +1,206 @@
+/**
+ * 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 { projectFor, sessionIdOf } from "./project-scope.js";
+import { guardDataSheetRequest } from "./routes.js";
+import { projectStoragesDirectory, runInProject } from "../store/project.js";
+/** 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) {
+    // 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` 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, relativeDirectory) {
+    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 = [];
+    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, relativePath, maxBytes = MAX_PICKED_BYTES) {
+    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, relativeDirectory) {
+    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) {
+    /** The project this request belongs to, resolved once per request. */
+    const projectOf = (req, url) => projectFor(ctx, sessionIdOf(req.headers, 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/lib/types/http/project-scope.d.ts

@@ -0,0 +1,50 @@
+/**
+ * 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';
+/**
+ * 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 declare function sessionIdOf(headers: Record<string, unknown>, url: URL): string | 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 declare function projectFor(ctx: Context, sessionId: string | undefined): string | undefined;
+/**
+ * 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 declare function runForProject<T>(project: string | undefined, body: () => Promise<T>): Promise<T>;

package/lib/types/http/project-scope.js

@@ -0,0 +1,52 @@
+import { projectScopeOf, runInProject } from "../store/project.js";
+/**
+ * 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, url) {
+    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, sessionId) {
+    const scope = ctx;
+    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(project, body) {
+    return project === undefined ? body() : runInProject(project, body);
+}

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

@@ -0,0 +1,98 @@
+/**
+ * HTTP transport for the Datasheet plugin (docs/issue/0022 P3).
+ *
+ * This module does two things and nothing else: it adapts the plugin's routes to
+ * whichever carrier is running (the DSH Connection fetch carrier, or the
+ * Electron shell's webserver), and it decides which route a
+ * `/data-sheet/workbook/...` path is. The handlers live in the domain modules
+ * beside it, so a new endpoint means one case here and one block in a handler.
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { Context } from '@deepseek-ai/cordis';
+/**
+ * Structural view of the host webserver route API (no manifest dependency).
+ *
+ * Declared here rather than in the plugin body because this is where the cast
+ * that needs it lives: `registerConnectionRoutes` registers the same handlers
+ * with both carriers.
+ */
+interface WebServerLike {
+    register(route: {
+        kind: 'exact' | 'prefix';
+        path: string;
+        handler: (req: IncomingMessage, res: ServerResponse) => Promise<void>;
+    }): () => void;
+}
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        webServer: WebServerLike;
+    }
+}
+export interface LegacyRoute {
+    readonly kind: 'exact' | 'prefix';
+    readonly path: string;
+    readonly handler: (req: IncomingMessage, res: ServerResponse) => Promise<void>;
+}
+export interface LegacyResponse {
+    writeHead(status: number, headers?: Record<string, string>): void;
+    write(chunk: string | Uint8Array): boolean;
+    end(chunk?: string | Uint8Array): void;
+    once(event: 'close', listener: () => void): void;
+    on(event: 'drain', listener: () => void): void;
+    destroy(): void;
+}
+export declare function routeFor(routes: readonly LegacyRoute[], pathname: string): LegacyRoute | undefined;
+/** Adapt the HTTP handlers to the official Electron shell's Connection carrier. */
+export declare function dispatchConnectionRoute(routes: readonly LegacyRoute[], request: Request, prefix: string): Promise<Response>;
+export declare function registerConnectionRoutes(ctx: Context, routes: readonly LegacyRoute[], prefix: string): void;
+export declare function readJsonBody(req: IncomingMessage): Promise<Record<string, unknown>>;
+/**
+ * Keep plugin routes behind the same browser-origin fence as the Host API.
+ * Loopback is allowed by default; non-loopback authorities must be explicitly
+ * listed in DSH_TRUSTED_HOSTS or match the local listening address.
+ */
+export declare function guardDataSheetRequest(req: IncomingMessage, res: ServerResponse): boolean;
+/** Resolve the per-tab session used to scope isolated worktrees. EventSource
+ * cannot send custom headers, so collaboration clients may provide `session`
+ * as a query parameter; normal fetch clients use the header. */
+export declare function requireDataSheetSession(req: IncomingMessage, res: ServerResponse, url: URL): string | null;
+export declare function writeOperationError(res: ServerResponse, error: unknown): void;
+/**
+ * The `?after=` revision cursor.
+ *
+ * An absent (or blank) cursor means "from the beginning", which is a real value,
+ * not an error. Anything else has to parse — this used to swallow every failure
+ * into `0`, so `?after=abc` did not fail, it silently replayed the *entire*
+ * operation log at the asking client. A malformed cursor is now a 400 like any
+ * other bad parameter, which is what the surrounding handlers already do.
+ */
+export declare function parseRevision(value: string | null): number;
+/**
+ * One matched `/data-sheet/workbook/...` path.
+ *
+ * Matching lives here, in the transport module, and dispatch lives in the domain
+ * modules: a handler can be read without working out which regexes it owns, and
+ * a new endpoint cannot silently shadow an existing one — the order of the `if`s
+ * inside a single 600-line handler used to decide that.
+ */
+export type WorkbookRoute = {
+    kind: 'view' | 'snapshot' | 'changes' | 'collaboration' | 'history' | 'history-diff' | 'range' | 'presence' | 'operation' | 'proposals' | 'rollback' | 'worktrees';
+    id: string;
+} | {
+    kind: 'proposal-action';
+    id: string;
+    proposalId: string;
+    action: 'commit' | 'reject';
+} | {
+    kind: 'worktree' | 'worktree-operations' | 'worktree-diff';
+    id: string;
+    worktreeId: string;
+} | {
+    kind: 'worktree-action';
+    id: string;
+    worktreeId: string;
+    action: 'ready' | 'reopen' | 'merge' | 'discard';
+};
+/** Match one workbook path; null when nothing here claims it. */
+export declare function matchWorkbookRoute(pathname: string): WorkbookRoute | null;
+export {};