nebula-notebook 0.1.1 → 0.2.1

package/node-server/dist/fs/fs-service.d.ts

@@ -41,6 +41,19 @@ export declare class FilesystemService {
      */
     private atomicWriteFileSync;
     private writeJsonAtomicSync;
+    /**
+     * Async variant of atomicWriteFileSync (write temp, fsync, rename, fsync dir).
+     * Used on hot notebook-save paths so large writes never block the event loop.
+     *
+     * `durable: false` skips both fsyncs while keeping the tmp+rename atomicity.
+     * Use it for auxiliary files (history/session/journal/lastsave): on network
+     * filesystems (GPFS) each fsync can take seconds, and a save doing ~10 of
+     * them was observed at 20-27s. A crash can lose the last few seconds of an
+     * auxiliary file, but never corrupt it — the rename is still atomic. The
+     * notebook file itself stays fully durable.
+     */
+    private atomicWriteFile;
+    private writeJsonAtomic;
     /**
      * Format file size for display
      */
@@ -53,6 +66,9 @@ export declare class FilesystemService {
      * Get file info for a path
      */
     private getFileInfo;
+    /** Async, non-blocking variant of getFileInfo (one `fsp.stat`). Used by
+     *  listDirectory so a folder's entries stat in parallel off the event loop. */
+    private getFileInfoAsync;
     /**
      * Convert FileInfo to FileInfoResponse for API
      */
@@ -64,15 +80,15 @@ export declare class FilesystemService {
     /**
      * Get file modification time
      */
-    getFileMtime(filePath: string): MtimeResponse;
+    getFileMtime(filePath: string): Promise<MtimeResponse>;
     /**
      * List contents of a directory
      */
-    listDirectory(dirPath: string): DirectoryListing;
+    listDirectory(dirPath: string): Promise<DirectoryListing>;
     /**
      * Read a file's contents
      */
-    readFile(filePath: string): ReadFileResponse;
+    readFile(filePath: string): Promise<ReadFileResponse>;
     /**
      * Write content to a file
      */
@@ -87,6 +103,16 @@ export declare class FilesystemService {
      * Get the history file path for a notebook
      */
     private getHistoryPath;
+    /**
+     * Last-Nebula-save record for text-format notebooks: the canonical cell
+     * state (id/type/content) as of the last save THROUGH Nebula. At history
+     * load, divergence between this record and the file means the notebook was
+     * edited externally (vim, git checkout, ...) — the difference is
+     * reconciled into history as a synthesized external-edit operation so
+     * undo/redo stays infinite across external edits.
+     */
+    private getLastSavePath;
+    private writeTextNotebookLastSave;
     /**
      * Get the session state file path for a notebook
      */
@@ -147,9 +173,19 @@ export declare class FilesystemService {
      */
     private convertOutputsToJupyter;
     /**
-     * Read a notebook and convert to internal cell format
+     * Read a notebook and convert to internal cell format (async; hot path for
+     * notebook load — large .ipynb reads must not block the event loop)
+     */
+    getNotebookCells(notebookPath: string): Promise<NotebookCellsResponse>;
+    /**
+     * Sync variant of getNotebookCells. Kept for cold callers that need a
+     * synchronous read (headless cache warm-up, initial-history bootstrap).
      */
-    getNotebookCells(notebookPath: string): NotebookCellsResponse;
+    getNotebookCellsSync(notebookPath: string): NotebookCellsResponse;
+    /**
+     * Convert raw notebook file content to the internal cell format (CPU only).
+     */
+    private buildNotebookCellsResponse;
     /**
      * Read a notebook and convert to internal cell format, resolving default kernel if needed
      */
@@ -157,16 +193,27 @@ export declare class FilesystemService {
     /**
      * Save cells to a notebook file
      */
-    saveNotebookCells(notebookPath: string, cells: NebulaCell[], kernelName?: string, notebookMetadata?: Record<string, unknown>): SaveNotebookResult;
+    saveNotebookCells(notebookPath: string, cells: NebulaCell[], kernelName?: string, notebookMetadata?: Record<string, unknown>): Promise<SaveNotebookResult>;
     /**
      * Save notebook cells and history in a single crash-safe commit.
      * Uses a small journal + atomic writes to avoid partial files.
      */
     saveNotebookBundle(notebookPath: string, cells: NebulaCell[], kernelName?: string, history?: unknown[], session?: Record<string, unknown>, notebookMetadata?: Record<string, unknown>): Promise<SaveNotebookResult>;
+    /**
+     * Save cells to a text-format notebook (.py percent / .qmd).
+     * Outputs and execution counts are never serialized — by format design.
+     */
+    private saveTextNotebookCells;
     /**
      * Get notebook-level metadata
      */
     getNotebookMetadata(notebookPath: string): Record<string, unknown>;
+    /**
+     * Async variant of getNotebookMetadata. Nebula-written notebooks put
+     * `metadata` first, so the head-bytes scan avoids reading and parsing the
+     * whole file; externally written notebooks fall back to a full async read.
+     */
+    getNotebookMetadataAsync(notebookPath: string): Promise<Record<string, unknown>>;
     /**
      * Update notebook-level metadata without modifying cells
      */
@@ -185,11 +232,20 @@ export declare class FilesystemService {
         success: boolean;
         error?: string;
         status?: AgentPermissionSnapshot;
+        mtime?: number;
     }>;
     /**
      * Derive agent permission status from persisted notebook metadata.
      */
     getAgentPermissionStatus(notebookPath: string): AgentPermissionSnapshot;
+    /**
+     * Async variant of getAgentPermissionStatus for hot request paths (it runs
+     * on every agent write operation). Reads metadata via the head-bytes fast
+     * path and checks history without parsing it, so the per-operation gate
+     * never blocks the event loop on a slow network filesystem.
+     */
+    getAgentPermissionStatusAsync(notebookPath: string): Promise<AgentPermissionSnapshot>;
+    private deriveAgentPermission;
     /**
      * Check if a notebook is permitted for agent modifications
      */
@@ -198,14 +254,36 @@ export declare class FilesystemService {
      * Check if a notebook has history tracking enabled
      */
     hasHistory(notebookPath: string): boolean;
+    /**
+     * Async variant of hasHistory that only parses small files: history journals
+     * grow to hundreds of KB, and this check runs on every agent operation — a
+     * file that large necessarily has entries, so its size alone answers.
+     */
+    hasHistoryAsync(notebookPath: string): Promise<boolean>;
     /**
      * Save operation history for a notebook
      */
     saveHistory(notebookPath: string, history: unknown[]): Promise<boolean>;
     /**
-     * Load operation history for a notebook
+     * Load operation history for a notebook (async; history files can be many MB)
+     */
+    loadHistory(notebookPath: string): Promise<unknown[]>;
+    /**
+     * Sync variant of loadHistory. Kept for cold callers that need a
+     * synchronous read (headless undo/redo state bootstrap).
+     */
+    loadHistorySync(notebookPath: string): unknown[];
+    /**
+     * Compare the file's current cells against the last-Nebula-save record.
+     * On divergence, append ONE synthesized batch operation describing the
+     * external edit (updateContent / insertCell / deleteCell, source
+     * 'external') — both undo systems replay these, so a single undo step
+     * reverts the external edit and redo reapplies it. Falls back to a plain
+     * snapshot entry if synthesis fails (undo then bottoms out there instead
+     * of corrupting).
      */
-    loadHistory(notebookPath: string): unknown[];
+    private reconcileExternalTextEdits;
+    private synthesizeExternalEditOps;
     /**
      * Save session state for a notebook
      */