@compass-ai/nova 1.0.73 → 1.0.74

package/dist/utils/command-parser.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Utility for parsing bash/shell commands from LLM markdown responses.
+ * Used by the agentic loop to extract and execute commands suggested by the LLM.
+ */
+/**
+ * Represents a parsed command block from markdown
+ */
+export interface ParsedCommand {
+    /** The command string to execute */
+    command: string;
+    /** The language/type of the code block (bash, sh, shell, etc.) */
+    language: string;
+    /** Optional comment/description preceding the command */
+    description?: string;
+}
+/**
+ * Parses bash/shell commands from a markdown LLM response.
+ * Extracts code blocks marked as bash, sh, shell, etc.
+ *
+ * @param response - The LLM response text containing markdown
+ * @returns Array of parsed commands
+ */
+export declare function parseCommandsFromResponse(response: string): ParsedCommand[];
+/**
+ * Determines if a command is safe for auto-execution (exploration only).
+ * Safe commands don't modify files or system state.
+ *
+ * @param command - The command to check
+ * @returns True if the command is safe to auto-execute
+ */
+export declare function isSafeExplorationCommand(command: string): boolean;
+/**
+ * Formats command execution results for sending back to the LLM
+ *
+ * @param command - The command that was executed
+ * @param stdout - Standard output
+ * @param stderr - Standard error
+ * @param exitCode - Exit code
+ * @returns Formatted string for LLM context
+ */
+export declare function formatCommandResult(command: string, stdout: string, stderr: string, exitCode: number): string;
+/**
+ * Checks if an LLM response contains executable commands
+ *
+ * @param response - The LLM response text
+ * @returns True if the response contains bash/shell commands
+ */
+export declare function hasExecutableCommands(response: string): boolean;
+/**
+ * Filters commands to only safe exploration commands
+ *
+ * @param commands - Array of parsed commands
+ * @returns Array of only safe commands
+ */
+export declare function filterSafeCommands(commands: ParsedCommand[]): ParsedCommand[];
+//# sourceMappingURL=command-parser.d.ts.map

package/dist/utils/command-parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-parser.d.ts","sourceRoot":"","sources":["../../src/utils/command-parser.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,oCAAoC;IACpC,OAAO,EAAE,MAAM,CAAC;IAChB,kEAAkE;IAClE,QAAQ,EAAE,MAAM,CAAC;IACjB,yDAAyD;IACzD,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAoFD;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,MAAM,GAAG,aAAa,EAAE,CAuC3E;AAeD;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAejE;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,GACf,MAAM,CAuBR;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAG/D;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,aAAa,EAAE,GAAG,aAAa,EAAE,CAE7E"}

package/dist/utils/command-parser.js

@@ -0,0 +1,206 @@
+/**
+ * Utility for parsing bash/shell commands from LLM markdown responses.
+ * Used by the agentic loop to extract and execute commands suggested by the LLM.
+ */
+/**
+ * Languages that indicate executable shell commands
+ */
+const SHELL_LANGUAGES = new Set([
+    'bash',
+    'sh',
+    'shell',
+    'zsh',
+    'fish',
+    'powershell',
+    'ps1',
+    'cmd',
+    'batch',
+    'terminal',
+    'console',
+]);
+/**
+ * Commands that are safe to auto-execute for exploration/understanding
+ * These don't modify files or system state
+ */
+const SAFE_EXPLORATION_COMMANDS = new Set([
+    'ls',
+    'dir',
+    'find',
+    'grep',
+    'rg',
+    'cat',
+    'head',
+    'tail',
+    'less',
+    'more',
+    'tree',
+    'pwd',
+    'echo',
+    'which',
+    'where',
+    'type',
+    'file',
+    'stat',
+    'wc',
+    'sort',
+    'uniq',
+    'diff',
+    'git', // git status, git log, git diff are safe for exploration
+    'npm', // npm list, npm outdated are safe
+    'node', // node --version, etc.
+    'python',
+    'python3',
+    'go',
+    'cargo',
+    'rustc',
+]);
+/**
+ * Patterns that indicate a command might modify state (unsafe)
+ */
+const UNSAFE_PATTERNS = [
+    /\brm\s/i,
+    /\brmdir\b/i,
+    /\bdel\b/i,
+    /\bmv\s/i,
+    /\bcp\s/i,
+    /\bmkdir\b/i,
+    /\btouch\b/i,
+    /\bchmod\b/i,
+    /\bchown\b/i,
+    /\bsudo\b/i,
+    /\bnpm\s+(install|i|add|remove|uninstall|update|publish)/i,
+    /\byarn\s+(add|remove|install)/i,
+    /\bpnpm\s+(add|remove|install)/i,
+    /\bgit\s+(push|commit|add|reset|checkout|merge|rebase|stash|clean)/i,
+    /\bpip\s+install/i,
+    /\bcargo\s+(build|install|publish)/i,
+    />\s*\S+/, // Output redirection
+    /\|\s*tee\b/i,
+    /\bdd\b/i,
+    /\bformat\b/i,
+    /\bkill\b/i,
+    /\bpkill\b/i,
+];
+/**
+ * Parses bash/shell commands from a markdown LLM response.
+ * Extracts code blocks marked as bash, sh, shell, etc.
+ *
+ * @param response - The LLM response text containing markdown
+ * @returns Array of parsed commands
+ */
+export function parseCommandsFromResponse(response) {
+    const commands = [];
+    // Match fenced code blocks with language identifier
+    // Captures: language, code content
+    const codeBlockRegex = /```(\w+)?\s*\n([\s\S]*?)```/g;
+    let match;
+    while ((match = codeBlockRegex.exec(response)) !== null) {
+        const language = (match[1] || '').toLowerCase();
+        const code = match[2].trim();
+        // Only process shell-like code blocks
+        if (language && SHELL_LANGUAGES.has(language)) {
+            // Split by newlines to get individual commands
+            // Filter out comments and empty lines
+            const lines = code.split('\n')
+                .map(line => line.trim())
+                .filter(line => line && !line.startsWith('#'));
+            // Look for description in text before this code block
+            const beforeBlock = response.substring(0, match.index);
+            const descMatch = beforeBlock.match(/([^\n]+)\s*$/);
+            const description = descMatch ? descMatch[1].trim() : undefined;
+            for (const line of lines) {
+                // Skip lines that are clearly not commands (e.g., output examples)
+                if (isLikelyCommand(line)) {
+                    commands.push({
+                        command: line,
+                        language,
+                        description,
+                    });
+                }
+            }
+        }
+    }
+    return commands;
+}
+/**
+ * Checks if a line is likely a command vs output/example
+ */
+function isLikelyCommand(line) {
+    // Skip if starts with common output patterns
+    if (line.startsWith('>') && !line.startsWith('>>'))
+        return false;
+    if (line.match(/^\s*\d+[.:]/))
+        return false; // Numbered list output
+    if (line.match(/^[A-Z][a-z]+:/))
+        return false; // Label: value output
+    // Must start with a word character or common command prefixes
+    return /^[\w./~$-]/.test(line);
+}
+/**
+ * Determines if a command is safe for auto-execution (exploration only).
+ * Safe commands don't modify files or system state.
+ *
+ * @param command - The command to check
+ * @returns True if the command is safe to auto-execute
+ */
+export function isSafeExplorationCommand(command) {
+    // Check for unsafe patterns first
+    for (const pattern of UNSAFE_PATTERNS) {
+        if (pattern.test(command)) {
+            return false;
+        }
+    }
+    // Get the base command (first word)
+    const baseCommand = command.trim().split(/\s+/)[0];
+    // Remove path prefix if present
+    const commandName = baseCommand.split('/').pop() || baseCommand;
+    return SAFE_EXPLORATION_COMMANDS.has(commandName.toLowerCase());
+}
+/**
+ * Formats command execution results for sending back to the LLM
+ *
+ * @param command - The command that was executed
+ * @param stdout - Standard output
+ * @param stderr - Standard error
+ * @param exitCode - Exit code
+ * @returns Formatted string for LLM context
+ */
+export function formatCommandResult(command, stdout, stderr, exitCode) {
+    const parts = [];
+    parts.push(`$ ${command}`);
+    if (stdout) {
+        // Truncate very long output
+        const maxLength = 5000;
+        const truncatedStdout = stdout.length > maxLength
+            ? stdout.substring(0, maxLength) + `\n... (truncated, ${stdout.length - maxLength} more characters)`
+            : stdout;
+        parts.push(truncatedStdout);
+    }
+    if (stderr) {
+        parts.push(`[stderr]: ${stderr}`);
+    }
+    if (exitCode !== 0) {
+        parts.push(`[exit code: ${exitCode}]`);
+    }
+    return parts.join('\n');
+}
+/**
+ * Checks if an LLM response contains executable commands
+ *
+ * @param response - The LLM response text
+ * @returns True if the response contains bash/shell commands
+ */
+export function hasExecutableCommands(response) {
+    const commands = parseCommandsFromResponse(response);
+    return commands.length > 0;
+}
+/**
+ * Filters commands to only safe exploration commands
+ *
+ * @param commands - Array of parsed commands
+ * @returns Array of only safe commands
+ */
+export function filterSafeCommands(commands) {
+    return commands.filter(cmd => isSafeExplorationCommand(cmd.command));
+}
+//# sourceMappingURL=command-parser.js.map

package/dist/utils/command-parser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-parser.js","sourceRoot":"","sources":["../../src/utils/command-parser.ts"],"names":[],"mappings":"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"}

package/dist/utils/console-capture.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Console output capture utility for slash commands
+ *
+ * Captures console.log/console.error output during slash command execution
+ * so it can be added to the conversation history in Ink-based UIs.
+ */
+/**
+ * Captures all console output during the execution of a function.
+ * Temporarily overrides console.log, console.error, console.warn methods
+ * and process.stdout.write to capture the output.
+ *
+ * @param fn - The function to execute while capturing output
+ * @returns Object containing the function's return value and captured output
+ *
+ * @example
+ * ```typescript
+ * const { result, output } = await captureConsoleOutput(async () => {
+ *   console.log('Hello');
+ *   console.log('World');
+ *   return 42;
+ * });
+ * // output === 'Hello\nWorld\n'
+ * // result === 42
+ * ```
+ */
+export declare function captureConsoleOutput<T>(fn: () => Promise<T> | T): Promise<{
+    result: T;
+    output: string;
+}>;
+//# sourceMappingURL=console-capture.d.ts.map

package/dist/utils/console-capture.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"console-capture.d.ts","sourceRoot":"","sources":["../../src/utils/console-capture.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,oBAAoB,CAAC,CAAC,EAC1C,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,GACvB,OAAO,CAAC;IAAE,MAAM,EAAE,CAAC,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CAqCxC"}

package/dist/utils/console-capture.js

@@ -0,0 +1,88 @@
+/**
+ * Console output capture utility for slash commands
+ *
+ * Captures console.log/console.error output during slash command execution
+ * so it can be added to the conversation history in Ink-based UIs.
+ */
+/**
+ * Captures all console output during the execution of a function.
+ * Temporarily overrides console.log, console.error, console.warn methods
+ * and process.stdout.write to capture the output.
+ *
+ * @param fn - The function to execute while capturing output
+ * @returns Object containing the function's return value and captured output
+ *
+ * @example
+ * ```typescript
+ * const { result, output } = await captureConsoleOutput(async () => {
+ *   console.log('Hello');
+ *   console.log('World');
+ *   return 42;
+ * });
+ * // output === 'Hello\nWorld\n'
+ * // result === 42
+ * ```
+ */
+export async function captureConsoleOutput(fn) {
+    const capturedLines = [];
+    // Save original methods
+    const originalLog = console.log;
+    const originalError = console.error;
+    const originalWarn = console.warn;
+    // Override console methods
+    console.log = (...args) => {
+        capturedLines.push(formatConsoleArgs(args));
+    };
+    console.error = (...args) => {
+        capturedLines.push(formatConsoleArgs(args));
+    };
+    console.warn = (...args) => {
+        capturedLines.push(formatConsoleArgs(args));
+    };
+    // NOTE: We intentionally do NOT override process.stdout.write or process.stderr.write
+    // because Ink uses stdout.write for rendering. Overriding it would block all UI updates
+    // during slash command execution. Commands should use the event emitter for output instead.
+    try {
+        const result = await fn();
+        return {
+            result,
+            output: capturedLines.join('\n'),
+        };
+    }
+    finally {
+        // Restore original methods
+        console.log = originalLog;
+        console.error = originalError;
+        console.warn = originalWarn;
+    }
+}
+/**
+ * Formats console arguments into a string, similar to how console.log works
+ */
+function formatConsoleArgs(args) {
+    return args
+        .map((arg) => {
+        if (typeof arg === 'string') {
+            return arg;
+        }
+        else if (arg === null) {
+            return 'null';
+        }
+        else if (arg === undefined) {
+            return 'undefined';
+        }
+        else if (typeof arg === 'object') {
+            try {
+                return JSON.stringify(arg, null, 2);
+            }
+            catch {
+                return String(arg);
+            }
+        }
+        else {
+            return String(arg);
+        }
+    })
+        .join(' ');
+}
+//# sourceMappingURL=console-capture.js.map

package/dist/utils/console-capture.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"console-capture.js","sourceRoot":"","sources":["../../src/utils/console-capture.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,EAAwB;IAExB,MAAM,aAAa,GAAa,EAAE,CAAC;IAEnC,wBAAwB;IACxB,MAAM,WAAW,GAAG,OAAO,CAAC,GAAG,CAAC;IAChC,MAAM,aAAa,GAAG,OAAO,CAAC,KAAK,CAAC;IACpC,MAAM,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAElC,2BAA2B;IAC3B,OAAO,CAAC,GAAG,GAAG,CAAC,GAAG,IAAe,EAAE,EAAE;QACnC,aAAa,CAAC,IAAI,CAAC,iBAAiB,CAAC,IAAI,CAAC,CAAC,CAAC;IAC9C,CAAC,CAAC;IAEF,OAAO,CAAC,KAAK,GAAG,CAAC,GAAG,IAAe,EAAE,EAAE;QACrC,aAAa,CAAC,IAAI,CAAC,iBAAiB,CAAC,IAAI,CAAC,CAAC,CAAC;IAC9C,CAAC,CAAC;IAEF,OAAO,CAAC,IAAI,GAAG,CAAC,GAAG,IAAe,EAAE,EAAE;QACpC,aAAa,CAAC,IAAI,CAAC,iBAAiB,CAAC,IAAI,CAAC,CAAC,CAAC;IAC9C,CAAC,CAAC;IAEF,sFAAsF;IACtF,wFAAwF;IACxF,4FAA4F;IAE5F,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,EAAE,EAAE,CAAC;QAC1B,OAAO;YACL,MAAM;YACN,MAAM,EAAE,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC;SACjC,CAAC;IACJ,CAAC;YAAS,CAAC;QACT,2BAA2B;QAC3B,OAAO,CAAC,GAAG,GAAG,WAAW,CAAC;QAC1B,OAAO,CAAC,KAAK,GAAG,aAAa,CAAC;QAC9B,OAAO,CAAC,IAAI,GAAG,YAAY,CAAC;IAC9B,CAAC;AACH,CAAC;AAED;;GAEG;AACH,SAAS,iBAAiB,CAAC,IAAe;IACxC,OAAO,IAAI;SACR,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE;QACX,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;YAC5B,OAAO,GAAG,CAAC;QACb,CAAC;aAAM,IAAI,GAAG,KAAK,IAAI,EAAE,CAAC;YACxB,OAAO,MAAM,CAAC;QAChB,CAAC;aAAM,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;YAC7B,OAAO,WAAW,CAAC;QACrB,CAAC;aAAM,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;YACnC,IAAI,CAAC;gBACH,OAAO,IAAI,CAAC,SAAS,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;YACtC,CAAC;YAAC,MAAM,CAAC;gBACP,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC;YACrB,CAAC;QACH,CAAC;aAAM,CAAC;YACN,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC;QACrB,CAAC;IACH,CAAC,CAAC;SACD,IAAI,CAAC,GAAG,CAAC,CAAC;AACf,CAAC"}

package/dist/utils/cron-parser.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Cron expression parser, validator, and human-readable converter.
+ *
+ * Handles standard 5-field cron expressions (minute hour day-of-month month day-of-week)
+ * and common natural-language schedule phrases. No external dependencies.
+ */
+import type { ScheduleExpression } from '../types/schedule.js';
+/**
+ * Validates a 5-field cron expression.
+ *
+ * @param expr - A cron expression string (e.g., "0 9 * * 1-5")
+ * @returns Object with `valid` boolean and optional `error` message
+ */
+export declare function validateCronExpression(expr: string): {
+    valid: boolean;
+    error?: string;
+};
+/**
+ * Converts a cron expression to a human-readable description.
+ *
+ * @param cron - A valid 5-field cron expression
+ * @returns Human-readable string (e.g., "Every Monday at 9:00 AM")
+ */
+export declare function cronToHumanReadable(cron: string): string;
+/**
+ * Parses a natural-language schedule string into a ScheduleExpression.
+ * Falls back to treating the input as a raw cron expression if no preset matches.
+ *
+ * @param input - Natural language (e.g., "every Friday at 3pm") or cron string
+ * @returns ScheduleExpression with cron, description, and raw input
+ * @throws Error if the input can't be parsed as either natural language or valid cron
+ */
+export declare function parseHumanSchedule(input: string): ScheduleExpression;
+/**
+ * Calculates the next run time for a cron expression.
+ * Scans forward from `from` (default: now) up to 366 days.
+ *
+ * @param cron - A valid 5-field cron expression
+ * @param from - Starting point (defaults to current time)
+ * @returns The next Date when the cron would fire, or null if none found within 366 days
+ */
+export declare function getNextRunTime(cron: string, from?: Date): Date | null;
+/**
+ * Parses a schedule expression (natural language or cron) into a full ScheduleExpression.
+ * This is the primary entry point for the cron parser module.
+ *
+ * @param input - Natural language phrase or 5-field cron expression
+ * @returns Parsed ScheduleExpression with cron, description, and raw input
+ * @throws Error if the input can't be parsed
+ */
+export declare function parseCronExpression(input: string): ScheduleExpression;
+//# sourceMappingURL=cron-parser.d.ts.map

package/dist/utils/cron-parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cron-parser.d.ts","sourceRoot":"","sources":["../../src/utils/cron-parser.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAoF/D;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAmBvF;AAgBD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAqExD;AAsCD;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,kBAAkB,CA8GpE;AA2CD;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,IAAI,GAAG,IAAI,GAAG,IAAI,CA6ErE;AAMD;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,kBAAkB,CAErE"}