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

package/dist/docs/integration-tests.md

@@ -0,0 +1,211 @@
+# Integration tests
+
+This document provides information about the integration testing framework used
+in this project.
+
+## Overview
+
+The integration tests are designed to validate the end-to-end functionality of
+the Cell CLI. They execute the built binary in a controlled environment and
+verify that it behaves as expected when interacting with the file system.
+
+These tests are located in the `integration-tests` directory and are run using a
+custom test runner.
+
+## Building the tests
+
+Prior to running any integration tests, you need to create a release bundle that
+you want to actually test:
+
+```bash
+npm run bundle
+```
+
+You must re-run this command after making any changes to the CLI source code,
+but not after making changes to tests.
+
+## Running the tests
+
+The integration tests are not run as part of the default `npm run test` command.
+They must be run explicitly using the `npm run test:integration:all` script.
+
+The integration tests can also be run using the following shortcut:
+
+```bash
+npm run test:e2e
+```
+
+## Running a specific set of tests
+
+To run a subset of test files, you can use
+`npm run <integration test command> <file_name1> ....` where &lt;integration
+test command&gt; is either `test:e2e` or `test:integration*` and `<file_name>`
+is any of the `.test.js` files in the `integration-tests/` directory. For
+example, the following command runs `list_directory.test.js` and
+`write_file.test.js`:
+
+```bash
+npm run test:e2e list_directory write_file
+```
+
+### Running a single test by name
+
+To run a single test by its name, use the `--test-name-pattern` flag:
+
+```bash
+npm run test:e2e -- --test-name-pattern "reads a file"
+```
+
+### Regenerating model responses
+
+Some integration tests use faked out model responses, which may need to be
+regenerated from time to time as the implementations change.
+
+To regenerate these golden files, set the REGENERATE_MODEL_GOLDENS environment
+variable to "true" when running the tests, for example:
+
+**WARNING**: If running locally you should review these updated responses for
+any information about yourself or your system that gemini may have included in
+these responses.
+
+```bash
+REGENERATE_MODEL_GOLDENS="true" npm run test:e2e
+```
+
+**WARNING**: Make sure you run **await rig.cleanup()** at the end of your test,
+else the golden files will not be updated.
+
+### Deflaking a test
+
+Before adding a **new** integration test, you should test it at least 5 times
+with the deflake script or workflow to make sure that it is not flaky.
+
+### Deflake script
+
+```bash
+npm run deflake -- --runs=5 --command="npm run test:e2e -- -- --test-name-pattern '<your-new-test-name>'"
+```
+
+#### Deflake workflow
+
+```bash
+gh workflow run deflake.yml --ref <your-branch> -f test_name_pattern="<your-test-name-pattern>"
+```
+
+### Running all tests
+
+To run the entire suite of integration tests, use the following command:
+
+```bash
+npm run test:integration:all
+```
+
+### Sandbox matrix
+
+The `all` command will run tests for `no sandboxing`, `docker` and `podman`.
+Each individual type can be run using the following commands:
+
+```bash
+npm run test:integration:sandbox:none
+```
+
+```bash
+npm run test:integration:sandbox:docker
+```
+
+```bash
+npm run test:integration:sandbox:podman
+```
+
+## Diagnostics
+
+The integration test runner provides several options for diagnostics to help
+track down test failures.
+
+### Keeping test output
+
+You can preserve the temporary files created during a test run for inspection.
+This is useful for debugging issues with file system operations.
+
+To keep the test output set the `KEEP_OUTPUT` environment variable to `true`.
+
+```bash
+KEEP_OUTPUT=true npm run test:integration:sandbox:none
+```
+
+When output is kept, the test runner will print the path to the unique directory
+for the test run.
+
+### Verbose output
+
+For more detailed debugging, set the `VERBOSE` environment variable to `true`.
+
+```bash
+VERBOSE=true npm run test:integration:sandbox:none
+```
+
+When using `VERBOSE=true` and `KEEP_OUTPUT=true` in the same command, the output
+is streamed to the console and also saved to a log file within the test's
+temporary directory.
+
+The verbose output is formatted to clearly identify the source of the logs:
+
+```
+--- TEST: <log dir>:<test-name> ---
+... output from the gemini command ...
+--- END TEST: <log dir>:<test-name> ---
+```
+
+## Linting and formatting
+
+To ensure code quality and consistency, the integration test files are linted as
+part of the main build process. You can also manually run the linter and
+auto-fixer.
+
+### Running the linter
+
+To check for linting errors, run the following command:
+
+```bash
+npm run lint
+```
+
+You can include the `:fix` flag in the command to automatically fix any fixable
+linting errors:
+
+```bash
+npm run lint:fix
+```
+
+## Directory structure
+
+The integration tests create a unique directory for each test run inside the
+`.integration-tests` directory. Within this directory, a subdirectory is created
+for each test file, and within that, a subdirectory is created for each
+individual test case.
+
+This structure makes it easy to locate the artifacts for a specific test run,
+file, or case.
+
+```
+.integration-tests/
+└── <run-id>/
+    └── <test-file-name>.test.js/
+        └── <test-case-name>/
+            ├── output.log
+            └── ...other test artifacts...
+```
+
+## Continuous integration
+
+To ensure the integration tests are always run, a GitHub Actions workflow is
+defined in `.github/workflows/chained_e2e.yml`. This workflow automatically runs
+the integrations tests for pull requests against the `main` branch, or when a
+pull request is added to a merge queue.
+
+The workflow runs the tests in different sandboxing environments to ensure Cell
+CLI is tested across each:
+
+- `sandbox:none`: Runs the tests without any sandboxing.
+- `sandbox:docker`: Runs the tests in a Docker container.
+- `sandbox:podman`: Runs the tests in a Podman container.

package/dist/docs/issue-and-pr-automation.md

@@ -0,0 +1,134 @@
+# Automation and triage processes
+
+This document provides a detailed overview of the automated processes we use to
+manage and triage issues and pull requests. Our goal is to provide prompt
+feedback and ensure that contributions are reviewed and integrated efficiently.
+Understanding this automation will help you as a contributor know what to expect
+and how to best interact with our repository bots.
+
+## Guiding principle: Issues and pull requests
+
+First and foremost, almost every Pull Request (PR) should be linked to a
+corresponding Issue. The issue describes the "what" and the "why" (the bug or
+feature), while the PR is the "how" (the implementation). This separation helps
+us track work, prioritize features, and maintain clear historical context. Our
+automation is built around this principle.
+
+> **Note:** Issues tagged as "🔒Maintainers only" are reserved for project
+> maintainers. We will not accept pull requests related to these issues.
+
+---
+
+## Detailed automation workflows
+
+Here is a breakdown of the specific automation workflows that run in our
+repository.
+
+### 1. When you open an issue: `Automated Issue Triage`
+
+This is the first bot you will interact with when you create an issue. Its job
+is to perform an initial analysis and apply the correct labels.
+
+- **Workflow File**: `.github/workflows/gemini-automated-issue-triage.yml`
+- **When it runs**: Immediately after an issue is created or reopened.
+- **What it does**:
+  - It uses a Gemini model to analyze the issue's title and body against a
+    detailed set of guidelines.
+  - **Applies one `area/*` label**: Categorizes the issue into a functional area
+    of the project (e.g., `area/ux`, `area/models`, `area/platform`).
+  - **Applies one `kind/*` label**: Identifies the type of issue (e.g.,
+    `kind/bug`, `kind/enhancement`, `kind/question`).
+  - **Applies one `priority/*` label**: Assigns a priority from P0 (critical) to
+    P3 (low) based on the described impact.
+  - **May apply `status/need-information`**: If the issue lacks critical details
+    (like logs or reproduction steps), it will be flagged for more information.
+  - **May apply `status/need-retesting`**: If the issue references a CLI version
+    that is more than six versions old, it will be flagged for retesting on a
+    current version.
+- **What you should do**:
+  - Fill out the issue template as completely as possible. The more detail you
+    provide, the more accurate the triage will be.
+  - If the `status/need-information` label is added, please provide the
+    requested details in a comment.
+
+### 2. When you open a pull request: `Continuous Integration (CI)`
+
+This workflow ensures that all changes meet our quality standards before they
+can be merged.
+
+- **Workflow File**: `.github/workflows/ci.yml`
+- **When it runs**: On every push to a pull request.
+- **What it does**:
+  - **Lint**: Checks that your code adheres to our project's formatting and
+    style rules.
+  - **Test**: Runs our full suite of automated tests across macOS, Windows, and
+    Linux, and on multiple Node.js versions. This is the most time-consuming
+    part of the CI process.
+  - **Post Coverage Comment**: After all tests have successfully passed, a bot
+    will post a comment on your PR. This comment provides a summary of how well
+    your changes are covered by tests.
+- **What you should do**:
+  - Ensure all CI checks pass. A green checkmark ✅ will appear next to your
+    commit when everything is successful.
+  - If a check fails (a red "X" ❌), click the "Details" link next to the failed
+    check to view the logs, identify the problem, and push a fix.
+
+### 3. Ongoing triage for pull requests: `PR Auditing and Label Sync`
+
+This workflow runs periodically to ensure all open PRs are correctly linked to
+issues and have consistent labels.
+
+- **Workflow File**: `.github/workflows/gemini-scheduled-pr-triage.yml`
+- **When it runs**: Every 15 minutes on all open pull requests.
+- **What it does**:
+  - **Checks for a linked issue**: The bot scans your PR description for a
+    keyword that links it to an issue (e.g., `Fixes #123`, `Closes #456`).
+  - **Adds `status/need-issue`**: If no linked issue is found, the bot will add
+    the `status/need-issue` label to your PR. This is a clear signal that an
+    issue needs to be created and linked.
+  - **Synchronizes labels**: If an issue _is_ linked, the bot ensures the PR's
+    labels perfectly match the issue's labels. It will add any missing labels
+    and remove any that don't belong, and it will remove the `status/need-issue`
+    label if it was present.
+- **What you should do**:
+  - **Always link your PR to an issue.** This is the most important step. Add a
+    line like `Resolves #<issue-number>` to your PR description.
+  - This will ensure your PR is correctly categorized and moves through the
+    review process smoothly.
+
+### 4. Ongoing triage for issues: `Scheduled Issue Triage`
+
+This is a fallback workflow to ensure that no issue gets missed by the triage
+process.
+
+- **Workflow File**: `.github/workflows/gemini-scheduled-issue-triage.yml`
+- **When it runs**: Every hour on all open issues.
+- **What it does**:
+  - It actively seeks out issues that either have no labels at all or still have
+    the `status/need-triage` label.
+  - It then triggers the same powerful Gemini-based analysis as the initial
+    triage bot to apply the correct labels.
+- **What you should do**:
+  - You typically don't need to do anything. This workflow is a safety net to
+    ensure every issue is eventually categorized, even if the initial triage
+    fails.
+
+### 5. Release automation
+
+This workflow handles the process of packaging and publishing new versions of
+the Cell CLI.
+
+- **Workflow File**: `.github/workflows/release-manual.yml`
+- **When it runs**: On a daily schedule for "nightly" releases, and manually for
+  official patch/minor releases.
+- **What it does**:
+  - Automatically builds the project, bumps the version numbers, and publishes
+    the packages to npm.
+  - Creates a corresponding release on GitHub with generated release notes.
+- **What you should do**:
+  - As a contributor, you don't need to do anything for this process. You can be
+    confident that once your PR is merged into the `main` branch, your changes
+    will be included in the very next nightly release.
+
+We hope this detailed overview is helpful. If you have any questions about our
+automation or processes, please don't hesitate to ask!

package/dist/docs/local-development.md

@@ -0,0 +1,128 @@
+# Local development guide
+
+This guide provides instructions for setting up and using local development
+features, such as development tracing.
+
+## Development tracing
+
+Development traces (dev traces) are OpenTelemetry (OTel) traces that help you
+debug your code by instrumenting interesting events like model calls, tool
+scheduler, tool calls, etc.
+
+Dev traces are verbose and are specifically meant for understanding agent
+behaviour and debugging issues. They are disabled by default.
+
+To enable dev traces, set the `GEMINI_DEV_TRACING=true` environment variable
+when running Cell CLI.
+
+### Viewing dev traces
+
+You can view dev traces using either Jaeger or the Genkit Developer UI.
+
+#### Using Genkit
+
+Genkit provides a web-based UI for viewing traces and other telemetry data.
+
+1.  **Start the Genkit telemetry server:**
+
+    Run the following command to start the Genkit server:
+
+    ```bash
+    npm run telemetry -- --target=genkit
+    ```
+
+    The script will output the URL for the Genkit Developer UI, for example:
+
+    ```
+    Genkit Developer UI: http://localhost:4000
+    ```
+
+2.  **Run Cell CLI with dev tracing:**
+
+    In a separate terminal, run your Cell CLI command with the
+    `GEMINI_DEV_TRACING` environment variable:
+
+    ```bash
+    GEMINI_DEV_TRACING=true gemini
+    ```
+
+3.  **View the traces:**
+
+    Open the Genkit Developer UI URL in your browser and navigate to the
+    **Traces** tab to view the traces.
+
+#### Using Jaeger
+
+You can view dev traces in the Jaeger UI. To get started, follow these steps:
+
+1.  **Start the telemetry collector:**
+
+    Run the following command in your terminal to download and start Jaeger and
+    an OTEL collector:
+
+    ```bash
+    npm run telemetry -- --target=local
+    ```
+
+    This command also configures your workspace for local telemetry and provides
+    a link to the Jaeger UI (usually `http://localhost:16686`).
+
+2.  **Run Cell CLI with dev tracing:**
+
+    In a separate terminal, run your Cell CLI command with the
+    `GEMINI_DEV_TRACING` environment variable:
+
+    ```bash
+    GEMINI_DEV_TRACING=true gemini
+    ```
+
+3.  **View the traces:**
+
+    After running your command, open the Jaeger UI link in your browser to view
+    the traces.
+
+For more detailed information on telemetry, see the
+[telemetry documentation](./cli/telemetry.md).
+
+### Instrumenting code with dev traces
+
+You can add dev traces to your own code for more detailed instrumentation. This
+is useful for debugging and understanding the flow of execution.
+
+Use the `runInDevTraceSpan` function to wrap any section of code in a trace
+span.
+
+Here is a basic example:
+
+```typescript
+import { runInDevTraceSpan } from '@google/gemini-cli-core';
+
+await runInDevTraceSpan({ name: 'my-custom-span' }, async ({ metadata }) => {
+  // The `metadata` object allows you to record the input and output of the
+  // operation as well as other attributes.
+  metadata.input = { key: 'value' };
+  // Set custom attributes.
+  metadata.attributes['gen_ai.request.model'] = 'gemini-4.0-mega';
+
+  // Your code to be traced goes here
+  try {
+    const output = await somethingRisky();
+    metadata.output = output;
+    return output;
+  } catch (e) {
+    metadata.error = e;
+    throw e;
+  }
+});
+```
+
+In this example:
+
+- `name`: The name of the span, which will be displayed in the trace.
+- `metadata.input`: (Optional) An object containing the input data for the
+  traced operation.
+- `metadata.output`: (Optional) An object containing the output data from the
+  traced operation.
+- `metadata.attributes`: (Optional) A record of custom attributes to add to the
+  span.
+- `metadata.error`: (Optional) An error object to record if the operation fails.

package/dist/docs/mcp_integration.md

@@ -0,0 +1,160 @@
+# Integración de `cell-cli` con el Servidor MCP
+
+## 1. Objetivo
+
+Este documento describe los pasos necesarios para pre-configurar el `cell-cli`
+para que se conecte "out-of-the-box" al `cell-mcp-adapter`. El objetivo es que,
+una vez que un usuario instale el CLI a través de `npm`, pueda interactuar
+inmediatamente con los modelos de la plataforma CELL sin necesidad de
+configuración manual adicional.
+
+## 2. Contexto y Arquitectura de Configuración
+
+`cell-cli` no utiliza un archivo estático como `defaults.json` para su
+configuración inicial de servidores. La configuración es dinámica y se construye
+a partir de varias fuentes en tiempo de ejecución, principalmente:
+
+1.  **Archivos de Configuración (`settings.json`, `config.yaml`):** Los usuarios
+    pueden definir servidores y otras configuraciones en archivos a nivel de
+    sistema, usuario (`~/.cell-cli/`) o espacio de trabajo
+    (`<project>/.cell-cli/`).
+2.  **Extensiones:** El CLI puede cargar "extensiones" que programáticamente
+    proveen configuraciones de servidores MCP.
+
+Para lograr una configuración "out-of-the-box", el enfoque correcto es **añadir
+una extensión "built-in"** directamente en el código fuente del CLI. Esta
+extensión leerá la configuración existente (específicamente el `agent_api_url`
+de `config.yaml`) para construir dinámicamente la URL del servidor MCP.
+
+## 3. Pasos para la Configuración
+
+La integración se logra modificando el punto de entrada principal del CLI para
+inyectar la configuración del servidor MCP como una extensión por defecto.
+
+### 3.1. Localizar el Punto de Entrada del CLI
+
+El archivo principal que orquesta el arranque del CLI es
+`packages/cli/src/gemini.tsx`. Aquí es donde se cargan las configuraciones y
+extensiones.
+
+### 3.2. Añadir la Extensión "Built-in"
+
+/ Modifique el archivo `packages/cli/src/gemini.tsx` para añadir un objeto que
+represente la extensión del servidor MCP por defecto.
+
+1.  Abra el archivo `packages/cli/src/gemini.tsx`.
+
+2.  Localice la función `main()`. Dentro de esta función, encontrará la
+    siguiente línea:
+
+    ```typescript
+    const extensions = loadExtensions(workspaceRoot);
+    ```
+
+3.  **Inmediatamente después** de esa línea, inserte el siguiente código para
+    crear y añadir la extensión del `cell-mcp-adapter`:
+
+    ```typescript
+    // --- INICIO: Añadir extensión MCP por defecto ---
+    // Se utiliza el `agentApiUrl` de la configuración para construir la URL del MCP.
+    if (settings.merged.agentApiUrl) {
+      const cellMcpExtension: Extension = {
+        path: 'built-in',
+        contextFiles: [],
+        config: {
+          name: 'cell-mcp-server',
+          version: '1.0.0',
+          mcpServers: {
+            'cell-mcp': {
+              description: 'Cell Agents MCP Server',
+              url: `${settings.merged.agentApiUrl}/mcp/v1`,
+            },
+          },
+        },
+      };
+      extensions.push(cellMcpExtension);
+    }
+    // --- FIN: Añadir extensión MCP por defecto ---
+    ```
+
+**Detalles de la configuración:**
+
+- `path`: Se establece en `"built-in"` para indicar que no proviene del sistema
+  de archivos.
+- `name`: `cell-mcp-server`, un nombre para la extensión.
+- `mcpServers`: Un objeto donde cada clave es un identificador único para el
+  servidor.
+  - `cell-mcp`: Es el `id` del servidor.
+  - `description`: El nombre que se mostrará al usuario: "Cell Agents MCP
+    Server".
+  - `url`: La URL base del `cell-mcp-adapter`. **Se construye dinámicamente** a
+    partir del valor `agent_api_url` definido en `~/.cell-cli/config.yaml`.
+- **Autenticación**: No se especifica un `authProviderType`. Al omitir esta
+  propiedad, el cliente MCP (`mcp-client.ts`) utilizará automáticamente el token
+  de sesión de Keycloak que encuentre en `~/.cell-cli/session.json`, añadiéndolo
+  a las cabeceras como `Authorization: Bearer <token>`. Esto asegura que se
+  reutilice la sesión de autenticación existente.
+
+### 3.3. Verificar la Integración
+
+Después de añadir el código y reconstruir el CLI, la configuración del
+`cell-mcp-adapter` será cargada automáticamente, utilizando la URL del
+`config.yaml` y la sesión de autenticación de Keycloak.
+
+## 4. Publicación y Experiencia del Usuario
+
+1.  **Guardar Cambios**: Guarde los cambios en `packages/cli/src/gemini.tsx`.
+2.  **Recompilar y Publicar**: Siga el proceso de build del proyecto y publique
+    la nueva versión de `cell-cli` en `npm`.
+
+Una vez completado, la experiencia del usuario será la siguiente:
+
+- Un desarrollador instala la herramienta globalmente: `npm install -g cell-cli`
+- El CLI creará un `config.yaml` por defecto en `~/.cell-cli/` si no existe.
+- Tras autenticarse una vez, el servidor `cell-mcp` estará disponible y
+  utilizará la sesión existente sin requerir configuración adicional.
+
+Esta configuración asegura que `cell-cli` esté listo para usar con la
+infraestructura de CELL desde el primer momento, de una manera robusta y
+correcta.
+
+## 5. Cómo Probar la Integración
+
+Una vez que haya realizado los cambios en el código y reconstruido el CLI, puede
+verificar que la integración funciona correctamente de la siguiente manera:
+
+1.  **Asegúrese de que su configuración sea correcta:**
+    - Verifique que el archivo `~/.cell-cli/config.yaml` existe y contiene una
+      entrada válida para `agent_api_url`. Por ejemplo:
+      ```yaml
+      agent:
+        agent_api_url: https://api.machina.ai
+      ```
+    - Asegúrese de haber iniciado sesión en el CLI para que exista un token de
+      sesión válido en `~/.cell-cli/session.json`.
+
+2.  **Inicie el CLI en modo interactivo:**
+
+    ```bash
+    cell-cli
+    ```
+
+3.  **Use el comando `/mcp`:** Dentro del CLI interactivo, escriba el siguiente
+    comando y presione Enter:
+
+    ```
+    /mcp
+    ```
+
+4.  **Verifique el resultado:** El resultado debería listar los servidores MCP
+    disponibles. Debería ver una entrada para el servidor que acaba de
+    configurar, similar a esta:
+
+    ```
+    MCP Servers:
+    - Cell Agents MCP Server (cell-mcp)
+    ```
+
+    Si el servidor aparece en la lista, significa que la extensión "built-in" se
+    cargó correctamente, leyó la configuración de su `config.yaml` y se registró
+    exitosamente en el CLI.