@chengxianglibra/dsh-data-analysis 0.1.1 → 0.2.0

package/lib/presentation/contracts/interaction.js

@@ -0,0 +1,62 @@
+export function defaultSelection(interaction) {
+    return Object.fromEntries(interaction.filters.map((filter) => [filter.id, filter.allOptionId]));
+}
+export function selectedSlice(interaction, selection) {
+    const slice = interaction.slices.find((slice) => interaction.filters.every((filter) => Object.hasOwn(selection, filter.id) && slice.selection[filter.id] === selection[filter.id]));
+    if (!slice)
+        throw new Error('Unknown presentation filter combination.');
+    return slice;
+}
+export function interactionRows(interaction, selection, block) {
+    if (!interaction?.blockIds.includes(block.id) || !('datasetId' in block))
+        return undefined;
+    const binding = selectedSlice(interaction, selection).datasets.find((entry) => entry.datasetId === block.datasetId);
+    if (!binding)
+        throw new Error('Missing presentation slice binding.');
+    return binding.rowIndices;
+}
+export function filterSummary(interaction, selection) {
+    return interaction.filters
+        .map((filter) => {
+        const option = filter.options.find((option) => option.id === selection[filter.id]);
+        if (!option)
+            throw new Error('Unknown presentation filter option.');
+        return `${filter.label}：${option.label}`;
+    })
+        .join(' · ');
+}
+/** Preserve the authored before / interactive / after boundary during host edits. */
+export function blockRegion(document, id) {
+    if (!document.interaction)
+        return 0;
+    if (document.interaction.blockIds.includes(id))
+        return 1;
+    return document.blocks.findIndex((block) => block.id === id) <
+        document.blocks.findIndex((block) => block.id === document.interaction.blockIds[0])
+        ? 0
+        : 2;
+}
+export function editedInteraction(document, blocks) {
+    if (!document.interaction)
+        return undefined;
+    const original = document.interaction;
+    const targets = blocks.filter((block) => original.blockIds.includes(block.id));
+    if (!targets.length)
+        return undefined;
+    const datasets = new Set(targets.flatMap((block) => 'datasetId' in block
+        ? [
+            block.datasetId,
+            ...(block.kind === 'chart'
+                ? (block.preparedViews ?? []).map((view) => view.datasetId)
+                : []),
+        ]
+        : []));
+    return {
+        ...original,
+        blockIds: targets.map((block) => block.id),
+        slices: original.slices.map((slice) => ({
+            ...slice,
+            datasets: slice.datasets.filter((entry) => datasets.has(entry.datasetId)),
+        })),
+    };
+}

package/lib/presentation/contracts/types.js

@@ -0,0 +1,15 @@
+export const PRESENTATION_SCHEMA_VERSION = 3;
+export const PRESENTATION_BUDGETS = {
+    documentBytes: 4 * 1024 * 1024,
+    draftBytes: 256 * 1024,
+    datasetBytes: 2 * 1024 * 1024,
+    htmlBytes: 8 * 1024 * 1024,
+    datasets: 16,
+    columns: 64,
+    rows: 5_000,
+    cells: 100_000,
+    sources: 64,
+    codeSnippets: 32,
+    blocks: 64,
+    text: 32_768,
+};

package/lib/presentation/contracts/values.js

@@ -0,0 +1,28 @@
+export class PresentationContractError extends Error {
+    code;
+    path;
+    hint;
+    reason;
+    constructor(code, path, message, hint = 'Correct the value at this path.') {
+        super(`${path || '/'}: ${message}`);
+        this.name = 'PresentationContractError';
+        this.reason = message;
+        this.code = code;
+        this.path = path;
+        this.hint = hint;
+    }
+}
+export function chartNumber(value, column, mode, path = '') {
+    if (value === null)
+        return null;
+    if (!['float64', 'int64', 'decimal'].includes(column.type))
+        throw new PresentationContractError('invalid_value', path, 'Chart series must be numeric.');
+    if (mode === 'exact' &&
+        (column.type === 'decimal' || (column.type === 'int64' && !Number.isSafeInteger(Number(value))))) {
+        throw new PresentationContractError('numeric_precision', path, 'Exact chart encoding cannot represent this value.', 'Set numericMode to approximate explicitly, or show the exact value in a table.');
+    }
+    const number = Number(value);
+    if (!Number.isFinite(number))
+        throw new PresentationContractError('numeric_precision', path, 'Chart encoding must remain finite.');
+    return number;
+}

package/lib/presentation/delivery.js

@@ -0,0 +1,71 @@
+import { finishCleanup, PendingTasks } from "../lifecycle.js";
+import { MARIVO_PRESENT_TOOL_NAME, MARIVO_PRESENTATION_DELIVERY_KIND, parsePresentationDelivery, } from "./receipt.js";
+/** Persist the same envelope on nested Code dispatch even when code discards the return value. */
+export function installMarivoPresentationCodeDelivery(ctx) {
+    const tasks = new PendingTasks();
+    let active = true;
+    const pending = new Map();
+    const stopResult = ctx.on('tools/result', (exec, result) => {
+        if (!active)
+            return;
+        if (exec.name !== MARIVO_PRESENT_TOOL_NAME || exec.parent === undefined || result.isError)
+            return;
+        try {
+            const value = result.value;
+            const delivery = parsePresentationDelivery(JSON.parse(value.deliveryJson));
+            if (delivery.dshSessionId !== String(exec.agent?.session.id))
+                return;
+            pending.set(String(exec.callId), { rootCallId: String(exec.rootCallId), delivery });
+            // Bounded transient dispatch rendezvous; receipts remain in Host events, never this map.
+            if (pending.size > 256)
+                pending.delete(pending.keys().next().value);
+        }
+        catch {
+            /* Invalid output cannot create a success card. */
+        }
+    });
+    let stopLog;
+    try {
+        stopLog = ctx.on('tools/ptc-dispatch-log', (dispatch, next) => tasks.track((async () => {
+            const content = await next();
+            if (!active)
+                return content;
+            if (dispatch.name !== MARIVO_PRESENT_TOOL_NAME)
+                return content;
+            const key = String(dispatch.subCallId);
+            const item = pending.get(key);
+            pending.delete(key);
+            if (dispatch.isError ||
+                !item ||
+                item.delivery.dshSessionId !== String(dispatch.agent?.session.id) ||
+                item.rootCallId !== String(dispatch.exec.rootCallId))
+                return content;
+            const root = [...(dispatch.agent?.session.snapshotEvents() ?? [])]
+                .reverse()
+                .find((event) => event.type === 'tool/call' && String(event.data.callId) === item.rootCallId);
+            if (root?.type !== 'tool/call' || root.data.turn !== item.delivery.turn)
+                return content;
+            return [
+                ...content,
+                {
+                    type: MARIVO_PRESENTATION_DELIVERY_KIND,
+                    delivery: item.delivery,
+                },
+            ];
+        })()), { prepend: true });
+    }
+    catch (error) {
+        active = false;
+        void finishCleanup([stopResult, () => tasks.drain()]);
+        throw error;
+    }
+    let closing;
+    return () => {
+        if (closing)
+            return closing;
+        active = false;
+        closing = finishCleanup([stopLog, stopResult, () => tasks.drain()]);
+        pending.clear();
+        return closing;
+    };
+}

package/lib/presentation/export-html.js

@@ -0,0 +1,214 @@
+import { randomUUID } from 'node:crypto';
+import { constants } from 'node:fs';
+import { link, lstat, mkdir, open, realpath, unlink } from 'node:fs/promises';
+import path from 'node:path';
+import { defineTool } from '@deepseek-ai/dsh-tools';
+import { registerMarivoTool } from "../tool-lifecycle.js";
+import { readReceiptAsset } from "./asset.js";
+import { parsePresentationBuildId } from "./contracts/index.js";
+import { readReportHistory } from "./reports.js";
+export const MARIVO_EXPORT_HTML_TOOL_NAME = 'marivo_export_html';
+export function parseHtmlOutputPath(value) {
+    if (typeof value !== 'string' ||
+        !value ||
+        value.length > 4096 ||
+        value.includes('\\') ||
+        value.includes('\0') ||
+        path.isAbsolute(value) ||
+        !value.endsWith('.html'))
+        throw new Error('invalid-html-output-path');
+    const segments = value.split('/');
+    if (segments.some((part) => !part || part === '.' || part === '..') ||
+        segments[0].toLowerCase() === '.dsh-data-analysis')
+        throw new Error('invalid-html-output-path');
+    return value;
+}
+/** Workspace-local hard-link publication is atomic and never replaces an existing target. */
+async function writeHtml(root, relative, bytes, assertOwner) {
+    const parents = [root];
+    const identities = [];
+    const inspect = async (filename) => {
+        const stat = await lstat(filename);
+        if (!stat.isDirectory() || stat.isSymbolicLink() || (await realpath(filename)) !== filename)
+            throw new Error('html-output-directory-mismatch');
+        return stat;
+    };
+    const check = async () => {
+        await assertOwner();
+        for (const [index, directory] of parents.entries()) {
+            const stat = await inspect(directory);
+            if (stat.dev !== identities[index].dev || stat.ino !== identities[index].ino)
+                throw new Error('html-output-directory-changed');
+        }
+    };
+    identities.push(await inspect(root));
+    for (const part of relative.split('/').slice(0, -1)) {
+        await check();
+        const directory = path.join(parents.at(-1), part);
+        try {
+            await mkdir(directory, { mode: 0o700 });
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST')
+                throw error;
+        }
+        identities.push(await inspect(directory));
+        parents.push(directory);
+    }
+    await check();
+    const target = path.join(root, relative);
+    // Stage at the highest ancestor on the destination filesystem, outside movable
+    // output subdirectories where possible, without introducing cross-device links.
+    const stagingParent = parents[identities.findIndex((identity) => identity.dev === identities.at(-1).dev)];
+    const temporary = path.join(stagingParent, `.html-export-${randomUUID()}.tmp`);
+    const handle = await open(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
+    const owned = await handle.stat();
+    let linked = false;
+    const removeOwned = async (filename) => {
+        try {
+            const stat = await lstat(filename);
+            if (stat.dev === owned.dev && stat.ino === owned.ino)
+                await unlink(filename);
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+    };
+    try {
+        await check();
+        await handle.writeFile(bytes);
+        await handle.sync();
+        await check();
+        await link(temporary, target);
+        linked = true;
+        await check();
+        const stat = await lstat(target);
+        if (stat.dev !== owned.dev || stat.ino !== owned.ino || stat.size !== bytes.length)
+            throw new Error('html-output-changed');
+        await removeOwned(temporary);
+        await check();
+        return target;
+    }
+    catch (error) {
+        // Paths may have moved or been replaced. The open handle still owns the exact inode,
+        // including any published hard link: erase failed output without following new paths.
+        const failures = [error];
+        try {
+            await handle.truncate(0);
+            await handle.sync();
+        }
+        catch (cleanupError) {
+            failures.push(cleanupError);
+        }
+        if (linked) {
+            try {
+                await removeOwned(target);
+            }
+            catch (cleanupError) {
+                failures.push(cleanupError);
+            }
+        }
+        if (failures.length > 1)
+            throw new AggregateError(failures, 'html-export-cleanup-failed');
+        throw error;
+    }
+    finally {
+        try {
+            await removeOwned(temporary);
+        }
+        finally {
+            await handle.close();
+        }
+    }
+}
+export function createMarivoExportHtmlTool(source, session) {
+    return defineTool({
+        name: MARIVO_EXPORT_HTML_TOOL_NAME,
+        description: 'Export a saved complete report as self-contained offline HTML only when requested. Uses the current Session Workspace, without analysis, Python, publication, new Builds or unsaved reader state. Specify build_id for an exact version; otherwise freezes current at call start. output_path must be a new Workspace-relative .html file; existing files are never overwritten. Returns file metadata, not HTML content. After success, call native present({files:[{path: result.path, description: "Offline HTML report"}]}) to deliver the file before your final response.',
+        parameters: {
+            report_id: {
+                type: 'string',
+                required: true,
+                description: 'Saved Report ID from its receipt.',
+            },
+            build_id: { type: 'string', description: 'Exact saved Build ID; omit to export current.' },
+            output_path: {
+                type: 'string',
+                required: true,
+                description: 'New Workspace-relative .html path, e.g. reports/analysis.html. Parent directories may be created.',
+            },
+        },
+        output: {
+            schema: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    workspace_id: { type: 'string', required: true },
+                    report_id: { type: 'string', required: true },
+                    build_id: { type: 'string', required: true },
+                    path: { type: 'string', required: true },
+                    mime_type: { type: 'string', required: true },
+                    bytes: { type: 'number', required: true },
+                    sha256: { type: 'string', required: true },
+                },
+            },
+            render: (_args, value) => [{ type: 'text', text: JSON.stringify(value) }],
+            presentationMeta: (_args, value) => value,
+        },
+        presentCall(args) {
+            return {
+                card: 'generic',
+                kind: 'edit',
+                title: 'Export report HTML',
+                locations: [{ path: args.output_path }],
+            };
+        },
+        timeoutMs: 120_000,
+        async execute(args, exec) {
+            const reportId = parsePresentationBuildId(args.report_id, '/report_id');
+            const buildId = args.build_id === undefined
+                ? undefined
+                : parsePresentationBuildId(args.build_id, '/build_id');
+            const relative = parseHtmlOutputPath(args.output_path);
+            const owner = exec.agent;
+            if (!owner || owner.session !== session)
+                throw new Error('presentation-session-mismatch');
+            exec.signal.throwIfAborted();
+            const workspace = await source();
+            const root = path.resolve(workspace.path);
+            const check = async () => {
+                exec.signal.throwIfAborted();
+                if (owner.session !== session)
+                    throw new Error('presentation-session-mismatch');
+                const current = await source();
+                if (current.id !== workspace.id || path.resolve(current.path) !== root)
+                    throw new Error('presentation-workspace-changed');
+                exec.signal.throwIfAborted();
+            };
+            await check();
+            const history = await readReportHistory(root, workspace.id, reportId, exec.signal);
+            const receipt = buildId === undefined
+                ? history.versions[0].receipt
+                : history.versions.find((entry) => entry.receipt.buildId === buildId)?.receipt;
+            if (!receipt)
+                throw new Error('presentation-build-unavailable');
+            await check();
+            const asset = await readReceiptAsset(root, workspace.id, receipt, 'index.html', exec.signal);
+            await check();
+            const filename = await writeHtml(root, relative, asset.bytes, check);
+            return {
+                workspace_id: workspace.id,
+                report_id: reportId,
+                build_id: receipt.buildId,
+                path: filename,
+                mime_type: 'text/html',
+                bytes: asset.bytes.length,
+                sha256: asset.sha256,
+            };
+        },
+    });
+}
+export function registerMarivoExportHtmlTool(ctx, source, session) {
+    return registerMarivoTool(ctx, createMarivoExportHtmlTool(source, session));
+}

package/lib/presentation/files.js

@@ -0,0 +1,82 @@
+import { createHash } from 'node:crypto';
+import { constants } from 'node:fs';
+import { lstat, open, realpath } from 'node:fs/promises';
+import path from 'node:path';
+import { presentationAssetRelativePath } from "./contracts/asset-path.js";
+import { PRESENTATION_BUDGETS, parsePresentationBuildId, } from "./contracts/index.js";
+export function presentationReportPath(root, reportId) {
+    parsePresentationBuildId(reportId, '/reportId');
+    return path.join(root, '.dsh-data-analysis', 'presentations', reportId);
+}
+export function presentationAssetPath(root, reportId, buildId, asset) {
+    return path.join(root, presentationAssetRelativePath(reportId, buildId, asset));
+}
+export function presentationSha256(bytes) {
+    return createHash('sha256').update(bytes).digest('hex');
+}
+/** Bounded raw-byte reader with no symbolic links and stable directory/file identity. */
+export async function readPresentationAsset(workspaceRoot, reportId, buildId, asset, signal) {
+    const filename = presentationAssetPath(workspaceRoot, reportId, buildId, asset);
+    return readReportFile(workspaceRoot, filename, asset === 'presentation.json'
+        ? PRESENTATION_BUDGETS.documentBytes
+        : PRESENTATION_BUDGETS.htmlBytes, signal);
+}
+export async function readReportFile(workspaceRoot, filename, maximum, signal) {
+    signal?.throwIfAborted();
+    const root = await realpath(workspaceRoot);
+    if (root !== path.resolve(workspaceRoot) || !filename.startsWith(`${root}${path.sep}`))
+        throw new Error('asset-path-mismatch');
+    const parents = [root];
+    for (const segment of path.relative(root, path.dirname(filename)).split(path.sep)) {
+        if (!segment || segment === '..' || segment === '.')
+            throw new Error('asset-path-mismatch');
+        parents.push(path.join(parents.at(-1), segment));
+    }
+    const beforeParents = await Promise.all(parents.map((parent) => lstat(parent)));
+    if (beforeParents.some((stat) => !stat.isDirectory() || stat.isSymbolicLink()))
+        throw new Error('asset-path-mismatch');
+    if ((await realpath(filename)) !== filename)
+        throw new Error('asset-path-mismatch');
+    const file = await open(filename, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    try {
+        const before = await file.stat();
+        if (!before.isFile())
+            throw new Error('asset-not-file');
+        if (before.size > maximum)
+            throw new Error('asset-too-large');
+        // Allocate for the observed file, retaining one extra byte to detect growth.
+        const bytes = Buffer.alloc(before.size + 1);
+        let length = 0;
+        while (length < bytes.length) {
+            signal?.throwIfAborted();
+            const read = await file.read(bytes, length, bytes.length - length, null);
+            if (read.bytesRead === 0)
+                break;
+            length += read.bytesRead;
+        }
+        if (length > maximum)
+            throw new Error('asset-too-large');
+        const after = await file.stat();
+        const current = await lstat(filename);
+        const afterParents = await Promise.all(parents.map((parent) => lstat(parent)));
+        if (afterParents.some((stat, index) => !stat.isDirectory() ||
+            stat.isSymbolicLink() ||
+            stat.dev !== beforeParents[index].dev ||
+            stat.ino !== beforeParents[index].ino) ||
+            (await realpath(workspaceRoot)) !== root ||
+            (await realpath(filename)) !== filename)
+            throw new Error('asset-path-mismatch');
+        if (current.dev !== after.dev ||
+            current.ino !== after.ino ||
+            before.size !== after.size ||
+            before.mtimeMs !== after.mtimeMs ||
+            before.ctimeMs !== after.ctimeMs ||
+            length !== after.size)
+            throw new Error('asset-changed');
+        signal?.throwIfAborted();
+        return bytes.subarray(0, length);
+    }
+    finally {
+        await file.close();
+    }
+}

package/lib/presentation/index.js

@@ -0,0 +1,6 @@
+export * from "./contracts/index.js";
+export * from "./delivery.js";
+export * from "./projection/index.js";
+export * from "./receipt.js";
+export * from "./rpc.js";
+export * from "./tool.js";

package/lib/presentation/lint.js

@@ -0,0 +1,46 @@
+import { PRESENTATION_BUDGETS, PresentationContractError, parsePresentationDraft, parseTypedDataset, } from "./contracts/index.js";
+import { readWorkspaceJson } from "./projection/files.js";
+/** Static preflight only: never starts a Runtime or publishes presentation assets. */
+export async function lintPresentationDraft(workspaceRoot, draftPath) {
+    const diagnostics = [];
+    let checkedComputedDatasets = 0;
+    const record = (error) => {
+        if (!(error instanceof PresentationContractError))
+            throw error;
+        diagnostics.push({
+            code: error.code,
+            path: error.path,
+            message: error.message,
+            hint: error.hint,
+        });
+    };
+    try {
+        const draft = parsePresentationDraft(await readWorkspaceJson(workspaceRoot, draftPath, PRESENTATION_BUDGETS.draftBytes, '/draft_path'));
+        for (const [index, dataset] of draft.datasets.entries()) {
+            if (dataset.kind !== 'computed')
+                continue;
+            try {
+                const data = await readWorkspaceJson(workspaceRoot, dataset.path, PRESENTATION_BUDGETS.datasetBytes, `/datasets/${index}/path`);
+                parseTypedDataset(data, `/datasets/${index}/data`);
+                checkedComputedDatasets++;
+            }
+            catch (error) {
+                record(error);
+            }
+        }
+    }
+    catch (error) {
+        record(error);
+    }
+    return {
+        ok: diagnostics.length === 0,
+        scope: 'draft-structure-and-computed-data',
+        checkedComputedDatasets,
+        diagnostics,
+        deferredChecks: [
+            'artifact-availability-and-data',
+            'codeRefs',
+            'projected-document-and-rendering',
+        ],
+    };
+}

package/lib/presentation/projection/files.js

@@ -0,0 +1,85 @@
+import { constants } from 'node:fs';
+import { lstat, open, realpath } from 'node:fs/promises';
+import path from 'node:path';
+import { PresentationContractError } from "../contracts/index.js";
+function boundary(location) {
+    throw new PresentationContractError('file_boundary', location, 'Expected an unchanged regular file inside the bound Workspace without symbolic links.');
+}
+/** Read raw bytes under a strict budget before JSON parsing, including concurrent growth. */
+export async function readWorkspaceJson(workspaceRoot, relativePath, maximum, location, signal) {
+    signal?.throwIfAborted();
+    if (path.isAbsolute(relativePath) ||
+        relativePath.includes('\\') ||
+        relativePath.includes('\0') ||
+        relativePath.split('/').some((part) => !part || part === '.' || part === '..'))
+        boundary(location);
+    try {
+        const root = await realpath(workspaceRoot);
+        if (root !== path.resolve(workspaceRoot))
+            boundary(location);
+        const segments = relativePath.split('/');
+        const filename = path.join(root, ...segments);
+        const parents = [
+            root,
+            ...segments.slice(0, -1).map((_, index) => path.join(root, ...segments.slice(0, index + 1))),
+        ];
+        const beforeParents = await Promise.all(parents.map((parent) => lstat(parent)));
+        if (beforeParents.some((stat) => !stat.isDirectory() || stat.isSymbolicLink()))
+            boundary(location);
+        if ((await realpath(filename)) !== filename)
+            boundary(location);
+        if (!(await lstat(filename)).isFile())
+            boundary(location);
+        const file = await open(filename, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+        try {
+            const before = await file.stat();
+            if (!before.isFile())
+                boundary(location);
+            if (before.size > maximum)
+                throw new PresentationContractError('budget', location, 'Input file exceeds the presentation byte budget.');
+            const bytes = Buffer.alloc(maximum + 1);
+            let length = 0;
+            while (length < bytes.length) {
+                signal?.throwIfAborted();
+                const { bytesRead } = await file.read(bytes, length, bytes.length - length, null);
+                if (bytesRead === 0)
+                    break;
+                length += bytesRead;
+            }
+            if (length > maximum)
+                throw new PresentationContractError('budget', location, 'Input file exceeds the presentation byte budget.');
+            const after = await file.stat();
+            const current = await lstat(filename);
+            const afterParents = await Promise.all(parents.map((parent) => lstat(parent)));
+            if (afterParents.some((stat, index) => !stat.isDirectory() ||
+                stat.isSymbolicLink() ||
+                stat.dev !== beforeParents[index].dev ||
+                stat.ino !== beforeParents[index].ino) ||
+                (await realpath(workspaceRoot)) !== root ||
+                (await realpath(filename)) !== filename ||
+                current.dev !== after.dev ||
+                current.ino !== after.ino ||
+                before.size !== after.size ||
+                before.mtimeMs !== after.mtimeMs ||
+                before.ctimeMs !== after.ctimeMs ||
+                length !== after.size)
+                boundary(location);
+            signal?.throwIfAborted();
+            try {
+                return JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes.subarray(0, length)));
+            }
+            catch {
+                throw new PresentationContractError('invalid_json', location, 'Expected valid UTF-8 JSON.');
+            }
+        }
+        finally {
+            await file.close();
+        }
+    }
+    catch (error) {
+        signal?.throwIfAborted();
+        if (error instanceof PresentationContractError)
+            throw error;
+        boundary(location);
+    }
+}