nebula-notebook 0.1.0

package/node-server/dist/notebook/undoRedoManager.d.ts

@@ -0,0 +1,194 @@
+/**
+ * Headless Undo/Redo Manager
+ *
+ * Manages undo/redo state for notebooks when operated via the headless backend (MCP).
+ * This mirrors the frontend UndoRedoManager but uses NebulaCell types.
+ *
+ * Note: This is a simplified version of lib/undoRedoCore.ts adapted for the backend.
+ * The core logic is intentionally similar to maintain feature parity.
+ */
+import { NebulaCell } from '../fs/types';
+import { FilesystemService } from '../fs/fs-service';
+export type EditSource = 'user' | 'ai' | 'mcp' | 'system' | 'error';
+export type MetadataChanges = Record<string, {
+    old: unknown;
+    new: unknown;
+}>;
+/** Patch format for content updates (diff-match-patch compatible) */
+export interface Patch {
+    diffs: Array<[number, string]>;
+    start1: number;
+    start2: number;
+    length1: number;
+    length2: number;
+}
+export type UndoableOperation = {
+    type: 'insertCell';
+    index: number;
+    cell: NebulaCell;
+    source?: EditSource;
+} | {
+    type: 'deleteCell';
+    index: number;
+    cell: NebulaCell;
+    source?: EditSource;
+} | {
+    type: 'moveCell';
+    fromIndex: number;
+    toIndex: number;
+    source?: EditSource;
+} | {
+    type: 'updateContent';
+    cellId: string;
+    oldContent: string;
+    newContent: string;
+    source?: EditSource;
+} | {
+    type: 'updateMetadata';
+    cellId: string;
+    changes: MetadataChanges;
+    source?: EditSource;
+} | {
+    type: 'batch';
+    operations: UndoableOperation[];
+    source?: EditSource;
+};
+export type EventCategory = 'execution' | 'kernel' | 'system' | 'ui';
+export type EventTarget = {
+    cellId?: string;
+    cellIndex?: number;
+};
+export type EventOperation = {
+    type: 'event';
+    category: EventCategory;
+    name: string;
+    target?: EventTarget;
+    runId?: string;
+    data?: Record<string, unknown>;
+    source?: EditSource;
+};
+export type LegacyLogOperation = {
+    type: 'runCell';
+    cellId: string;
+    cellIndex: number;
+    runId?: string;
+} | {
+    type: 'runAllCells';
+    cellCount?: number;
+    cellIds?: string[];
+} | {
+    type: 'interruptKernel';
+} | {
+    type: 'restartKernel';
+} | {
+    type: 'runCellComplete';
+    cellId: string;
+    cellIndex: number;
+    durationMs: number;
+    success: boolean;
+    output?: string;
+    runId?: string;
+};
+export type LogOperation = EventOperation | LegacyLogOperation;
+export interface SnapshotOperation {
+    type: 'snapshot';
+    cells: NebulaCell[];
+}
+export interface BaseOperation {
+    timestamp: number;
+    operationId?: string;
+    isUndo?: boolean;
+    undoesOperationId?: string;
+}
+export type TimestampedOperation = BaseOperation & (UndoableOperation | LogOperation | SnapshotOperation);
+export type Operation = UndoableOperation;
+export interface UndoRedoResult {
+    success: boolean;
+    affectedCellIds: string[];
+    operationType: string;
+    error?: string;
+}
+/** Summary of an update for agent awareness */
+export interface UpdateSummary {
+    kind: 'edit' | 'event';
+    type: string;
+    category?: EventCategory;
+    name?: string;
+    cellId?: string;
+    cellIndex?: number;
+    timestamp: number;
+    description: string;
+    source?: EditSource;
+    runId?: string;
+    data?: Record<string, unknown>;
+}
+interface NotebookUndoState {
+    undoStack: Operation[];
+    redoStack: Operation[];
+    fullHistory: TimestampedOperation[];
+    lastContent: Map<string, string>;
+}
+/**
+ * Manages undo/redo state for multiple notebooks in the headless backend.
+ */
+export declare class HeadlessUndoRedoManager {
+    private states;
+    private fsService;
+    constructor(fsService: FilesystemService);
+    /**
+     * Get or initialize undo state for a notebook.
+     */
+    getState(notebookPath: string, cells: NebulaCell[]): NotebookUndoState;
+    /**
+     * Rebuild undo stack from history.
+     */
+    private rebuildUndoStack;
+    /**
+     * Record an operation (called by headless handler after executing an operation).
+     */
+    recordOperation(notebookPath: string, cells: NebulaCell[], op: UndoableOperation): void;
+    /**
+     * Record a non-undoable log operation (history only).
+     */
+    recordLogOperation(notebookPath: string, cells: NebulaCell[], op: LogOperation): void;
+    /**
+     * Undo the last operation.
+     */
+    undo(notebookPath: string, cells: NebulaCell[]): {
+        cells: NebulaCell[];
+        result: UndoRedoResult;
+    };
+    /**
+     * Redo the last undone operation.
+     */
+    redo(notebookPath: string, cells: NebulaCell[]): {
+        cells: NebulaCell[];
+        result: UndoRedoResult;
+    };
+    private updateContentTrackingAfterUndo;
+    private updateContentTrackingAfterRedo;
+    /**
+     * Check if undo is available.
+     */
+    canUndo(notebookPath: string, cells: NebulaCell[]): boolean;
+    /**
+     * Check if redo is available.
+     */
+    canRedo(notebookPath: string, cells: NebulaCell[]): boolean;
+    /**
+     * Get history for a notebook.
+     */
+    getHistory(notebookPath: string, cells: NebulaCell[]): TimestampedOperation[];
+    /**
+     * Clear state for a notebook (e.g., when closing).
+     */
+    clearState(notebookPath: string): void;
+    /**
+     * Get updates since a timestamp (for agent awareness).
+     * Returns human-readable summaries of operations made between agent sessions.
+     * Includes both edits and non-undoable events (no source filtering).
+     */
+    getUpdatesSince(notebookPath: string, cells: NebulaCell[], sinceTimestamp: number): UpdateSummary[];
+}
+export declare function getUndoRedoManager(fsService: FilesystemService): HeadlessUndoRedoManager;
+export {};