mrmd-js 2.0.0

package/src/types/execution.js

@@ -0,0 +1,62 @@
+/**
+ * Execution Types
+ *
+ * Types for code execution (MRP /execute endpoints).
+ * @module types/execution
+ */
+
+/**
+ * @typedef {Object} ExecuteOptions
+ * @property {string} [session='default'] - Session ID
+ * @property {string} [language] - Language override
+ * @property {boolean} [storeHistory=true] - Add to execution history
+ * @property {boolean} [silent=false] - Suppress output
+ * @property {string} [execId] - Unique execution identifier
+ * @property {string} [cellId] - Cell identifier (for linking)
+ * @property {Record<string, *>} [cellMeta] - Metadata from code fence
+ */
+
+/**
+ * @typedef {Object} ExecutionResult
+ * @property {boolean} success - Whether execution succeeded
+ * @property {string} stdout - Standard output (console.log, etc.)
+ * @property {string} stderr - Standard error (console.error, etc.)
+ * @property {*} [result] - Return value (raw)
+ * @property {string} [resultString] - Return value (formatted string)
+ * @property {ExecutionError} [error] - Error information if failed
+ * @property {DisplayData[]} displayData - Rich display outputs
+ * @property {Asset[]} assets - Generated assets
+ * @property {number} executionCount - Execution count in session
+ * @property {number} duration - Execution duration in milliseconds
+ * @property {string[]} [imports] - Detected imports
+ */
+
+/**
+ * @typedef {Object} ExecutionError
+ * @property {string} type - Error type/class name
+ * @property {string} message - Error message
+ * @property {string[]} [traceback] - Stack trace lines
+ * @property {number} [line] - Line number where error occurred
+ * @property {number} [column] - Column number where error occurred
+ */
+
+/**
+ * @typedef {Object} DisplayData
+ * @property {Record<string, string>} data - MIME type → content mapping
+ * @property {Record<string, *>} metadata - Additional metadata
+ */
+
+/**
+ * @typedef {'image' | 'html' | 'json' | 'other'} AssetType
+ */
+
+/**
+ * @typedef {Object} Asset
+ * @property {string} path - Asset path/identifier
+ * @property {string} url - URL to access asset (blob URL in browser)
+ * @property {string} mimeType - MIME type
+ * @property {AssetType} assetType - Asset type category
+ * @property {number} [size] - Size in bytes
+ */
+
+export {};

package/src/types/index.js

@@ -0,0 +1,16 @@
+/**
+ * Type Definitions
+ *
+ * All MRP type definitions exported from one place.
+ * @module types
+ */
+
+// Re-export all types
+export * from './capabilities.js';
+export * from './session.js';
+export * from './execution.js';
+export * from './streaming.js';
+export * from './completion.js';
+export * from './inspection.js';
+export * from './variables.js';
+export * from './analysis.js';

package/src/types/inspection.js

@@ -0,0 +1,39 @@
+/**
+ * Inspection Types
+ *
+ * Types for symbol inspection (MRP /inspect and /hover endpoints).
+ * @module types/inspection
+ */
+
+/**
+ * @typedef {Object} InspectOptions
+ * @property {string} [session] - Session ID
+ * @property {0 | 1 | 2} [detail=0] - Detail level: 0=signature, 1=+docs, 2=+source
+ */
+
+/**
+ * @typedef {Object} InspectResult
+ * @property {boolean} found - Whether symbol was found
+ * @property {'runtime' | 'lsp' | 'static'} source - Where info came from
+ * @property {string} [name] - Symbol name
+ * @property {string} [kind] - Symbol kind
+ * @property {string} [type] - Type string
+ * @property {string} [signature] - Function/method signature
+ * @property {string} [docstring] - Documentation string
+ * @property {string} [sourceCode] - Source code (if available)
+ * @property {string} [file] - File where defined
+ * @property {number} [line] - Line number
+ * @property {string} [value] - Value preview
+ * @property {import('./variables.js').VariableInfo[]} [children] - Children for expandable
+ */
+
+/**
+ * @typedef {Object} HoverResult
+ * @property {boolean} found - Whether info was found
+ * @property {string} [name] - Symbol name
+ * @property {string} [type] - Type string
+ * @property {string} [value] - Value preview
+ * @property {string} [signature] - Function signature
+ */
+
+export {};

package/src/types/session.js

@@ -0,0 +1,32 @@
+/**
+ * Session Types
+ *
+ * Types for session management (MRP /sessions endpoints).
+ * @module types/session
+ */
+
+/**
+ * @typedef {'iframe' | 'worker' | 'none'} IsolationMode
+ */
+
+/**
+ * @typedef {Object} SessionInfo
+ * @property {string} id - Unique session identifier
+ * @property {string} language - Primary language for this session
+ * @property {string} created - ISO timestamp of creation
+ * @property {string} lastActivity - ISO timestamp of last activity
+ * @property {number} executionCount - Number of executions
+ * @property {number} variableCount - Number of variables in namespace
+ * @property {IsolationMode} isolation - Session isolation mode
+ */
+
+/**
+ * @typedef {Object} CreateSessionOptions
+ * @property {string} [id] - Session ID (generated if not provided)
+ * @property {string} [language='javascript'] - Primary language
+ * @property {IsolationMode} [isolation='iframe'] - Isolation mode
+ * @property {boolean} [allowMainAccess=false] - Allow access to main document
+ * @property {Record<string, *>} [utilities] - Custom utilities to inject
+ */
+
+export {};

package/src/types/streaming.js

@@ -0,0 +1,74 @@
+/**
+ * Streaming Types
+ *
+ * Types for streaming execution (MRP /execute/stream endpoint).
+ * @module types/streaming
+ */
+
+/**
+ * @typedef {StartEvent | StdoutEvent | StderrEvent | StdinRequestEvent | DisplayEvent | AssetEvent | ResultEvent | ErrorEvent | DoneEvent} StreamEvent
+ */
+
+/**
+ * @typedef {Object} StartEvent
+ * @property {'start'} type
+ * @property {string} execId
+ * @property {string} timestamp
+ */
+
+/**
+ * @typedef {Object} StdoutEvent
+ * @property {'stdout'} type
+ * @property {string} content
+ * @property {string} accumulated
+ */
+
+/**
+ * @typedef {Object} StderrEvent
+ * @property {'stderr'} type
+ * @property {string} content
+ * @property {string} accumulated
+ */
+
+/**
+ * @typedef {Object} StdinRequestEvent
+ * @property {'stdin_request'} type
+ * @property {string} prompt
+ * @property {boolean} password
+ * @property {string} execId
+ */
+
+/**
+ * @typedef {Object} DisplayEvent
+ * @property {'display'} type
+ * @property {Record<string, string>} data
+ * @property {Record<string, *>} metadata
+ */
+
+/**
+ * @typedef {Object} AssetEvent
+ * @property {'asset'} type
+ * @property {string} path
+ * @property {string} url
+ * @property {string} mimeType
+ * @property {string} assetType
+ */
+
+/**
+ * @typedef {Object} ResultEvent
+ * @property {'result'} type
+ * @property {import('./execution.js').ExecutionResult} result
+ */
+
+/**
+ * @typedef {Object} ErrorEvent
+ * @property {'error'} type
+ * @property {import('./execution.js').ExecutionError} error
+ */
+
+/**
+ * @typedef {Object} DoneEvent
+ * @property {'done'} type
+ */
+
+export {};

package/src/types/variables.js

@@ -0,0 +1,54 @@
+/**
+ * Variables Types
+ *
+ * Types for variable inspection (MRP /variables endpoints).
+ * @module types/variables
+ */
+
+/**
+ * @typedef {Object} VariableFilter
+ * @property {string[]} [types] - Only include these types
+ * @property {string} [namePattern] - Name must match this regex
+ * @property {boolean} [excludePrivate] - Exclude names starting with _
+ */
+
+/**
+ * @typedef {Object} VariableInfo
+ * @property {string} name - Variable name
+ * @property {string} type - Type string
+ * @property {string} value - Value preview (truncated)
+ * @property {string} [size] - Size description (e.g., "1.2 KB")
+ * @property {boolean} expandable - Whether this can be expanded
+ * @property {number[]} [shape] - Shape for arrays/matrices
+ * @property {string} [dtype] - Data type for typed arrays
+ * @property {number} [length] - Length for arrays/strings
+ * @property {string[]} [keys] - Keys for objects/maps
+ */
+
+/**
+ * @typedef {Object} VariableDetailOptions
+ * @property {string} [session] - Session ID
+ * @property {string[]} [path] - Path to drill into
+ * @property {number} [maxChildren=100] - Max children to return
+ * @property {number} [maxValueLength=1000] - Max chars for value strings
+ */
+
+/**
+ * @typedef {Object} VariableDetail
+ * @property {string} name - Variable name
+ * @property {string} type - Type string
+ * @property {string} value - Value preview
+ * @property {string} [size] - Size description
+ * @property {boolean} expandable - Whether expandable
+ * @property {number[]} [shape] - Shape for arrays
+ * @property {string} [dtype] - Data type
+ * @property {number} [length] - Length
+ * @property {string[]} [keys] - Keys
+ * @property {string} [fullValue] - Full value (up to maxValueLength)
+ * @property {VariableInfo[]} [children] - Child items
+ * @property {string[]} [methods] - Available methods
+ * @property {string[]} [attributes] - Available attributes
+ * @property {boolean} truncated - Whether results were truncated
+ */
+
+export {};

package/src/utils/ansi-renderer.js

@@ -0,0 +1,301 @@
+/**
+ * ANSI to HTML Renderer
+ *
+ * Converts ANSI escape sequences to HTML with appropriate styling.
+ * Useful for rendering terminal output from code execution.
+ *
+ * @module utils/ansi-renderer
+ */
+
+/**
+ * @typedef {Object} AnsiStyle
+ * @property {string} [color] - Foreground color
+ * @property {string} [background] - Background color
+ * @property {boolean} [bold] - Bold text
+ * @property {boolean} [dim] - Dim text
+ * @property {boolean} [italic] - Italic text
+ * @property {boolean} [underline] - Underlined text
+ * @property {boolean} [strikethrough] - Strikethrough text
+ * @property {boolean} [inverse] - Inverse colors
+ */
+
+/**
+ * ANSI color codes to CSS colors
+ */
+const COLORS = {
+  30: '#000000', // Black
+  31: '#cc0000', // Red
+  32: '#00cc00', // Green
+  33: '#cccc00', // Yellow
+  34: '#0000cc', // Blue
+  35: '#cc00cc', // Magenta
+  36: '#00cccc', // Cyan
+  37: '#cccccc', // White
+  90: '#666666', // Bright Black (Gray)
+  91: '#ff0000', // Bright Red
+  92: '#00ff00', // Bright Green
+  93: '#ffff00', // Bright Yellow
+  94: '#0000ff', // Bright Blue
+  95: '#ff00ff', // Bright Magenta
+  96: '#00ffff', // Bright Cyan
+  97: '#ffffff', // Bright White
+};
+
+const BG_COLORS = {
+  40: '#000000',
+  41: '#cc0000',
+  42: '#00cc00',
+  43: '#cccc00',
+  44: '#0000cc',
+  45: '#cc00cc',
+  46: '#00cccc',
+  47: '#cccccc',
+  100: '#666666',
+  101: '#ff0000',
+  102: '#00ff00',
+  103: '#ffff00',
+  104: '#0000ff',
+  105: '#ff00ff',
+  106: '#00ffff',
+  107: '#ffffff',
+};
+
+/**
+ * ANSI Renderer class
+ */
+export class AnsiRenderer {
+  /** @type {boolean} */
+  #escapeHtml = true;
+
+  /**
+   * Create ANSI renderer
+   * @param {{ escapeHtml?: boolean }} [options]
+   */
+  constructor(options = {}) {
+    this.#escapeHtml = options.escapeHtml !== false;
+  }
+
+  /**
+   * Convert ANSI text to HTML
+   *
+   * @param {string} text - Text with ANSI escape sequences
+   * @returns {string} HTML string
+   */
+  render(text) {
+    if (!text) return '';
+
+    /** @type {AnsiStyle} */
+    let currentStyle = {};
+    const parts = [];
+    let currentText = '';
+
+    // ANSI escape sequence regex
+    const ansiRegex = /\x1b\[([0-9;]*)m/g;
+    let lastIndex = 0;
+    let match;
+
+    while ((match = ansiRegex.exec(text)) !== null) {
+      // Add text before this escape sequence
+      const beforeText = text.slice(lastIndex, match.index);
+      if (beforeText) {
+        currentText += beforeText;
+      }
+
+      // Parse codes
+      const codes = match[1].split(';').map(c => parseInt(c, 10) || 0);
+
+      // Flush current text with current style
+      if (currentText) {
+        parts.push(this.#wrapWithStyle(currentText, currentStyle));
+        currentText = '';
+      }
+
+      // Update style based on codes
+      currentStyle = this.#updateStyle(currentStyle, codes);
+
+      lastIndex = ansiRegex.lastIndex;
+    }
+
+    // Add remaining text
+    const remainingText = text.slice(lastIndex);
+    if (remainingText) {
+      currentText += remainingText;
+    }
+
+    if (currentText) {
+      parts.push(this.#wrapWithStyle(currentText, currentStyle));
+    }
+
+    return parts.join('');
+  }
+
+  /**
+   * Render to a DOM element
+   *
+   * @param {string} text - ANSI text
+   * @param {HTMLElement} container - Target container
+   * @param {{ clear?: boolean }} [options]
+   */
+  renderTo(text, container, options = {}) {
+    const html = this.render(text);
+
+    if (options.clear !== false) {
+      container.innerHTML = '';
+    }
+
+    const wrapper = document.createElement('pre');
+    wrapper.className = 'ansi-output';
+    wrapper.innerHTML = html;
+    container.appendChild(wrapper);
+  }
+
+  /**
+   * Update style based on ANSI codes
+   * @param {AnsiStyle} style
+   * @param {number[]} codes
+   * @returns {AnsiStyle}
+   */
+  #updateStyle(style, codes) {
+    const newStyle = { ...style };
+
+    for (const code of codes) {
+      if (code === 0) {
+        // Reset all
+        return {};
+      } else if (code === 1) {
+        newStyle.bold = true;
+      } else if (code === 2) {
+        newStyle.dim = true;
+      } else if (code === 3) {
+        newStyle.italic = true;
+      } else if (code === 4) {
+        newStyle.underline = true;
+      } else if (code === 7) {
+        newStyle.inverse = true;
+      } else if (code === 9) {
+        newStyle.strikethrough = true;
+      } else if (code === 22) {
+        newStyle.bold = false;
+        newStyle.dim = false;
+      } else if (code === 23) {
+        newStyle.italic = false;
+      } else if (code === 24) {
+        newStyle.underline = false;
+      } else if (code === 27) {
+        newStyle.inverse = false;
+      } else if (code === 29) {
+        newStyle.strikethrough = false;
+      } else if (code === 39) {
+        delete newStyle.color;
+      } else if (code === 49) {
+        delete newStyle.background;
+      } else if (code >= 30 && code <= 37) {
+        newStyle.color = COLORS[code];
+      } else if (code >= 40 && code <= 47) {
+        newStyle.background = BG_COLORS[code];
+      } else if (code >= 90 && code <= 97) {
+        newStyle.color = COLORS[code];
+      } else if (code >= 100 && code <= 107) {
+        newStyle.background = BG_COLORS[code];
+      }
+      // TODO: 256 color and RGB support (38;5;n and 38;2;r;g;b)
+    }
+
+    return newStyle;
+  }
+
+  /**
+   * Wrap text with style span
+   * @param {string} text
+   * @param {AnsiStyle} style
+   * @returns {string}
+   */
+  #wrapWithStyle(text, style) {
+    // Escape HTML if needed
+    let escaped = text;
+    if (this.#escapeHtml) {
+      escaped = text
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&#39;');
+    }
+
+    // No style needed
+    if (Object.keys(style).length === 0) {
+      return escaped;
+    }
+
+    // Build inline style
+    const styles = [];
+
+    if (style.color) {
+      styles.push(`color:${style.color}`);
+    }
+    if (style.background) {
+      styles.push(`background-color:${style.background}`);
+    }
+    if (style.bold) {
+      styles.push('font-weight:bold');
+    }
+    if (style.dim) {
+      styles.push('opacity:0.5');
+    }
+    if (style.italic) {
+      styles.push('font-style:italic');
+    }
+    if (style.underline) {
+      styles.push('text-decoration:underline');
+    }
+    if (style.strikethrough) {
+      if (style.underline) {
+        styles.push('text-decoration:underline line-through');
+      } else {
+        styles.push('text-decoration:line-through');
+      }
+    }
+
+    if (styles.length === 0) {
+      return escaped;
+    }
+
+    return `<span style="${styles.join(';')}">${escaped}</span>`;
+  }
+
+  /**
+   * Strip ANSI codes from text
+   * @param {string} text
+   * @returns {string}
+   */
+  static strip(text) {
+    return text.replace(/\x1b\[[0-9;]*m/g, '');
+  }
+}
+
+/**
+ * Convert ANSI text to HTML (convenience function)
+ * @param {string} text
+ * @returns {string}
+ */
+export function ansiToHtml(text) {
+  return new AnsiRenderer().render(text);
+}
+
+/**
+ * Strip ANSI codes (convenience function)
+ * @param {string} text
+ * @returns {string}
+ */
+export function stripAnsi(text) {
+  return AnsiRenderer.strip(text);
+}
+
+/**
+ * Create an ANSI renderer
+ * @param {{ escapeHtml?: boolean }} [options]
+ * @returns {AnsiRenderer}
+ */
+export function createAnsiRenderer(options) {
+  return new AnsiRenderer(options);
+}