@nomad-e/bluma-cli 0.0.103 → 0.0.105

package/README.md

@@ -1,4 +1,4 @@
-# BluMa CLI
+# BluMa — Base Language Unit · Model Agent
 
 [![npm version](https://img.shields.io/npm/v/bluma.svg?style=flat-square)](https://www.npmjs.com/package/bluma)
 [![License: Apache 2.0](https://img.shields.io/badge/license-Apache%202.0-blue.svg?style=flat-square)](LICENSE)
@@ -8,16 +8,18 @@
   <img src="https://pharmaseedevsa.blob.core.windows.net/pharmassee-dev-storage/bluma.png" alt="Screenshot BluMa CLI" width="1000"/>
 </p>
 
-BluMa CLI is an independent agent for automation and advanced software engineering. The project is a conversational assistant that interacts via terminal (CLI), built with React/Ink, supporting smart agents (LLM, OpenAI Azure), tool execution, persistent history, session management, and extensibility through external plugins/tools.
+BluMa is a CLI-based model agent responsible for language-level code generation, refactoring and semantic transformations in the Factor AI stack. The project is a conversational assistant that interacts via terminal (CLI), built with React/Ink, supporting smart agents (LLM via OpenRouter), tool execution, persistent history, session management, and extensibility through external plugins/tools.
 
 ---
 
 ## Table of Contents
 - [Overview](#overview)
+- [Why BluMa?](#why-bluma)
 - [Key Features](#key-features)
 - [Requirements](#requirements)
-- [Architecture Diagram](#-architecture-diagram)
+- [Quick Start](#quick-start)
 - [Installation](#installation)
+- [Screenshots](#screenshots)
 - [Usage](#usage)
   - [Examples](#-usage-examples)
 - [Configuration and Environment Variables](#configuration-and-environment-variables)
@@ -33,14 +35,27 @@ BluMa CLI is an independent agent for automation and advanced software engineeri
 ---
 
 ## <a name="overview"></a>Overview
-BluMa CLI is a modular conversational agent and task automation framework focused on advanced software engineering workflows. It runs entirely in the terminal using React (via Ink) for a rich interactive UI, and is architected around a **UI layer** (`main.ts` + `App.tsx`) and an **agent layer** (`Agent` orchestrator + `BluMaAgent` core). It enables LLM-powered automation, documentation, refactoring, running complex development tasks, and integrating with both native and external tools. The system features persistent sessions, contextual reasoning, smart feedback, and an interactive confirmation system for controlled execution.
+BluMa is a CLI-based model agent responsible for language-level code generation, refactoring and semantic transformations in the Factor AI stack. It is a modular conversational agent and task automation framework focused on advanced software engineering workflows. It runs entirely in the terminal using React (via Ink) for a rich interactive UI, and is architected around a **UI layer** (`main.ts` + `App.tsx`) and an **agent layer** (`Agent` orchestrator + `BluMaAgent` core). It enables LLM-powered automation, documentation, refactoring, running complex development tasks, and integrating with both native and external tools. The system features persistent sessions, contextual reasoning, smart feedback, and an interactive confirmation system for controlled execution.
+
+---
+
+## Why BluMa?
+BluMa stands out as the premier CLI-based model agent for software engineering:
+
+- **Language-Level Expertise:** Specializes in code generation, refactoring, and semantic transformations, making it ideal for Factor AI stack development.
+- **Conversational Automation:** Interact naturally with an AI that understands context, history, and your project's needs.
+- **Secure & Controlled:** Built-in confirmations and whitelists ensure safe execution of powerful tools.
+- **Extensible & Modular:** Easily add tools and plugins to adapt to your workflow.
+- **Real-Time Collaboration:** Live overlays allow pair-programming style guidance during processing.
+
+Choose BluMa for intelligent, efficient, and collaborative software engineering automation.
 
 ---
 
 ## <a name="key-features"></a>Key Features
 - **Rich CLI interface** using React/Ink 5, with interactive prompts and custom components.
 - **Session management:** automatic persistence of conversation and tool history via files.
-- **Central agent (LLM):** orchestrated by Azure OpenAI (or compatible), enabling natural language-driven automation.
+- **Central agent (LLM):** orchestrated by OpenRouter, enabling natural language-driven automation.
 - **Tool invocation:** native and via MCP SDK for running commands, code manipulation, file management, and more.
 - **Dynamic prompts:** builds live conversational context, behavioral rules, and technical history.
 - **Smart feedback component** with technical suggestions and checks.
@@ -52,7 +67,7 @@ BluMa CLI is a modular conversational agent and task automation framework focuse
 ## <a name="requirements"></a>Requirements
 - Node.js >= 18
 - npm >= 9
-- Account (with key) for Azure OpenAI (or equivalent variables for OpenAI-compatible endpoints)
+- OpenRouter API key (get one at [openrouter.ai](https://openrouter.ai))
 
 ---
 
@@ -82,27 +97,17 @@ If you get permission errors, EXAMPLES:
 > Only use sudo to install, never to run the CLI.
 
 ### Setting Up Environment Variables
-For BluMa CLI to operate with OpenAI/Azure, GitHub, and Notion, set the following environment variables globally in your system.
+For BluMa CLI to operate, set the following environment variable globally in your system.
 
 **Required:**
-- `AZURE_OPENAI_ENDPOINT`
-- `AZURE_OPENAI_API_KEY`
-- `AZURE_OPENAI_API_VERSION`
-- `AZURE_OPENAI_DEPLOYMENT`
-- `GITHUB_PERSONAL_ACCESS_TOKEN` (if you'll use GitHub)
-- `NOTION_API_TOKEN` (if you'll use Notion)
+- `OPENROUTER_API_KEY` (get your key at [openrouter.ai](https://openrouter.ai))
 
 #### How to set environment variables globally:
 
 **Linux/macOS:**
 Add to your `~/.bashrc`, `~/.zshrc`, or equivalent:
 ```sh
-export AZURE_OPENAI_ENDPOINT="https://..."
-export AZURE_OPENAI_API_KEY="your_key"
-export AZURE_OPENAI_API_VERSION="2025-01-01-preview"
-export AZURE_OPENAI_DEPLOYMENT="bluma-gpt"
-export GITHUB_PERSONAL_ACCESS_TOKEN="..."
-export NOTION_API_TOKEN="..."
+export OPENROUTER_API_KEY="your_openrouter_key"
 ```
 Then run:
 ```sh
@@ -111,23 +116,13 @@ source ~/.bashrc # or whichever file you edited
 
 **Windows (CMD):**
 ```cmd
-setx AZURE_OPENAI_ENDPOINT "https://..."
-setx AZURE_OPENAI_API_KEY "your_key"
-setx AZURE_OPENAI_API_VERSION "2025-01-01-preview"
-setx AZURE_OPENAI_DEPLOYMENT "bluma-gpt"
-setx GITHUB_PERSONAL_ACCESS_TOKEN "..."
-setx NOTION_API_TOKEN "..."
+setx OPENROUTER_API_KEY "your_openrouter_key"
 ```
 (Only needs to be run once per variable. Restart the terminal after.)
 
 **Windows (PowerShell):**
 ```powershell
-[Environment]::SetEnvironmentVariable("AZURE_OPENAI_ENDPOINT", "https://...", "Machine")
-[Environment]::SetEnvironmentVariable("AZURE_OPENAI_API_KEY", "your_key", "Machine")
-[Environment]::SetEnvironmentVariable("AZURE_OPENAI_API_VERSION", "2025-01-01-preview", "Machine")
-[Environment]::SetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT", "bluma-gpt", "Machine")
-[Environment]::SetEnvironmentVariable("GITHUB_PERSONAL_ACCESS_TOKEN", "...", "Machine")
-[Environment]::SetEnvironmentVariable("NOTION_API_TOKEN", "...", "Machine")
+[Environment]::SetEnvironmentVariable("OPENROUTER_API_KEY", "your_openrouter_key", "Machine")
 ```
 
 ### ℹ️ Global Installation of npm Packages in PowerShell (Windows)
@@ -160,6 +155,40 @@ npx bluma
 
 ---
 
+## Quick Start
+
+Get up and running with BluMa in minutes:
+
+1. **Install BluMa:**
+   ```bash
+   npm install -g @nomad-e/bluma-cli
+   ```
+
+2. **Configure Environment:**
+   Set your OpenRouter API key (see [Configuration](#configuration-and-environment-variables)).
+
+3. **Launch BluMa:**
+   ```bash
+   bluma
+   ```
+
+4. **Interact:**
+   Start a conversation! Try commands like "Help me refactor this code" or "Run tests for my project."
+
+For full installation details, see [Installation](#installation).
+
+---
+
+## Screenshots
+
+Here's BluMa in action:
+
+![BluMa CLI Interface](https://pharmaseedevsa.blob.core.windows.net/pharmassee-dev-storage/bluma.png)
+
+*BluMa's interactive CLI interface for conversational software engineering.*
+
+---
+
 ## <a name="project-structure"></a>Project Structure
 ```
 bluma-engineer/
@@ -240,15 +269,10 @@ Notes
 ---
 
 ## <a name="configuration-and-environment-variables"></a>Configuration and Environment Variables
-You must create a `.env` file (copy if needed from `.env.example`) with the following variables:
-- `AZURE_OPENAI_ENDPOINT`
-- `AZURE_OPENAI_API_KEY`
-- `AZURE_OPENAI_API_VERSION`
-- `AZURE_OPENAI_DEPLOYMENT`
-- `GITHUB_PERSONAL_ACCESS_TOKEN` (optional; required for GitHub integrations)
-- `NOTION_API_TOKEN` (optional; required for Notion integrations)
+You must create a `.env` file (copy if needed from `.env.example`) with the following variable:
+- `OPENROUTER_API_KEY` (required; get from [openrouter.ai](https://openrouter.ai))
 
-And others required by your agent/context or Azure setup.
+And others required by your agent/context.
 
 Advanced config files are located in `src/app/agent/config/`.
 
@@ -261,7 +285,7 @@ Advanced config files are located in `src/app/agent/config/`.
 - Bundler: esbuild, with `esbuild-plugin-node-externals`
 - Test Runner: Jest 30 + babel-jest
 - Transpilers: Babel presets (env, react, typescript)
-- LLM/Agent: Azure OpenAI via `openai` SDK; MCP via `@modelcontextprotocol/sdk`
+- LLM/Agent: OpenRouter via API; MCP via `@modelcontextprotocol/sdk`
 - Config loading: dotenv
 - Utilities: uuid, diff, react-devtools-core
 
@@ -385,9 +409,7 @@ stateDiagram-v2
 ```mermaid
 graph TD
     CLI["CLI (BluMa)"] --> LocalFS[("Local File System")]
-    CLI --> AzureOpenAI[("Azure OpenAI API")]
-    CLI --> GitHubAPI[("GitHub API")]
-    CLI --> NotionAPI[("Notion API")]
+    CLI --> OpenRouter[("OpenRouter API")]
     CLI --> OtherAPIs[("Other External APIs")]
     CLI --> MCPServer[("MCP Server / Plugins")]
 ```
@@ -472,7 +494,7 @@ We welcome contributions! For full details, read [CONTRIBUTING.md](CONTRIBUTING.
 ---
 
 ## ⚠️ Limitations / Next Steps
-- Current LLM integration optimised for Azure OpenAI; add more providers.
+- Current LLM integration uses OpenRouter; add more providers.
 - Logging verbosity could be made configurable.
 - Potential for richer plugin lifecycle (install/remove at runtime).
 - Improve error reporting in subagents.

package/dist/config/bluma-mcp.json

@@ -1,6 +1,7 @@
 {
   "mcpServers": {
-    "reasoning": {
+    "_comment": "MCP servers are disabled - using native OpenAI reasoning field instead",
+    "_disabled_reasoning": {
       "type": "stdio",
       "command": "cmd",
       "args": [

package/dist/config/native_tools.json

@@ -227,6 +227,348 @@
         }
       }
     },
+    {
+      "type": "function",
+      "function": {
+        "name": "find_by_name",
+        "description": "Search for files and directories by name using glob patterns. Automatically ignores common directories like node_modules, .git, etc. Use this to quickly locate files in a project.",
+        "parameters": {
+          "type": "object",
+          "properties": {
+            "pattern": {
+              "type": "string",
+              "description": "Glob pattern to search for. Supports: * (wildcard), ? (single char), ** (recursive). Examples: '*.ts', 'test_*.py', 'README*'"
+            },
+            "directory": {
+              "type": "string",
+              "description": "Directory to search in. Defaults to current working directory.",
+              "default": "."
+            },
+            "extensions": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              },
+              "description": "File extensions to filter (e.g., ['.ts', '.js']). If not provided, matches all."
+            },
+            "max_depth": {
+              "type": "integer",
+              "description": "Maximum directory depth to search. Default is 10.",
+              "default": 10
+            },
+            "include_hidden": {
+              "type": "boolean",
+              "description": "Include hidden files/directories (starting with .).",
+              "default": false
+            },
+            "exclude_patterns": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              },
+              "description": "Additional patterns to exclude beyond defaults."
+            }
+          },
+          "required": [
+            "pattern"
+          ]
+        }
+      }
+    },
+    {
+      "type": "function",
+      "function": {
+        "name": "grep_search",
+        "description": "Search for text patterns within files. Supports regex, case sensitivity, and context lines. Automatically skips binary files and common non-source directories. Use this to find code, strings, or patterns across a project.",
+        "parameters": {
+          "type": "object",
+          "properties": {
+            "query": {
+              "type": "string",
+              "description": "Text or regex pattern to search for."
+            },
+            "path": {
+              "type": "string",
+              "description": "File or directory path to search. Can be a specific file or a directory for recursive search."
+            },
+            "case_insensitive": {
+              "type": "boolean",
+              "description": "Ignore case when matching. Default is true.",
+              "default": true
+            },
+            "is_regex": {
+              "type": "boolean",
+              "description": "Treat query as a regular expression. Default is false (literal match).",
+              "default": false
+            },
+            "include_patterns": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              },
+              "description": "Glob patterns for files to include (e.g., ['*.ts', '*.js']). If not provided, searches all text files."
+            },
+            "max_results": {
+              "type": "integer",
+              "description": "Maximum number of matches to return. Default is 100.",
+              "default": 100
+            },
+            "context_lines": {
+              "type": "integer",
+              "description": "Number of lines to show before/after each match. Default is 0.",
+              "default": 0
+            }
+          },
+          "required": [
+            "query",
+            "path"
+          ]
+        }
+      }
+    },
+    {
+      "type": "function",
+      "function": {
+        "name": "view_file_outline",
+        "description": "Shows the structure of a code file: classes, functions, methods, interfaces, with line numbers. Useful for understanding file organization before editing. Supports TypeScript, JavaScript, Python, Java, Go, Rust, Ruby, PHP, C#, Swift, Kotlin, Scala, C/C++.",
+        "parameters": {
+          "type": "object",
+          "properties": {
+            "file_path": {
+              "type": "string",
+              "description": "Path to the file to analyze."
+            }
+          },
+          "required": [
+            "file_path"
+          ]
+        }
+      }
+    },
+    {
+      "type": "function",
+      "function": {
+        "name": "run_command_async",
+        "description": "Start a command in background and get a command_id to track it. Use this for long-running commands like npm install, builds, or tests. The command runs asynchronously and you can check its status with command_status.",
+        "parameters": {
+          "type": "object",
+          "properties": {
+            "command": {
+              "type": "string",
+              "description": "The shell command to execute in background."
+            },
+            "cwd": {
+              "type": "string",
+              "description": "Working directory for command execution. Defaults to current directory."
+            },
+            "timeout": {
+              "type": "integer",
+              "description": "Timeout in seconds. 0 means no timeout. Default is 0.",
+              "default": 0
+            }
+          },
+          "required": [
+            "command"
+          ]
+        }
+      }
+    },
+    {
+      "type": "function",
+      "function": {
+        "name": "command_status",
+        "description": "Check the status of a background command started with run_command_async. Returns current status, output, and exit code if completed.",
+        "parameters": {
+          "type": "object",
+          "properties": {
+            "command_id": {
+              "type": "string",
+              "description": "The command ID returned by run_command_async."
+            },
+            "wait_seconds": {
+              "type": "integer",
+              "description": "Optionally wait up to N seconds for the command to complete before returning status. Default is 0 (no wait).",
+              "default": 0
+            },
+            "output_limit": {
+              "type": "integer",
+              "description": "Maximum characters of output to return. Default is 10000.",
+              "default": 10000
+            }
+          },
+          "required": [
+            "command_id"
+          ]
+        }
+      }
+    },
+    {
+      "type": "function",
+      "function": {
+        "name": "send_command_input",
+        "description": "Send input to a running background command's stdin. Useful for commands that expect user input like confirmations (y/n).",
+        "parameters": {
+          "type": "object",
+          "properties": {
+            "command_id": {
+              "type": "string",
+              "description": "The command ID of the running command."
+            },
+            "input": {
+              "type": "string",
+              "description": "The input to send to the command. Include newline if needed to submit."
+            }
+          },
+          "required": [
+            "command_id",
+            "input"
+          ]
+        }
+      }
+    },
+    {
+      "type": "function",
+      "function": {
+        "name": "kill_command",
+        "description": "Terminate a running background command.",
+        "parameters": {
+          "type": "object",
+          "properties": {
+            "command_id": {
+              "type": "string",
+              "description": "The command ID of the command to kill."
+            }
+          },
+          "required": [
+            "command_id"
+          ]
+        }
+      }
+    },
+    {
+      "type": "function",
+      "function": {
+        "name": "task_boundary",
+        "description": "Indicate the start of a task or make an update to the current task. Use this to organize complex work into phases (PLANNING, EXECUTION, VERIFICATION). The UI will show this as a structured task view with progress tracking.",
+        "parameters": {
+          "type": "object",
+          "properties": {
+            "task_name": {
+              "type": "string",
+              "description": "Name of the task, e.g. 'Implementing Authentication'. Use the same name to update an existing task."
+            },
+            "mode": {
+              "type": "string",
+              "enum": [
+                "PLANNING",
+                "EXECUTION",
+                "VERIFICATION"
+              ],
+              "description": "Current mode: PLANNING (research/design), EXECUTION (implementing), VERIFICATION (testing)."
+            },
+            "task_status": {
+              "type": "string",
+              "description": "Current activity, e.g. 'Creating authentication middleware'. Describes what you are about to do."
+            },
+            "task_summary": {
+              "type": "string",
+              "description": "Summary of what has been accomplished so far. Should be concise but comprehensive."
+            }
+          },
+          "required": [
+            "task_name",
+            "mode",
+            "task_status",
+            "task_summary"
+          ]
+        }
+      }
+    },
+    {
+      "type": "function",
+      "function": {
+        "name": "search_web",
+        "description": "Search for programming solutions across developer-focused sources: Reddit (programming subreddits), GitHub (issues/discussions), StackOverflow, and X (link only). Use this to find solutions, best practices, and community discussions about errors or implementation approaches.",
+        "parameters": {
+          "type": "object",
+          "properties": {
+            "query": {
+              "type": "string",
+              "description": "Search query, e.g. 'typescript cannot find module', 'react useEffect infinite loop fix'"
+            },
+            "sources": {
+              "type": "array",
+              "items": {
+                "type": "string",
+                "enum": [
+                  "reddit",
+                  "github",
+                  "stackoverflow",
+                  "x"
+                ]
+              },
+              "description": "Which sources to search. Default: ['reddit', 'github', 'stackoverflow']",
+              "default": [
+                "reddit",
+                "github",
+                "stackoverflow"
+              ]
+            },
+            "max_results": {
+              "type": "integer",
+              "description": "Maximum total results to return. Default is 10.",
+              "default": 10
+            }
+          },
+          "required": [
+            "query"
+          ]
+        }
+      }
+    },
+    {
+      "type": "function",
+      "function": {
+        "name": "create_artifact",
+        "description": "Create or update an artifact file in the artifacts directory (~/.bluma/artifacts/). Use this to save implementation plans, walkthroughs, notes, or any document the user should review. Supports markdown files.",
+        "parameters": {
+          "type": "object",
+          "properties": {
+            "filename": {
+              "type": "string",
+              "description": "Name of the artifact file to create. Examples: 'implementation_plan.md', 'walkthrough.md', 'notes.md'."
+            },
+            "content": {
+              "type": "string",
+              "description": "Content to write to the artifact file. Supports markdown formatting."
+            }
+          },
+          "required": [
+            "filename",
+            "content"
+          ]
+        }
+      }
+    },
+    {
+      "type": "function",
+      "function": {
+        "name": "read_artifact",
+        "description": "Read an existing artifact file from the artifacts directory. Use this to retrieve previously saved plans, walkthroughs, or notes.",
+        "parameters": {
+          "type": "object",
+          "properties": {
+            "filename": {
+              "type": "string",
+              "description": "Name of the artifact file to read. Examples: 'implementation_plan.md', 'task.md'."
+            }
+          },
+          "required": [
+            "filename"
+          ]
+        }
+      }
+    },
     {
       "type": "function",
       "function": {