Implement interactive development mode and shell REPL (#32)

[konard]

Summary

Implements interactive development mode and shell REPL functionality as requested in #32, providing the foundation for the best developer experience for shell scripting.

Features Implemented

1. Interactive Shell REPL

• CLI Access: npx command-stream repl starts an interactive shell
• $ Command Support: Full support for $command`` syntax within REPL
• Auto-completion: Tab completion for commands and JavaScript keywords
• Multiline Support: Automatic detection and handling of multiline statements
• Built-in Commands:
  • help - Show available commands
  • exit - Exit REPL
  • clear - Clear screen
  • .commands - List registered virtual commands
• Error Handling: Graceful error reporting with optional verbose mode

2. Development Mode

• CLI Access: npx command-stream dev starts development mode
• Programmatic API: $.dev(options) method available on $ object
• File Watching: Configurable file watching with glob patterns
• REPL Integration: $.dev({ repl: true }) combines dev mode with REPL
• Customizable Patterns: Default watches **/*.mjs, **/*.js, **/*.json

3. CLI Infrastructure

• Executable: Added bin/cli.mjs with proper shebang and permissions
• Package.json: Added bin field for npx command-stream access
• Help System: Built-in help with usage examples

Usage Examples

// Interactive REPL
$ npx command-stream repl
> await $`ls -la`
> const result = await $`git status`
> result.stdout

// Development mode with file watching  
$ npx command-stream dev

// Programmatic usage
import { $ } from 'command-stream';

// Start dev mode with REPL
await $.dev({ repl: true });

// Custom file watching
await $.dev({ 
  watch: ['./scripts/*.mjs', './src/**/*.js'],
  verbose: true 
});

Test Coverage

• REPL Tests: Comprehensive test suite for interactive functionality
• Dev Mode Tests: Testing CLI, programmatic API, and integration
• Integration Tests: End-to-end testing of CLI commands

Architecture

• Modular Design: Separated REPL and dev functionality into dedicated modules
• Backward Compatibility: All existing functionality preserved
• Cross-Runtime: Works with both Bun and Node.js runtimes
• Security: Safe evaluation context with proper sandboxing

Future Extensibility

This implementation provides the foundation for the advanced features mentioned in #32:

• Visual pipeline debugger (can be integrated into REPL)
• IDE integration (REPL can serve as language server backend)
• Testing framework (REPL provides interactive testing environment)
• Hot-reload virtual commands (dev mode provides file watching)

Test Plan

• REPL starts successfully via CLI
• REPL executes $ commands correctly
• REPL handles multiline input
• REPL built-in commands work
• Dev mode starts and watches files
• $.dev() method available and functional
• CLI help system works
• All existing tests still pass
• New functionality tested comprehensively

🤖 Generated with Claude Code

---

Resolves #32