@nomad-e/bluma-cli 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Alex Fonseca and NomadEngenuity contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,216 @@
+# BluMa CLI
+
+[![npm version](https://img.shields.io/npm/v/bluma.svg?style=flat-square)](https://www.npmjs.com/package/bluma)
+[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square)](LICENSE)
+[![Build Status](https://img.shields.io/badge/build-passing-brightgreen?style=flat-square)](https://shields.io/)
+
+<p align="center">
+  <img src="docs\assets\images\bluma.png" alt="Tela inicial 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.
+
+---
+
+## Table of Contents
+- [Overview](#overview)
+- [Key Features](#key-features)
+- [Requirements](#requirements)
+- [Installation](#installation)
+- [How to Run](#how-to-run)
+- [Project Structure](#project-structure)
+- [Development and Build](#development-and-build)
+- [Extensibility: Tools and Plugins](#extensibility-tools-and-plugins)
+- [Tests](#tests)
+- [Configuration and Environment Variables](#configuration-and-environment-variables)
+- [License](#license)
+
+---
+
+## <a name="overview"></a>Overview
+BluMa CLI is a modern CLI focused on automation, LLM collaboration, documentation, refactoring, running complex tasks, and integrating with external tools. It uses React (via Ink) for rich terminal interfaces and features context/conversation management, smart feedback, and interactive confirmation systems.
+
+---
+
+## <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.
+- **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.
+
+---
+
+## <a name="requirements"></a>Requirements
+- Node.js >= 18
+- npm >= 9
+- Account (with key) for Azure OpenAI (or equivalent variables for OpenAI-compatible endpoints)
+
+---
+
+## <a name="installation"></a>Installation
+
+### Recommended: Global Installation
+
+> **Important:** It is recommended to install BluMa globally so the `bluma` command works in any terminal.
+
+```bash
+npm install -g @nomad-e/bluma-cli
+```
+
+If you get permission errors, EXAMPLES:
+  - **Linux:** Run as administrator using `sudo`:
+    ```bash
+    sudo npm install -g @nomad-e/bluma-cli
+    ```
+  - **Windows:** Open Command Prompt/Terminal as Administrator and repeat the command
+
+> **macOS:** After global installation, **always run the `bluma` command without sudo**:
+>
+> ```bash
+> bluma
+> ```
+> Running with sudo may cause permission problems, environment variable issues, and npm cache ownership problems.
+> 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.
+
+**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)
+
+#### 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="2024-06-01"
+export AZURE_OPENAI_DEPLOYMENT="bluma-gpt"
+export GITHUB_PERSONAL_ACCESS_TOKEN="..."
+export NOTION_API_TOKEN="..."
+```
+Then run:
+```sh
+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 "2024-06-01"
+setx AZURE_OPENAI_DEPLOYMENT "bluma-gpt"
+setx GITHUB_PERSONAL_ACCESS_TOKEN "..."
+setx NOTION_API_TOKEN "..."
+```
+(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", "2024-06-01", "Machine")
+[Environment]::SetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT", "bluma-gpt", "Machine")
+[Environment]::SetEnvironmentVariable("GITHUB_PERSONAL_ACCESS_TOKEN", "...", "Machine")
+[Environment]::SetEnvironmentVariable("NOTION_API_TOKEN", "...", "Machine")
+```
+
+### ℹ️ Global Installation of npm Packages in PowerShell (Windows)
+When installing BluMa (or any npm package globally) in PowerShell, you might see:
+```
+Do you want to change the execution policy?
+[Y] Yes  [A] Yes to All  [N] No  [L] No to All  [S] Suspend  [?] Help (default is "N"):
+```
+👉 **Choose `Y` (Yes) or `A` (Yes to All)**. This will change the execution policy to **RemoteSigned** (only scripts from the internet need a digital signature).
+
+- This is safe for devs: Windows only requires digital signatures for web scripts—local scripts, from npm, work normally.
+- Read more: [About Execution Policies (Microsoft Docs)](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.security/about/about_execution_policies)
+
+**To restore the default policy after installation, run:**
+```powershell
+Set-ExecutionPolicy Default
+```
+
+> **Tip:** Restart your terminal to ensure the variables are loaded globally.
+
+---
+
+## <a name="how-to-run"></a>How to Run
+```bash
+npm start
+# Or directly using the built binary
+npx bluma
+```
+==> The CLI will open an interactive terminal interface for dialogue, command execution, and engineering workflow automation.
+
+---
+
+## <a name="project-structure"></a>Project Structure
+```
+bluma-engineer/
+├── package.json               # npm/project config
+├── tsconfig.json              # TypeScript config
+├── 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
+│        └── protocols/        # Protocols & helpers
+```
+---
+
+## <a name="development-and-build"></a>Development and Build
+- Build is performed using [esbuild](https://esbuild.github.io/) (see scripts/build.js).
+- TS source files are in `src/` and compiled to `dist/`.
+- Use `npm run build` to compile and get the CLI binary ready.
+- Config files are automatically copied to `dist/config`.
+
+### Main scripts:
+```bash
+npm run build    # Compiles project to dist/
+npm start        # Runs CLI (after build)
+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="tests"></a>Tests
+- Organize your tests inside the `test/` folder in your preferred style or as your project's coverage grows
+
+---
+
+## <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`
+
+And others required by your agent/context or Azure setup.
+
+Advanced config files are located in `src/app/agent/config/`.
+
+---
+
+## <a name="license"></a>License
+MIT. Made by Alex Fonseca and NomadEngenuity contributors.
+
+Enjoy, hack, and—if possible—contribute!

package/dist/config/bluma-mcp.json

@@ -0,0 +1,52 @@
+{
+  "mcpServers": {
+    "bluma": {
+      "type": "stdio", 
+      "command": "cmd",
+      "args": [
+        "/c",
+        "npx",
+        "-y",
+        "@sousaalex1605/bluma-nootebook"
+      ]
+    },
+    "github": {
+      "type": "stdio", 
+      "command": "cmd",
+      "args": [
+        "/c",
+        "npx",
+        "-y",
+        "@modelcontextprotocol/server-github"
+      ],
+      "env": {
+        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_PERSONAL_ACCESS_TOKEN}"
+      }
+    },
+    "notion": {
+      "type": "stdio", 
+      "command": "cmd",
+      "args": [
+        "/c",
+        "npx",
+        "-y",
+        "@suekou/mcp-notion-server"
+      ],
+      "env": {
+        "NOTION_API_TOKEN": "${NOTION_API_TOKEN}"
+      }
+    },
+    "upstash_context7-mcp": {
+      "type": "stdio", 
+      "command": "cmd",
+      "args": [
+        "/c",
+        "npx",
+        "-y",
+        "@upstash/context7-mcp@latest"
+      ],
+      "disabled": false,
+      "autoApprove": []
+    }
+  }
+}

package/dist/config/native_tools.json

@@ -0,0 +1,199 @@
+{
+    "nativeTools": [
+        {
+            "type": "function",
+            "function": {
+                "name": "shell_command",
+                "description": "Executes a terminal command in a robust and Windows/Linux compatible way.",
+                "parameters": {
+                    "type": "object",
+                    "properties": {
+                        "command": {
+                            "type": "string",
+                            "description": "Shell command to execute"
+                        },
+                        "timeout": {
+                            "type": "integer",
+                            "description": "Maximum execution time in seconds",
+                            "default": 20
+                        },
+                        "cwd": {
+                            "type": "string",
+                            "description": "Working directory for command execution (must use absolute path)"
+                        },
+                        "verbose": {
+                            "type": "boolean",
+                            "description": "If True, returns detailed report; if False, only main output",
+                            "default": false
+                        }
+                    },
+                    "required": [
+                        "command"
+                    ]
+                }
+            }
+        },
+        {
+            "type": "function",
+            "function": {
+                "name": "edit_tool",
+                "description": "Replaces text within a file. By default, replaces a single occurrence, but can replace multiple occurrences when `expected_replacements` is specified. This tool requires providing significant context around the change to ensure precise targeting. Always use the read file tool to examine the file's current content before attempting a text replacement.\n\nExpectation for required parameters:\n1. `file_path` MUST be an absolute path; otherwise an error will be thrown.\n2. `old_string` MUST be the exact literal text to replace (including all whitespace, indentation, newlines, and surrounding code etc.).\n3. `new_string` MUST be the exact literal text to replace `old_string` with (also including all whitespace, indentation, newlines, and surrounding code etc.). Ensure the resulting code is correct and idiomatic.\n4. NEVER escape `old_string` or `new_string`, that would break the exact literal text requirement.\n**Important:** If ANY of the above are not satisfied, the tool will fail. CRITICAL for `old_string`: Must uniquely identify the single instance to change. Include at least 3 lines of context BEFORE and AFTER the target text, matching whitespace and indentation precisely. If this string matches multiple locations, or does not match exactly, the tool will fail.\n**Multiple replacements:** Set `expected_replacements` to the number of occurrences you want to replace. The tool will replace ALL occurrences that match `old_string` exactly. Ensure the number of replacements matches your expectation.",
+                "parameters": {
+                    "type": "object",
+                    "properties": {
+                        "file_path": {
+                            "type": "string",
+                            "description": "The absolute path to the file to modify. Must start with '/'."
+                        },
+                        "old_string": {
+                            "type": "string",
+                            "description": "The exact literal text to replace, preferably unescaped. For single replacements (default), include at least 3 lines of context BEFORE and AFTER the target text, matching whitespace and indentation precisely. For multiple replacements, specify expected_replacements parameter. If this string is not the exact literal text (i.e. you escaped it) or does not match exactly, the tool will fail."
+                        },
+                        "new_string": {
+                            "type": "string",
+                            "description": "The exact literal text to replace `old_string` with, preferably unescaped. Provide the EXACT text. Ensure the resulting code is correct and idiomatic."
+                        },
+                        "expected_replacements": {
+                            "type": "integer",
+                            "description": "Number of replacements expected. Defaults to 1 if not specified. Use when you want to replace multiple occurrences.",
+                            "default": 1
+                        }
+                    },
+                    "required": [
+                        "file_path",
+                        "old_string",
+                        "new_string"
+                    ]
+                }
+            }
+        },
+        {
+            "type": "function",
+            "function": {
+                "name": "agent_end_task",
+                "description": "Ends the current task and logs out of the agent",
+                "parameters": {
+                    "type": "object",
+                    "properties": {},
+                    "required": []
+                }
+            }
+        },
+        {
+            "type": "function",
+            "function": {
+                "name": "message_notify_dev",
+                "description": "Send a message to dev without requiring a response. Use for acknowledging receipt of messages, providing progress updates, reporting task completion, or explaining changes in approach.",
+                "parameters": {
+                    "type": "object",
+                    "properties": {
+                        "text_markdown": {
+                            "type": "string",
+                            "description": "The body of the message in Markdown format."
+                        }
+                    },
+                    "required": [
+                        "text_markdown"
+                    ]
+                }
+            }
+        },
+        {
+            "type": "function",
+            "function": {
+              "name": "ls_tool",
+              "description": "Lists files and subdirectories with advanced support for pagination and filtering. Automatically ignores common unnecessary files/directories like '.venv', 'node_modules', etc.",
+              "parameters": {
+                "type": "object",
+                "properties": {
+                  "directory_path": {
+                    "type": "string",
+                    "description": "Path of the directory to list. Defaults to '.' (current directory).",
+                    "default": "."
+                  },
+                  "recursive": {
+                    "type": "boolean",
+                    "description": "If True, lists recursively all subdirectories.",
+                    "default": false
+                  },
+                  "ignore_patterns": {
+                    "type": "array",
+                    "items": {
+                      "type": "string"
+                    },
+                    "description": "Additional patterns to ignore (beyond defaults). E.g., ['test_*', '*.tmp']"
+                  },
+                  "start_index": {
+                    "type": "integer",
+                    "description": "Starting index for pagination (0-based).",
+                    "default": 0
+                  },
+                  "end_index": {
+                    "type": "integer",
+                    "description": "Ending index for pagination (exclusive). If not provided, lists everything from start_index."
+                  },
+                  "show_hidden": {
+                    "type": "boolean",
+                    "description": "If True, shows files/directories starting with '.'.",
+                    "default": false
+                  },
+                  "file_extensions": {
+                    "type": "array",
+                    "items": {
+                      "type": "string"
+                    },
+                    "description": "List of extensions to filter (e.g., ['.ts', '.js', '.md']). If not provided, shows all file types."
+                  },
+                  "max_depth": {
+                    "type": "integer",
+                    "description": "Maximum depth for recursive listing. If not provided, there is no limit."
+                  }
+                },
+                "required": []
+              }
+            }
+          },
+          {
+            "type": "function",
+            "function": {
+              "name": "count_file_lines",
+              "description": "Counts and returns the total number of lines in a text file. Useful for quickly determining file size or checking if a file is empty before reading it.",
+              "parameters": {
+                "type": "object",
+                "properties": {
+                  "filepath": {
+                    "type": "string",
+                    "description": "Path to the file to count lines from. Can be relative or absolute."
+                  }
+                },
+                "required": ["filepath"]
+              }
+            }
+          },
+          {
+            "type": "function",
+            "function": {
+              "name": "read_file_lines",
+              "description": "Reads and returns content between specific line numbers from a text file. Ideal for efficiently reading portions of large files.",
+              "parameters": {
+                "type": "object",
+                "properties": {
+                  "filepath": {
+                    "type": "string",
+                    "description": "Path to the file to read from."
+                  },
+                  "start_line": {
+                    "type": "integer",
+                    "description": "Starting line number (1-based index). Must be >= 1."
+                  },
+                  "end_line": {
+                    "type": "integer",
+                    "description": "Ending line number (1-based index, inclusive). Must be >= start_line."
+                  }
+                },
+                "required": ["filepath", "start_line", "end_line"]
+              }
+            }
+          }
+    ]
+}