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

package/lib/types/tools/workbook-edit.d.ts

@@ -0,0 +1,192 @@
+import { type SheetColumn, type SheetColumnType, type WorkbookOperationPayload, type WorkbookOperationType, type WorkbookRange } from '../types.ts';
+import { DataSheetError } from '../errors.ts';
+import type { LineageContext } from '#contracts';
+import { type ToolArguments } from './arguments.ts';
+/** Agent-facing receipt seed for one `import_file` step. It is stripped before
+ * the command is persisted, so the Version/Step payload keeps its existing
+ * shape and replay model. */
+export interface ImportFileMeta {
+    sourcePath: string;
+    range: WorkbookRange;
+    rowsWritten: number;
+    cellsWritten: number;
+    sourceRowCount: number;
+    truncated: boolean;
+    verifyCapacity: boolean;
+    firstRow: unknown[];
+    lastRow: unknown[];
+    valuesHash: string;
+}
+/** One parsed command plus non-persisted Agent-facing metadata. */
+export interface ParsedCommand {
+    type: WorkbookOperationType;
+    payload: WorkbookOperationPayload;
+    importFile?: ImportFileMeta;
+}
+/**
+ * Copy a sheet's cell content and column widths into a new sheet of the target
+ * workbook (docs/issue/0011 I2 / T7).
+ *
+ * Expanded into the existing `create_sheet` / `update_cells` /
+ * `set_column_width` commands rather than becoming a new persisted operation:
+ * the Version/Step model is untouched and the browser projection needs no new
+ * branch. The source is read from storage, so it has to exist before the batch
+ * starts — a sheet created earlier in the same batch is not visible here.
+ *
+ * What is copied is the content that was tedious to retype (title block, header
+ * row, long SQL text) plus column widths. Styles, merges, freeze panes and data
+ * validation are deliberately not copied; they stay with the source sheet.
+ */
+export declare function expandDuplicateSheet(raw: ToolArguments, index: number, targetWorkbookId: string, warnings?: string[]): Promise<ParsedCommand[]>;
+export declare function parseEditCommands(value: unknown, warnings?: string[], targetWorkbookId?: string): Promise<ParsedCommand[]>;
+export interface ImportedTable {
+    /** Resolved absolute path of the source file. */
+    path: string;
+    name?: string;
+    columns?: unknown;
+    rows: unknown[];
+}
+/**
+ * Expand a tabular import (`{ columns?, rows }`) into the rectangular value
+ * matrix the `update_cells` write path consumes. CSV/XLSX/JSONL produce row
+ * objects, so the column order is inferred from the row keys — the same rule
+ * `append_rows` uses — while `validateSheet` keeps the caps and error wording
+ * for both shapes. Ragged array rows are padded by `normalizeValueMatrix`.
+ */
+export declare function importedValueMatrix(imported: ImportedTable, label: string): unknown[][];
+/** Stable content digest so an import receipt can prove what was written. */
+export declare function hashValueMatrix(matrix: readonly unknown[][]): string;
+/**
+ * The literal value matrix of an `update_cells` command, if it carries one.
+ * Shared by the import pre-read and the command branch so both agree on when a
+ * `sourcePath` is actually consulted.
+ */
+export declare function literalValueMatrix(raw: ToolArguments): unknown;
+/**
+ * `update_cells` anchors at `range`, or at the top-level `startRow` /
+ * `startColumn` pair. A missing anchor keeps the historical default (row 1,
+ * column 0) — the P1-2 origin change is intentionally out of scope here.
+ */
+export declare function valueCommandRange(raw: ToolArguments): unknown;
+/** Read a local tabular file for bulk Agent imports. The file is converted to
+ * the same append_rows/update_cells contract before it reaches the durable
+ * mutator, so a failed parse never creates a partial workbook revision. */
+export declare function readTabularSource(rawPath: unknown, rawFormat: unknown): Promise<ImportedTable>;
+export interface ParsedEditVersion {
+    summary: string;
+    intent?: string;
+    commands: ParsedCommand[];
+}
+/**
+ * Convert the tool protocol into the aggregate's two durable levels:
+ * semantic Version groups, each containing replayable command Steps. The
+ * shorthand keeps older callers working while making their whole request one
+ * coherent Version instead of one Version per command.
+ */
+export declare function parseEditVersionGroups(rawVersions: unknown, rawCommands: unknown, defaultIntent?: string, warnings?: string[], targetWorkbookId?: string): Promise<ParsedEditVersion[]>;
+export declare function assertNeverEditCommand(value: never): never;
+/**
+ * Bind the forgiving Agent wire format to the durable workbook format. This
+ * runs after the workbook has been loaded, so a single-sheet workbook can
+ * safely omit `sheet`, sheet names can be converted to ids, and commands that
+ * create a sheet can be followed by commands targeting that new sheet.
+ */
+export declare function bindEditVersionGroups(snapshot: unknown, groups: ParsedEditVersion[], workbookId?: string): ParsedEditVersion[];
+/** Deterministic create_sheet id so preview and commit address the same sheet. */
+export declare function stableCreateSheetId(workbookId: string, name: unknown, groupIndex: number, commandIndex: number): string;
+/**
+ * Warn when one edit plan writes the same cell more than once. The later
+ * command wins, which is easy to do by accident in a 15-command batch.
+ */
+export declare function collectDuplicateCellWrites(versions: readonly ParsedEditVersion[], warnings: string[]): void;
+export declare function resolveCommandSheetRef(snapshot: unknown, explicit: unknown, label: string, allowMissing: boolean): string | undefined;
+export declare function inferAppendTable(snapshot: unknown, sheetRef: unknown, rawRows: unknown, label: string): {
+    columns: SheetColumn[];
+    rows: Array<Record<string, unknown>>;
+};
+export declare function projectRowsToColumns(rows: Array<Record<string, unknown>>, columns: SheetColumn[]): Array<Record<string, unknown>>;
+export declare function inferredColumnType(rows: Array<Record<string, unknown>>, key: string): SheetColumnType;
+/**
+ * A rejected edit plan used to come back as a bare message, so the caller had
+ * to replay the whole payload just to discover what it had sent (docs/issue/0011
+ * I8 / T7). Every validation failure now names the shape that was received and
+ * says that only the offending command has to change; `details` carries the
+ * same facts as data for callers that can read them.
+ */
+export declare function withEditRetryContext(error: unknown, args: {
+    workbookId: string;
+    versions?: unknown;
+    commands?: unknown;
+}): DataSheetError;
+export declare function executeWorkbookEdit(args: {
+    workbookId: string;
+    versions: unknown;
+    commands: unknown;
+    baseRevision?: number;
+    opId?: string;
+    intent?: string;
+    agentRunId?: string;
+    lineage?: LineageContext;
+    dryRun: boolean;
+}): Promise<unknown>;
+/**
+ * One `import_file` step after binding (its sheet reference is resolved). The
+ * command itself is already normalized to a durable `update_cells` payload.
+ */
+export interface ImportFileStep {
+    type: WorkbookOperationType;
+    payload: WorkbookOperationPayload;
+    importFile: ImportFileMeta;
+}
+export declare function collectImportFileSteps(versions: readonly ParsedEditVersion[]): ImportFileStep[];
+/** One Agent-facing import receipt for a single `import_file` command. */
+export interface ImportFileReceipt {
+    workbookId: string;
+    revisionBefore: number;
+    revisionAfter: number;
+    sheetId: string | null;
+    range: WorkbookRange;
+    rowsWritten: number;
+    cellsWritten: number;
+    sourceRowCount: number;
+    truncated: boolean;
+    sourcePath: string;
+    rowCountBefore: number | null;
+    rowCountAfter: number | null;
+    capacityExpanded: boolean;
+    firstRow: unknown[];
+    lastRow: unknown[];
+    valuesHash: string;
+    warnings: string[];
+}
+/**
+ * Self-verifying import receipt: range/row/cell counts, source size, a content
+ * digest plus first/last row samples, and the auto-expansion result so the
+ * Agent never has to reread the whole range to prove the write landed.
+ */
+export declare function importFileReceipt(step: ImportFileStep, context: {
+    workbookId: string;
+    revisionBefore: number;
+    revisionAfter: number;
+    snapshotBefore: unknown;
+    snapshotAfter: unknown;
+}): ImportFileReceipt;
+/** Physical row capacity (`rowCount`) of one sheet in a snapshot. */
+export declare function snapshotRowCapacity(snapshot: unknown, sheetRef: string | null): number | null;
+/** Receipt data that lets an Agent prove what a write touched without rereading storage. */
+export declare function summarizeAffectedSheets(versions: readonly ParsedEditVersion[], snapshot: unknown): {
+    sheets: string[];
+    refs: Array<{
+        name: string;
+        sheetId: string;
+    }>;
+    cellCount: number;
+};
+export declare function newAgentVersionId(workbookId: string, opId?: string): string;
+export declare function parseStyle(value: unknown): NonNullable<WorkbookOperationPayload['style']>;
+export declare function parseSheetMeta(value: unknown): {
+    source?: string;
+    query?: string;
+    generatedAt?: string;
+    notes?: string;
+} | undefined;