rl-rockcli 0.0.9 → 0.0.11

package/commands/attach/ink-repl/builtinCommands.js

@@ -0,0 +1,1253 @@
+import { createRequire } from 'module';
+const require = createRequire(import.meta.url);
+
+const logger = require('../../../utils/logger');
+import { hasDangerousShellChars, shellEscapePosix } from './utils/remotePathSafety.js';
+import { formatUploadResult } from './utils/responseFormatter.js';
+import { friendlyErrorMessage } from './utils/parseError.js';
+
+/**
+ * Command help descriptions
+ */
+export const COMMAND_HELP = {
+  // Primary commands
+  status: 'Show sandbox status',
+  sessions: 'List attach sessions',
+    log: 'View sandbox logs. Usage: /log [-f file] [-k keyword] [-n lines]',
+  tail: 'View last lines of a file. Usage: /tail [-n lines] [-k keyword] [-f] <file>',
+  upload: 'Upload file/directory to sandbox. Usage: /upload @<local> @<remote>',
+  download: 'Download file from sandbox. Usage: /download @<remote> @<local>',
+  // Utility commands
+  stop: 'Stop the sandbox',
+  // resume: 'Resume a previous session. Usage: /resume [session-id]', // DISABLED
+  clear: 'Clear terminal screen',
+  stats: 'Show session statistics',
+  copy: 'Copy output of last command to clipboard',
+  about: 'Show about information',
+  retry: 'Retry last failed command',
+  theme: 'Switch UI theme. Usage: /theme <name> | /theme list',
+  'cleanup-history': 'Clean up history sessions. Usage: /cleanup-history [--sandbox <id>] [--all]',
+  // Meta commands
+  help: 'Show help message',
+  docs: 'Open documentation',
+  bug: 'Report a bug',
+  close: 'Close the session permanently and exit',
+  exit: 'Exit the REPL (session kept alive for resume)',
+};
+
+/**
+ * Command parameter templates for inline hints
+ * Used by paramHint.js to show placeholder text when user is typing commands
+ */
+export const COMMAND_PARAM_TEMPLATES = {
+  upload: {
+    template: '@<local> @<remote>',
+    params: [
+      { placeholder: '<local>', prefix: '@' },
+      { placeholder: '<remote>', prefix: '@' }
+    ]
+  },
+  download: {
+    template: '@<remote> @<local>',
+    params: [
+      { placeholder: '<remote>', prefix: '@' },
+      { placeholder: '<local>', prefix: '@' }
+    ]
+  }
+};
+
+function clampNumber(value, { min, max, fallback }) {
+  const num = Number(value);
+  if (!Number.isFinite(num)) return fallback;
+  return Math.max(min, Math.min(max, Math.floor(num)));
+}
+
+function isSafeLogFileName(name) {
+  if (!name) return false;
+  // Only allow basenames for Loghouse log file selection.
+  // For remote tail fallback, absolute paths are handled separately.
+  if (name.includes('/')) return false;
+  return /^[A-Za-z0-9._-]{1,128}$/.test(name);
+}
+
+function resolveRemoteLogPath(file) {
+  if (!file) return '/var/log/sandbox.log';
+  if (file.startsWith('/')) return file;
+  if (file === 'sandbox.log') return '/var/log/sandbox.log';
+  if (file === 'command.log') return '/data/logs/command.log';
+  return `/data/logs/${file}`;
+}
+
+/**
+ * Interactive commands that should be blocked
+ */
+export const INTERACTIVE_COMMANDS = {
+  vim: 'Use: cat <file> to view, or echo "content" > file to write',
+  vi: 'Use: cat <file> to view, or echo "content" > file to write',
+  nano: 'Use: cat <file> to view, or echo "content" > file to write',
+  emacs: 'Use: cat <file> to view, or echo "content" > file to write',
+  less: 'Use: cat <file> or head/tail <file>',
+  more: 'Use: cat <file> or head/tail <file>',
+  top: 'Use: ps aux | head -20, or top -b -n 1',
+  htop: 'Use: ps aux | head -20, or top -b -n 1',
+  tail: 'Use: tail -n 50 <file> (without -f)',
+  python: 'Try: python -c "print(1+1)" or python script.py',
+  python3: 'Try: python3 -c "print(1+1)" or python3 script.py',
+  node: 'Use: node -e "code" or node script.js',
+  mysql: 'Use: mysql -e "query" dbname',
+  psql: 'Use: psql -c "query" dbname',
+  ssh: 'SSH not supported in attach mode',
+  man: 'Use: command --help',
+  watch: 'Use command directly or in a loop',
+  irb: 'Use: ruby -e "code"',
+  bash: 'Already in bash shell',
+  sh: 'Already in shell',
+};
+
+/**
+ * Upload a directory recursively to sandbox
+ * @param {Object} ctx - Execution context
+ * @param {string} localDir - Local directory path (resolved)
+ * @param {string} remoteDir - Remote directory path
+ * @param {string} displayPath - Original path for display
+ * @returns {Promise<{ output: string, exitCode: number }>}
+ */
+async function uploadDirectory(ctx, localDir, remoteDir, displayPath) {
+  const fs = require('fs');
+  const path = require('path');
+
+  const uploadedFiles = [];
+  const errors = [];
+
+  // Ensure remote directory ends with /
+  const normalizedRemoteDir = remoteDir.endsWith('/') ? remoteDir : `${remoteDir}/`;
+
+  // Recursive function to collect all files
+  function collectFiles(dir, relativePath = '') {
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+    const files = [];
+
+    for (const entry of entries) {
+      const localPath = path.join(dir, entry.name);
+      const relPath = relativePath ? `${relativePath}/${entry.name}` : entry.name;
+
+      if (entry.isDirectory()) {
+        files.push(...collectFiles(localPath, relPath));
+      } else if (entry.isFile()) {
+        files.push({
+          localPath,
+          relativePath: relPath,
+          remotePath: `${normalizedRemoteDir}${relPath}`,
+        });
+      }
+    }
+
+    return files;
+  }
+
+  try {
+    const files = collectFiles(localDir);
+
+    if (files.length === 0) {
+      return { output: `Directory is empty: ${displayPath}`, exitCode: 0 };
+    }
+
+    // Upload each file
+    for (const file of files) {
+      try {
+        const result = await ctx.client.uploadFile(file.localPath, file.remotePath);
+        if (result.success) {
+          uploadedFiles.push(file.relativePath);
+        } else {
+          errors.push(`${file.relativePath}: ${result.message}`);
+        }
+      } catch (err) {
+        const errMessage = err?.message || (typeof err === 'string' ? err : 'Unknown error');
+        errors.push(`${file.relativePath}: ${errMessage}`);
+      }
+    }
+
+    // Build result message
+    const lines = [];
+    if (uploadedFiles.length > 0) {
+      lines.push(`✓ Uploaded ${uploadedFiles.length} file(s): ${displayPath} → ${remoteDir}`);
+      if (uploadedFiles.length <= 10) {
+        for (const f of uploadedFiles) {
+          lines.push(`  ✓ ${f}`);
+        }
+      } else {
+        for (const f of uploadedFiles.slice(0, 5)) {
+          lines.push(`  ✓ ${f}`);
+        }
+        lines.push(`  ... and ${uploadedFiles.length - 5} more`);
+      }
+    }
+
+    if (errors.length > 0) {
+      lines.push('');
+      lines.push(`✗ Failed to upload ${errors.length} file(s):`);
+      for (const e of errors.slice(0, 5)) {
+        lines.push(`  ✗ ${e}`);
+      }
+      if (errors.length > 5) {
+        lines.push(`  ... and ${errors.length - 5} more errors`);
+      }
+    }
+
+    return {
+      output: lines.join('\n'),
+      exitCode: errors.length > 0 ? 1 : 0,
+    };
+  } catch (error) {
+    return { output: `Failed to read directory: ${error.message}`, exitCode: 1 };
+  }
+}
+
+/**
+ * Builtin command handlers
+ * Each handler receives (context, args) and returns { output, exitCode }
+ */
+export const commandHandlers = {
+  /**
+   * /exit - Exit REPL
+   */
+  exit: async (ctx, args) => {
+    return { action: 'exit' };
+  },
+
+  /**
+   * /quit - Alias for exit
+   */
+  quit: async (ctx, args) => {
+    return { action: 'exit' };
+  },
+
+  /**
+   * /clear - Clear screen
+   */
+  clear: async (ctx, args) => {
+    return { action: 'clear' };
+  },
+
+  /**
+   * /help - Show help
+   */
+  help: async (ctx, args) => {
+    if (args.length > 0) {
+      const cmd = args[0].replace(/^\//, '');
+      if (COMMAND_HELP[cmd]) {
+        return { output: `/${cmd}: ${COMMAND_HELP[cmd]}`, exitCode: 0 };
+      }
+      return { output: `Unknown command: ${cmd}`, exitCode: 1 };
+    }
+
+    const lines = [
+      'Available commands:',
+      '',
+      'Builtin commands (start with /):',
+      ...Object.entries(COMMAND_HELP).map(([cmd, desc]) =>
+        `  /${cmd.padEnd(12)} ${desc}`
+      ),
+      '',
+      'Shell commands:',
+      '  Any command not starting with / is executed as a shell command.',
+      '  Examples: ls -la, cd /app, python script.py',
+      '',
+      'Tips:',
+      '  - Use Up/Down arrows to navigate history',
+      '  - Use Tab for auto-completion',
+      '  - Double Ctrl+C to exit',
+    ];
+
+    return { output: lines.join('\n'), exitCode: 0 };
+  },
+
+  /**
+   * /status - Show sandbox status
+   */
+  status: async (ctx, args) => {
+    try {
+      const status = await ctx.client.getStatus();
+
+      // Status indicator
+      const aliveIcon = status.isAlive ? '●' : '○';
+      const aliveText = status.isAlive ? 'Running' : 'Stopped';
+
+      // Stage status with icons
+      let stagesLine = '';
+      if (status.status) {
+        const stages = Object.entries(status.status);
+        const stageDisplay = stages.map(([stage, details]) => {
+          const s = details.status || 'unknown';
+          let icon = '?';
+          if (s === 'success') icon = '✓';
+          else if (s === 'failed' || s === 'error') icon = '✗';
+          else if (s === 'running' || s === 'pending') icon = '◐';
+          return `${icon} ${stage.replace(/_/g, ' ')}`;
+        });
+        stagesLine = stageDisplay.join('  ');
+      }
+
+      // Build compact status display
+      const lines = [
+        '',
+        `  ${aliveIcon} Sandbox ${aliveText}`,
+        '',
+        `     ID         ${ctx.sandboxId}`,
+        `     Cluster    ${status.cluster || 'N/A'}`,
+        `     Host       ${status.hostName || 'N/A'}`,
+        `     IP         ${status.hostIp || 'N/A'}`,
+      ];
+
+      if (stagesLine) {
+        lines.push(`     Stages     ${stagesLine}`);
+      }
+
+      lines.push('');
+
+      return { output: lines.join('\n'), exitCode: 0 };
+    } catch (error) {
+      // Error message is already user-friendly from getStatus()
+      return { output: error.message, exitCode: 1 };
+    }
+  },
+
+  /**
+   * /tail - View last lines of a file
+   */
+  tail: async (ctx, args) => {
+    let lines = 10;
+    let keyword = null;
+    let follow = false;
+    let filePath = null;
+
+    for (let i = 0; i < args.length; i++) {
+      if (args[i] === '-n' && args[i + 1]) {
+        lines = clampNumber(args[++i], { min: 1, max: 10000, fallback: 10 });
+      } else if (args[i] === '-k' && args[i + 1]) {
+        keyword = args[++i];
+      } else if (args[i] === '-f' || args[i] === '--follow') {
+        follow = true;
+      } else if (!args[i].startsWith('-')) {
+        filePath = args[i];
+      }
+    }
+
+    if (!filePath) {
+      return {
+        output: 'Usage: /tail [-n lines] [-k keyword] [-f] <file>\nExample: /tail /var/log/sandbox.log\n         /tail -n 50 -k error /var/log/sandbox.log',
+        exitCode: 1,
+      };
+    }
+
+    if (hasDangerousShellChars(filePath)) {
+      return { output: 'Invalid file path: dangerous characters detected', exitCode: 1 };
+    }
+
+    if (follow) {
+      // Follow mode requires interactive terminal, not supported in tests
+      return {
+        output: 'Follow mode (-f) is not supported in this environment. Use tail without -f.',
+        exitCode: 1,
+      };
+    }
+
+    try {
+      let command = `tail -n ${lines} -- ${shellEscapePosix(filePath)}`;
+      if (keyword) {
+        command = `${command} | grep -i -- ${shellEscapePosix(keyword)}`;
+      }
+
+      const result = await ctx.sessionManager.execute(command);
+
+      if (result.exit_code !== 0) {
+        const errorMsg = result.stderr || result.output || '';
+        if (errorMsg.includes('No such file') || errorMsg.includes('cannot access')) {
+          return { output: 'Failed to read file: file not found', exitCode: 1 };
+        }
+        return { output: `Failed to read file: ${errorMsg}`, exitCode: 1 };
+      }
+
+      const output = result.output || '';
+      if (!output.trim()) {
+        return { output: '(empty file)', exitCode: 0 };
+      }
+
+      return { output, exitCode: 0 };
+    } catch (error) {
+      return { output: `Failed to read file: ${error.message}`, exitCode: 1 };
+    }
+  },
+
+  /**
+   * /log - View sandbox logs
+   */
+  log: async (ctx, args) => {
+    let keyword = null;
+    let lines = 100;
+    let logFile = 'command.log';
+
+    for (let i = 0; i < args.length; i++) {
+      if (args[i] === '-k' && args[i + 1]) {
+        keyword = args[++i];
+      } else if (args[i] === '-n' && args[i + 1]) {
+        lines = clampNumber(args[++i], { min: 1, max: 5000, fallback: 100 });
+      } else if ((args[i] === '-f' || args[i] === '--file') && args[i + 1]) {
+        logFile = args[++i];
+      }
+    }
+
+    // Reject obvious shell injection for user-provided values. This is not an auto-triggered path,
+    // but we still keep it safe since it runs in the sandbox shell.
+    if (hasDangerousShellChars(logFile) || (keyword && hasDangerousShellChars(keyword))) {
+      return { output: 'Invalid log parameters.', exitCode: 1 };
+    }
+
+    try {
+      // Try Loghouse first (only supports safe basenames for logFile)
+      const safeLoghouseFile = isSafeLogFileName(logFile) ? logFile : null;
+      const handleLogSearch =
+        typeof ctx.handleLogSearch === 'function'
+          ? ctx.handleLogSearch
+          : require('../../log/search').handleLogSearch;
+
+      const searchArgv = {
+        sandboxId: ctx.sandboxId,
+        logFile: safeLoghouseFile || 'command.log',
+        minutes: 60,
+        limit: lines,
+        keyword: keyword || undefined,
+        raw: false,
+        highlight: true,
+        highlightSandboxId: false,
+        truncate: 200,
+      };
+
+      // Capture console output
+      const output = [];
+      const originalLog = console.log;
+      const originalError = console.error;
+
+      console.log = (...args) => output.push(args.join(' '));
+      console.error = (...args) => output.push(args.join(' '));
+
+      try {
+        await handleLogSearch(searchArgv);
+      } finally {
+        console.log = originalLog;
+        console.error = originalError;
+      }
+
+      if (output.length > 0) {
+        return { output: output.join('\n'), exitCode: 0 };
+      }
+      return { output: 'No logs found.', exitCode: 0 };
+    } catch (error) {
+      // Fallback to local log
+      try {
+        const remotePath = resolveRemoteLogPath(logFile);
+        if (hasDangerousShellChars(remotePath)) {
+          return { output: 'Invalid log file path.', exitCode: 1 };
+        }
+
+        let command = `tail -n ${lines} -- ${shellEscapePosix(remotePath)} 2>/dev/null`;
+        if (keyword) {
+          command = `${command} | grep -i -- ${shellEscapePosix(keyword)}`;
+        }
+        command = `${command} || echo ${shellEscapePosix(keyword ? 'No matching logs' : 'No logs available')}`;
+
+        const result = await ctx.sessionManager.execute(command);
+        return { output: result.output || 'No logs available', exitCode: 0 };
+      } catch (e) {
+        return { output: `Failed to get logs: ${e.message}`, exitCode: 1 };
+      }
+    }
+  },
+
+  /**
+   * /upload - Upload file or directory to sandbox
+   * Supports @ prefix for paths (e.g., /upload @local.txt @/remote.txt)
+   */
+  upload: async (ctx, args) => {
+    if (args.length < 2) {
+      return {
+        output: 'Usage: /upload @<local-path> @<remote-path>\nExample: /upload @./script.py @/app/script.py\n        /upload @./src/ @/app/src/',
+        exitCode: 1,
+      };
+    }
+
+    const fs = require('fs');
+    const path = require('path');
+
+    // Strip @ prefix from paths
+    const localPath = args[0].startsWith('@') ? args[0].slice(1) : args[0];
+    let remotePath = args[1].startsWith('@') ? args[1].slice(1) : args[1];
+
+    try {
+      const resolvedPath = path.resolve(localPath);
+      if (!fs.existsSync(resolvedPath)) {
+        return { output: `File not found: ${localPath}`, exitCode: 1 };
+      }
+
+      const stats = fs.statSync(resolvedPath);
+
+      if (stats.isDirectory()) {
+        // Upload directory recursively
+        const result = await uploadDirectory(ctx, resolvedPath, remotePath, localPath);
+        return result;
+      } else {
+        // If remote path ends with /, append the local filename
+        if (remotePath.endsWith('/')) {
+          remotePath = remotePath + path.basename(resolvedPath);
+        }
+        // Upload single file
+        const result = await ctx.client.uploadFile(resolvedPath, remotePath);
+        return formatUploadResult(result, { localPath, remotePath });
+      }
+    } catch (error) {
+      const errorMessage = error?.message || (typeof error === 'string' ? error : 'Unknown error');
+      return { output: `Upload failed: ${errorMessage}`, exitCode: 1 };
+    }
+  },
+
+  /**
+   * /download - Download file from sandbox
+   */
+  download: async (ctx, args) => {
+    if (args.length < 2) {
+      return {
+        output: 'Usage: /download @<remote-path> @<local-path>\nExample: /download @/app/output.txt @./output.txt',
+        exitCode: 1,
+      };
+    }
+
+    // Remove @ prefix from paths if present
+    let remotePath = args[0];
+    let localPath = args[1];
+    
+    if (remotePath.startsWith('@')) {
+      remotePath = remotePath.substring(1);
+    }
+    if (localPath.startsWith('@')) {
+      localPath = localPath.substring(1);
+    }
+
+    // Check for dangerous characters in remote path
+    if (hasDangerousShellChars(remotePath)) {
+      return { output: '✗ Download failed: Invalid characters in remote path', exitCode: 1 };
+    }
+
+    const fs = require('fs');
+    const path = require('path');
+
+    try {
+      // If localPath is a directory, append the remote filename
+      if (localPath.endsWith('/') || localPath === '.') {
+        const remoteFileName = path.basename(remotePath);
+        localPath = path.join(localPath, remoteFileName);
+      }
+
+      // Use cat command to read the entire file content (with escaped path)
+      const result = await ctx.sessionManager.execute(`cat -- ${shellEscapePosix(remotePath)}`);
+      
+      // Check exit_code (note: underscore format)
+      if (result.exit_code !== 0) {
+        const errorMsg = result.stderr || result.output || 'Failed to read file';
+        return { output: `✗ Download failed\n\nerror: ${errorMsg}`, exitCode: 1 };
+      }
+
+      const resolvedPath = path.resolve(localPath);
+      fs.writeFileSync(resolvedPath, result.output);
+
+      return { output: `✓ ${remotePath} → ${resolvedPath}`, exitCode: 0 };
+    } catch (error) {
+      return { output: `✗ Download failed\n\nerror: ${error.message}`, exitCode: 1 };
+    }
+  },
+
+  /**
+   * /stop - Stop the sandbox
+   */
+  stop: async (ctx, args) => {
+    try {
+      await ctx.client.stop();
+      return { output: 'Sandbox stopped.', exitCode: 0, action: 'exit' };
+    } catch (error) {
+      return { output: `Failed to stop sandbox: ${error.message}`, exitCode: 1 };
+    }
+  },
+
+  /**
+   * /sessions - List attach sessions
+   */
+  sessions: async (ctx, args) => {
+    if (!ctx.historyManager || typeof ctx.historyManager.listSessions !== 'function') {
+      return { output: 'Session history not available.', exitCode: 0 };
+    }
+
+    try {
+      const sessions = await ctx.historyManager.listSessions();
+
+      if (!sessions || !Array.isArray(sessions) || sessions.length === 0) {
+        return { output: 'No previous sessions found.', exitCode: 0 };
+      }
+
+      // Get terminal width from context (REPL environment) or fallback to process.stdout
+      const terminalWidth = ctx.terminalWidth || process.stdout.columns || 120;
+      
+      // opentui OutputBlock: marginLeft/Right=2 each (4 chars) + border=2 + paddingLeft/Right=1 each (2 chars) = 8 chars total
+      // ink OutputItem: border=2 + paddingLeft/Right=1 each (2 chars) = 4 chars total
+      // Use 8 chars to be safe for both modes (extra padding won't hurt)
+      const outputBoxPadding = 8;
+      const availableWidth = terminalWidth - outputBoxPadding;
+      
+      // Separator and content use the same available width
+      // All lines have '  ' prefix (2 chars)
+      const separatorWidth = availableWidth - 2;
+      
+      // Data rows format: '  ' + mark(' ★' or '  ') + ' ' + columns
+      // Total prefix width: 2 + 2 + 1 = 5 chars
+      const dataRowPrefixWidth = 5;
+      
+      // Available width for content columns
+      const contentWidth = availableWidth - dataRowPrefixWidth;
+
+      // Format date/time
+      const formatTime = (ts) => {
+        if (!ts) return '     --   ';
+        const d = new Date(ts);
+        return d.toLocaleString('zh-CN', {
+          month: '2-digit',
+          day: '2-digit',
+          hour: '2-digit',
+          minute: '2-digit',
+        });
+      };
+
+      // Calculate dynamic column widths
+      const timeWidth = 13; // "02/06 15:37" format
+      const spacing = 4;    // 4 spaces between each column
+      
+      // Minimum widths for column headers
+      const minSessionIdWidth = 'SESSION'.length; // 7
+      const minPathWidth = 'PATH'.length; // 4
+      
+      // Fixed width: time*2 + spacing*3 (between sessionId, created, updated, path)
+      const fixedWidth = timeWidth + timeWidth + spacing * 3;
+      const flexibleWidth = contentWidth - fixedWidth;
+      
+      // Split flexible width between session ID and path (70% session, 30% path)
+      // But ensure minimum widths for headers
+      const sessionIdWidth = Math.max(minSessionIdWidth, Math.floor(flexibleWidth * 0.7));
+      const pathWidth = Math.max(minPathWidth, flexibleWidth - sessionIdWidth);
+
+      const formatCwd = (cwd) => {
+        const safe = String(cwd || '/');
+        if (safe.length <= pathWidth) return safe.padEnd(pathWidth);
+        return `…${safe.slice(-(pathWidth - 1))}`;
+      };
+
+      // Get current session ID
+      const currentHistorySessionId = ctx.historyManager.sessionId || '';
+      const currentShellSessionName = ctx.sessionManager?.sessionId || '';
+
+      const separator = '─'.repeat(separatorWidth);
+      const lines = [
+        '',
+        '  Recent Sessions',
+        '  ' + separator,
+        // Header: 5 chars prefix + columns (PATH is padded to pathWidth)
+        '     ' + `${'SESSION'.padEnd(sessionIdWidth)}    ${'CREATED'.padEnd(timeWidth)}    ${'UPDATED'.padEnd(timeWidth)}    ${'PATH'.padEnd(pathWidth)}`,
+        '  ' + separator,
+      ];
+
+      for (const session of sessions.slice(0, 10)) {
+        const historySessionId = session.session_id || session.id || '-';
+        const shellSessionName = session.shell_session_name || '-';
+        const isCurrent = historySessionId === currentHistorySessionId ||
+          (currentShellSessionName && shellSessionName === currentShellSessionName);
+        const created = formatTime(session.created_at || session.start_time);
+        const updated = formatTime(session.updated_at || session.ended_at || session.created_at || session.start_time);
+        const cwd = formatCwd(session.work_dir || session.cwd || '/');
+
+        const sessionIdForAttach = shellSessionName && shellSessionName !== '-' ? shellSessionName : '-';
+        const currentMark = isCurrent ? ' ★' : '  ';
+        
+        // Format: '  ' + mark + ' ' + content
+        const sessionIdPadded = sessionIdForAttach.padEnd(sessionIdWidth);
+        lines.push(`  ${currentMark} ${sessionIdPadded}    ${created}    ${updated}    ${cwd}`);
+      }
+
+      lines.push('  ' + separator);
+      lines.push('');
+
+      // Debug: Add width info (remove this after debugging)
+      if (process.env.DEBUG_SESSIONS_WIDTH) {
+        lines.push(`  [Debug] Terminal width: ${terminalWidth}`);
+        lines.push(`  [Debug] Separator line length: ${('  ' + separator).length}`);
+        lines.push(`  [Debug] Expected: ${terminalWidth}, Actual: ${('  ' + separator).length}`);
+      }
+
+      return { output: lines.join('\n'), exitCode: 0 };
+    } catch (error) {
+      return { output: `Failed to list sessions: ${error.message}`, exitCode: 1 };
+    }
+  },
+
+  /**
+   * /cleanup-history - Clean up history sessions (keep current)
+   * Usage: /cleanup-history [--sandbox <id>] [--all]
+   */
+  'cleanup-history': async (ctx, args) => {
+    if (!ctx.historyManager) {
+      return { output: 'Session history not available.', exitCode: 1 };
+    }
+
+    const fs = require('fs');
+    const path = require('path');
+    const os = require('os');
+    const readline = require('readline');
+
+    let targetSandboxId = null;
+    let cleanupAll = false;
+    let skipConfirm = false;
+
+    for (let i = 0; i < args.length; i++) {
+      if (args[i] === '--sandbox' && args[i + 1]) {
+        targetSandboxId = args[++i];
+      } else if (args[i] === '--all') {
+        cleanupAll = true;
+      } else if (args[i] === '--confirm') {
+        skipConfirm = true;
+      }
+    }
+
+    try {
+      // Get sessions list
+      if (typeof ctx.historyManager.listSessions !== 'function') {
+        return { output: 'Session listing not available.', exitCode: 1 };
+      }
+
+      const allSessions = await ctx.historyManager.listSessions();
+      if (!allSessions || !Array.isArray(allSessions)) {
+        return { output: 'No sessions found.', exitCode: 0 };
+      }
+
+      // Get current session IDs
+      const currentHistorySessionId = ctx.historyManager.sessionId || '';
+      const currentShellSessionName = ctx.sessionManager?.sessionId || '';
+
+      // Filter sessions to clean (exclude current unless --all)
+      let sessionsToClean;
+      if (cleanupAll) {
+        sessionsToClean = allSessions;
+      } else {
+        sessionsToClean = allSessions.filter(session => {
+          const historyId = session.session_id || session.id || '';
+          const shellName = session.shell_session_name || '';
+          return historyId !== currentHistorySessionId && shellName !== currentShellSessionName;
+        });
+      }
+
+      if (sessionsToClean.length === 0) {
+        return { output: 'No sessions to clean up.', exitCode: 0 };
+      }
+
+      // Format session items for display (max 10)
+      const maxDisplay = 10;
+      const displaySessions = sessionsToClean.slice(0, maxDisplay);
+      const moreCount = sessionsToClean.length > maxDisplay ? sessionsToClean.length - maxDisplay : 0;
+
+      const formatTime = (ts) => {
+        if (!ts) return '     --   ';
+        const d = new Date(ts);
+        return d.toLocaleString('zh-CN', {
+          month: '2-digit',
+          day: '2-digit',
+          hour: '2-digit',
+          minute: '2-digit',
+        });
+      };
+
+      // Build output with session list
+      const lines = [
+        '',
+        `Found ${sessionsToClean.length} session${sessionsToClean.length !== 1 ? 's' : ''} to clean up:`,
+        '',
+        '  SESSION     CREATED      UPDATED      PATH',
+        '  ' + '─'.repeat(50),
+      ];
+
+      displaySessions.forEach(session => {
+        const sessionId = (session.session_id || session.id || '').slice(0, 8);
+        const created = formatTime(session.created_at || session.start_time);
+        const updated = formatTime(session.updated_at || session.ended_at);
+        const cwd = session.work_dir || session.cwd || '/';
+        lines.push(`  ${sessionId.padEnd(10)}  ${created}  ${updated}  ${cwd}`);
+      });
+
+      if (moreCount > 0) {
+        lines.push(`  ... and ${moreCount} more session${moreCount !== 1 ? 's' : ''}`);
+      }
+
+      lines.push('');
+
+      // Get user confirmation if not skipped
+      if (!skipConfirm) {
+        const rl = readline.createInterface({
+          input: process.stdin,
+          output: process.stdout
+        });
+
+        const answer = await new Promise((resolve) => {
+          rl.question(`Clean up ${sessionsToClean.length} session${sessionsToClean.length !== 1 ? 's' : ''}? (y/N): `, (input) => {
+            rl.close();
+            resolve(input.trim().toLowerCase());
+          });
+        });
+
+        if (answer !== 'y' && answer !== 'yes') {
+          return { output: 'Cleanup cancelled.', exitCode: 0 };
+        }
+      }
+
+      // Get sandbox directory
+      const sandboxId = targetSandboxId || ctx.historyManager.sandboxId;
+      const sandboxDir = targetSandboxId
+        ? path.join(os.homedir(), '.rock', 'history', targetSandboxId)
+        : ctx.historyManager._getSandboxDir();
+      const indexFile = path.join(sandboxDir, 'index.json');
+
+      // Read index
+      let index = { current_session: null, sessions: [] };
+      if (fs.existsSync(indexFile)) {
+        try {
+          index = JSON.parse(fs.readFileSync(indexFile, 'utf8'));
+        } catch (e) {
+          // Ignore parse errors
+        }
+      }
+
+      const currentSessionId = index.current_session || ctx.historyManager.sessionId;
+      const sessions = index.sessions || [];
+
+      // Determine which sessions to clean
+      let sessionsToCleanIds;
+      if (cleanupAll) {
+        sessionsToCleanIds = sessions.map(s => s.id);
+      } else {
+        sessionsToCleanIds = sessions.filter(s => s.id !== currentSessionId).map(s => s.id);
+      }
+
+      // Delete sessions
+      let success = 0;
+      let failed = 0;
+      for (const sessionId of sessionsToCleanIds) {
+        const sessionDir = path.join(sandboxDir, sessionId);
+        try {
+          if (fs.existsSync(sessionDir)) {
+            fs.rmSync(sessionDir, { recursive: true, force: true });
+            success++;
+          }
+        } catch (e) {
+          failed++;
+        }
+      }
+
+      // Update index
+      const newSessions = cleanupAll
+        ? []
+        : sessions.filter(s => s.id === currentSessionId);
+      fs.writeFileSync(indexFile, JSON.stringify({
+        sandbox_id: sandboxId,
+        current_session: cleanupAll ? null : currentSessionId,
+        sessions: newSessions
+      }, null, 2));
+
+      // Build output message
+      lines.push(`Cleaned up ${success} session${success !== 1 ? 's' : ''}${failed > 0 ? ` (${failed} failed)` : ''}`);
+      lines.push('');
+
+      return { output: lines.join('\n'), exitCode: 0 };
+    } catch (error) {
+      return { output: `Failed to cleanup history: ${error.message}`, exitCode: 1 };
+    }
+  },
+
+  /**
+   * /resume - Resume a previous session
+   * DISABLED: Use /sessions to view session history
+   */
+  /*
+  resume: async (ctx, args) => {
+    if (!ctx.historyManager) {
+      return { output: 'Session history not available.', exitCode: 0 };
+    }
+
+    try {
+      let sessionId = args[0];
+
+      if (!sessionId) {
+        // Get last session
+        if (typeof ctx.historyManager.listSessions !== 'function') {
+          return { output: 'Session listing not available.', exitCode: 0 };
+        }
+        const sessions = await ctx.historyManager.listSessions();
+        if (!sessions || !Array.isArray(sessions) || sessions.length < 2) {
+          return { output: 'No previous session to resume.', exitCode: 0 };
+        }
+        sessionId = sessions[1].session_id || sessions[1].id;
+      }
+
+      if (typeof ctx.historyManager.getSessionHistory !== 'function') {
+        return { output: 'Session history retrieval not available.', exitCode: 0 };
+      }
+      const history = await ctx.historyManager.getSessionHistory(sessionId);
+      if (!history || history.length === 0) {
+        return { output: `No commands found in session ${sessionId}`, exitCode: 0 };
+      }
+
+      const lines = [`Session ${sessionId.slice(0, 8)} history:`, ''];
+      for (const entry of history) {
+        lines.push(`  ${entry.command}`);
+      }
+
+      return { output: lines.join('\n'), exitCode: 0 };
+    } catch (error) {
+      return { output: `Failed to resume session: ${error.message}`, exitCode: 1 };
+    }
+  },
+  */
+
+  /**
+   * /stats - Show session statistics
+   */
+  stats: async (ctx, args) => {
+    const stats = ctx.stats || {};
+    const uptime = stats.startTime
+      ? Math.round((Date.now() - stats.startTime) / 1000)
+      : 0;
+
+    const lines = [
+      'Session Statistics:',
+      `  Uptime: ${uptime}s`,
+      `  Shell commands: ${stats.shellCommands || 0}`,
+      `  Builtin commands: ${stats.builtinCommands || 0}`,
+    ];
+
+    return { output: lines.join('\n'), exitCode: 0 };
+  },
+
+  theme: async (ctx, args) => {
+    const themeManager = ctx.themeManager;
+    const setTheme = ctx.setTheme;
+    if (!themeManager || !setTheme) {
+      return { output: 'Theme switching not available in this mode.', exitCode: 1 };
+    }
+
+    if (!args || args.length === 0 || args[0] === 'list') {
+      const current = ctx.themeName;
+      const available = themeManager.listThemes().map(t => `  - ${t.name}${t.name === current ? ' (current)' : ''}`);
+      return {
+        output: ['Available themes:', ...available, '', 'Usage: /theme <name>'].join('\n'),
+        exitCode: 0,
+      };
+    }
+
+    const target = args[0];
+    if (setTheme(target)) {
+      if (ctx.setUIConfig) {
+        await ctx.setUIConfig('theme', target);
+      }
+      return { output: `Theme switched to ${target}`, exitCode: 0 };
+    }
+
+    return { output: `Unknown theme: ${target}`, exitCode: 1 };
+  },
+
+  /**
+   * /copy - Copy last output to clipboard
+   */
+  copy: async (ctx, args) => {
+    if (!ctx.lastOutput) {
+      return { output: 'No output to copy.', exitCode: 0 };
+    }
+
+    try {
+      const { exec } = require('child_process');
+      const { promisify } = require('util');
+      const execAsync = promisify(exec);
+
+      // Detect OS and use appropriate clipboard command
+      const platform = process.platform;
+      let cmd;
+
+      if (platform === 'darwin') {
+        cmd = 'pbcopy';
+      } else if (platform === 'linux') {
+        cmd = 'xclip -selection clipboard';
+      } else {
+        return { output: 'Clipboard not supported on this platform.', exitCode: 1 };
+      }
+
+      await execAsync(cmd, { input: ctx.lastOutput });
+      return { output: 'Output copied to clipboard.', exitCode: 0 };
+    } catch (error) {
+      return { output: `Failed to copy: ${error.message}`, exitCode: 1 };
+    }
+  },
+
+  /**
+   * /about - Show about information
+   */
+  about: async (ctx, args) => {
+    const version = ctx.version || 'unknown';
+
+    // OSC 8 终端超链接格式: \e]8;;URL\a文本\e]8;;\a
+    // \e = ESC (\u001B), \a = BEL (\u0007)
+    const createHyperlink = (text, url) => {
+      return `\u001B]8;;${url}\u0007${text}\u001B]8;;\u0007`;
+    };
+
+    const docLink = createHyperlink('查看文档', 'https://rock-cli.io.example.com/docs/rock_cli_introduction');
+
+    // 格式化信息
+    const formatRow = (label, value) => {
+      return `  ${label.padEnd(6)} ${value}`;
+    };
+
+    const lines = [
+      '',
+      '  关于 ROCK CLI',
+      '',
+      formatRow('版本', version === 'unknown' ? '未知' : version),
+      formatRow('沙箱', ctx.sandboxId || '未知'),
+      formatRow('目录', process.cwd()),
+      '',
+      `  ${docLink}`,
+      '',
+    ];
+
+    return { output: lines.join('\n'), exitCode: 0 };
+  },
+
+  /**
+   * /docs - Open documentation
+   */
+  docs: async (ctx, args) => {
+    const url = 'https://rock-cli.io.example.com/docs/rock_cli_introduction';
+    const { exec } = require('child_process');
+
+    try {
+      const platform = process.platform;
+      if (platform === 'darwin') {
+        exec(`open ${url}`);
+      } else if (platform === 'linux') {
+        exec(`xdg-open ${url}`);
+      }
+      return { output: `Opening ${url}...`, exitCode: 0 };
+    } catch (error) {
+      return { output: `Visit: ${url}`, exitCode: 0 };
+    }
+  },
+
+  /**
+   * /bug - Report a bug
+   */
+  bug: async (ctx, args) => {
+    const url = 'https://project.aone.example.com/v2/project/2125004/req#viewIdentifier=d7f112f9d023e2108fa1b0d8';
+    const { exec } = require('child_process');
+
+    try {
+      const platform = process.platform;
+      if (platform === 'darwin') {
+        exec(`open ${url}`);
+      } else if (platform === 'linux') {
+        exec(`xdg-open ${url}`);
+      }
+      return { output: `Opening ${url}...`, exitCode: 0 };
+    } catch (error) {
+      return { output: `Visit: ${url}`, exitCode: 0 };
+    }
+  },
+
+  /**
+   * /retry - Retry last failed command
+   */
+  retry: async (ctx, args) => {
+    if (!ctx.lastCommand) {
+      return { output: 'No command to retry.', exitCode: 0 };
+    }
+
+    return { action: 'retry', command: ctx.lastCommand };
+  },
+
+  /**
+   * /close - Close session permanently and exit
+   */
+  close: async (ctx, args) => {
+    try {
+      const sessionId = ctx.sessionManager?.sessionId;
+      if (sessionId && ctx.client?.closeSession) {
+        await ctx.client.closeSession(sessionId);
+        return { output: 'Session closed.', exitCode: 0, action: 'exit' };
+      }
+      return { output: 'No active session to close.', exitCode: 0, action: 'exit' };
+    } catch (error) {
+      logger.debug(`Failed to close session: ${error.message}`);
+      return { output: `Warning: ${error.message}`, exitCode: 0, action: 'exit' };
+    }
+  },
+};
+
+/**
+ * Shell-like commands that work without / prefix
+ */
+const SHELL_BUILTINS = ['quit', 'exit', 'clear'];
+
+/**
+ * Check if input is a valid builtin command
+ * @param {string} input - User input
+ * @returns {boolean}
+ */
+export function isBuiltinCommand(input) {
+  if (!input) return false;
+
+  // Check /command format
+  if (input.startsWith('/')) {
+    const cmd = input.slice(1).split(/\s+/)[0].toLowerCase();
+    return cmd in commandHandlers;
+  }
+
+  // Check shell-like builtins (quit, exit, clear without /)
+  const cmd = input.trim().split(/\s+/)[0].toLowerCase();
+  return SHELL_BUILTINS.includes(cmd) && cmd in commandHandlers;
+}
+
+/**
+ * Parse builtin command
+ * @param {string} input - User input like "/log -n 50" or "quit"
+ * @returns {{ command: string, args: string[] }}
+ */
+export function parseBuiltinCommand(input) {
+  // Handle /command format
+  if (input.startsWith('/')) {
+    const parts = input.slice(1).split(/\s+/);
+    const command = parts[0].toLowerCase();
+    const args = parts.slice(1);
+    return { command, args };
+  }
+
+  // Handle shell-like builtins (quit, exit, clear)
+  const parts = input.trim().split(/\s+/);
+  const command = parts[0].toLowerCase();
+  const args = parts.slice(1);
+  return { command, args };
+}
+
+/**
+ * Execute a builtin command
+ * @param {string} input - User input like "/log -n 50"
+ * @param {Object} context - Execution context { client, sessionManager, historyManager, sandboxId, stats, lastCommand, lastOutput }
+ * @returns {Promise<{ output: string, exitCode: number, action?: string }>}
+ */
+export async function executeBuiltinCommand(input, context) {
+  const { command, args } = parseBuiltinCommand(input);
+
+  const handler = commandHandlers[command];
+  if (!handler) {
+    return {
+      output: `Unknown command: /${command}. Type / for available commands.`,
+      exitCode: 1,
+    };
+  }
+
+  try {
+    return await handler(context, args);
+  } catch (error) {
+    logger.debug(`Builtin command error: ${error.stack}`);
+    return {
+      output: `Error executing /${command}: ${friendlyErrorMessage(error.message)}`,
+      exitCode: 1,
+    };
+  }
+}
+
+/**
+ * Check if command is interactive (requires PTY)
+ * @param {string} command - Shell command
+ * @returns {{ isInteractive: boolean, cmdName: string, alternative: string|null }}
+ */
+export function checkInteractiveCommand(command) {
+  const parts = command.trim().split(/\s+/);
+  const fullCmd = parts[0] || '';
+  const cmdName = fullCmd.split('/').pop();
+
+  if (!(cmdName in INTERACTIVE_COMMANDS)) {
+    return { isInteractive: false, cmdName, alternative: null };
+  }
+
+  // Check for non-interactive flags
+  const nonInteractiveFlags = {
+    python: ['-c', '-m', '-V', '--version', '-h', '--help'],
+    python3: ['-c', '-m', '-V', '--version', '-h', '--help'],
+    node: ['-e', '-p', '-c', '-v', '--version', '-h', '--help', '--check'],
+    top: ['-b'],
+    mysql: ['-e', '--execute', '-V', '--version', '-h', '--help'],
+    psql: ['-c', '--command', '-V', '--version', '-h', '--help'],
+  };
+
+  if (nonInteractiveFlags[cmdName]) {
+    for (const flag of nonInteractiveFlags[cmdName]) {
+      if (parts.includes(flag)) {
+        return { isInteractive: false, cmdName, alternative: null };
+      }
+    }
+    // Check for --execute= or --command= format
+    if (cmdName === 'mysql' || cmdName === 'psql') {
+      for (const part of parts) {
+        if (part.startsWith('--execute=') || part.startsWith('--command=')) {
+          return { isInteractive: false, cmdName, alternative: null };
+        }
+      }
+    }
+  }
+
+  // tail -f is interactive
+  if (cmdName === 'tail') {
+    if (command.includes('-f') || command.includes('--follow')) {
+      return { isInteractive: true, cmdName, alternative: 'tail -n 50 <file>' };
+    }
+    return { isInteractive: false, cmdName, alternative: null };
+  }
+
+  // python/node/irb: only interactive when called with no arguments
+  if (['python', 'python3', 'node', 'irb'].includes(cmdName)) {
+    if (parts.length === 1) {
+      return { isInteractive: true, cmdName, alternative: INTERACTIVE_COMMANDS[cmdName] };
+    }
+    // Has arguments (script file or -c/-e), not interactive
+    return { isInteractive: false, cmdName, alternative: null };
+  }
+
+  // mysql/psql: interactive when called with no arguments or only database name
+  // Non-interactive when using -e/--execute (mysql) or -c/--command (psql)
+  if (['mysql', 'psql'].includes(cmdName)) {
+    if (parts.length === 1) {
+      return { isInteractive: true, cmdName, alternative: INTERACTIVE_COMMANDS[cmdName] };
+    }
+    // Already checked non-interactive flags above, so if we get here with args, check again
+    // If no non-interactive flag found, it's still interactive (e.g., mysql dbname)
+    return { isInteractive: true, cmdName, alternative: INTERACTIVE_COMMANDS[cmdName] };
+  }
+
+  // Always interactive commands (no non-interactive mode)
+  // Note: top is here because -b check happens before this
+  // Note: mysql and psql removed - they have -e/--execute and -c/--command non-interactive modes
+  const alwaysInteractive = ['vim', 'vi', 'nano', 'emacs', 'less', 'more', 'top', 'htop', 'ssh', 'man', 'watch', 'bash', 'sh'];
+  if (alwaysInteractive.includes(cmdName)) {
+    return { isInteractive: true, cmdName, alternative: INTERACTIVE_COMMANDS[cmdName] };
+  }
+
+  return { isInteractive: false, cmdName, alternative: null };
+}