@chengxianglibra/dsh-data-analysis 0.1.2 → 0.2.1

package/lib/types/presentation/contracts/catalog.d.ts

@@ -0,0 +1,27 @@
+import { type PresentationReceipt } from './index.ts';
+export interface PublicationSource {
+    kind: 'agent' | 'reader';
+    sessionId: string | null;
+}
+export interface ReportVersion {
+    receipt: PresentationReceipt;
+    publishedAt: string | null;
+    source: PublicationSource | null;
+}
+export interface ReportHistory {
+    workspaceId: string;
+    reportId: string;
+    currentBuildId: string;
+    legacyHistoryUnavailable: boolean;
+    versions: ReportVersion[];
+}
+export interface ReportCatalog {
+    workspaceId: string;
+    reports: ReportVersion[];
+    unavailable: number;
+}
+export declare const REPORT_HISTORY_BYTES: number;
+export declare const REPORT_HISTORY_LIMIT = 4096;
+export declare function parseReportVersion(value: unknown): ReportVersion;
+export declare function parseReportHistory(value: unknown): ReportHistory;
+export declare function parseReportCatalog(value: unknown): ReportCatalog;

package/lib/types/presentation/contracts/charts.d.ts

@@ -1,12 +1,10 @@
 import { type ChartType, type ChartView, type TypedDataset } from './types.ts';
 export type { ChartBindings, ChartOptions, ChartType, ChartView } from './types.ts';
 export declare const CHART_TYPES: readonly ["line", "area", "stackedArea", "sparkline", "bar", "horizontalBar", "stackedBar", "stackedBar100", "horizontalStackedBar", "horizontalStackedBar100", "histogram", "boxPlot", "scatter", "heatmap", "pie", "leaderboard", "funnel", "waterfall"];
-export declare const CHART_LABELS: Record<ChartType, string>;
 /** Strictly validates one binding. A containing block handles id/kind/preparedViews. */
 export declare function parseChartViewShape(value: unknown, path?: string): asserts value is ChartView;
 /** Exact source columns, including every auxiliary field used by geometry or tooltip. */
 export declare function chartColumns(view: ChartView): string[];
-export declare function chartSeriesFields(view: ChartView): string[];
 /** Verifies supplied values only: never bins, ranks, accumulates, normalizes or sorts. */
 export declare function validateChartView(view: ChartView, dataset: TypedDataset, path?: string, dataPath?: string, rowIndices?: readonly number[]): void;
 /** Changes geometry only. Statistical views must be declared with prepared bindings. */

package/lib/types/presentation/contracts/types.d.ts

@@ -1,7 +1,7 @@
 /** Pure presentation data. No Marivo schema, Node runtime or Host imports. */
 import type { PythonCodeRef, PythonCodeSnippet } from '../../python-execution-contracts.ts';
 export type { PythonCodeRef, PythonCodeSnippet } from '../../python-execution-contracts.ts';
-export declare const PRESENTATION_SCHEMA_VERSION: 2;
+export declare const PRESENTATION_SCHEMA_VERSION: 3;
 export declare const PRESENTATION_BUDGETS: {
     readonly documentBytes: number;
     readonly draftBytes: number;
@@ -203,8 +203,10 @@ export interface PresentationInteraction {
     filters: PresentationFilter[];
     slices: PresentationSlice[];
 }
+export type PresentationLocale = 'zh-CN' | 'en-US';
 export interface PresentationDraft {
-    schemaVersion: 1;
+    schemaVersion: 2;
+    locale: PresentationLocale;
     title: string;
     datasets: DraftDataset[];
     sources: DeclaredSource[];
@@ -217,7 +219,8 @@ export interface PresentationDiagnostic {
     message: string;
 }
 export interface PresentationDocument {
-    schemaVersion: 2;
+    schemaVersion: 3;
+    locale: PresentationLocale;
     reportId: string;
     workspaceId: string;
     buildId: string;
@@ -247,6 +250,6 @@ export interface PresentationReceipt {
     summary: string;
     files: {
         document: PresentationFile<'presentation.json'>;
-        html: PresentationFile<'index.html'>;
+        html?: PresentationFile<'index.html'>;
     };
 }

package/lib/types/presentation/delivery.d.ts

@@ -1,3 +1,3 @@
 import type { Context } from '@deepseek-ai/cordis';
 /** Persist the same envelope on nested Code dispatch even when code discards the return value. */
-export declare function installMarivoPresentationCodeDelivery(ctx: Context): () => void;
+export declare function installMarivoPresentationCodeDelivery(ctx: Context): () => Promise<void>;

package/lib/types/presentation/export-html.d.ts

@@ -0,0 +1,13 @@
+import type { Context } from '@deepseek-ai/cordis';
+import type { Session } from '@deepseek-ai/dsh-session';
+export declare const MARIVO_EXPORT_HTML_TOOL_NAME = "marivo_export_html";
+export type ExportWorkspaceSource = () => {
+    id: string;
+    path: string;
+} | Promise<{
+    id: string;
+    path: string;
+}>;
+export declare function parseHtmlOutputPath(value: unknown): string;
+export declare function createMarivoExportHtmlTool(source: ExportWorkspaceSource, session: Session): import("@deepseek-ai/dsh-tools").ToolDefinition;
+export declare function registerMarivoExportHtmlTool(ctx: Context, source: ExportWorkspaceSource, session: Session): () => Promise<void>;

package/lib/types/presentation/reports.d.ts

@@ -1,5 +1,10 @@
+import { type PublicationSource, type ReportCatalog, type ReportHistory } from './contracts/catalog.ts';
 import { type PresentationDocument, type PresentationReceipt } from './contracts/index.ts';
 export declare function readReceiptDocument(root: string, receipt: PresentationReceipt, signal?: AbortSignal): Promise<PresentationDocument>;
+/** Current and its publication history become visible through one atomic rename. */
+export declare function readReportHistory(root: string, workspaceId: string, reportId: string, signal?: AbortSignal): Promise<ReportHistory>;
 export declare function resolvePresentation(root: string, workspaceId: string, reportId: string, signal?: AbortSignal): Promise<PresentationReceipt>;
+/** Enumerate only publication pointers, never completed-but-unpublished build directories. */
+export declare function listReports(root: string, workspaceId: string, signal?: AbortSignal): Promise<ReportCatalog>;
 /** The mutable pointer is the publication boundary; completed builds are never overwritten. */
-export declare function publishPresentation(root: string, document: PresentationDocument, expectedBuildId: string | null, assertOwner: () => Promise<void>, signal?: AbortSignal): Promise<PresentationReceipt>;
+export declare function publishPresentation(root: string, document: PresentationDocument, expectedBuildId: string | null, assertOwner: () => Promise<void>, signal?: AbortSignal, source?: PublicationSource | null): Promise<PresentationReceipt>;

package/lib/types/presentation/rpc.d.ts

@@ -7,8 +7,9 @@ export interface PresentationWorkspace {
 export type PresentationWorkspaceResolver = (sessionId: string) => PresentationWorkspace | undefined | Promise<PresentationWorkspace | undefined>;
 export declare class MarivoPresentationFileService {
     #private;
-    constructor(resolve: PresentationWorkspaceResolver);
-    close(): void;
+    constructor(resolve: PresentationWorkspaceResolver, resolveId?: PresentationWorkspaceResolver);
+    catalog(endpoint: 'reports/list' | 'reports/history', payload: unknown, caller?: AbortSignal): Promise<import("./contracts/catalog.ts").ReportHistory | import("./contracts/catalog.ts").ReportCatalog>;
+    close(): Promise<void>;
     report(endpoint: 'reports/resolve' | 'reports/save', payload: unknown, caller?: AbortSignal): Promise<import("./contracts/types.ts").PresentationReceipt>;
     read(payload: unknown, caller?: AbortSignal): Promise<{
         workspaceId: string;

package/lib/types/presentation/tool.d.ts

@@ -7,6 +7,6 @@ export interface PresentationBinding {
     projection: MarivoPresentationProjection;
 }
 export type PresentationBindingSource = () => PresentationBinding | Promise<PresentationBinding>;
-/** One call projects a draft, builds both assets, commits them, then emits the receipt. */
+/** One call projects a draft, builds the document, commits them, then emits the receipt. */
 export declare function createMarivoPresentTool(source: PresentationBindingSource, session: Session, lifecycleSignal?: AbortSignal): ToolDefinition;
-export declare function registerMarivoPresentTool(ctx: Context, source: PresentationBindingSource, session: Session): () => void;
+export declare function registerMarivoPresentTool(ctx: Context, source: PresentationBindingSource, session: Session): () => Promise<void>;

package/lib/types/report-publishing/adapters.d.ts

@@ -0,0 +1,6 @@
+import type { Context } from '@deepseek-ai/cordis';
+import type { HostConnectionHandle } from '@deepseek-ai/dsh-client-connection';
+import type { ReportPublishingService } from './service.ts';
+export declare const PUBLISHING_CHANNEL = "/dsh-report-publishing";
+export declare function registerPublishingCredentials(connection: HostConnectionHandle, service: ReportPublishingService, workspaceExists: (id: string) => boolean): () => Promise<void>;
+export declare function registerReportPublishTool(ctx: Context, service: ReportPublishingService, sessionId: string): () => Promise<void>;

package/lib/types/report-publishing/config.d.ts

@@ -0,0 +1,22 @@
+import { z } from 'zod';
+export declare const publishingConfigSchema: z.ZodObject<{
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    storage: z.ZodObject<{
+        name: z.ZodString;
+        protocol: z.ZodDefault<z.ZodLiteral<"s3">>;
+        endpoint: z.ZodString;
+        region: z.ZodString;
+        bucket: z.ZodString;
+        forcePathStyle: z.ZodDefault<z.ZodBoolean>;
+        accessKeyIdRef: z.ZodString;
+        secretAccessKeyRef: z.ZodString;
+        sessionTokenRef: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+    pathPrefix: z.ZodDefault<z.ZodString>;
+    publicBaseUrl: z.ZodString;
+}, z.core.$strict>;
+export type ReportPublishingConfig = z.input<typeof publishingConfigSchema> | {
+    enabled?: false;
+};
+export type EnabledPublishingConfig = z.output<typeof publishingConfigSchema>;
+export declare function resolvePublishingConfig(value?: ReportPublishingConfig): EnabledPublishingConfig | undefined;

package/lib/types/report-publishing/service.d.ts

@@ -0,0 +1,68 @@
+import { type CredentialProvider } from '@deepseek-ai/dsh-credentials';
+import type { MarivoPresentationFileService } from '../presentation/rpc.ts';
+import type { EnabledPublishingConfig } from './config.ts';
+export declare function publishingPathName(value: string, fallback: string): string;
+export type PublishingField = 'accessKeyId' | 'secretAccessKey' | 'sessionToken';
+export interface PublishingCredentialField {
+    field: PublishingField;
+    reference: string;
+    required: boolean;
+    configured: boolean;
+    writable: boolean;
+    source?: string;
+}
+export interface PublishingCredentialView {
+    enabled: boolean;
+    configId?: string;
+    name?: string;
+    bucket?: string;
+    fields: PublishingCredentialField[];
+}
+type Store = Pick<CredentialProvider, 'describe' | 'set' | 'unset' | 'resolve'>;
+export interface UploadInput {
+    config: EnabledPublishingConfig;
+    credentials: {
+        accessKeyId: string;
+        secretAccessKey: string;
+        sessionToken?: string;
+    };
+    key: string;
+    bytes: Buffer;
+    signal: AbortSignal;
+}
+export declare function uploadReport(input: UploadInput): Promise<void>;
+export declare class ReportPublishingService {
+    readonly configId: `${string}-${string}-${string}-${string}-${string}`;
+    readonly config: EnabledPublishingConfig | undefined;
+    readonly store: Store;
+    readonly files: Pick<MarivoPresentationFileService, 'catalog' | 'read'>;
+    readonly upload: (input: UploadInput) => Promise<void>;
+    readonly workspaceName: (id: string) => string;
+    constructor(config: EnabledPublishingConfig | undefined, store: Store, files: Pick<MarivoPresentationFileService, 'catalog' | 'read'>, upload?: (input: UploadInput) => Promise<void>, workspaceName?: (id: string) => string);
+    assertConfig(configId: string): void;
+    references(): Array<{
+        field: PublishingField;
+        reference: string;
+        required: boolean;
+    }>;
+    describe(): Promise<PublishingCredentialView>;
+    change(field: PublishingField, value: string | undefined, signal: AbortSignal): Promise<void>;
+    publish(scope: {
+        sessionId: string;
+    } | {
+        workspaceId: string;
+    }, reportId: string, buildId: string, signal: AbortSignal, viewHtml?: string): Promise<{
+        storage: string;
+        bucket: string;
+        key: string;
+        url: string;
+        workspaceId: string;
+        reportId: string;
+        buildId: string;
+        sha256: string;
+        bytes: number;
+        kind: string;
+        publishedAt: string;
+    }>;
+}
+export {};

package/lib/types/rpc.d.ts

@@ -0,0 +1,3 @@
+/** Dedicated plugin RPC envelopes over Harness-owned authenticated exact Fetch routes. */
+import { type ConnectionRpcHandler, type HostConnectionHandle } from '@deepseek-ai/dsh-client-connection';
+export declare function registerPluginRpc(connection: Pick<HostConnectionHandle, 'fetch'>, channel: string, endpoints: readonly string[], handler: ConnectionRpcHandler): () => Promise<void>;

package/lib/types/semantic-browser/contracts.d.ts

@@ -2,6 +2,7 @@ import { type SemanticRef } from '../semantic-reference/contracts.ts';
 import { type ComputationDefinition } from './definition.ts';
 export declare const BROWSER_ENDPOINT = "semantic-browser/catalog";
 export declare const CATALOG_MAX_BYTES: number;
+export declare const CATALOG_ERROR_SCHEMA = "marivo.semantic_catalog_error/v1";
 export interface DisplayField {
     readonly name: string;
     readonly value: string;
@@ -30,6 +31,11 @@ export interface CatalogProjection {
     readonly kinds: readonly string[];
     readonly objects: readonly SemanticObjectView[];
 }
+export interface CatalogFailure {
+    readonly schema: typeof CATALOG_ERROR_SCHEMA;
+    readonly kind: 'semantic';
+    readonly message: string;
+}
 export interface CatalogSnapshot extends CatalogProjection {
     readonly workspaceId: string;
     readonly projectRoot: string;
@@ -37,4 +43,5 @@ export interface CatalogSnapshot extends CatalogProjection {
     readonly loadedAt: string;
 }
 export declare function parseCatalogProjection(value: unknown): CatalogProjection;
+export declare function parseCatalogFailure(value: unknown): CatalogFailure | undefined;
 export declare function parseCatalogSnapshot(value: unknown): CatalogSnapshot;

package/lib/types/semantic-browser/service.d.ts

@@ -9,12 +9,18 @@ export interface BrowserHost {
     projectRoot(workspace: BrowserWorkspace): string;
     resolve(root: string): Promise<MarivoCheckedRunner>;
 }
+export declare class SemanticCatalogLoadError extends Error {
+    readonly code = "catalog-load-failed";
+    readonly diagnostic: string;
+    constructor(diagnostic: string);
+}
 /** Workspace-addressed read service; intentionally has no Agent or credential dependency. */
 export declare class SemanticBrowserService {
     #private;
     constructor(host: BrowserHost);
     read(payload: unknown, caller: AbortSignal): Promise<CatalogSnapshot>;
+    close(): Promise<void>;
     dispose(): void;
 }
-/** Fixed diagnostics only: Python errors may contain model code or datasource secrets. */
+/** Preserve Marivo semantic diagnostics; keep unknown Python failures behind a fixed fallback. */
 export declare function browserFailure(error: unknown): string;

package/lib/types/semantic-reference/bridge.d.ts

@@ -6,6 +6,7 @@ export declare class SemanticReferenceBridge {
     #private;
     constructor(clock?: () => number);
     candidates(runner: MarivoCheckedRunner, signal: AbortSignal): Promise<Projection>;
+    close(): Promise<void>;
     invalidate(key: string): void;
     dispose(): void;
 }

package/lib/types/semantic-reference/contracts.d.ts

@@ -1,7 +1,6 @@
 /** Browser-safe wire contracts. These bounds do not reimplement Marivo's domain grammar. */
 export declare const CHANNEL = "/dsh-data-analysis";
 export declare const SOURCE = "marivo-semantic";
-export declare const LIMIT = 40;
 export declare const MAX_WIRE_BYTES: number;
 export interface SemanticRef {
     readonly schema: 'marivo.semantic_ref/v1';
@@ -46,6 +45,10 @@ export declare function parseCandidatesRequest(value: unknown): {
     sessionId: string;
     query: string;
     quoted: boolean;
-    limit: number;
 };
 export declare function parseCandidatesResponse(value: unknown): CandidatesResponse;
+/** Browser selection identity only; preparation never reloads semantic content. */
+export declare function parsePrepareRequest(value: unknown): {
+    workspaceId: string;
+    envelope: Envelope;
+};

package/lib/types/semantic-reference/environment.d.ts

@@ -0,0 +1,22 @@
+import type { MarivoCheckedRunner } from '../environment/types.ts';
+import type { EnvironmentResolver } from './rpc.ts';
+interface Workspace {
+    id: string;
+    path: string;
+}
+interface Binding {
+    root: string;
+    environment: Promise<MarivoCheckedRunner>;
+}
+export interface ReferenceEnvironmentHost<A extends object> {
+    agent(sessionId: string): A | undefined;
+    binding(agent: A): Binding | undefined;
+    projectRoot(agent: A): string;
+    resolve(agent: A): Promise<MarivoCheckedRunner>;
+    workspace(sessionId: string): Workspace;
+}
+/** Reference identity includes Harness ownership; the underlying Runtime stays unchanged. */
+export declare function semanticEnvironmentFingerprint(workspaceId: string, runtimeFingerprint: string): string;
+/** Explicit selection establishes ownership; serialization never repairs it. */
+export declare function referenceEnvironmentResolver<A extends object>(host: ReferenceEnvironmentHost<A>): EnvironmentResolver;
+export {};

package/lib/types/semantic-reference/labels.d.ts

@@ -0,0 +1,16 @@
+/** Shared display labels and search aliases; object kinds still come from the live Catalog. */
+export declare const semanticKindLabels: {
+    readonly domain: "业务域";
+    readonly datasource: "数据源";
+    readonly entity: "实体";
+    readonly dimension: "维度";
+    readonly measure: "度量";
+    readonly time_dimension: "时间维度";
+    readonly metric: "指标";
+    readonly relationship: "关系";
+    readonly event: "事件";
+    readonly state_model: "状态模型";
+    readonly period_calendar: "周期日历";
+    readonly temporal_set: "时间集合";
+    readonly work_schedule: "工作日程";
+};

package/lib/types/semantic-reference/rpc.d.ts

@@ -2,7 +2,7 @@ import type { ConnectionRpcHandler, HostConnectionHandle } from '@deepseek-ai/ds
 import type { MarivoCheckedRunner } from '../environment/types.ts';
 import { SemanticReferenceBridge } from './bridge.ts';
 import { type SemanticReferenceUsage } from './usage.ts';
-export type EnvironmentResolver = (sessionId: string, purpose: 'candidates' | 'reference') => Promise<MarivoCheckedRunner>;
+export type EnvironmentResolver = (sessionId: string, purpose: 'candidates' | 'reference' | 'prepare', workspaceId?: string) => Promise<MarivoCheckedRunner>;
 /** Abort the caller's wait, without pretending to cancel the shared Environment resolver. */
 export declare function abortable<T>(promise: Promise<T>, signal: AbortSignal): Promise<T>;
 export declare class SemanticReferenceService {

package/lib/types/semantic-reference/search.d.ts

@@ -1,4 +1,4 @@
-import { type Projection, type RankedCandidate } from './contracts.ts';
+import type { Projection, RankedCandidate } from './contracts.ts';
 export interface UsageScore {
     readonly count: number;
     readonly last: number;

package/lib/types/settings.d.ts

@@ -0,0 +1,14 @@
+import type { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+import { type MarivoPythonOptions } from './datasource/python-options.ts';
+export declare const PYTHON_SETTINGS_NAMESPACE = "dsh-data-analysis";
+export declare const PythonSettings: z<Schemastery.ObjectS<{
+    pythonTimeoutMs: z<number, number>;
+}>, Schemastery.ObjectT<{
+    pythonTimeoutMs: z<number, number>;
+}>>;
+/** Follow the Host settings provider; headless compositions retain their entry configuration. */
+export declare function installPythonSettings(ctx: Context, options: MarivoPythonOptions): {
+    get: () => Required<MarivoPythonOptions>;
+    dispose: () => Promise<void>;
+};

package/lib/types/tool-lifecycle.d.ts

@@ -0,0 +1,4 @@
+import type { Context } from '@deepseek-ai/cordis';
+import type { ToolDefinition } from '@deepseek-ai/dsh-tools';
+/** A plugin tool owns its execution promises; withdrawing its schema is not a drain. */
+export declare function registerMarivoTool(ctx: Context, tool: ToolDefinition): () => Promise<void>;

package/lib/types/workspace-identity.d.ts

@@ -0,0 +1,6 @@
+import type { Context } from '@deepseek-ai/cordis';
+/** Resolve only Harness-owned, header-validated Workspace membership; never infer it from a path. */
+export declare function resolvePresentationWorkspace(ctx: Context, sessionId: string): {
+    id: string;
+    path: string;
+};

package/lib/workspace-identity.js

@@ -0,0 +1,9 @@
+/** Resolve only Harness-owned, header-validated Workspace membership; never infer it from a path. */
+export function resolvePresentationWorkspace(ctx, sessionId) {
+    const matches = ctx.workspaceRegistry
+        .list()
+        .filter((workspace) => workspace.sessionIds.some((id) => String(id) === sessionId));
+    if (matches.length !== 1)
+        throw new Error('Presentation requires one current Session Workspace');
+    return { id: String(matches[0].id), path: matches[0].path };
+}