@nomad-e/bluma-cli 0.1.30 → 0.1.31

package/README.md

@@ -8,7 +8,7 @@
   <img src="https://pharmaseedevsa.blob.core.windows.net/pharmassee-dev-storage/bluma.png" alt="Screenshot BluMa CLI" width="1000"/>
 </p>
 
-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.
+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 FactorRouter), tool execution, persistent history, session management, coding memory, and extensibility through external plugins/tools and skills.
 
 ---
 
@@ -25,8 +25,9 @@ BluMa is a CLI-based model agent responsible for language-level code generation,
 - [Sandbox / Agent Mode](#sandbox-agent-mode)
 - [Configuration and Environment Variables](#configuration-and-environment-variables)
 - [Development and Build](#development-and-build)
-- [Extensibility: Tools and Plugins](#extensibility-tools-and-plugins)
+- [Extensibility: Tools, Skills and Plugins](#extensibility-tools-and-plugins)
 - [Tests](#tests)
+- [Coding Memory](#coding-memory)
 - [Limitations / Next Steps](#️-limitations--next-steps)
 - [Security Notes](#-security-notes)
 - [Tech Stack Overview](#stack)
@@ -56,19 +57,21 @@ Choose BluMa for intelligent, efficient, and collaborative software engineering
 ## <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 OpenRouter, enabling natural language-driven automation.
+- **Central agent (LLM):** orchestrated by FactorRouter, 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.
 - **ConfirmPrompt & Workflow Decision:** confirmations for sensitive operations, edit/code previews, always-accepted tool whitelists.
-- **Extensible:** easily add new tools or integrate external SDK/plugins.
+- **Coding Memory:** persistent notes about the codebase, decisions, and context that survive across sessions.
+- **Skills System:** pluggable knowledge modules for domain-specific expertise (git, testing, docker, etc.).
+- **Extensible:** easily add new tools, skills, or integrate external SDK/plugins.
 
 ---
 
 ## <a name="requirements"></a>Requirements
 - Node.js >= 18
 - npm >= 9
-- OpenRouter API key (get one at [openrouter.ai](https://openrouter.ai))
+- FactorRouter API key (get one from your FactorRouter admin)
 
 ---
 
@@ -98,17 +101,19 @@ 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, set the following environment variable globally in your system.
+For BluMa CLI to operate, set the following environment variables globally in your system.
 
 **Required:**
-- `OPENROUTER_API_KEY` (get your key at [openrouter.ai](https://openrouter.ai))
+- `FACTOR_ROUTER_KEY` — API key from your FactorRouter admin (e.g., `sk-fai-...`)
+- `FACTOR_ROUTER_URL` — FactorRouter gateway base URL (e.g., `http://host:8003/router-api`)
 
 #### How to set environment variables globally:
 
 **Linux/macOS:**
 Add to your `~/.bashrc`, `~/.zshrc`, or equivalent:
 ```sh
-export OPENROUTER_API_KEY="your_openrouter_key"
+export FACTOR_ROUTER_KEY="your_factor_router_key"
+export FACTOR_ROUTER_URL="http://host:8003/router-api"
 ```
 Then run:
 ```sh
@@ -117,13 +122,15 @@ source ~/.bashrc # or whichever file you edited
 
 **Windows (CMD):**
 ```cmd
-setx OPENROUTER_API_KEY "your_openrouter_key"
+setx FACTOR_ROUTER_KEY "your_factor_router_key"
+setx FACTOR_ROUTER_URL "http://host:8003/router-api"
 ```
 (Only needs to be run once per variable. Restart the terminal after.)
 
 **Windows (PowerShell):**
 ```powershell
-[Environment]::SetEnvironmentVariable("OPENROUTER_API_KEY", "your_openrouter_key", "Machine")
+[Environment]::SetEnvironmentVariable("FACTOR_ROUTER_KEY", "your_factor_router_key", "Machine")
+[Environment]::SetEnvironmentVariable("FACTOR_ROUTER_URL", "http://host:8003/router-api", "Machine")
 ```
 
 ### ℹ️ Global Installation of npm Packages in PowerShell (Windows)
@@ -166,7 +173,7 @@ Get up and running with BluMa in minutes:
    ```
 
 2. **Configure Environment:**
-   Set your OpenRouter API key (see [Configuration](#configuration-and-environment-variables)).
+   Set your FactorRouter API key and URL (see [Configuration](#configuration-and-environment-variables)).
 
 3. **Launch BluMa:**
    ```bash
@@ -412,15 +419,34 @@ Here's BluMa in action:
 
 ## <a name="project-structure"></a>Project Structure
 ```
-bluma-engineer/
+bluma-cli/
 ├── package.json               # npm/project config
 ├── tsconfig.json              # TypeScript config
-├── scripts/build.js           # Build script using esbuild
+├── scripts/
+│   └── build.js               # Build script using esbuild
 ├── src/
-│   ├── main.ts                # Entry point (Ink renderer)
-│   └── app/
-│        ├── agent/            # Agent core (session mgmt, tools, MCP, prompt, feedback)
-│        ├── ui/               # Ink/React CLI interface components
+│   ├── main.tsx               # Entry point (Ink renderer)
+│   ├── App.tsx                # Main React/Ink UI component
+│   ├── app/
+│   │   ├── agent/             # Agent core
+│   │   │   ├── Agent.ts       # Main orchestrator
+│   │   │   ├── BluMaAgent.ts  # Core agent loop & state
+│   │   │   ├── config/        # Configuration files
+│   │   │   ├── mcp/           # MCP client integration
+│   │   │   ├── prompts/       # System prompts
+│   │   │   ├── skills/        # Pluggable skills system
+│   │   │   ├── subagents/     # Sub-agent implementations
+│   │   │   └── tools/         # Tool definitions
+│   │   │       ├── natives/   # Native tools (shell, file ops, etc.)
+│   │   │       └── types.ts   # Tool type definitions
+│   │   └── ui/                # Ink/React CLI interface components
+│   ├── lib/                   # Shared utilities
+│   └── types/                 # TypeScript type definitions
+├── tests/                     # Test files
+├── artifacts/                 # Generated deliverables (runtime)
+└── .bluma/                    # User config & sessions (runtime)
+    ├── sessions/              # Persistent session history
+    └── skills/                # Installed skills
 ```
 ---
 
@@ -439,10 +465,26 @@ npm run dev      # (If configured, hot-reload/TS watch)
 
 ---
 
-## <a name="extensibility-tools-and-plugins"></a>Extensibility: Tools and Plugins
-- Add native tools in `src/app/agent/tools/natives/`
-- Use the MCP SDK for advanced plugins integrating with external APIs
-- Create custom Ink components to expand the interface
+## <a name="extensibility-tools-and-plugins"></a>Extensibility: Tools, Skills and Plugins
+
+### Native Tools
+Add native tools in `src/app/agent/tools/natives/` for file operations, shell commands, code search, and more.
+
+### Skills System
+BluMa features a **pluggable skills system** that loads domain-specific knowledge modules:
+
+- Skills are stored in `.bluma/skills/` (user) or `src/app/agent/skills/` (built-in)
+- Each skill is a directory with a `SKILL.md` file containing workflows and best practices
+- Skills can include `references/` (extra docs) and `scripts/` (executable helpers)
+- Load a skill with `load_skill({ skill_name: "git-commit" })`
+
+Available skills include: `git-commit`, `git-pr`, `testing`, `docker`, `pdf`, `xlsx`, and more.
+
+### MCP Integration
+Use the MCP SDK for advanced plugins integrating with external APIs and services.
+
+### Custom UI Components
+Create custom Ink components in `src/app/ui/` to expand the interface.
 
 ---
 
@@ -661,7 +703,7 @@ stateDiagram-v2
 ```mermaid
 graph TD
     CLI["CLI (BluMa)"] --> LocalFS[("Local File System")]
-    CLI --> OpenRouter[("OpenRouter API")]
+    CLI --> FactorRouter[("FactorRouter API")]
     CLI --> OtherAPIs[("Other External APIs")]
     CLI --> MCPServer[("MCP Server / Plugins")]
 ```
@@ -745,15 +787,47 @@ We welcome contributions! For full details, read [CONTRIBUTING.md](CONTRIBUTING.
 
 ---
 
+## Coding memory
+
+BluMa includes a **persistent coding memory** system that stores notes about the codebase, decisions, and context that survive across sessions:
+
+- Memory is stored in `~/.bluma/coding_memory.json`
+- Use the `coding_memory` tool to **add**, **list**, **search**, **update** (by id), or **remove** (one id at a time). There is **no** bulk “clear all” action.
+- Notes can be tagged for easy categorization (e.g., `['api', 'auth', 'performance']`)
+- Memory is loaded at session start and can be searched during tasks
+
+### When to use Coding Memory:
+- After learning stable facts about architecture or conventions
+- To store important URLs, API endpoints, or design decisions
+- To remember user preferences that should persist across sessions
+- To document invariants or critical system behaviors
+
+### Example:
+```json
+{
+  "action": "add",
+  "note": "Project uses FactorRouter for LLM routing with model auto-selection",
+  "tags": ["llm", "architecture"]
+}
+```
+
+---
+
 ## ⚠️ Limitations / Next Steps
-- 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.
+- Expand skill library with more domain-specific modules.
 
 ---
 
 ## 🔒 Security Notes
+- **API Keys:** Never commit `.env` files or hardcode API keys in source code.
+- **File Operations:** `edit_tool` can modify files — always review previews before accepting changes.
+- **Sandbox Mode:** When `BLUMA_SANDBOX=true`, BluMa is forbidden from exposing environment variables, API keys, or infrastructure details.
+- **Permissions:** Use restricted permissions for API tokens wherever possible (principle of least privilege).
+- **Shared Systems:** If using on shared systems, ensure `.bluma` config directory is private (`chmod 700 ~/.bluma`).
+- **Input Validation:** All user inputs are validated and sanitized to prevent prompt injection attacks.
 
 ---
 
@@ -824,7 +898,3 @@ BluMa handles different classes of errors gracefully:
 - Add unit tests for all business logic.
 
 ---
-- Protect your API keys: never commit `.env` files.
-- `edit_tool` can modify files — review previews before accepting.
-- Use restricted permissions for API tokens wherever possible.
-- If using on shared systems, ensure `.bluma` config is private.

package/dist/config/native_tools.json

@@ -40,7 +40,7 @@
       "type": "function",
       "function": {
         "name": "edit_tool",
-        "description": "Safely and precisely replaces text in a file, or creates a new file. The tool is resilient to common formatting issues but performs best with precise input.\n\n**Best Practices for Success:**\n1.  **Use a read tool first:** Always read the file to get the exact content before generating the `old_string`.\n2.  **Provide Context:** For `old_string`, provide a unique, multi-line segment of the file. Including 3+ lines of context around the target change is highly recommended to ensure precision.\n3.  **Create New Files:** To create a new file, provide the full `file_path` and an empty string for `old_string`.",
+        "description": "Replaces exact text in a file or creates a new file. Prefer **one** well-scoped edit over many tiny edits.\n\n**Critical — avoid line-by-line surgery:**\n- Do **not** change the same file in a dozen sequential calls with one line each; that drifts, breaks whitespace, and often fails.\n- After `read_file_lines`, copy a **single contiguous block** (whole function, whole component, or 5–20 lines with unique context) into `old_string`, then replace with your revised block in `new_string`.\n- If the tool reports no match or ambiguous match, **widen** `old_string` (more surrounding lines) or fix indentation to match the file **exactly** — do not blindly retry a one-line fragment.\n\n**CLI note:** The user may press Ctrl+O to see more lines of a **truncated** read/shell preview in the terminal. That view is UI-only and may still omit lines; always trust `read_file_lines` for exact text and whitespace before calling `edit_tool`.\n\n**Checklist:**\n1. Read the file first; use literal newlines in `old_string`/`new_string` (not the two-character sequence backslash-n).\n2. `expected_replacements` must match how many times `old_string` appears (default 1).\n3. New file: `old_string` empty, `new_string` full content.",
         "parameters": {
           "type": "object",
           "properties": {
@@ -573,29 +573,33 @@
       "type": "function",
       "function": {
         "name": "coding_memory",
-        "description": "Persists and retrieves short notes about the codebase, decisions, and context that should be remembered across turns. Use this to store important insights (APIs, invariants, design decisions) and to search them later.",
+        "description": "CRUD for durable coding notes on disk (~/.bluma/coding_memory.json), separate from chat. There is **no** action to wipe all entries: delete only one id at a time with `remove`.",
         "parameters": {
           "type": "object",
           "properties": {
             "action": {
               "type": "string",
-              "description": "Operation to perform: add a new note, list all notes, search by text/tags, or clear all entries.",
-              "enum": ["add", "list", "search", "clear"]
+              "description": "add=new note | list=all entries with ids | search=filter by query | remove=delete one entry by id | update=change note and/or tags for one id",
+              "enum": ["add", "list", "search", "remove", "update"]
+            },
+            "id": {
+              "type": "integer",
+              "description": "Required for remove and update. Obtain from list, search, or the id shown in the system prompt snapshot."
             },
             "note": {
               "type": "string",
-              "description": "The note to store when action is 'add'. Should summarize something worth remembering about the code, architecture, or requirements."
+              "description": "For add: full note text. For update: new note text (non-empty); omit if only changing tags."
             },
             "tags": {
               "type": "array",
               "items": {
                 "type": "string"
               },
-              "description": "Optional tags to categorize the note (e.g. ['api', 'auth', 'performance'])."
+              "description": "For add: optional tags. For update: optional new tag list (replaces tags when provided)."
             },
             "query": {
               "type": "string",
-              "description": "Search text used when action is 'search'. Matches against note text and tags."
+              "description": "Required for search. Matches note text and tags."
             }
           },
           "required": ["action"]