@machina.ai/cell-cli-core 1.22.5-rc1 → 1.25.0-rc2

package/dist/docs/AFTER_MERGE_PROMPT.md

@@ -0,0 +1,26 @@
+There is a git branch called "release/v0.25.0", we are refering to this branch
+as "upstream branch"
+
+We have just completed a very complex merge from the upstream branch and the
+integrated code now lives in the feat/cell branch. For context, and so you can
+fully understand the scope of the changes in feat/cell, read the file located at
+@docs/CHANGES.md.
+
+You must treat the code in the upstream branch as our single source of truth. If
+there are failing tests or code that does not compile, you must not invent a
+fix. First, analyze how that code exists in the upstream branch, or verify
+whether the affected code was modified exclusively in the feat/cell branch. As a
+general rule, the upstream branch governs all decisions because it is the
+authoritative version. The only exception is when dealing with features
+explicitly described in CHANGES.md.
+
+The merge resulted in changes across hundreds of files, so the most efficient
+approach is to ensure a clean preflight run and then review each file with
+errors individually, always understanding the differences between this branch
+and the upstream branch (doing a git diff). Do not assume anything — always
+verify. The project in upstream branch compiles cleanly and without errors.
+Therefore, any failing test must be the result of changes made in feat/cell or
+side effects of the merge itself.
+
+Always consider the scope described in CHANGES.md when deciding the best course
+of action. If no clear path exists, ask the user directly before proceeding.

package/dist/docs/CHANGES.md

@@ -0,0 +1,124 @@
+# Changes in branch feat/cell vs. release/v0.8.1
+
+This document outlines the key modifications in the `feat/cell` branch for
+context-setting purposes. The primary goal of these changes is to adapt the
+Gemini CLI for a specific enterprise environment.
+
+## Core Architectural Changes
+
+### 1. New Packages
+
+Three new packages have been introduced to handle custom enterprise
+requirements:
+
+- **`@cell/api-proxy`**:
+  - **Purpose**: Provides backward compatibility for a legacy tool.
+  - **Functionality**: It starts a local server on a specific port to expose the
+    CLI's APIs, reusing the existing authentication.
+  - **IMPORTANT CONTEXT**: This package is a **temporary compatibility layer**.
+    It is not part of the core functionality of the CLI and should be ignored
+    when developing new features unless specifically related to legacy script
+    support.
+
+- **`@cell/auth-keycloak`**:
+  - **Purpose**: Manages enterprise authentication.
+  - **Functionality**: Implements an SSO (Single Sign-On) flow using an
+    on-premise Keycloak instance.
+
+- **`@cell/config-yaml`**:
+  - **Purpose**: Isolates custom configuration.
+  - **Functionality**: Manages all configuration related to the enterprise
+    modifications (e.g., SSO settings, service endpoints) in a dedicated
+    `config.yml` file. This approach avoids contaminating the native
+    `settings.json` file, which is reserved for the original CLI's settings.
+
+### 2. Integration and Re-branding
+
+- **Glue Code**: The existing codebase has been modified to integrate and
+  utilize the new packages described above.
+- **Re-branding**: Minor changes have been made to reflect a different branding.
+- **Package Aliasing**: To minimize intrusive changes to the original source
+  code, package aliases are used in `package.json`. This allows the original
+  import paths to remain the same while pointing to the new, custom packages
+  where necessary.
+
+## Summary of Intent
+
+The `feat/cell` branch is a customized version of the Gemini CLI tailored for an
+enterprise environment. The key features are SSO authentication via Keycloak and
+a temporary API proxy for backward compatibility. All custom configurations are
+stored separately in `config.yml`.
+
+## New Features
+
+### 1. User Feedback and Session Statistics
+
+- **Rating Widget**: A user feedback widget has been added to the application.
+  It appears when the user quits a session (`/quit` command), but only if at
+  least one tool was executed during that session.
+- **Backend Service Integration**:
+  - Upon quitting, the CLI now sends detailed session statistics (tool usage,
+    performance metrics, model usage) to a backend endpoint for analysis.
+  - After the user submits their rating and optional comment, this feedback is
+    sent to a separate backend endpoint.
+  - These calls are designed to be robust, with built-in retry logic, and ensure
+    that the application waits for them to complete before exiting.
+
+### 2. Self-Managed MCP Server
+
+- **Problem**: The previous method for configuring the default MCP server relied
+  on a complex and platform-specific `bash` command embedded in `settings.json`.
+  This was not compatible with Windows, was difficult to debug, and depended on
+  tools like `git` being available on the system.
+- **Solution**: A new bootstrap system has been implemented directly in the CLI.
+  For any MCP server configured with `"managed": true`, the CLI now
+  automatically handles the installation and management of the server and its
+  dependencies.
+- **Key Improvements**:
+  - **Cross-Platform**: The new system is written in Node.js and works on
+    Windows, macOS, and Linux.
+  - **Simplified Configuration**: Users no longer need a complex command. The
+    configuration is now a simple flag: `"managed": true`.
+  - **Dependency Management**: The system bootstraps its own lightweight `uv`
+    environment to install the server, avoiding reliance on system Python or
+    `pip` and removing the dependency on `git` for installation.
+  - **Robustness**: Installations are atomic, preventing corrupted server
+    setups. The CLI manages updates and ensures the correct version is running.
+
+### 3. Autenticación Automática para Servidores MCP Internos
+
+- **Problema**: Al comunicarse con un servidor MCP (Model Context Protocol) que
+  es un proxy o un servicio interno (es decir, que reside en el mismo dominio
+  que el `agent_api_url`), el CLI no incluía las cabeceras de autenticación
+  necesarias, lo que resultaba en fallos de conexión.
+- **Solución**: Se ha restaurado una funcionalidad que detecta automáticamente
+  cuándo la URL de un servidor MCP pertenece al mismo dominio que el
+  `agent_api_url` configurado. En estos casos, el CLI ahora adjunta las
+  cabeceras de autenticación (`Authorization` y `Sessionid`) a la solicitud,
+  permitiendo una comunicación segura y fluida con los servicios MCP internos.
+
+## Name and Variable Renaming
+
+The following table documents the major renaming changes from "Gemini" to "Cell"
+across environment variables, configuration directories, and internal literals.
+
+| Old Name/Literal            | New Name/Literal          |
+| :-------------------------- | :------------------------ | ------------------ | --------------------------------------------- |
+| `GEMINI_DIR`                | `CELL_DIR`                | Aa                 |
+| `GEMINI_CLI_*`              | `CELL_CLI_*`              | Aa                 |
+| `gemini_cli_`               | `cell_cli_`               | Aa                 |
+| `gemini-cli-vscode-ide-`    | `cell-cli-vscode-ide-`    | Aa                 |
+| `gemini-ide-server-`        | `cell-ide-server-`        | Aa                 |
+| `GEMINI_CONFIG_DIR`         | `CELL_CONFIG_DIR`         | Aa                 |
+| `gemini-cli-test-home-`     | `cell-cli-test-home-`     | Aa                 |
+| `GEMINI_TELEMETRY`          | `CELL_TELEMETRY`          | Aa                 |
+| `GEMINI_SYSTEM_MD`          | `CELL_SYSTEM_MD`          | Aa                 |
+| `GEMINI_WRITE_SYSTEM_MD`    | `CELL_WRITE_SYSTEM_MD`    | Aa                 |
+| `GEMINI_FORCE_FILE_STORAGE` | `CELL_FORCE_FILE_STORAGE` | Aa                 |
+| `'gemini.diff`              | `'cell-cli.diff`          | Aa                 |
+| `gemini-cli.`               | `cell-cli.`               | Aa                 |
+| `.gemini`                   | `.cell-cli`               | \*Match Whole Word |
+| `Gemini CLI`                | `Cell CLI`                | \*Match Whole Word |
+| `.gemini/`                  | `.cell-cli/`              | \*Match Whole Word |
+| `gemini-home-`              | `cell-home-`              | \*Match Whole Word |
+| `'Cell CLI MCP Client'`     | `'Gemini CLI MCP Client'` | \*Match Whole Word | <--- esta es al contrario, debe quedar Gemini |

package/dist/docs/api-proxy.md

@@ -0,0 +1,27 @@
+# Local API Proxy
+
+The local API proxy exposes the same OpenAI‑compatible endpoints used by the CLI
+on a configurable port. Requests are forwarded to `agent_api_url` after
+validating the current Keycloak session.
+
+## Configuration
+
+Set the following fields in `~/.cell-cli/config.yaml`:
+
+```yaml
+port: 13800
+agent:
+  agent_api_url: https://api.example.com
+  timeout_seconds: 60
+```
+
+- `port` – Port where the proxy listens.
+- `agent.agent_api_url` – Backend URL to forward requests to.
+- `agent.timeout_seconds` – Request timeout applied by the proxy.
+
+## Usage
+
+When the CLI starts, the plugin defined in `gemini.config.ts` launches the
+proxy. External tools can send OpenAI‑compatible requests (including a `meta`
+object) to `http://localhost:<port>` and they will be authenticated and
+forwarded unchanged.

package/dist/docs/architecture.md

@@ -0,0 +1,80 @@
+# Cell CLI Architecture Overview
+
+This document provides a high-level overview of the Cell CLI's architecture.
+
+## Core components
+
+The Cell CLI is primarily composed of two main packages, along with a suite of
+tools that can be used by the system in the course of handling command-line
+input:
+
+1.  **CLI package (`packages/cli`):**
+    - **Purpose:** This contains the user-facing portion of the Cell CLI, such
+      as handling the initial user input, presenting the final output, and
+      managing the overall user experience.
+    - **Key functions contained in the package:**
+      - [Input processing](/docs/cli/commands.md)
+      - History management
+      - Display rendering
+      - [Theme and UI customization](/docs/cli/themes.md)
+      - [CLI configuration settings](/docs/get-started/configuration.md)
+
+2.  **Core package (`packages/core`):**
+    - **Purpose:** This acts as the backend for the Cell CLI. It receives
+      requests sent from `packages/cli`, orchestrates interactions with the
+      Gemini API, and manages the execution of available tools.
+    - **Key functions contained in the package:**
+      - API client for communicating with the Google Gemini API
+      - Prompt construction and management
+      - Tool registration and execution logic
+      - State management for conversations or sessions
+      - Server-side configuration
+
+3.  **Tools (`packages/core/src/tools/`):**
+    - **Purpose:** These are individual modules that extend the capabilities of
+      the Gemini model, allowing it to interact with the local environment
+      (e.g., file system, shell commands, web fetching).
+    - **Interaction:** `packages/core` invokes these tools based on requests
+      from the Gemini model.
+
+## Interaction flow
+
+A typical interaction with the Cell CLI follows this flow:
+
+1.  **User input:** The user types a prompt or command into the terminal, which
+    is managed by `packages/cli`.
+2.  **Request to core:** `packages/cli` sends the user's input to
+    `packages/core`.
+3.  **Request processed:** The core package:
+    - Constructs an appropriate prompt for the Gemini API, possibly including
+      conversation history and available tool definitions.
+    - Sends the prompt to the Gemini API.
+4.  **Gemini API response:** The Gemini API processes the prompt and returns a
+    response. This response might be a direct answer or a request to use one of
+    the available tools.
+5.  **Tool execution (if applicable):**
+    - When the Gemini API requests a tool, the core package prepares to execute
+      it.
+    - If the requested tool can modify the file system or execute shell
+      commands, the user is first given details of the tool and its arguments,
+      and the user must approve the execution.
+    - Read-only operations, such as reading files, might not require explicit
+      user confirmation to proceed.
+    - Once confirmed, or if confirmation is not required, the core package
+      executes the relevant action within the relevant tool, and the result is
+      sent back to the Gemini API by the core package.
+    - The Gemini API processes the tool result and generates a final response.
+6.  **Response to CLI:** The core package sends the final response back to the
+    CLI package.
+7.  **Display to user:** The CLI package formats and displays the response to
+    the user in the terminal.
+
+## Key design principles
+
+- **Modularity:** Separating the CLI (frontend) from the Core (backend) allows
+  for independent development and potential future extensions (e.g., different
+  frontends for the same backend).
+- **Extensibility:** The tool system is designed to be extensible, allowing new
+  capabilities to be added.
+- **User experience:** The CLI focuses on providing a rich and interactive
+  terminal experience.