@rcrsr/rill-cli 0.6.0

package/src/cli-eval.ts

@@ -0,0 +1,145 @@
+#!/usr/bin/env node
+/**
+ * Rill CLI - Evaluate rill expressions
+ *
+ * Usage:
+ *   rill-eval '"hello".len'
+ *   rill-eval --help
+ *   rill-eval --version
+ */
+
+import {
+  createRuntimeContext,
+  execute,
+  parse,
+  type ExecutionResult,
+} from '@rcrsr/rill';
+import { formatOutput, determineExitCode, VERSION } from './cli-shared.js';
+
+/**
+ * Parse command-line arguments into structured command
+ */
+function parseArgs(
+  argv: string[]
+):
+  | { mode: 'exec'; file: string; args: string[] }
+  | { mode: 'eval'; expression: string }
+  | { mode: 'help' | 'version' } {
+  // Check for --help and --version in any position
+  if (argv.includes('--help')) {
+    return { mode: 'help' };
+  }
+  if (argv.includes('--version')) {
+    return { mode: 'version' };
+  }
+
+  // Check for unknown flags (anything starting with -)
+  for (const arg of argv) {
+    if (arg.startsWith('-') && arg !== '-') {
+      throw new Error(`Unknown option: ${arg}`);
+    }
+  }
+
+  // If no arguments, default to help
+  if (argv.length === 0) {
+    return { mode: 'help' };
+  }
+
+  // First positional arg determines mode
+  const firstArg = argv[0]!;
+
+  // Eval mode: direct expression
+  return { mode: 'eval', expression: firstArg };
+}
+
+/**
+ * Evaluate a Rill expression without file context
+ */
+export async function evaluateExpression(
+  expression: string
+): Promise<ExecutionResult> {
+  const ctx = createRuntimeContext({
+    callbacks: {
+      onLog: (value) => console.log(formatOutput(value)),
+    },
+  });
+
+  // Set pipeValue to empty list (Rill has no null concept per language spec)
+  ctx.pipeValue = [];
+
+  const ast = parse(expression);
+  return execute(ast, ctx);
+}
+
+/**
+ * Display help information
+ */
+function showHelp(): void {
+  console.log(`Rill Expression Evaluator
+
+Usage:
+  rill-eval <expression>      Evaluate a Rill expression
+  rill-eval --help            Show this help message
+  rill-eval --version         Show version information
+
+Examples:
+  rill-eval '"hello".len'
+  rill-eval '5 + 3'
+  rill-eval '[1, 2, 3] -> map |x|($x * 2)'`);
+}
+
+/**
+ * Display version information
+ */
+function showVersion(): void {
+  console.log(`rill-eval ${VERSION}`);
+}
+
+/**
+ * Entry point for rill-eval binary
+ */
+async function main(): Promise<void> {
+  try {
+    const args = process.argv.slice(2);
+    const command = parseArgs(args);
+
+    if (command.mode === 'help') {
+      showHelp();
+      return;
+    }
+
+    if (command.mode === 'version') {
+      showVersion();
+      return;
+    }
+
+    if (command.mode === 'eval') {
+      const result = await evaluateExpression(command.expression);
+      const { code, message } = determineExitCode(result.value);
+
+      if (message !== undefined) {
+        console.log(message);
+      } else {
+        console.log(formatOutput(result.value));
+      }
+      process.exit(code);
+    }
+
+    // Unreachable - exec mode not supported in rill-eval
+    console.error('Unexpected command mode');
+    process.exit(1);
+  } catch (err) {
+    console.error(err instanceof Error ? err.message : String(err));
+    process.exit(1);
+  }
+}
+
+// Only run main if this is the entry point (not imported)
+const shouldRunMain =
+  process.env['NODE_ENV'] !== 'test' &&
+  !process.env['VITEST'] &&
+  !process.env['VITEST_WORKER_ID'];
+
+if (shouldRunMain) {
+  main();
+}

package/src/cli-exec.ts

@@ -0,0 +1,408 @@
+#!/usr/bin/env node
+/**
+ * CLI Execution Entry Point
+ *
+ * Implements main(), parseArgs(), and executeScript() for rill-exec and rill-eval binaries.
+ * Handles file execution, stdin input, and module loading.
+ */
+
+import * as fs from 'fs/promises';
+import * as fsSync from 'fs';
+import * as path from 'path';
+import * as yaml from 'yaml';
+import { parse, execute, createRuntimeContext } from '@rcrsr/rill';
+import type { RillValue, ExecutionResult } from '@rcrsr/rill';
+import {
+  formatOutput,
+  formatError,
+  determineExitCode,
+  VERSION,
+  detectHelpVersionFlag,
+} from './cli-shared.js';
+import { loadModule } from './cli-module-loader.js';
+import { explainError } from './cli-explain.js';
+
+/**
+ * Parsed command-line arguments
+ */
+export type ParsedArgs =
+  | {
+      mode: 'exec';
+      file: string;
+      args: string[];
+      format: 'human' | 'json' | 'compact';
+      verbose: boolean;
+      maxStackDepth: number;
+    }
+  | { mode: 'eval'; expression: string }
+  | { mode: 'help' | 'version' }
+  | { mode: 'explain'; errorId: string };
+
+/**
+ * Parse command-line arguments into structured command
+ *
+ * @param argv - Raw command-line arguments (typically process.argv.slice(2))
+ * @returns Parsed command object
+ */
+export function parseArgs(argv: string[]): ParsedArgs {
+  // Check for --help or --version flags in any position
+  const helpVersionFlag = detectHelpVersionFlag(argv);
+  if (helpVersionFlag !== null) {
+    return helpVersionFlag;
+  }
+
+  // Check for --explain flag (IC-11)
+  const explainIndex = argv.findIndex((arg) => arg === '--explain');
+  if (explainIndex !== -1) {
+    const errorId = argv[explainIndex + 1];
+    if (!errorId) {
+      throw new Error('Missing error ID after --explain');
+    }
+    return { mode: 'explain', errorId };
+  }
+
+  // Parse format, verbose, and max-stack-depth flags (IC-11)
+  let format: 'human' | 'json' | 'compact' = 'human';
+  let verbose = false;
+  let maxStackDepth = 10;
+
+  const formatIndex = argv.findIndex((arg) => arg === '--format');
+  if (formatIndex !== -1) {
+    const formatValue = argv[formatIndex + 1];
+    // AC-15: Unknown --format value
+    if (
+      formatValue !== 'human' &&
+      formatValue !== 'json' &&
+      formatValue !== 'compact'
+    ) {
+      throw new Error(
+        `Invalid --format value: ${formatValue}. Must be one of: human, json, compact`
+      );
+    }
+    format = formatValue;
+  }
+
+  if (argv.includes('--verbose')) {
+    verbose = true;
+  }
+
+  const maxStackDepthIndex = argv.findIndex(
+    (arg) => arg === '--max-stack-depth'
+  );
+  if (maxStackDepthIndex !== -1) {
+    const depthValue = argv[maxStackDepthIndex + 1];
+    if (!depthValue) {
+      throw new Error('Missing value after --max-stack-depth');
+    }
+    const depth = parseInt(depthValue, 10);
+    if (isNaN(depth) || depth < 1 || depth > 100) {
+      throw new Error('--max-stack-depth must be a number between 1 and 100');
+    }
+    maxStackDepth = depth;
+  }
+
+  // Check for unknown flags
+  const knownFlags = [
+    '--help',
+    '-h',
+    '--version',
+    '-v',
+    '--explain',
+    '--format',
+    '--verbose',
+    '--max-stack-depth',
+  ];
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg && arg.startsWith('--')) {
+      if (!knownFlags.includes(arg)) {
+        throw new Error(`Unknown option: ${arg}`);
+      }
+      // Skip next argument if this is a flag that takes a value
+      if (
+        arg === '--format' ||
+        arg === '--max-stack-depth' ||
+        arg === '--explain'
+      ) {
+        i++;
+      }
+    } else if (arg && arg.startsWith('-') && arg !== '-') {
+      if (!knownFlags.includes(arg)) {
+        throw new Error(`Unknown option: ${arg}`);
+      }
+    }
+  }
+
+  // Determine mode from first positional argument (skip flags and their values)
+  let firstArg: string | undefined;
+  const positionalArgs: string[] = [];
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (!arg) continue;
+
+    // Skip flags
+    if (knownFlags.includes(arg)) {
+      // Skip the flag's value if it takes one
+      if (
+        arg === '--format' ||
+        arg === '--max-stack-depth' ||
+        arg === '--explain'
+      ) {
+        i++;
+      }
+      continue;
+    }
+
+    // This is a positional argument
+    if (!firstArg) {
+      firstArg = arg;
+    }
+    positionalArgs.push(arg);
+  }
+
+  if (!firstArg) {
+    throw new Error('Missing file argument');
+  }
+
+  // Eval mode is not supported in rill-exec (only rill-eval)
+  // This function is shared but context determines valid modes
+  if (firstArg === '-e') {
+    if (positionalArgs.length < 2) {
+      throw new Error('Missing expression after -e');
+    }
+    return { mode: 'eval', expression: positionalArgs[1]! };
+  }
+
+  // Exec mode (file or stdin)
+  const file = firstArg;
+  const args = positionalArgs.slice(1);
+  return { mode: 'exec', file, args, format, verbose, maxStackDepth };
+}
+
+/**
+ * Execute a Rill script file with arguments and module support
+ *
+ * @param file - File path or '-' for stdin
+ * @param args - Command-line arguments to pass as $ pipe value
+ * @param options - Execution options
+ * @returns Execution result with value, variables, and source text
+ * @throws Error if file not found or execution fails
+ */
+export async function executeScript(
+  file: string,
+  args: string[],
+  options?: { stdin?: boolean; source?: string }
+): Promise<ExecutionResult & { source: string }> {
+  // Use pre-read source if provided, otherwise read from file or stdin
+  let source: string;
+  let scriptPath: string;
+
+  if (options?.source !== undefined) {
+    source = options.source;
+    scriptPath =
+      file === '-'
+        ? path.resolve(process.cwd(), '<stdin>')
+        : path.resolve(file);
+  } else if (file === '-' || options?.stdin) {
+    // Read from stdin (must use sync API for stdin)
+    source = fsSync.readFileSync(0, 'utf-8');
+    scriptPath = path.resolve(process.cwd(), '<stdin>');
+  } else {
+    // Check if file exists
+    try {
+      await fs.access(file);
+    } catch {
+      throw new Error(`File not found: ${file}`);
+    }
+
+    // Read from file
+    source = await fs.readFile(file, 'utf-8');
+    scriptPath = path.resolve(file);
+  }
+
+  // Parse the script
+  const ast = parse(source);
+
+  // Extract frontmatter for use: declarations
+  const frontmatter: Record<string, unknown> = ast.frontmatter
+    ? ((yaml.parse(ast.frontmatter.content) as Record<
+        string,
+        unknown
+      > | null) ?? {})
+    : {};
+
+  // Load modules if use: declarations exist
+  const variables: Record<string, RillValue> = {};
+  if (frontmatter['use'] && Array.isArray(frontmatter['use'])) {
+    const cache = new Map<string, Record<string, RillValue>>();
+    for (const entry of frontmatter['use']) {
+      if (typeof entry === 'object' && entry !== null) {
+        const [name, modulePath] = Object.entries(entry)[0] as [string, string];
+        variables[name] = await loadModule(modulePath, scriptPath, cache);
+      }
+    }
+  }
+
+  // Create runtime context with modules
+  const ctx = createRuntimeContext({
+    variables,
+    callbacks: {
+      onLog: (value) => console.log(formatOutput(value)),
+    },
+  });
+
+  // Set pipe value to arguments (string array)
+  ctx.pipeValue = args;
+
+  // Execute the script and return with source
+  const result = await execute(ast, ctx);
+  return { ...result, source };
+}
+
+/**
+ * Entry point for rill-exec and rill-eval binaries
+ *
+ * Parses command-line arguments, executes scripts, and handles errors.
+ * Writes results to stdout and errors to stderr.
+ * Sets process.exit(1) on any error.
+ */
+export async function main(): Promise<void> {
+  let source: string | undefined;
+  let formatOptions:
+    | {
+        format: 'human' | 'json' | 'compact';
+        verbose: boolean;
+        maxStackDepth: number;
+      }
+    | undefined;
+
+  try {
+    const parsed = parseArgs(process.argv.slice(2));
+
+    switch (parsed.mode) {
+      case 'help':
+        console.log(`Usage:
+  rill-exec <script.rill> [args...]  Execute a Rill script file
+  rill-exec -                        Read script from stdin
+  rill-exec --help                   Show this help message
+  rill-exec --version                Show version information
+  rill-exec --explain RILL-XXXX      Show error documentation
+
+Options:
+  --format <format>         Output format: human, json, compact (default: human)
+  --verbose                 Include additional error details
+  --max-stack-depth <n>     Maximum call stack depth to display (default: 10, range: 1-100)
+
+Arguments:
+  args are passed to the script as a list of strings in $ (pipe value)
+
+Examples:
+  rill-exec script.rill
+  rill-exec script.rill arg1 arg2
+  rill-exec --format json script.rill
+  rill-exec --verbose --max-stack-depth 20 script.rill
+  rill-exec --explain RILL-R009
+  echo "log(\\"hello\\")" | rill-exec -`);
+        return;
+
+      case 'version': {
+        console.log(VERSION);
+        return;
+      }
+
+      case 'explain': {
+        // AC-16: Handle --explain command
+        const documentation = explainError(parsed.errorId);
+        if (documentation === null) {
+          // AC-16: Malformed errorId shows usage help
+          console.error(`Invalid error ID: ${parsed.errorId}`);
+          console.error(
+            'Error ID must be in format RILL-{L|P|R|C}{3-digit}, e.g., RILL-R009'
+          );
+          process.exit(1);
+          return;
+        }
+        console.log(documentation);
+        return;
+      }
+
+      case 'eval':
+        // This shouldn't happen in rill-exec, but handle it anyway
+        console.error(
+          'Eval mode not supported in rill-exec. Use rill-eval instead.'
+        );
+        process.exit(1);
+        return;
+
+      case 'exec': {
+        // Store format options for error handling
+        formatOptions = {
+          format: parsed.format,
+          verbose: parsed.verbose,
+          maxStackDepth: parsed.maxStackDepth,
+        };
+
+        // Read source early so it's available for error enrichment even if parsing fails
+        if (parsed.file === '-') {
+          source = fsSync.readFileSync(0, 'utf-8');
+        } else {
+          try {
+            source = await fs.readFile(parsed.file, 'utf-8');
+          } catch {
+            throw new Error(`File not found: ${parsed.file}`);
+          }
+        }
+
+        // Execute mode
+        const result = await executeScript(parsed.file, parsed.args, {
+          source,
+        });
+
+        const { code, message } = determineExitCode(result.value);
+
+        // Output message if present, otherwise output the result value
+        if (message !== undefined) {
+          console.log(message);
+        } else {
+          console.log(formatOutput(result.value));
+        }
+
+        // Exit with computed code
+        process.exit(code);
+      }
+    }
+  } catch (err) {
+    if (err instanceof Error) {
+      // IC-11: Pass source text and format options to formatError
+      console.error(
+        formatError(err, source, {
+          format: formatOptions?.format ?? 'human',
+          verbose: formatOptions?.verbose ?? false,
+          includeCallStack: true,
+          maxCallStackDepth: formatOptions?.maxStackDepth ?? 10,
+        })
+      );
+    } else {
+      console.error(
+        formatError(new Error(String(err)), source, {
+          format: formatOptions?.format ?? 'human',
+          verbose: formatOptions?.verbose ?? false,
+          includeCallStack: true,
+          maxCallStackDepth: formatOptions?.maxStackDepth ?? 10,
+        })
+      );
+    }
+    process.exit(1);
+  }
+}
+
+// Only run main if not in test environment
+const shouldRunMain =
+  process.env['NODE_ENV'] !== 'test' &&
+  !process.env['VITEST'] &&
+  !process.env['VITEST_WORKER_ID'];
+
+if (shouldRunMain) {
+  main();
+}

package/src/cli-explain.ts

@@ -0,0 +1,76 @@
+/**
+ * CLI Error Explanation
+ * Function for rendering full error documentation
+ */
+
+import { ERROR_REGISTRY } from '@rcrsr/rill';
+
+/**
+ * Render full error documentation for --explain command.
+ *
+ * Constraints:
+ * - Lookup from ERROR_REGISTRY
+ * - Renders cause, resolution, examples sections
+ *
+ * @param errorId - Error identifier (format: RILL-{category}{3-digit})
+ * @returns Formatted documentation string, or null if errorId is invalid/unknown
+ *
+ * @example
+ * explainError("RILL-R009")
+ * // Returns: formatted documentation with cause, resolution, examples
+ *
+ * @example
+ * explainError("invalid")
+ * // Returns: null
+ */
+export function explainError(errorId: string): string | null {
+  // EC-12: Invalid errorId format returns null
+  const errorIdPattern = /^RILL-[LPRC]\d{3}$/;
+  if (!errorIdPattern.test(errorId)) {
+    return null;
+  }
+
+  // EC-13: Unknown errorId returns null
+  const definition = ERROR_REGISTRY.get(errorId);
+  if (!definition) {
+    return null;
+  }
+
+  // Build documentation sections
+  const sections: string[] = [];
+
+  // Header: errorId and description
+  sections.push(`${definition.errorId}: ${definition.description}`);
+  sections.push('');
+
+  // Cause section (if present)
+  if (definition.cause) {
+    sections.push('Cause:');
+    sections.push(`  ${definition.cause}`);
+    sections.push('');
+  }
+
+  // Resolution section (if present)
+  if (definition.resolution) {
+    sections.push('Resolution:');
+    sections.push(`  ${definition.resolution}`);
+    sections.push('');
+  }
+
+  // Examples section (if present)
+  if (definition.examples && definition.examples.length > 0) {
+    sections.push('Examples:');
+    for (const example of definition.examples) {
+      sections.push(`  ${example.description}`);
+      sections.push('');
+      // Indent code block
+      const codeLines = example.code.split('\n');
+      for (const line of codeLines) {
+        sections.push(`    ${line}`);
+      }
+      sections.push('');
+    }
+  }
+
+  return sections.join('\n').trimEnd();
+}