@didim365/agent-cli-core 0.1.0 → 0.1.2

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

@@ -1,134 +0,0 @@
-# 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 Gemini 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

@@ -1,128 +0,0 @@
-# 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
-behavior and debugging issues. They are disabled by default.
-
-To enable dev traces, set the `GEMINI_DEV_TRACING=true` environment variable
-when running Gemini 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 Gemini CLI with dev tracing:**
-
-    In a separate terminal, run your Gemini 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 Gemini CLI with dev tracing:**
-
-    In a separate terminal, run your Gemini 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 '@didim365/agent-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/mermaid/context.mmd

@@ -1,103 +0,0 @@
-graph LR
-    %% --- Style Definitions ---
-    classDef new fill:#98fb98,color:#000
-    classDef changed fill:#add8e6,color:#000
-    classDef unchanged fill:#f0f0f0,color:#000
-
-    %% --- Subgraphs ---
-    subgraph "Context Providers"
-        direction TB
-        A["gemini.tsx"]
-        B["AppContainer.tsx"]
-    end
-
-    subgraph "Contexts"
-        direction TB
-        CtxSession["SessionContext"]
-        CtxVim["VimModeContext"]
-        CtxSettings["SettingsContext"]
-        CtxApp["AppContext"]
-        CtxConfig["ConfigContext"]
-        CtxUIState["UIStateContext"]
-        CtxUIActions["UIActionsContext"]
-    end
-
-    subgraph "Component Consumers"
-        direction TB
-        ConsumerApp["App"]
-        ConsumerAppContainer["AppContainer"]
-        ConsumerAppHeader["AppHeader"]
-        ConsumerDialogManager["DialogManager"]
-        ConsumerHistoryItem["HistoryItemDisplay"]
-        ConsumerComposer["Composer"]
-        ConsumerMainContent["MainContent"]
-        ConsumerNotifications["Notifications"]
-    end
-
-    %% --- Provider -> Context Connections ---
-    A -.-> CtxSession
-    A -.-> CtxVim
-    A -.-> CtxSettings
-
-    B -.-> CtxApp
-    B -.-> CtxConfig
-    B -.-> CtxUIState
-    B -.-> CtxUIActions
-    B -.-> CtxSettings
-
-    %% --- Context -> Consumer Connections ---
-    CtxSession -.-> ConsumerAppContainer
-    CtxSession -.-> ConsumerApp
-
-    CtxVim -.-> ConsumerAppContainer
-    CtxVim -.-> ConsumerComposer
-    CtxVim -.-> ConsumerApp
-
-    CtxSettings -.-> ConsumerAppContainer
-    CtxSettings -.-> ConsumerAppHeader
-    CtxSettings -.-> ConsumerDialogManager
-    CtxSettings -.-> ConsumerApp
-
-    CtxApp -.-> ConsumerAppHeader
-    CtxApp -.-> ConsumerNotifications
-
-    CtxConfig -.-> ConsumerAppHeader
-    CtxConfig -.-> ConsumerHistoryItem
-    CtxConfig -.-> ConsumerComposer
-    CtxConfig -.-> ConsumerDialogManager
-
-
-
-    CtxUIState -.-> ConsumerApp
-    CtxUIState -.-> ConsumerMainContent
-    CtxUIState -.-> ConsumerComposer
-    CtxUIState -.-> ConsumerDialogManager
-
-    CtxUIActions -.-> ConsumerComposer
-    CtxUIActions -.-> ConsumerDialogManager
-
-    %% --- Apply Styles ---
-    %% New Elements (Green)
-    class B,CtxApp,CtxConfig,CtxUIState,CtxUIActions,ConsumerAppHeader,ConsumerDialogManager,ConsumerComposer,ConsumerMainContent,ConsumerNotifications new
-
-    %% Heavily Changed Elements (Blue)
-    class A,ConsumerApp,ConsumerAppContainer,ConsumerHistoryItem changed
-
-    %% Mostly Unchanged Elements (Gray)
-    class CtxSession,CtxVim,CtxSettings unchanged
-
-    %% --- Link Styles ---
-    %% CtxSession (Red)
-    linkStyle 0,8,9 stroke:#e57373,stroke-width:2px
-    %% CtxVim (Orange)
-    linkStyle 1,10,11,12 stroke:#ffb74d,stroke-width:2px
-    %% CtxSettings (Yellow)
-    linkStyle 2,7,13,14,15,16 stroke:#fff176,stroke-width:2px
-    %% CtxApp (Green)
-    linkStyle 3,17,18 stroke:#81c784,stroke-width:2px
-    %% CtxConfig (Blue)
-    linkStyle 4,19,20,21,22 stroke:#64b5f6,stroke-width:2px
-    %% CtxUIState (Indigo)
-    linkStyle 5,23,24,25,26 stroke:#7986cb,stroke-width:2px
-    %% CtxUIActions (Violet)
-    linkStyle 6,27,28 stroke:#ba68c8,stroke-width:2px

package/dist/docs/mermaid/render-path.mmd

@@ -1,64 +0,0 @@
-graph TD
-    %% --- Style Definitions ---
-    classDef new fill:#98fb98,color:#000
-    classDef changed fill:#add8e6,color:#000
-    classDef unchanged fill:#f0f0f0,color:#000
-    classDef dispatcher fill:#f9e79f,color:#000,stroke:#333,stroke-width:1px
-    classDef container fill:#f5f5f5,color:#000,stroke:#ccc
-
-    %% --- Component Tree ---
-    subgraph "Entry Point"
-      A["gemini.tsx"]
-    end
-
-    subgraph "State & Logic Wrapper"
-      B["AppContainer.tsx"]
-    end
-
-    subgraph "Primary Layout"
-      C["App.tsx"]
-    end
-
-    A -.-> B
-    B -.-> C
-
-    subgraph "UI Containers"
-        direction LR
-        C -.-> D["MainContent"]
-        C -.-> G["Composer"]
-        C -.-> F["DialogManager"]
-        C -.-> E["Notifications"]
-    end
-
-    subgraph "MainContent"
-        direction TB
-        D -.-> H["AppHeader"]
-        D -.-> I["HistoryItemDisplay"]:::dispatcher
-        D -.-> L["ShowMoreLines"]
-    end
-
-    subgraph "Composer"
-        direction TB
-        G -.-> K_Prompt["InputPrompt"]
-        G -.-> K_Footer["Footer"]
-    end
-
-    subgraph "DialogManager"
-        F -.-> J["Various Dialogs<br>(Auth, Theme, Settings, etc.)"]
-    end
-
-    %% --- Apply Styles ---
-    class B,D,E,F,G,H,J,K_Prompt,L new
-    class A,C,I changed
-    class K_Footer unchanged
-
-    %% --- Link Styles ---
-    %% MainContent Branch (Blue)
-    linkStyle 2,6,7,8 stroke:#64b5f6,stroke-width:2px
-    %% Composer Branch (Green)
-    linkStyle 3,9,10 stroke:#81c784,stroke-width:2px
-    %% DialogManager Branch (Orange)
-    linkStyle 4,11 stroke:#ffb74d,stroke-width:2px
-    %% Notifications Branch (Violet)
-    linkStyle 5 stroke:#ba68c8,stroke-width:2px
-

package/dist/docs/migration.md

@@ -1,78 +0,0 @@
-# Migration Guide: Gemini-Only to Multi-Provider
-
-This guide summarizes practical migration steps for moving from Gemini-only
-flows to provider-independent flows.
-
-## 1. Enable Multi-Provider Mode
-
-```bash
-export ENABLE_MULTI_PROVIDER=true
-```
-
-Without this flag, the runtime follows the legacy Gemini-focused path.
-
-## 2. Set Provider and Credentials
-
-Choose one provider path:
-
-```bash
-# Claude
-export LLM_PROVIDER=claude
-export ANTHROPIC_API_KEY="your-key"
-
-# OpenAI
-export LLM_PROVIDER=openai
-export OPENAI_API_KEY="your-key"
-```
-
-## 3. Update Runtime Call Path
-
-For non-Gemini providers, use provider-independent methods:
-
-- `llmGenerateContent(...)`
-- `llmGenerateContentStream(...)`
-- `llmCountTokens(...)`
-
-Do not rely on legacy Gemini SDK methods for non-Gemini providers.
-
-## 4. Model Handling
-
-If your configured model is Gemini-specific (`auto`, `pro`, `flash`,
-`gemini-*`), non-Gemini providers resolve to provider defaults.
-
-Use `LLM_MODEL` to enforce a concrete provider model:
-
-```bash
-export LLM_MODEL=claude-sonnet-4-20250514
-```
-
-## 5. Validate
-
-- Confirm startup succeeds with `ENABLE_MULTI_PROVIDER=true`.
-- Confirm prompt calls reach the selected provider.
-- Confirm no legacy API error appears:
-  `Provider "<name>" does not support legacy Gemini API. Use llm* methods.`
-
-## 6. vLLM Migration Path
-
-For vLLM or other OpenAI-compatible local endpoints:
-
-```bash
-export ENABLE_MULTI_PROVIDER=true
-export LLM_PROVIDER=openai-compatible
-export LLM_BASE_URL="http://localhost:8000/v1"
-export LLM_MODEL="Qwen/Qwen2.5-7B-Instruct"
-```
-
-Then run:
-
-```bash
-gemini -m Qwen/Qwen2.5-7B-Instruct
-```
-
-If your gateway requires custom auth header semantics:
-
-```bash
-export LLM_API_KEY="your-key"
-export LLM_API_KEY_HEADER="X-API-Key"
-```

package/dist/docs/npm.md

@@ -1,62 +0,0 @@
-# Package overview
-
-This monorepo contains two main packages: `@didim365/agent-cli` and
-`@didim365/agent-cli-core`.
-
-## `@didim365/agent-cli`
-
-This is the main package for the Gemini CLI. It is responsible for the user
-interface, command parsing, and all other user-facing functionality.
-
-When this package is published, it is bundled into a single executable file.
-This bundle includes all of the package's dependencies, including
-`@didim365/agent-cli-core`. This means that whether a user installs the package
-with `npm install -g @didim365/agent-cli` or runs it directly with
-`npx @didim365/agent-cli`, they are using this single, self-contained executable.
-
-## `@didim365/agent-cli-core`
-
-This package contains the core logic for interacting with the Gemini API. It is
-responsible for making API requests, handling authentication, and managing the
-local cache.
-
-This package is not bundled. When it is published, it is published as a standard
-Node.js package with its own dependencies. This allows it to be used as a
-standalone package in other projects, if needed. All transpiled js code in the
-`dist` folder is included in the package.
-
-## NPM workspaces
-
-This project uses
-[NPM Workspaces](https://docs.npmjs.com/cli/v10/using-npm/workspaces) to manage
-the packages within this monorepo. This simplifies development by allowing us to
-manage dependencies and run scripts across multiple packages from the root of
-the project.
-
-### How it works
-
-The root `package.json` file defines the workspaces for this project:
-
-```json
-{
-  "workspaces": ["packages/*"]
-}
-```
-
-This tells NPM that any folder inside the `packages` directory is a separate
-package that should be managed as part of the workspace.
-
-### Benefits of workspaces
-
-- **Simplified dependency management**: Running `npm install` from the root of
-  the project will install all dependencies for all packages in the workspace
-  and link them together. This means you don't need to run `npm install` in each
-  package's directory.
-- **Automatic linking**: Packages within the workspace can depend on each other.
-  When you run `npm install`, NPM will automatically create symlinks between the
-  packages. This means that when you make changes to one package, the changes
-  are immediately available to other packages that depend on it.
-- **Simplified script execution**: You can run scripts in any package from the
-  root of the project using the `--workspace` flag. For example, to run the
-  `build` script in the `cli` package, you can run
-  `npm run build --workspace @didim365/agent-cli`.