@nomad-e/bluma-cli 0.3.0 → 0.5.0

package/README.md

@@ -1,8 +1,15 @@
-# BluMa CLI — AI Agent for Advanced Software Engineering
+# BluMa CLI — AI-Powered Agent for Advanced Software Engineering
+
+![BluMa Background](assets/bg.png)
 
 [![License: Apache 2.0](https://img.shields.io/badge/license-Apache%2.0-blue.svg?style=flat-square)](LICENSE)
 [![Node.js >=20](https://img.shields.io/badge/node-%3E%3D20-brightgreen?style=flat-square)](https://nodejs.org/)
 [![Version](https://img.shields.io/npm/v/@nomad-e/bluma-cli?style=flat-square)](https://www.npmjs.com/package/@nomad-e/bluma-cli)
+[![Build Status](https://img.shields.io/badge/build-passing-brightgreen?style=flat-square)](https://github.com/Nomad-e/bluma-cli/actions)
+[![Tests](https://img.shields.io/badge/tests-Jest-blue?style=flat-square)](https://jestjs.io/)
+[![TypeScript](https://img.shields.io/badge/%3C%2F%3E-TypeScript-%230074c1.svg?style=flat-square)](https://www.typescriptlang.org/)
+[![Code Style](https://img.shields.io/badge/code_style-Prettier-ff69b4?style=flat-square)](https://prettier.io/)
+[![Downloads](https://img.shields.io/npm/dm/@nomad-e/bluma-cli?style=flat-square)](https://www.npmjs.com/package/@nomad-e/bluma-cli)
 
 **BluMa** is an independent AI agent CLI for automation and advanced software engineering. It combines powerful tool orchestration, multi-agent coordination, and intelligent context management to help you build software faster and with higher quality.
 
@@ -14,9 +21,12 @@
 # Install globally
 npm install -g @nomad-e/bluma-cli
 
-# Run BluMa
+# Run BluMa (new session)
 bluma
 
+# Resume a previous session
+bluma resume {session_id}
+
 # Or run from source
 npm install
 npm run build
@@ -27,75 +37,112 @@ npm start
 
 ## ✨ Key Features
 
-### 🤖 **50+ Native Tools**
-Comprehensive toolset for file operations, code analysis, web search, and more:
-- **Filesystem**: `edit_tool`, `file_write`, `read_file_lines`, `ls_tool`, `find_by_name`, `grep_search`
-- **Execution**: `shell_command`, `repl`, `command_status`, `kill_command`
-- **Communication**: `ask_user_question`, `send_message`, `brief`, `signal_mailbox`
-- **Planning**: `todo`, `task_boundary`, `task_create`, `task_update`, `enter_plan_mode`
-- **Knowledge**: `search_web`, `web_fetch`, `coding_memory`, `ctx_inspect`
-- **Agent Coordination**: `spawn_agent`, `wait_agent`, `list_agents`, `kill_agent`
-- **Specialized**: `context_collapse`, `dream_engine`, `snip`, `lsp_query`, `notebook_edit`
+### 🤖 **Native Tools** (45+ tools)
+Comprehensive toolset organized by category with risk levels and auto-approve policies.  
+Tools are now modularly structured in `src/app/agent/tools/` with separate UI components:
+
+**Filesystem** (10 tools):
+- `ls_tool`, `read_file_lines`, `count_file_lines`, `find_by_name`, `grep_search`
+- `view_file_outline`, `edit_tool`, `file_write`, `notebook_edit`, `lsp_query`
+
+**Execution** (6 tools):
+- `shell_command`, `command_status`, `send_command_input`, `kill_command`
+- `repl` (interactive code execution for Python/Node/Bash)
+- `task_output` (real-time output following)
+
+**Communication** (7 tools):
+- `message`, `ask_user_question`, `brief`, `send_message`
+- `list_mailbox_messages`, `poll_mailbox`, `signal_mailbox`
+
+**Planning** (11 tools):
+- `todo`, `task_boundary`, `task_create`, `task_update`, `task_stop`
+- `task_list`, `task_get`, `enter_plan_mode`, `exit_plan_mode`
+- `cron_create`, `cron_list`, `cron_delete`
+
+**Knowledge** (10 tools):
+- `search_web`, `web_fetch`, `load_skill`, `coding_memory`
+- `ctx_inspect`, `dream`, `context_collapse`, `snip`
+- `list_mcp_resources`, `read_mcp_resource`
+
+**Agent Coordination** (4 tools):
+- `spawn_agent`, `wait_agent`, `list_agents`, `kill_agent`
+
+**FactorAI Sandbox** (5 tools):
+- `factorai.sh.create_next_app`, `factorai.sh.deploy_app`
+- `factorai.sh.get_app_status`, `factorai.sh.apply_app_changes`
+- `factorai.sh.redeploy_app`
 
 ### 🧠 **Multi-Agent Orchestration**
 - **Coordinator Mode**: Product Owner + Engineering Manager hybrid that delegates to specialist workers
 - **Parallel Execution**: Launch multiple workers concurrently for research, implementation, and verification
-- **Mailbox IPC**: Bidirectional communication between coordinator and workers
+- **Mailbox IPC**: Bidirectional communication between coordinator and workers via `send_message`, `list_mailbox_messages`, `poll_mailbox`, `signal_mailbox`
 - **Worker Types**: Researchers, implementers, verifiers with specialized roles
+- **Session Registry**: Track and manage agent sessions with lifecycle events
+
+### 📝 **Slash Commands** (80+ commands)
+Quick access to common operations across 5 categories:
 
-### 📝 **50+ Slash Commands**
-Quick access to common operations:
-- **Session**: `/undo`, `/redo`, `/diff`, `/clear`, `/sessions`, `/attach`, `/bridge`, `/logs`, `/resume`, `/kill`
-- **Inspect**: `/explain`, `/fix`, `/editor`, `/config`, `/bug`, `/optimize`, `/refactor`, `/document`, `/search`, `/context`, `/token`, `/settings`, `/history`, `/alias`, `/macro`, `/template`, `/share`, `/copy`
-- **Agent**: `/test`, `/chat`, `/code`, `/terminal`, `/file`
-- **Git**: `/pr` (create PRs), `/release` (release engineering)
-- **Input**: `/help`, Ctrl+V for images
+- **Session** (25+): `/clear`, `/sessions`, `/attach`, `/follow`, `/bridge`, `/status`, `/logs`, `/resume`, `/kill`, `/compact`, `/export`, `/summarize`, `/history`, `/share`, `/copy`, `/commit`, `/pr`, `/release`, `/snip`, `/collapse`, `/brief`, `/undo`, `/redo`, `/thread` (with subcommands: list/new/resume/fork/rename/archive/delete)
+- **Inspect** (30+): `/plugins`, `/plugin`, `/diagnostics`, `/permissions`, `/features`, `/hooks`, `/model`, `/effort`, `/style`, `/sandbox`, `/worktree`, `/statusline`, `/skills`, `/tools`, `/mcp`, `/debug-workers`, `/cost`, `/memory`, `/stats`, `/theme`, `/keybindings`, `/vim`, `/ctx`, `/dream`, `/diff`, `/editor`, `/config`, `/file`, `/search`, `/context`, `/token`, `/settings`, `/alias`, `/macro`, `/thread stats`
+- **Agent** (15+): `/agent`, `/agents`, `/img`, `/image`, `/init`, `/review`, `/explain`, `/fix`, `/debug`, `/bug`, `/test`, `/optimize`, `/refactor`, `/document`, `/chat`, `/code`, `/terminal`, `/template`
+- **Help**: `/help`
+- **Input**: `Ctrl+V`/`Cmd+V` (paste image/text/file), `Ctrl+Shift+I` (same as Ctrl+V)
 
 ### 🎯 **Intelligent Context Management**
 - **Auto Memory**: Persistent coding notes across sessions (`coding_memory`)
-- **Context Collapse**: Advanced history compaction with token budget control
-- **Snip Tool**: Extract and remove old conversation snippets
-- **Dream Engine**: Background memory consolidation and deduplication
+- **Context Collapse**: Advanced history compaction with multiple strategies (aggressive, moderate, minimal, target token budget)
+- **Snip Tool**: Extract and remove old conversation snippets (extract/remove/auto modes)
+- **Dream Engine**: Background memory consolidation — deduplicates, merges, prunes, and enriches coding memory entries
 - **Token Tracking**: Real-time token usage monitoring with `ctx_inspect`
+- **Thread Management**: Full thread lifecycle with create, resume, fork, rename, archive, delete operations
 
-### 🔧 **Plan Mode**
+### 🛠️ **Plan Mode**
 Structured problem-solving workflow with 3 phases:
 1. **PLANNING**: Research and design
 2. **EXECUTION**: Implementation
 3. **VERIFICATION**: Testing and validation
 
-### 🛠️ **Skills System**
+### 🔧 **Skills System**
 Extendable expertise modules with progressive disclosure:
-- **git-commit**: Conventional commits automation
+- **git-commit**: Conventional commits automation with BluMa watermark
 - **git-pr**: Pull request creation and management
-- **git-release**: Full release engineering workflow
-- **pdf**: PDF generation and manipulation
-- **xlsx**: Spreadsheet processing
+- **git-release**: Full release engineering workflow (version bumps, changelog, tags, npm publish)
+- **pdf**: PDF generation and manipulation (reports, merge, forms, OCR)
+- **xlsx**: Spreadsheet processing (create, edit, formulas, charting, cleaning)
 - **skill-creator**: Create custom skills
 
 ### 🎨 **Modern UI**
 - Built with **Ink** (React for CLI)
-- **Shimmer effects** for working states
-- **Streamlined transcript** with syntax highlighting
-- **Bottom dock** for status and controls
-- **Workers overlay** for multi-agent visualization
-- **Thread management** for multi-thread conversations
+- **Shimmer effects** for working states (WorkingShimmerText, Spinner with ShimmerChar/FlashingChar)
+- **Streamlined transcript** with syntax highlighting (HighlightedCode, MarkdownRenderer)
+- **Bottom dock** for status and controls (BlumaBottomDock, StatusBar)
+- **Worker overlay** for multi-agent visualization (WorkerOverlay, WorkerStatusList)
+- **Real-time streaming** (StreamingMarkdown, StreamingText, TypewriterText)
+- **Animated indicators** (Spinner, ProgressBar)
+- **Theme system** with configurable themes (blumaTerminal theme)
 
 ### 🔒 **Sandbox Security**
 - **Permission modes**: Local (auto-approve) vs Sandbox (confirmation required)
 - **Policy enforcement**: `rm -rf` protection, sudo blocking, dangerous command detection
-- **FactorAI integration**: Optional sandbox backend for isolated execution
+- **Tool risk levels**: safe, write, execute, network — with per-mode auto-approve settings
+- **FactorAI integration**: Optional sandbox backend for isolated execution with workspace manifest persistence
 
-### 📦 **Native Performance**
-- **Rust clipboard**: Cross-platform clipboard support (no wl-paste/xclip dependencies)
-- **Native modules**: High-performance bindings for critical operations
+### 📦 **Performance**
 - **TypeScript**: Full type safety with strict mode
+- **ES Modules**: Modern module system with bundler resolution
+- **React 19**: Latest React with concurrent features
+- **Optimized rendering**: Memoized message blocks, offscreen freeze, expandable previews
 
 ### 🔌 **MCP Support**
 - **Model Context Protocol**: Connect to external MCP servers
 - **Resource listing**: Discover and read MCP resources
 - **SSE transport**: Server-Sent Events for real-time communication
 
+### 🧵 **Thread Management**
+- **Thread lifecycle**: Create, resume, fork, rename, archive, delete threads
+- **Thread stats**: View thread metadata and statistics
+- **Codex-style interface**: Familiar thread management commands
+
 ---
 
 ## 🏗️ Architecture
@@ -105,31 +152,62 @@ Extendable expertise modules with progressive disclosure:
 │                      BluMa CLI (Ink UI)                     │
 ├─────────────────────────────────────────────────────────────┤
 │  BlumaShell  │  BlumaViewport  │  BlumaTranscript          │
-│  BlumaBottomDock  │  BlumaWorkersOverlay                   │
+│  BlumaBottomDock  │  BlumaWorkersOverlay  │  PlanPopup      │
 ├─────────────────────────────────────────────────────────────┤
 │              useBlumaSessionRuntime (Hook)                  │
 ├─────────────────────────────────────────────────────────────┤
-│  Message Queue  │  Agent Core  │  Tool Invoker             │
-│  Session Manager  │  Prompt Builder                         │
+│  Session Registry  │  Agent Core  │  Tool Invoker          │
+│  Thread Manager  │  Prompt Builder  │  Mailbox IPC         │
 ├─────────────────────────────────────────────────────────────┤
-│  Native Tools (50+)  │  Skills  │  MCP Clients             │
+│  Native Tools (45+)  │  Skills (6)  │  MCP Clients         │
+│  FactorAI Sandbox  │  Hook Registry  │  Feature Flags      │
 └─────────────────────────────────────────────────────────────┘
 ```
 
+### Modular Tool Architecture
+
+Each tool in `src/app/agent/tools/` follows a consistent structure:
+
+```
+ToolName/
+├── index.ts           # Public API exports
+├── ToolName.ts        # Core implementation logic
+├── UI.tsx             # React/Ink UI component
+└── types.ts           # Type definitions
+```
+
+This modular design enables:
+- **Independent testing** of each tool
+- **Clear separation** of logic and presentation
+- **Easy discovery** and maintenance
+- **Consistent patterns** across the codebase
+
 ### Core Components
 
-- **`src/main.ts`**: Entry point
+- **`src/main.ts`**: Entry point with CLI mode, agent mode, session management
 - **`src/app/ui/`**: React/Ink UI components
   - `App.tsx`: Main orchestrator
-  - `BlumaSession.tsx`: Session management
-  - `components/`: Reusable UI elements
+  - `BlumaSession.tsx`: Session management and UI lifecycle
+  - `components/`: Reusable UI elements (40+ components)
+  - `hooks/`: React hooks for state management
+  - `theme/`: Theme system and terminal styling
+  - `utils/`: Utility functions and slash command registry
 - **`src/app/agent/`**: AI agent core
-  - `core/`: Prompt building, context management
-  - `tools/`: Native tool implementations
-  - `runtime/`: Session runtime, sandbox policy
+  - `core/`: Prompt building, context management, LLM integration, thread management
+  - `tools/`: **Modular tool architecture** — 43+ tool directories, each with:
+    - Implementation logic (`*.ts`)
+    - UI components (`UI.tsx`)
+    - Type definitions (`types.ts`)
+    - Index exports (`index.ts`)
+  - `runtime/`: Session runtime, sandbox policy, plugin system, hook registry
   - `session_manager/`: Multi-session orchestration
-- **`src/app/hooks/`**: React hooks for state management
-- **`src/app/utils/`**: Utility functions and helpers
+  - `subagents/`: Worker system with base LLM subagent and coordinator tools
+  - `bluma/`: BluMa-specific core logic and turn start payload
+- **`src/app/agent/config/`**: Configuration files and skill definitions
+- **`src/ink/`**: Ink renderer shims and compatibility layer
+- **`src/shims/`**: Build-time shims for react-compiler-runtime and bidi-js
+- **`native/`**: Rust-based native modules (clipboard, yoga-layout)
+- **`vscode-extension/`**: VS Code extension for chat integration
 
 ---
 
@@ -172,7 +250,6 @@ BLUMA_PERMISSION_MODE=sandbox
 
 - Node.js >= 20
 - npm >= 9
-- Rust (for native clipboard module, optional)
 
 ### Setup
 
@@ -187,9 +264,6 @@ npm install
 # Build the project
 npm run build
 
-# Or build with native modules
-npm run build:all
-
 # Start BluMa
 npm start
 ```
@@ -199,12 +273,14 @@ npm start
 | Script | Description |
 |--------|-------------|
 | `npm run build` | TypeScript check + bundle |
-| `npm run build:native` | Build Rust native modules |
+| `npm run build:native` | Build native modules |
 | `npm run build:all` | Build native + TypeScript |
+| `npm run precommit` | Run pre-commit validation |
 | `npm start` | Build + run BluMa |
 | `npm test` | Run Jest tests |
 | `npm run test:watch` | Watch mode for tests |
 | `npm run test:parallel` | Parallel test execution |
+| `npm run test:parallel:fast` | Fast parallel tests with 8 workers |
 | `npm run lint` | ESLint check |
 | `npm run lint:fix` | Auto-fix lint errors |
 
@@ -235,8 +311,9 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed contribution guidelines.
 - **[Developer Guide](docs/BLUMA_DEVELOPER_GUIDE.md)**: Complete technical reference
 - **[Skills Guide](docs/SKILLS.md)**: How to create and use skills
 - **[Mailbox IPC](docs/MAILBOX_IPC.md)**: Multi-agent communication
-- **[Plan Mode](docs/plan-mode/)**: Structured problem-solving workflow
 - **[CI/CD](docs/CI-TEST.md)**: Continuous integration setup
+- **[Message Queue](docs/message-queue-design.md)**: IPC system design
+- **[Parallel Tests](docs/parallel-tests.md)**: Test parallelization guide
 
 ---
 
@@ -272,100 +349,21 @@ bluma
 
 ### 4. **Pull Request Creation**
 ```bash
-/pr dev to main                    # Create PR from dev to main
-/pr feature/auth to develop --draft  # Draft PR
-```
-
-### 5. **Context Management**
-```bash
-/context              # Inspect current context
-/token                # View token usage
-/summarize            # Summarize conversation
+/pr "feat: add new authentication"  # Create PR with conventional commit
 ```
 
 ---
 
-## 🔧 Tool Categories
-
-### Filesystem Tools (12)
-`edit_tool`, `file_write`, `read_file_lines`, `ls_tool`, `find_by_name`, `grep_search`, `view_file_outline`, `count_file_lines`, `file_write`, `snip`, `ctx_inspect`, `workspace_snapshot`
-
-### Execution Tools (6)
-`shell_command`, `command_status`, `send_command_input`, `kill_command`, `repl`, `task_output`
-
-### Communication Tools (5)
-`ask_user_question`, `send_message`, `list_mailbox_messages`, `signal_mailbox`, `brief`
-
-### Planning Tools (8)
-`todo`, `task_boundary`, `task_create`, `task_update`, `task_stop`, `task_list`, `enter_plan_mode`, `exit_plan_mode`
-
-### Knowledge Tools (6)
-`search_web`, `web_fetch`, `coding_memory`, `ctx_inspect`, `dream_engine`, `load_skill`
-
-### Agent Coordination Tools (6)
-`spawn_agent`, `wait_agent`, `list_agents`, `kill_agent`, `send_message`, `list_mailbox_messages`
-
-### Specialized Tools (7)
-`context_collapse`, `snip`, `brief`, `lsp_query`, `notebook_edit`, `createNextApp`, `deployApp`
-
-### MCP Tools (2)
-`list_mcp_resources`, `read_mcp_resource`
-
-### Session Tools (3)
-`cronCreate`, `cronList`, `cronDelete`
-
----
-
-## 🎨 UI Components
-
-- **BlumaShell**: Main application shell with header and footer
-- **BlumaViewport**: Scrollable transcript view
-- **BlumaTranscript**: Message rendering with syntax highlighting
-- **BlumaBottomDock**: Status bar and controls
-- **BlumaWorkersOverlay**: Worker status visualization
-- **WorkingShimmerText**: Animated working state indicator
-- **FilePathLink**: Clickable file paths
-- **HighlightedCode**: Syntax-highlighted code blocks
-- **CtrlOToExpand**: Expandable content indicator
-
----
-
-## 🔐 Security
-
-- **Sandbox Policy**: Blocks dangerous commands (`rm -rf /`, `sudo`, etc.)
-- **Permission Modes**: Configurable auto-approve vs confirmation
-- **Input Validation**: JSON argument validation for tool calls
-- **Error Handling**: User-friendly error messages with hints
-- **Rate Limiting**: Web search and external API rate limiting
-
----
-
-## 📦 Package Info
-
-- **Name**: `@nomad-e/bluma-cli`
-- **Version**: `0.2.3`
-- **License**: Apache 2.0
-- **Engine**: Node.js >= 20
-- **Type**: ES Modules
-- **Main**: `dist/main.js`
-- **Bin**: `bluma`
-
----
-
-## 🤝 Community
+## 📄 License
 
-- **Issues**: Report bugs and suggest features on GitHub
-- **Discussions**: Open questions and community discussions
-- **Contributions**: See [CONTRIBUTING.md](CONTRIBUTING.md)
+Apache 2.0 — see [LICENSE](LICENSE) for details.
 
 ---
 
-## 📄 License
+## 👤 Author
 
-Apache 2.0 — see [LICENSE](LICENSE) for details.
+**Alex Fonseca** — [@nomad-e](https://github.com/Nomad-e)
 
 ---
 
-<p align="center">
-  <sub>Built with ❤️ by <a href="https://github.com/Nomad-e">NomadEngenuity</a></sub>
-</p>
+*BluMa CLI v0.3.1 — Built with TypeScript, React/Ink, and ES modules.*

package/dist/config/native_tools.json

@@ -294,6 +294,10 @@
             "filepath": {
               "type": "string",
               "description": "Path to the file to count lines from. Can be relative or absolute."
+            },
+            "file_path": {
+              "type": "string",
+              "description": "Alias for filepath, accepted for consistency with edit/file tools."
             }
           },
           "required": [
@@ -314,6 +318,10 @@
               "type": "string",
               "description": "Path to the file (workspace-relative or absolute)."
             },
+            "file_path": {
+              "type": "string",
+              "description": "Alias for filepath, accepted for consistency with edit/file tools."
+            },
             "offset": {
               "type": "integer",
               "description": "1-based start line; same as start_line. Defaults to 1."
@@ -765,7 +773,7 @@
       "type": "function",
       "function": {
         "name": "ask_user_question",
-        "description": "Ask the user one or more multiple-choice questions in the terminal (AskUserQuestion). Blocks until they answer. Only the first question is shown; options must be single-select.",
+        "description": "Ask the user one or more multiple-choice questions in the terminal (AskUserQuestion). Blocks until they answer. Supports multiple questions, option previews, and optional multi-select.",
         "parameters": {
           "type": "object",
           "properties": {
@@ -776,14 +784,15 @@
                 "properties": {
                   "question": { "type": "string", "description": "Question text" },
                   "header": { "type": "string", "description": "Short section title" },
-                  "multiSelect": { "type": "boolean", "description": "Not supported yet; omit or false." },
+                  "multiSelect": { "type": "boolean", "description": "Allow selecting multiple options for this question." },
                   "options": {
                     "type": "array",
                     "items": {
                       "type": "object",
                       "properties": {
                         "label": { "type": "string" },
-                        "description": { "type": "string" }
+                        "description": { "type": "string" },
+                        "preview": { "type": "string", "description": "Optional rendered preview shown beside the options." }
                       },
                       "required": ["label"]
                     }