stone-lang 0.1.0

package/adapters/FileSystemAdapter.js

@@ -0,0 +1,230 @@
+/**
+ * FileSystemAdapter - Base class for Stone file system access
+ *
+ * Provides an abstraction layer between the Stone execution engine and
+ * the file system. Allows different implementations for:
+ * - Node.js (CLI) - uses actual filesystem
+ * - Web app - uses in-memory file map or API
+ * - Testing - uses mock filesystem
+ */
+export class FileSystemAdapter {
+  /**
+   * Read file contents
+   * @param {string} path - File path
+   * @returns {Promise<string>} File contents
+   * @throws {Error} If file not found or read fails
+   */
+  async readFile(path) {
+    throw new Error('FileSystemAdapter.readFile() not implemented');
+  }
+
+  /**
+   * Write file contents
+   * @param {string} path - File path
+   * @param {string} content - Content to write
+   * @returns {Promise<void>}
+   * @throws {Error} If write fails
+   */
+  async writeFile(path, content) {
+    throw new Error('FileSystemAdapter.writeFile() not implemented');
+  }
+
+  /**
+   * Check if file exists
+   * @param {string} path - File path
+   * @returns {Promise<boolean>}
+   */
+  async exists(path) {
+    throw new Error('FileSystemAdapter.exists() not implemented');
+  }
+
+  /**
+   * List files in directory
+   * @param {string} path - Directory path
+   * @returns {Promise<string[]>} List of file names
+   * @throws {Error} If directory not found or read fails
+   */
+  async readDir(path) {
+    throw new Error('FileSystemAdapter.readDir() not implemented');
+  }
+
+  /**
+   * Resolve path relative to base
+   * @param {string} base - Base path
+   * @param {string} relative - Relative path
+   * @returns {string} Resolved absolute path
+   */
+  resolvePath(base, relative) {
+    throw new Error('FileSystemAdapter.resolvePath() not implemented');
+  }
+
+  /**
+   * Get directory name from path
+   * @param {string} path - File path
+   * @returns {string} Directory path
+   */
+  dirname(path) {
+    throw new Error('FileSystemAdapter.dirname() not implemented');
+  }
+
+  /**
+   * Get base name from path
+   * @param {string} path - File path
+   * @returns {string} File name
+   */
+  basename(path) {
+    throw new Error('FileSystemAdapter.basename() not implemented');
+  }
+
+  /**
+   * Join path segments
+   * @param {...string} segments - Path segments
+   * @returns {string} Joined path
+   */
+  join(...segments) {
+    throw new Error('FileSystemAdapter.join() not implemented');
+  }
+
+  /**
+   * Check if path is absolute
+   * @param {string} path - Path to check
+   * @returns {boolean}
+   */
+  isAbsolute(path) {
+    throw new Error('FileSystemAdapter.isAbsolute() not implemented');
+  }
+}
+
+/**
+ * MemoryFileSystemAdapter - In-memory file system for testing and web
+ *
+ * Uses a Map to store file contents. Useful for:
+ * - Unit testing without touching real filesystem
+ * - Web app where files are loaded from API/memory
+ */
+export class MemoryFileSystemAdapter extends FileSystemAdapter {
+  constructor(files = {}) {
+    super();
+    // files is an object { path: content }
+    this.files = new Map(Object.entries(files));
+  }
+
+  async readFile(path) {
+    const normalizedPath = this._normalizePath(path);
+    if (!this.files.has(normalizedPath)) {
+      throw new Error(`File not found: ${path}`);
+    }
+    return this.files.get(normalizedPath);
+  }
+
+  async writeFile(path, content) {
+    const normalizedPath = this._normalizePath(path);
+    this.files.set(normalizedPath, content);
+  }
+
+  async exists(path) {
+    const normalizedPath = this._normalizePath(path);
+    return this.files.has(normalizedPath);
+  }
+
+  async readDir(path) {
+    const normalizedPath = this._normalizePath(path);
+    const prefix = normalizedPath.endsWith('/') ? normalizedPath : normalizedPath + '/';
+
+    const entries = new Set();
+    for (const filePath of this.files.keys()) {
+      if (filePath.startsWith(prefix)) {
+        const remaining = filePath.slice(prefix.length);
+        const firstPart = remaining.split('/')[0];
+        if (firstPart) {
+          entries.add(firstPart);
+        }
+      }
+    }
+    return Array.from(entries);
+  }
+
+  resolvePath(base, relative) {
+    if (this.isAbsolute(relative)) {
+      return this._normalizePath(relative);
+    }
+    const baseParts = base.split('/').filter(Boolean);
+    const relativeParts = relative.split('/').filter(Boolean);
+
+    // Remove filename from base if it doesn't end with /
+    if (base && !base.endsWith('/')) {
+      baseParts.pop();
+    }
+
+    for (const part of relativeParts) {
+      if (part === '..') {
+        baseParts.pop();
+      } else if (part !== '.') {
+        baseParts.push(part);
+      }
+    }
+
+    return '/' + baseParts.join('/');
+  }
+
+  dirname(path) {
+    const parts = path.split('/').filter(Boolean);
+    parts.pop();
+    return '/' + parts.join('/');
+  }
+
+  basename(path) {
+    const parts = path.split('/').filter(Boolean);
+    return parts[parts.length - 1] || '';
+  }
+
+  join(...segments) {
+    return this._normalizePath(segments.join('/'));
+  }
+
+  isAbsolute(path) {
+    return path.startsWith('/');
+  }
+
+  /**
+   * Add a file to the in-memory filesystem
+   * @param {string} path - File path
+   * @param {string} content - File content
+   */
+  addFile(path, content) {
+    this.files.set(this._normalizePath(path), content);
+  }
+
+  /**
+   * Remove a file from the in-memory filesystem
+   * @param {string} path - File path
+   */
+  removeFile(path) {
+    this.files.delete(this._normalizePath(path));
+  }
+
+  /**
+   * Clear all files
+   */
+  clear() {
+    this.files.clear();
+  }
+
+  _normalizePath(path) {
+    // Normalize path: remove duplicate slashes, resolve . and ..
+    const parts = path.split('/').filter(Boolean);
+    const result = [];
+
+    for (const part of parts) {
+      if (part === '..') {
+        result.pop();
+      } else if (part !== '.') {
+        result.push(part);
+      }
+    }
+
+    return '/' + result.join('/');
+  }
+}
+
+export default FileSystemAdapter;

package/adapters/OutputAdapter.js

@@ -0,0 +1,208 @@
+/**
+ * OutputAdapter - Base class for Stone execution output handling
+ *
+ * Provides an abstraction layer between the Stone execution engine and
+ * the output destination (CLI terminal, web app React state, JSON stream, etc.)
+ *
+ * All methods are no-ops by default - subclasses override what they need.
+ */
+export class OutputAdapter {
+  /**
+   * Called when print() builtin is invoked
+   * @param {string} text - Text to print
+   */
+  print(text) {
+    // Default: no-op
+  }
+
+  /**
+   * Called when a new terminal is created (graph2d, graph3d, console, etc.)
+   * @param {string} id - Unique terminal ID (e.g., 'graph2d_0')
+   * @param {string} type - Terminal type ('graph2d', 'graph3d', 'console')
+   * @param {Object} config - Terminal configuration (title, x_label, etc.)
+   */
+  createTerminal(id, type, config) {
+    // Default: no-op
+  }
+
+  /**
+   * Called when data is added to a terminal (e.g., graph.add(data))
+   * @param {string} id - Terminal ID
+   * @param {any} data - Data to add (format depends on terminal type)
+   */
+  addToTerminal(id, data) {
+    // Default: no-op
+  }
+
+  /**
+   * Called when terminal data is replaced (e.g., graph.set(data))
+   * @param {string} id - Terminal ID
+   * @param {any} data - New data (replaces existing)
+   */
+  setTerminal(id, data) {
+    // Default: no-op
+  }
+
+  /**
+   * Called when a terminal is cleared
+   * @param {string} id - Terminal ID
+   */
+  clearTerminal(id) {
+    // Default: no-op
+  }
+
+  /**
+   * Called when script execution finishes
+   * @param {boolean} success - Whether execution succeeded
+   * @param {any} result - Final result value (or error)
+   */
+  finish(success, result) {
+    // Default: no-op
+  }
+
+  /**
+   * Called when a type-checking or compilation error occurs
+   * @param {string} message - Error message
+   * @param {Object} location - Source location {line, column, file}
+   */
+  error(message, location) {
+    // Default: no-op
+  }
+
+  /**
+   * Called for progress updates during execution
+   * @param {Object} info - Progress information {phase, message, percent}
+   */
+  progress(info) {
+    // Default: no-op
+  }
+}
+
+/**
+ * BufferedOutputAdapter - Collects output in memory for batch return
+ *
+ * Used for backward compatibility with existing StoneEngineService API
+ * that returns all output at once after execution.
+ */
+export class BufferedOutputAdapter extends OutputAdapter {
+  constructor() {
+    super();
+    this.output = [];
+    this.terminalsData = {};
+    this.errors = [];
+    this.result = null;
+    this.success = true;
+    this._debug = false;
+  }
+
+  print(text) {
+    if (this._debug) console.log('[BufferedAdapter] print:', text);
+    this.output.push(text);
+  }
+
+  createTerminal(id, type, config) {
+    if (this._debug) console.log('[BufferedAdapter] createTerminal:', id, type);
+    this.terminalsData[id] = {
+      type,
+      config,
+      plots: type === 'graph2d' ? [] : undefined,
+      objects: type === 'graph3d' ? [] : undefined,
+      lines: type === 'console' ? [] : undefined,
+    };
+  }
+
+  addToTerminal(id, data) {
+    if (this._debug) console.log('[BufferedAdapter] addToTerminal:', id, 'items:', Array.isArray(data) ? data.length : 1);
+    const terminal = this.terminalsData[id];
+    if (!terminal) {
+      if (this._debug) console.log('[BufferedAdapter] WARNING: terminal not found:', id);
+      return;
+    }
+
+    const items = Array.isArray(data) ? data : [data];
+
+    switch (terminal.type) {
+      case 'graph2d':
+        terminal.plots.push(...items);
+        break;
+      case 'graph3d':
+        terminal.objects.push(...items);
+        if (this._debug) console.log('[BufferedAdapter] graph3d objects count:', terminal.objects.length);
+        break;
+      case 'console':
+        terminal.lines.push(...items);
+        break;
+    }
+  }
+
+  setTerminal(id, data) {
+    const terminal = this.terminalsData[id];
+    if (!terminal) return;
+
+    const items = Array.isArray(data) ? data : [data];
+
+    switch (terminal.type) {
+      case 'graph2d':
+        terminal.plots = items;
+        break;
+      case 'graph3d':
+        terminal.objects = items;
+        break;
+      case 'console':
+        terminal.lines = items;
+        break;
+    }
+  }
+
+  clearTerminal(id) {
+    const terminal = this.terminalsData[id];
+    if (!terminal) return;
+
+    switch (terminal.type) {
+      case 'graph2d':
+        terminal.plots = [];
+        break;
+      case 'graph3d':
+        terminal.objects = [];
+        break;
+      case 'console':
+        terminal.lines = [];
+        break;
+    }
+  }
+
+  finish(success, result) {
+    this.success = success;
+    this.result = result;
+  }
+
+  error(message, location) {
+    this.errors.push({ message, location });
+  }
+
+  /**
+   * Get collected output for batch return
+   */
+  getOutput() {
+    return {
+      output: this.output,
+      terminalsData: this.terminalsData,
+      errors: this.errors,
+      result: this.result,
+      success: this.success,
+    };
+  }
+
+  /**
+   * Reset adapter state for reuse
+   */
+  reset() {
+    this.output = [];
+    this.terminalsData = {};
+    this.errors = [];
+    this.result = null;
+    this.success = true;
+  }
+}
+
+export default OutputAdapter;

package/adapters/index.js

@@ -0,0 +1,6 @@
+/**
+ * Stone Adapters - Platform abstraction for output and file system
+ */
+
+export { OutputAdapter, BufferedOutputAdapter } from './OutputAdapter.js';
+export { FileSystemAdapter, MemoryFileSystemAdapter } from './FileSystemAdapter.js';

package/cli/CLIOutputAdapter.js

@@ -0,0 +1,196 @@
+/**
+ * CLIOutputAdapter - Human-readable terminal output with colors
+ *
+ * Formats Stone execution output for the command line:
+ * - Colorized print output
+ * - Terminal updates (for console terminals)
+ * - Error messages with source locations
+ * - Progress indicators
+ *
+ * Graph terminals (graph2d, graph3d) trigger browser viewing
+ * instead of printing to console.
+ */
+
+import { OutputAdapter } from '../adapters/OutputAdapter.js';
+
+// ANSI color codes
+const colors = {
+  reset: '\x1b[0m',
+  bold: '\x1b[1m',
+  dim: '\x1b[2m',
+
+  // Text colors
+  black: '\x1b[30m',
+  red: '\x1b[31m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  blue: '\x1b[34m',
+  magenta: '\x1b[35m',
+  cyan: '\x1b[36m',
+  white: '\x1b[37m',
+
+  // Bright colors
+  brightRed: '\x1b[91m',
+  brightGreen: '\x1b[92m',
+  brightYellow: '\x1b[93m',
+  brightBlue: '\x1b[94m',
+  brightMagenta: '\x1b[95m',
+  brightCyan: '\x1b[96m',
+};
+
+const c = (color, text) => `${colors[color]}${text}${colors.reset}`;
+
+/**
+ * CLIOutputAdapter - Formats output for terminal display
+ */
+export class CLIOutputAdapter extends OutputAdapter {
+  constructor(options = {}) {
+    super();
+    this.colorize = options.colorize !== false;
+    this.verbose = options.verbose || false;
+    this.quiet = options.quiet || false;
+    this.stream = options.stream || process.stdout;
+    this.errorStream = options.errorStream || process.stderr;
+
+    // Track terminals for graph viewing
+    this.terminals = {};
+    this.hasGraphTerminals = false;
+
+    // Callback for when graphs are created
+    this.onGraphCreated = options.onGraphCreated || null;
+  }
+
+  _write(text) {
+    if (!this.quiet) {
+      this.stream.write(text);
+    }
+  }
+
+  _writeError(text) {
+    this.errorStream.write(text);
+  }
+
+  _color(color, text) {
+    return this.colorize ? c(color, text) : text;
+  }
+
+  print(text) {
+    this._write(text + '\n');
+  }
+
+  createTerminal(id, type, config) {
+    this.terminals[id] = {
+      type,
+      config,
+      data: [],
+    };
+
+    if (type === 'graph2d' || type === 'graph3d') {
+      this.hasGraphTerminals = true;
+
+      if (this.verbose) {
+        this._write(this._color('dim', `[Created ${type} terminal: ${config.title || id}]\n`));
+      }
+
+      // Notify about graph creation
+      if (this.onGraphCreated) {
+        this.onGraphCreated(id, type, config);
+      }
+    }
+  }
+
+  addToTerminal(id, data) {
+    const terminal = this.terminals[id];
+    if (!terminal) return;
+
+    const items = Array.isArray(data) ? data : [data];
+    terminal.data.push(...items);
+
+    // For console terminals, print lines
+    if (terminal.type === 'console') {
+      for (const item of items) {
+        this.print(String(item));
+      }
+    }
+  }
+
+  setTerminal(id, data) {
+    const terminal = this.terminals[id];
+    if (!terminal) return;
+
+    const items = Array.isArray(data) ? data : [data];
+    terminal.data = items;
+
+    // For console terminals, re-print all lines
+    // (This is mainly for interactive/REPL use)
+    if (terminal.type === 'console') {
+      for (const item of items) {
+        this.print(String(item));
+      }
+    }
+  }
+
+  clearTerminal(id) {
+    const terminal = this.terminals[id];
+    if (terminal) {
+      terminal.data = [];
+    }
+  }
+
+  error(message, location) {
+    let output = this._color('brightRed', 'Error: ');
+
+    if (location) {
+      const loc = `${location.file || '<script>'}:${location.line}:${location.column}`;
+      output += this._color('cyan', loc) + ' ';
+    }
+
+    output += message + '\n';
+    this._writeError(output);
+  }
+
+  finish(success, result) {
+    if (this.verbose) {
+      if (success) {
+        this._write(this._color('green', '\n✓ Execution completed successfully\n'));
+        if (result !== null && result !== undefined) {
+          this._write(this._color('dim', `Result: ${JSON.stringify(result)}\n`));
+        }
+      } else {
+        this._write(this._color('red', '\n✗ Execution failed\n'));
+      }
+    }
+  }
+
+  progress(info) {
+    if (this.verbose && !this.quiet) {
+      const { phase, message, percent } = info;
+      let output = this._color('dim', '[');
+
+      if (phase) output += phase;
+      if (message) output += ': ' + message;
+      if (percent !== undefined) output += ` (${percent}%)`;
+
+      output += this._color('dim', ']\n');
+      this._write(output);
+    }
+  }
+
+  /**
+   * Get all terminal data (for graph viewing)
+   * @returns {Object} Terminal data by ID
+   */
+  getTerminals() {
+    return this.terminals;
+  }
+
+  /**
+   * Check if there are any graph terminals
+   * @returns {boolean}
+   */
+  hasGraphs() {
+    return this.hasGraphTerminals;
+  }
+}
+
+export default CLIOutputAdapter;