@runloop/rl-cli 0.1.2 → 0.2.0

package/dist/utils/output.js

@@ -1,17 +1,98 @@
 /**
  * Utility for handling different output formats across CLI commands
+ *
+ * Simple API:
+ * - output(data, options) - outputs data in specified format
+ * - outputError(message, error) - outputs error and exits
  */
 import YAML from "yaml";
 /**
- * Check if the command should use non-interactive output
+ * Resolve the output format from options
  */
-export function shouldUseNonInteractiveOutput(options) {
-    return !!options.output && options.output !== "interactive";
+function resolveFormat(options) {
+    const format = options.format || options.defaultFormat || "json";
+    if (format === "json" || format === "yaml" || format === "text") {
+        return format;
+    }
+    console.error(`Unknown output format: ${format}. Valid options: text, json, yaml`);
+    process.exit(1);
 }
 /**
- * Output data in the specified format
+ * Format a value for text output (key-value pairs)
  */
-export function outputData(data, format = "json") {
+function formatKeyValue(data, indent = 0) {
+    const prefix = "  ".repeat(indent);
+    if (data === null || data === undefined) {
+        return `${prefix}(none)`;
+    }
+    if (typeof data === "string" ||
+        typeof data === "number" ||
+        typeof data === "boolean") {
+        return String(data);
+    }
+    if (Array.isArray(data)) {
+        if (data.length === 0) {
+            return `${prefix}(empty)`;
+        }
+        // For arrays of primitives, join them
+        if (data.every((item) => typeof item !== "object" || item === null)) {
+            return data.join(", ");
+        }
+        // For arrays of objects, format each with separator
+        return data
+            .map((item) => {
+            if (typeof item === "object" && item !== null) {
+                const lines = [];
+                for (const [key, value] of Object.entries(item)) {
+                    if (value !== null && value !== undefined) {
+                        const formattedValue = typeof value === "object"
+                            ? formatKeyValue(value, indent + 1)
+                            : String(value);
+                        lines.push(`${prefix}${key}: ${formattedValue}`);
+                    }
+                }
+                return lines.join("\n");
+            }
+            return `${prefix}${item}`;
+        })
+            .join(`\n${prefix}---\n`);
+    }
+    if (typeof data === "object") {
+        const lines = [];
+        for (const [key, value] of Object.entries(data)) {
+            if (value !== null && value !== undefined) {
+                if (typeof value === "object" && !Array.isArray(value)) {
+                    lines.push(`${prefix}${key}:`);
+                    lines.push(formatKeyValue(value, indent + 1));
+                }
+                else if (Array.isArray(value)) {
+                    lines.push(`${prefix}${key}: ${formatKeyValue(value, 0)}`);
+                }
+                else {
+                    lines.push(`${prefix}${key}: ${value}`);
+                }
+            }
+        }
+        return lines.join("\n");
+    }
+    return String(data);
+}
+/**
+ * Main output function - outputs data in the specified format
+ *
+ * @param data - The data to output
+ * @param options - Output options (format, defaultFormat)
+ *
+ * @example
+ * // Output a devbox as text (default for single items)
+ * output(devbox, { format: options.output, defaultFormat: 'text' });
+ *
+ * @example
+ * // Output a list as JSON (default for lists)
+ * output(devboxes, { format: options.output, defaultFormat: 'json' });
+ */
+export function output(data, options = {}) {
+    const format = resolveFormat(options);
     if (format === "json") {
         console.log(JSON.stringify(data, null, 2));
         return;
@@ -20,49 +101,78 @@ export function outputData(data, format = "json") {
         console.log(YAML.stringify(data));
         return;
     }
-    if (format === "text") {
-        // Simple text output
-        if (Array.isArray(data)) {
-            // For lists of complex objects, just output IDs
-            data.forEach((item) => {
-                if (typeof item === "object" && item !== null && "id" in item) {
-                    console.log(item.id);
-                }
-                else {
-                    console.log(formatTextOutput(item));
-                }
-            });
-        }
-        else {
-            console.log(formatTextOutput(data));
-        }
-        return;
+    // Text format - key-value pairs
+    console.log(formatKeyValue(data));
+}
+/**
+ * Output an error message and exit
+ *
+ * @param message - Human-readable error message
+ * @param error - Optional Error object with details
+ *
+ * @example
+ * outputError('Failed to get devbox', error);
+ */
+export function outputError(message, error) {
+    const errorMessage = error instanceof Error ? error.message : String(error || message);
+    console.error(`Error: ${message}`);
+    if (error && errorMessage !== message) {
+        console.error(`  ${errorMessage}`);
     }
-    console.error(`Unknown output format: ${format}`);
     process.exit(1);
 }
 /**
- * Format a single item as text output
+ * Output a success message for action commands
+ *
+ * @param message - Success message
+ * @param data - Optional data to include
+ * @param options - Output options
  */
-function formatTextOutput(item) {
-    if (typeof item === "string") {
-        return item;
-    }
-    // For objects, create a simple key: value format
-    const lines = [];
-    for (const [key, value] of Object.entries(item)) {
-        if (value !== null && value !== undefined) {
-            lines.push(`${key}: ${value}`);
-        }
+export function outputSuccess(message, data, options = {}) {
+    const format = resolveFormat(options);
+    if (format === "json") {
+        console.log(JSON.stringify({
+            success: true,
+            message,
+            ...(data && typeof data === "object" ? data : { data }),
+        }, null, 2));
+        return;
+    }
+    if (format === "yaml") {
+        console.log(YAML.stringify({
+            success: true,
+            message,
+            ...(data && typeof data === "object" ? data : { data }),
+        }));
+        return;
+    }
+    // Text format
+    console.log(`✓ ${message}`);
+    if (data) {
+        console.log(formatKeyValue(data));
     }
-    return lines.join("\n");
 }
+// ============================================================================
+// Legacy API (for backward compatibility during migration)
+// ============================================================================
 /**
- * Output a single result (for create, delete, etc)
+ * @deprecated Use output() instead
+ */
+export function shouldUseNonInteractiveOutput(options) {
+    return !!options.output && options.output !== "interactive";
+}
+/**
+ * @deprecated Use output() instead
+ */
+export function outputData(data, format = "json") {
+    output(data, { format, defaultFormat: format });
+}
+/**
+ * @deprecated Use output() instead
  */
 export function outputResult(result, options, successMessage) {
     if (shouldUseNonInteractiveOutput(options)) {
-        outputData(result, options.output);
+        output(result, { format: options.output, defaultFormat: "text" });
         return;
     }
     // Interactive mode - print success message
@@ -71,34 +181,15 @@ export function outputResult(result, options, successMessage) {
     }
 }
 /**
- * Output a list of items (for list commands)
+ * @deprecated Use output() instead
  */
 export function outputList(items, options) {
     if (shouldUseNonInteractiveOutput(options)) {
-        outputData(items, options.output);
-    }
-}
-/**
- * Handle errors in both interactive and non-interactive modes
- */
-export function outputError(error, options) {
-    if (shouldUseNonInteractiveOutput(options)) {
-        if (options.output === "json") {
-            console.error(JSON.stringify({ error: error.message }, null, 2));
-        }
-        else if (options.output === "yaml") {
-            console.error(YAML.stringify({ error: error.message }));
-        }
-        else {
-            console.error(`Error: ${error.message}`);
-        }
-        process.exit(1);
+        output(items, { format: options.output, defaultFormat: "json" });
     }
-    // Let interactive UI handle the error
-    throw error;
 }
 /**
- * Validate output format option
+ * @deprecated Use validateOutputFormat with the new output() function
  */
 export function validateOutputFormat(format) {
     if (!format || format === "text") {

package/dist/utils/screen.js

@@ -0,0 +1,23 @@
+/**
+ * Terminal screen buffer utilities.
+ *
+ * The alternate screen buffer provides a fullscreen experience similar to
+ * applications like vim, top, or htop. When enabled, the terminal saves
+ * the current screen content and switches to a clean buffer. Upon exit,
+ * the original screen content is restored.
+ */
+/**
+ * Enter the alternate screen buffer.
+ * This provides a fullscreen experience where content won't mix with
+ * previous terminal output. Like vim or top.
+ */
+export function enterAlternateScreenBuffer() {
+    process.stdout.write("\x1b[?1049h");
+}
+/**
+ * Exit the alternate screen buffer and restore the previous screen content.
+ * This returns the terminal to its original state before enterAlternateScreen() was called.
+ */
+export function exitAlternateScreenBuffer() {
+    process.stdout.write("\x1b[?1049l");
+}

package/dist/utils/ssh.js

@@ -99,7 +99,9 @@ export function getSSHUrl() {
  */
 export function getProxyCommand() {
     const sshUrl = getSSHUrl();
-    return `openssl s_client -quiet -verify_quiet -servername %h -connect ${sshUrl} 2>/dev/null`;
+    // macOS openssl doesn't support -verify_quiet, use compatible flags
+    // servername should be %h (target hostname) - SSH will replace %h with the actual hostname from the SSH command
+    return `openssl s_client -quiet -servername %h -connect ${sshUrl} 2>/dev/null`;
 }
 /**
  * Execute SSH command

package/dist/utils/sshSession.js

@@ -1,29 +1,5 @@
-import { spawnSync } from "child_process";
-export async function runSSHSession(config) {
-    // Reset terminal to fix input visibility issues
-    // This ensures the terminal is in a proper state after exiting Ink
-    spawnSync("reset", [], { stdio: "inherit" });
-    console.clear();
-    console.log(`\nConnecting to devbox ${config.devboxName}...\n`);
-    // Spawn SSH in foreground with proper terminal settings
-    const result = spawnSync("ssh", [
-        "-t", // Force pseudo-terminal allocation for proper input handling
-        "-i",
-        config.keyPath,
-        "-o",
-        `ProxyCommand=${config.proxyCommand}`,
-        "-o",
-        "StrictHostKeyChecking=no",
-        "-o",
-        "UserKnownHostsFile=/dev/null",
-        `${config.sshUser}@${config.url}`,
-    ], {
-        stdio: "inherit",
-        shell: false,
-    });
-    return {
-        exitCode: result.status || 0,
-        shouldRestart: true,
-        returnToDevboxId: config.devboxId,
-    };
-}
+/**
+ * SSH Session types - kept for compatibility and type references
+ * Actual SSH session handling is now done via ink-spawn in SSHSessionScreen
+ */
+export {};

package/dist/utils/terminalDetection.js

@@ -0,0 +1,97 @@
+/**
+ * Terminal background color detection utility
+ * Uses ANSI escape sequences to query the terminal's background color
+ */
+import { stdin, stdout } from "process";
+/**
+ * Calculate luminance from RGB values to determine if background is light or dark
+ * Using relative luminance formula: https://www.w3.org/TR/WCAG20/#relativeluminancedef
+ */
+function getLuminance(r, g, b) {
+    const [rs, gs, bs] = [r, g, b].map((c) => {
+        const normalized = c / 255;
+        return normalized <= 0.03928
+            ? normalized / 12.92
+            : Math.pow((normalized + 0.055) / 1.055, 2.4);
+    });
+    return 0.2126 * rs + 0.7152 * gs + 0.0722 * bs;
+}
+/**
+ * Parse RGB color from terminal response
+ * Expected format: rgb:RRRR/GGGG/BBBB or similar variations
+ */
+function parseRGBResponse(response) {
+    // Match patterns like: rgb:RRRR/GGGG/BBBB or rgba:RRRR/GGGG/BBBB/AAAA
+    const rgbMatch = response.match(/rgba?:([0-9a-f]+)\/([0-9a-f]+)\/([0-9a-f]+)/i);
+    if (!rgbMatch) {
+        return null;
+    }
+    // Parse hex values and normalize to 0-255 range
+    const r = parseInt(rgbMatch[1].substring(0, 2), 16);
+    const g = parseInt(rgbMatch[2].substring(0, 2), 16);
+    const b = parseInt(rgbMatch[3].substring(0, 2), 16);
+    return { r, g, b };
+}
+/**
+ * Detect terminal theme by querying background color
+ * Returns 'light' or 'dark' based on background luminance, or null if detection fails
+ *
+ * NOTE: This is disabled by default to prevent flashing. Theme detection writes
+ * escape sequences to stdout which can cause visible flashing on the terminal.
+ * Users can explicitly enable it with RUNLOOP_ENABLE_THEME_DETECTION=1
+ */
+export async function detectTerminalTheme() {
+    // Skip detection in non-TTY environments
+    if (!stdin.isTTY || !stdout.isTTY) {
+        return null;
+    }
+    // Theme detection is now OPT-IN instead of OPT-OUT to prevent flashing
+    // Users need to explicitly enable it
+    if (process.env.RUNLOOP_ENABLE_THEME_DETECTION !== "1") {
+        return null;
+    }
+    return new Promise((resolve) => {
+        let response = "";
+        let timeout;
+        const cleanup = () => {
+            stdin.setRawMode(false);
+            stdin.pause();
+            stdin.removeListener("data", onData);
+            clearTimeout(timeout);
+        };
+        const onData = (chunk) => {
+            response += chunk.toString();
+            // Check if we have a complete response (ends with ESC \ or BEL)
+            if (response.includes("\x1b\\") || response.includes("\x07")) {
+                cleanup();
+                const rgb = parseRGBResponse(response);
+                if (rgb) {
+                    const luminance = getLuminance(rgb.r, rgb.g, rgb.b);
+                    // Threshold: luminance > 0.5 is considered light background
+                    resolve(luminance > 0.5 ? "light" : "dark");
+                }
+                else {
+                    resolve(null);
+                }
+            }
+        };
+        // Set timeout for terminals that don't support the query
+        timeout = setTimeout(() => {
+            cleanup();
+            resolve(null);
+        }, 50); // 50ms timeout - quick to minimize any visual flashing
+        try {
+            // Enable raw mode to capture escape sequences
+            stdin.setRawMode(true);
+            stdin.resume();
+            stdin.on("data", onData);
+            // Query background color using OSC 11 sequence
+            // Format: ESC ] 11 ; ? ESC \
+            stdout.write("\x1b]11;?\x1b\\");
+        }
+        catch {
+            cleanup();
+            resolve(null);
+        }
+    });
+}

package/dist/utils/terminalSync.js

@@ -0,0 +1,39 @@
+/**
+ * Terminal synchronous update mode utilities
+ *
+ * Uses ANSI escape sequences to prevent screen flicker by batching terminal updates.
+ * This tells the terminal to buffer all output between BEGIN and END markers
+ * and only display it atomically, preventing the visible flashing during redraws.
+ *
+ * Supported by most modern terminals (iTerm2, Terminal.app, Alacritty, etc.)
+ * When not supported, these sequences are simply ignored.
+ */
+// Begin Synchronous Update (BSU) - tells terminal to start buffering
+export const BEGIN_SYNC = "\x1b[?2026h";
+// End Synchronous Update (ESU) - tells terminal to flush buffer atomically
+export const END_SYNC = "\x1b[?2026l";
+/**
+ * Enable synchronous updates for the terminal
+ * Call this once at application startup
+ */
+export function enableSynchronousUpdates() {
+    return;
+    //process.stdout.write(BEGIN_SYNC);
+}
+/**
+ * Disable synchronous updates for the terminal
+ * Call this at application shutdown
+ */
+export function disableSynchronousUpdates() {
+    return;
+    //process.stdout.write(END_SYNC);
+}
+/**
+ * Wrap terminal output with synchronous update markers
+ * This ensures the output is displayed atomically without flicker
+ */
+export function withSynchronousUpdate(fn) {
+    //process.stdout.write(BEGIN_SYNC);
+    fn();
+    //process.stdout.write(END_SYNC);
+}

package/dist/utils/theme.js

@@ -2,21 +2,155 @@
  * Color theme constants for the CLI application
  * Centralized color definitions for easy theme customization
  */
-export const colors = {
+import { detectTerminalTheme } from "./terminalDetection.js";
+import { getThemePreference, getDetectedTheme, setDetectedTheme, } from "./config.js";
+// Dark mode color palette (default)
+const darkColors = {
     // Primary brand colors
-    primary: "cyan",
-    secondary: "magenta",
+    primary: "#00D9FF", // Bright cyan
+    secondary: "#FF6EC7", // Vibrant magenta
     // Status colors
-    success: "green",
-    warning: "yellow",
-    error: "red",
-    info: "blue",
+    success: "#10B981", // Emerald green
+    warning: "#F59E0B", // Amber
+    error: "#EF4444", // Red
+    info: "#3B82F6", // Blue
     // UI colors
-    text: "white",
-    textDim: "gray",
-    border: "gray",
+    text: "#FFFFFF", // White
+    textDim: "#9CA3AF", // Gray
+    border: "#6B7280", // Medium gray
+    background: "#000000", // Black
     // Accent colors for menu items and highlights
-    accent1: "cyan",
-    accent2: "magenta",
-    accent3: "green",
+    accent1: "#00D9FF", // Same as primary
+    accent2: "#FF6EC7", // Same as secondary
+    accent3: "#10B981", // Same as success
+    // ID color for displaying resource IDs
+    idColor: "#60A5FA", // Muted blue for IDs
 };
+// Light mode color palette
+const lightColors = {
+    // Primary brand colors (brighter/darker for visibility on light backgrounds)
+    primary: "#2563EB", // Deep blue
+    secondary: "#C026D3", // Deep magenta
+    // Status colors
+    success: "#059669", // Deep green
+    warning: "#D97706", // Deep amber
+    error: "#DC2626", // Deep red
+    info: "#2563EB", // Deep blue
+    // UI colors
+    text: "#000000", // Black
+    textDim: "#4B5563", // Dark gray for better contrast on light backgrounds
+    border: "#9CA3AF", // Medium gray
+    background: "#FFFFFF", // White
+    // Accent colors for menu items and highlights
+    accent1: "#2563EB", // Same as primary
+    accent2: "#C026D3", // Same as secondary
+    accent3: "#059669", // Same as success
+    // ID color for displaying resource IDs
+    idColor: "#0284C7", // Deeper blue for IDs on light backgrounds
+};
+// Current active color palette (initialized by initializeTheme)
+let activeColors = darkColors;
+let currentTheme = "dark";
+/**
+ * Get the current color palette
+ * This is the main export that components should use
+ */
+export const colors = new Proxy({}, {
+    get(_target, prop) {
+        return activeColors[prop];
+    },
+});
+/**
+ * Initialize the theme system
+ * Must be called at CLI startup before rendering any UI
+ */
+export async function initializeTheme() {
+    const preference = getThemePreference();
+    let detectedTheme = null;
+    // Auto-detect if preference is 'auto'
+    if (preference === "auto") {
+        // Check cache first - only detect if we haven't cached a result
+        const cachedTheme = getDetectedTheme();
+        if (cachedTheme) {
+            // Use cached detection result (no flashing!)
+            detectedTheme = cachedTheme;
+        }
+        else {
+            // First time detection - run it and cache the result
+            try {
+                detectedTheme = await detectTerminalTheme();
+                if (detectedTheme) {
+                    // Cache the result so we don't detect again
+                    setDetectedTheme(detectedTheme);
+                }
+            }
+            catch {
+                // Detection failed, fall back to dark mode
+                detectedTheme = null;
+            }
+        }
+    }
+    // Determine final theme
+    if (preference === "light") {
+        currentTheme = "light";
+        activeColors = lightColors;
+    }
+    else if (preference === "dark") {
+        currentTheme = "dark";
+        activeColors = darkColors;
+    }
+    else if (detectedTheme) {
+        // Auto mode with successful detection
+        currentTheme = detectedTheme;
+        activeColors = detectedTheme === "light" ? lightColors : darkColors;
+    }
+    else {
+        // Auto mode with failed detection - default to dark
+        currentTheme = "dark";
+        activeColors = darkColors;
+    }
+}
+/**
+ * Get the current theme mode
+ */
+export function getCurrentTheme() {
+    return currentTheme;
+}
+/**
+ * Get chalk function for a color name
+ * Useful for applying colors dynamically
+ */
+export function getChalkColor(colorName) {
+    return activeColors[colorName];
+}
+/**
+ * Check if we should use inverted colors (light mode)
+ * Useful for components that need to explicitly set backgrounds
+ */
+export function isLightMode() {
+    return currentTheme === "light";
+}
+/**
+ * Force set theme mode directly without detection
+ * Used for live preview in theme selector
+ */
+export function setThemeMode(mode) {
+    currentTheme = mode;
+    activeColors = mode === "light" ? lightColors : darkColors;
+}
+/**
+ * Sanitize width values to prevent Yoga WASM crashes
+ * Ensures width is a valid, finite number within safe bounds
+ *
+ * @param width - The width value to sanitize
+ * @param min - Minimum allowed width (default: 1)
+ * @param max - Maximum allowed width (default: 100)
+ * @returns A safe width value guaranteed to be within [min, max]
+ */
+export function sanitizeWidth(width, min = 1, max = 100) {
+    // Check for NaN, Infinity, or other invalid numbers
+    if (!Number.isFinite(width) || width < min) {
+        return min;
+    }
+    return Math.min(width, max);
+}