Add tool definitions operations and schemas

Author: goanpeca

packages/react/package.json

@@ -29,9 +29,9 @@
     "access": "public"
   },
   "scripts": {
-    "build": "gulp resources-to-lib && tsc && webpack",
-    "build:lib": "tsc",
-    "build:prod": "gulp resources-to-lib && tsc && npm run clean && npm run build:lib",
+    "build": "npm run validate:tools && gulp resources-to-lib && tsc && webpack",
+    "build:lib": "npm run validate:tools && tsc",
+    "build:prod": "npm run validate:tools && gulp resources-to-lib && tsc && npm run clean && npm run build:lib",
     "build:tsc:watch:res": "gulp resources-to-lib-watch",
     "build:tsc:watch:tsc": "tsc --watch",
     "build:webpack": "cross-env BUILD_APP=true webpack-cli build",
@@ -62,6 +62,7 @@
     "test": "jest --coverage",
     "test:visual": "playwright test",
     "typedoc": "typedoc ./src",
+    "validate:tools": "node scripts/validate-tools-sync.js",
     "watch": "run-p watch:src",
     "watch:src": "tsc -w"
   },
@@ -144,6 +145,7 @@
     "@lumino/default-theme": "^2.0.0",
     "@primer/react": "^37.19.0",
     "@primer/react-brand": "^0.58.2",
+    "@toon-format/toon": "^1.3.0",
     "ansi-to-html": "^0.7.2",
     "assert": "^2.0.0",
     "bufferutil": "^4.0.8",

packages/react/scripts/validate-tools-sync.js

@@ -0,0 +1,132 @@
+#!/usr/bin/env node
+/*
+ * Copyright (c) 2021-2023 Datalayer, Inc.
+ *
+ * MIT License
+ */
+
+/**
+ * Validation script to ensure tool definitions and operations stay in sync.
+ *
+ * Checks:
+ * 1. Every definition has a corresponding operation
+ * 2. Every operation has a corresponding definition
+ * 3. Tool names match between definition and operation
+ * 4. No orphaned files
+ *
+ * Usage: npm run validate:tools
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const TOOLS_DIR = path.join(__dirname, '../src/tools');
+const DEFINITIONS_DIR = path.join(TOOLS_DIR, 'definitions');
+const OPERATIONS_DIR = path.join(TOOLS_DIR, 'operations');
+
+function getToolFiles(dir) {
+  const files = fs.readdirSync(dir);
+  return files
+    .filter(f => f.endsWith('.ts') && f !== 'index.ts')
+    .map(f => ({
+      name: f.replace('.ts', ''),
+      path: path.join(dir, f),
+    }));
+}
+
+function extractToolName(filePath) {
+  const content = fs.readFileSync(filePath, 'utf-8');
+
+  // For definitions: export const xxxTool
+  const defMatch = content.match(/export const (\w+)Tool:/);
+  if (defMatch) {
+    return defMatch[1]; // e.g., "insertCell" from "insertCellTool"
+  }
+
+  // For operations: export const xxxOperation
+  const opMatch = content.match(/export const (\w+)Operation:/);
+  if (opMatch) {
+    return opMatch[1]; // e.g., "insertCell" from "insertCellOperation"
+  }
+
+  return null;
+}
+
+function main() {
+  console.log('🔍 Validating tool definitions and operations sync...\n');
+
+  const definitions = getToolFiles(DEFINITIONS_DIR);
+  const operations = getToolFiles(OPERATIONS_DIR);
+
+  console.log(`Found ${definitions.length} definitions:`);
+  definitions.forEach(d => console.log(`  - ${d.name}`));
+  console.log();
+
+  console.log(`Found ${operations.length} operations:`);
+  operations.forEach(o => console.log(`  - ${o.name}`));
+  console.log();
+
+  let hasErrors = false;
+
+  // Check 1: File name alignment
+  const defNames = new Set(definitions.map(d => d.name));
+  const opNames = new Set(operations.map(o => o.name));
+
+  // Find definitions without operations
+  const missingOps = definitions.filter(d => !opNames.has(d.name));
+  if (missingOps.length > 0) {
+    console.error('❌ Definitions without matching operations:');
+    missingOps.forEach(d => console.error(`   ${d.name}`));
+    hasErrors = true;
+  }
+
+  // Find operations without definitions
+  const missingDefs = operations.filter(o => !defNames.has(o.name));
+  if (missingDefs.length > 0) {
+    console.error('❌ Operations without matching definitions:');
+    missingDefs.forEach(o => console.error(`   ${o.name}`));
+    hasErrors = true;
+  }
+
+  // Check 2: Tool name extraction from file content
+  console.log('\n📝 Checking exported names...');
+  for (const def of definitions) {
+    const toolName = extractToolName(def.path);
+    if (!toolName) {
+      console.error(`❌ Could not extract tool name from ${def.name}`);
+      hasErrors = true;
+    } else if (toolName !== def.name) {
+      console.error(
+        `❌ File name mismatch: ${def.name}.ts exports ${toolName}Tool`
+      );
+      hasErrors = true;
+    }
+  }
+
+  for (const op of operations) {
+    const toolName = extractToolName(op.path);
+    if (!toolName) {
+      console.error(`❌ Could not extract tool name from ${op.name}`);
+      hasErrors = true;
+    } else if (toolName !== op.name) {
+      console.error(
+        `❌ File name mismatch: ${op.name}.ts exports ${toolName}Operation`
+      );
+      hasErrors = true;
+    }
+  }
+
+  // Summary
+  console.log('\n' + '='.repeat(60));
+  if (hasErrors) {
+    console.error('❌ Validation FAILED - tools are out of sync!');
+    process.exit(1);
+  } else {
+    console.log('✅ Validation PASSED - all tools are in sync!');
+    console.log(`\n   ${definitions.length} definition(s)`);
+    console.log(`   ${operations.length} operation(s)`);
+    console.log('   Perfect 1:1 alignment! 🎉');
+  }
+}
+
+main();

packages/react/src/components/notebook/Notebook2Adapter.ts

@@ -13,6 +13,7 @@ import {
 import { Context } from '@jupyterlab/docregistry';
 import { NotebookModel } from '@jupyterlab/notebook';
 import * as nbformat from '@jupyterlab/nbformat';
+import { NotebookCommandIds } from './NotebookCommands';
 
 export class Notebook2Adapter {
   private _commands: CommandRegistry;
@@ -198,6 +199,209 @@ export class Notebook2Adapter {
     NotebookActions.redo(notebook);
   }
 
+  /**
+   * Set the active cell by index.
+   *
+   * @param index - The index of the cell to activate (0-based)
+   *
+   * @remarks
+   * This method programmatically selects a cell at the specified index.
+   * If the index is out of bounds, the operation has no effect.
+   */
+  setActiveCell(index: number): void {
+    const notebook = this._notebook;
+    const cellCount = notebook.model?.cells.length ?? 0;
+
+    if (index >= 0 && index < cellCount) {
+      notebook.activeCellIndex = index;
+    }
+  }
+
+  /**
+   * Get all cells from the notebook.
+   *
+   * @returns Array of cell data including type, source, and outputs
+   *
+   * @remarks
+   * This method extracts cell information from the notebook model.
+   * For code cells, outputs are included. Returns an empty array if
+   * the notebook model is not available.
+   */
+  getCells(): Array<{
+    type: nbformat.CellType;
+    source: string;
+    outputs?: unknown[];
+  }> {
+    const cells = this._notebook.model?.cells;
+    if (!cells) {
+      return [];
+    }
+
+    const result: Array<{
+      type: nbformat.CellType;
+      source: string;
+      outputs?: unknown[];
+    }> = [];
+
+    for (let i = 0; i < cells.length; i++) {
+      const cell = cells.get(i);
+      if (cell) {
+        result.push({
+          type: cell.type as nbformat.CellType,
+          source: cell.sharedModel.getSource(),
+          outputs:
+            cell.type === 'code' ? (cell as any).outputs?.toJSON() : undefined,
+        });
+      }
+    }
+
+    return result;
+  }
+
+  /**
+   * Get the total number of cells in the notebook.
+   *
+   * @returns The number of cells, or 0 if the notebook model is not available
+   */
+  getCellCount(): number {
+    return this._notebook.model?.cells.length ?? 0;
+  }
+
+  /**
+   * Insert a new cell at a specific index.
+   *
+   * @param cellIndex - The index where the cell should be inserted (0-based)
+   * @param source - Optional source code/text for the new cell
+   *
+   * @remarks
+   * This method inserts a cell at the specified position by:
+   * 1. Setting the active cell to cellIndex
+   * 2. Calling insertAbove to insert before that cell
+   *
+   * Note: The cell type is determined by _defaultCellType, which should be set
+   * before calling this method (typically done by the store layer).
+   */
+  insertAt(cellIndex: number, source?: string): void {
+    const cellCount = this.getCellCount();
+
+    console.log('[Notebook2Adapter.insertAt] BEFORE:', {
+      cellIndex,
+      sourceLength: source?.length || 0,
+      sourcePreview: source?.substring(0, 50),
+      currentActiveCell: this._notebook.activeCellIndex,
+      cellCount,
+      defaultCellType: this._defaultCellType,
+    });
+
+    // If index is beyond cell count, insert at the end
+    if (cellIndex >= cellCount) {
+      console.log(
+        '[Notebook2Adapter.insertAt] Index beyond cell count, inserting at end'
+      );
+      this.insertBelow(source);
+      return;
+    }
+
+    this.setActiveCell(cellIndex);
+
+    console.log('[Notebook2Adapter.insertAt] AFTER setActiveCell:', {
+      newActiveCell: this._notebook.activeCellIndex,
+    });
+
+    this.insertAbove(source);
+
+    console.log('[Notebook2Adapter.insertAt] AFTER insertAbove:', {
+      cellCount: this.getCellCount(),
+      newActiveCell: this._notebook.activeCellIndex,
+    });
+  }
+
+  /**
+   * NEW ALIGNED TOOL METHODS
+   * These methods align 1:1 with tool operation names for seamless integration
+   */
+
+  /**
+   * Insert a cell at a specific index (aligned with insertCell tool).
+   *
+   * @param cellType - Type of cell to insert (code, markdown, or raw)
+   * @param cellIndex - Index where to insert (0-based). Use large number for end.
+   * @param source - Optional source code/text for the cell
+   */
+  insertCell(
+    cellType: nbformat.CellType,
+    cellIndex: number,
+    source?: string
+  ): void {
+    this.setDefaultCellType(cellType);
+    this.insertAt(cellIndex, source);
+  }
+
+  /**
+   * Delete the currently active cell (aligned with deleteCell tool).
+   */
+  deleteCell(): void {
+    this.deleteCells();
+  }
+
+  /**
+   * Update a cell's content and/or type (aligned with updateCell tool).
+   *
+   * @param cellType - New cell type
+   * @param source - New source content (optional)
+   */
+  updateCell(cellType: nbformat.CellType, source?: string): void {
+    if (source !== undefined && this._notebook.activeCell) {
+      this._notebook.activeCell.model.sharedModel.setSource(source);
+    }
+    this.changeCellType(cellType);
+  }
+
+  /**
+   * Get a cell's content by index or active cell (aligned with getCell tool).
+   *
+   * @param index - Optional cell index (0-based). If not provided, returns active cell.
+   * @returns Cell data or undefined if not found
+   */
+  getCell(
+    index?: number
+  ):
+    | { type: nbformat.CellType; source: string; outputs?: unknown[] }
+    | undefined {
+    if (index !== undefined) {
+      // Get cell at specific index
+      const cells = this.getCells();
+      return cells[index];
+    } else {
+      // Get active cell
+      const activeCell = this._notebook.activeCell;
+      if (!activeCell) return undefined;
+
+      return {
+        type: activeCell.model.type,
+        source: activeCell.model.sharedModel.getSource(),
+        outputs:
+          activeCell.model.type === 'code'
+            ? (activeCell.model as any).outputs?.toJSON()
+            : undefined,
+      };
+    }
+  }
+
+  /**
+   * Run the active cell (aligned with runCell tool).
+   */
+  runCell(): void {
+    this._commands.execute(NotebookCommandIds.run);
+  }
+
+  /**
+   * Run all cells in the notebook (aligned with runAllCells tool).
+   */
+  runAllCells(): void {
+    this._commands.execute(NotebookCommandIds.runAll);
+  }
+
   /**
    * Dispose of the adapter.
    */