@didim365/agent-cli-core 0.1.0 → 0.1.2

package/dist/docs/extensions/releasing.md

@@ -1,183 +0,0 @@
-# Extension releasing
-
-There are two primary ways of releasing extensions to users:
-
-- [Git repository](#releasing-through-a-git-repository)
-- [Github Releases](#releasing-through-github-releases)
-
-Git repository releases tend to be the simplest and most flexible approach,
-while GitHub releases can be more efficient on initial install as they are
-shipped as single archives instead of requiring a git clone which downloads each
-file individually. Github releases may also contain platform specific archives
-if you need to ship platform specific binary files.
-
-## Releasing through a git repository
-
-This is the most flexible and simple option. All you need to do is create a
-publicly accessible git repo (such as a public github repository) and then users
-can install your extension using `gemini extensions install <your-repo-uri>`.
-They can optionally depend on a specific ref (branch/tag/commit) using the
-`--ref=<some-ref>` argument, this defaults to the default branch.
-
-Whenever commits are pushed to the ref that a user depends on, they will be
-prompted to update the extension. Note that this also allows for easy rollbacks,
-the HEAD commit is always treated as the latest version regardless of the actual
-version in the `gemini-extension.json` file.
-
-### Managing release channels using a git repository
-
-Users can depend on any ref from your git repo, such as a branch or tag, which
-allows you to manage multiple release channels.
-
-For instance, you can maintain a `stable` branch, which users can install this
-way `gemini extensions install <your-repo-uri> --ref=stable`. Or, you could make
-this the default by treating your default branch as your stable release branch,
-and doing development in a different branch (for instance called `dev`). You can
-maintain as many branches or tags as you like, providing maximum flexibility for
-you and your users.
-
-Note that these `ref` arguments can be tags, branches, or even specific commits,
-which allows users to depend on a specific version of your extension. It is up
-to you how you want to manage your tags and branches.
-
-### Example releasing flow using a git repo
-
-While there are many options for how you want to manage releases using a git
-flow, we recommend treating your default branch as your "stable" release branch.
-This means that the default behavior for
-`gemini extensions install <your-repo-uri>` is to be on the stable release
-branch.
-
-Lets say you want to maintain three standard release channels, `stable`,
-`preview`, and `dev`. You would do all your standard development in the `dev`
-branch. When you are ready to do a preview release, you merge that branch into
-your `preview` branch. When you are ready to promote your preview branch to
-stable, you merge `preview` into your stable branch (which might be your default
-branch or a different branch).
-
-You can also cherry pick changes from one branch into another using
-`git cherry-pick`, but do note that this will result in your branches having a
-slightly divergent history from each other, unless you force push changes to
-your branches on each release to restore the history to a clean slate (which may
-not be possible for the default branch depending on your repository settings).
-If you plan on doing cherry picks, you may want to avoid having your default
-branch be the stable branch to avoid force-pushing to the default branch which
-should generally be avoided.
-
-## Releasing through GitHub releases
-
-Gemini CLI extensions can be distributed through
-[GitHub Releases](https://docs.github.com/en/repositories/releasing-projects-on-github/about-releases).
-This provides a faster and more reliable initial installation experience for
-users, as it avoids the need to clone the repository.
-
-Each release includes at least one archive file, which contains the full
-contents of the repo at the tag that it was linked to. Releases may also include
-[pre-built archives](#custom-pre-built-archives) if your extension requires some
-build step or has platform specific binaries attached to it.
-
-When checking for updates, gemini will just look for the "latest" release on
-github (you must mark it as such when creating the release), unless the user
-installed a specific release by passing `--ref=<some-release-tag>`.
-
-You may also install extensions with the `--pre-release` flag in order to get
-the latest release regardless of whether it has been marked as "latest". This
-allows you to test that your release works before actually pushing it to all
-users.
-
-### Custom pre-built archives
-
-Custom archives must be attached directly to the github release as assets and
-must be fully self-contained. This means they should include the entire
-extension, see [archive structure](#archive-structure).
-
-If your extension is platform-independent, you can provide a single generic
-asset. In this case, there should be only one asset attached to the release.
-
-Custom archives may also be used if you want to develop your extension within a
-larger repository, you can build an archive which has a different layout from
-the repo itself (for instance it might just be an archive of a subdirectory
-containing the extension).
-
-#### Platform specific archives
-
-To ensure Gemini CLI can automatically find the correct release asset for each
-platform, you must follow this naming convention. The CLI will search for assets
-in the following order:
-
-1.  **Platform and architecture-Specific:**
-    `{platform}.{arch}.{name}.{extension}`
-2.  **Platform-specific:** `{platform}.{name}.{extension}`
-3.  **Generic:** If only one asset is provided, it will be used as a generic
-    fallback.
-
-- `{name}`: The name of your extension.
-- `{platform}`: The operating system. Supported values are:
-  - `darwin` (macOS)
-  - `linux`
-  - `win32` (Windows)
-- `{arch}`: The architecture. Supported values are:
-  - `x64`
-  - `arm64`
-- `{extension}`: The file extension of the archive (e.g., `.tar.gz` or `.zip`).
-
-**Examples:**
-
-- `darwin.arm64.my-tool.tar.gz` (specific to Apple Silicon Macs)
-- `darwin.my-tool.tar.gz` (for all Macs)
-- `linux.x64.my-tool.tar.gz`
-- `win32.my-tool.zip`
-
-#### Archive structure
-
-Archives must be fully contained extensions and have all the standard
-requirements - specifically the `gemini-extension.json` file must be at the root
-of the archive.
-
-The rest of the layout should look exactly the same as a typical extension, see
-[extensions.md](./index.md).
-
-#### Example GitHub Actions workflow
-
-Here is an example of a GitHub Actions workflow that builds and releases a
-Gemini CLI extension for multiple platforms:
-
-```yaml
-name: Release Extension
-
-on:
-  push:
-    tags:
-      - 'v*'
-
-jobs:
-  release:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v3
-
-      - name: Set up Node.js
-        uses: actions/setup-node@v3
-        with:
-          node-version: '20'
-
-      - name: Install dependencies
-        run: npm ci
-
-      - name: Build extension
-        run: npm run build
-
-      - name: Create release assets
-        run: |
-          npm run package -- --platform=darwin --arch=arm64
-          npm run package -- --platform=linux --arch=x64
-          npm run package -- --platform=win32 --arch=x64
-
-      - name: Create GitHub Release
-        uses: softprops/action-gh-release@v1
-        with:
-          files: |
-            release/darwin.arm64.my-tool.tar.gz
-            release/linux.arm64.my-tool.tar.gz
-            release/win32.arm64.my-tool.zip
-```

package/dist/docs/extensions/writing-extensions.md

@@ -1,283 +0,0 @@
-# Getting started with Gemini CLI extensions
-
-This guide will walk you through creating your first Gemini CLI extension.
-You'll learn how to set up a new extension, add a custom tool via an MCP server,
-create a custom command, and provide context to the model with a `GEMINI.md`
-file.
-
-## Prerequisites
-
-Before you start, make sure you have the Gemini CLI installed and a basic
-understanding of Node.js.
-
-## When to use what
-
-Extensions offer a variety of ways to customize Gemini CLI.
-
-| Feature                                                        | What it is                                                                                                         | When to use it                                                                                                                                                                                                                                                                                 | Invoked by            |
-| :------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------- |
-| **[MCP server](reference.md#mcp-servers)**                     | A standard way to expose new tools and data sources to the model.                                                  | Use this when you want the model to be able to _do_ new things, like fetching data from an internal API, querying a database, or controlling a local application. We also support MCP resources (which can replace custom commands) and system instructions (which can replace custom context) | Model                 |
-| **[Custom commands](../cli/custom-commands.md)**               | A shortcut (like `/my-cmd`) that executes a pre-defined prompt or shell command.                                   | Use this for repetitive tasks or to save long, complex prompts that you use frequently. Great for automation.                                                                                                                                                                                  | User                  |
-| **[Context file (`GEMINI.md`)](reference.md#contextfilename)** | A markdown file containing instructions that are loaded into the model's context at the start of every session.    | Use this to define the "personality" of your extension, set coding standards, or provide essential knowledge that the model should always have.                                                                                                                                                | CLI provides to model |
-| **[Agent skills](../cli/skills.md)**                           | A specialized set of instructions and workflows that the model activates only when needed.                         | Use this for complex, occasional tasks (like "create a PR" or "audit security") to avoid cluttering the main context window when the skill isn't being used.                                                                                                                                   | Model                 |
-| **[Hooks](../hooks/index.md)**                                 | A way to intercept and customize the CLI's behavior at specific lifecycle events (e.g., before/after a tool call). | Use this when you want to automate actions based on what the model is doing, like validating tool arguments, logging activity, or modifying the model's input/output.                                                                                                                          | CLI                   |
-
-## Step 1: Create a new extension
-
-The easiest way to start is by using one of the built-in templates. We'll use
-the `mcp-server` example as our foundation.
-
-Run the following command to create a new directory called `my-first-extension`
-with the template files:
-
-```bash
-gemini extensions new my-first-extension mcp-server
-```
-
-This will create a new directory with the following structure:
-
-```
-my-first-extension/
-├── example.js
-├── gemini-extension.json
-└── package.json
-```
-
-## Step 2: Understand the extension files
-
-Let's look at the key files in your new extension.
-
-### `gemini-extension.json`
-
-This is the manifest file for your extension. It tells Gemini CLI how to load
-and use your extension.
-
-```json
-{
-  "name": "mcp-server-example",
-  "version": "1.0.0",
-  "mcpServers": {
-    "nodeServer": {
-      "command": "node",
-      "args": ["${extensionPath}${/}example.js"],
-      "cwd": "${extensionPath}"
-    }
-  }
-}
-```
-
-- `name`: The unique name for your extension.
-- `version`: The version of your extension.
-- `mcpServers`: This section defines one or more Model Context Protocol (MCP)
-  servers. MCP servers are how you can add new tools for the model to use.
-  - `command`, `args`, `cwd`: These fields specify how to start your server.
-    Notice the use of the `${extensionPath}` variable, which Gemini CLI replaces
-    with the absolute path to your extension's installation directory. This
-    allows your extension to work regardless of where it's installed.
-
-### `example.js`
-
-This file contains the source code for your MCP server. It's a simple Node.js
-server that uses the `@modelcontextprotocol/sdk`.
-
-```javascript
-/**
- * @license
- * Copyright 2025 Google LLC
- * SPDX-License-Identifier: Apache-2.0
- */
-
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { z } from 'zod';
-
-const server = new McpServer({
-  name: 'prompt-server',
-  version: '1.0.0',
-});
-
-// Registers a new tool named 'fetch_posts'
-server.registerTool(
-  'fetch_posts',
-  {
-    description: 'Fetches a list of posts from a public API.',
-    inputSchema: z.object({}).shape,
-  },
-  async () => {
-    const apiResponse = await fetch(
-      'https://jsonplaceholder.typicode.com/posts',
-    );
-    const posts = await apiResponse.json();
-    const response = { posts: posts.slice(0, 5) };
-    return {
-      content: [
-        {
-          type: 'text',
-          text: JSON.stringify(response),
-        },
-      ],
-    };
-  },
-);
-
-// ... (prompt registration omitted for brevity)
-
-const transport = new StdioServerTransport();
-await server.connect(transport);
-```
-
-This server defines a single tool called `fetch_posts` that fetches data from a
-public API.
-
-### `package.json`
-
-This is the standard configuration file for a Node.js project. It defines
-dependencies and scripts.
-
-## Step 3: Link your extension
-
-Before you can use the extension, you need to link it to your Gemini CLI
-installation for local development.
-
-1.  **Install dependencies:**
-
-    ```bash
-    cd my-first-extension
-    npm install
-    ```
-
-2.  **Link the extension:**
-
-    The `link` command creates a symbolic link from the Gemini CLI extensions
-    directory to your development directory. This means any changes you make
-    will be reflected immediately without needing to reinstall.
-
-    ```bash
-    gemini extensions link .
-    ```
-
-Now, restart your Gemini CLI session. The new `fetch_posts` tool will be
-available. You can test it by asking: "fetch posts".
-
-## Step 4: Add a custom command
-
-Custom commands provide a way to create shortcuts for complex prompts. Let's add
-a command that searches for a pattern in your code.
-
-1.  Create a `commands` directory and a subdirectory for your command group:
-
-    ```bash
-    mkdir -p commands/fs
-    ```
-
-2.  Create a file named `commands/fs/grep-code.toml`:
-
-    ```toml
-    prompt = """
-    Please summarize the findings for the pattern `{{args}}`.
-
-    Search Results:
-    !{grep -r {{args}} .}
-    """
-    ```
-
-    This command, `/fs:grep-code`, will take an argument, run the `grep` shell
-    command with it, and pipe the results into a prompt for summarization.
-
-After saving the file, restart the Gemini CLI. You can now run
-`/fs:grep-code "some pattern"` to use your new command.
-
-## Step 5: Add a custom `GEMINI.md`
-
-You can provide persistent context to the model by adding a `GEMINI.md` file to
-your extension. This is useful for giving the model instructions on how to
-behave or information about your extension's tools. Note that you may not always
-need this for extensions built to expose commands and prompts.
-
-1.  Create a file named `GEMINI.md` in the root of your extension directory:
-
-    ```markdown
-    # My First Extension Instructions
-
-    You are an expert developer assistant. When the user asks you to fetch
-    posts, use the `fetch_posts` tool. Be concise in your responses.
-    ```
-
-2.  Update your `gemini-extension.json` to tell the CLI to load this file:
-
-    ```json
-    {
-      "name": "my-first-extension",
-      "version": "1.0.0",
-      "contextFileName": "GEMINI.md",
-      "mcpServers": {
-        "nodeServer": {
-          "command": "node",
-          "args": ["${extensionPath}${/}example.js"],
-          "cwd": "${extensionPath}"
-        }
-      }
-    }
-    ```
-
-Restart the CLI again. The model will now have the context from your `GEMINI.md`
-file in every session where the extension is active.
-
-## (Optional) Step 6: Add an Agent Skill
-
-_Note: This is an experimental feature enabled via `experimental.skills`._
-
-[Agent Skills](../cli/skills.md) let you bundle specialized expertise and
-procedural workflows. Unlike `GEMINI.md`, which provides persistent context,
-skills are activated only when needed, saving context tokens.
-
-1.  Create a `skills` directory and a subdirectory for your skill:
-
-    ```bash
-    mkdir -p skills/security-audit
-    ```
-
-2.  Create a `skills/security-audit/SKILL.md` file:
-
-    ```markdown
-    ---
-    name: security-audit
-    description:
-      Expertise in auditing code for security vulnerabilities. Use when the user
-      asks to "check for security issues" or "audit" their changes.
-    ---
-
-    # Security Auditor
-
-    You are an expert security researcher. When auditing code:
-
-    1. Look for common vulnerabilities (OWASP Top 10).
-    2. Check for hardcoded secrets or API keys.
-    3. Suggest remediation steps for any findings.
-    ```
-
-Skills bundled with your extension are automatically discovered and can be
-activated by the model during a session when it identifies a relevant task.
-
-## Step 7: Release your extension
-
-Once you're happy with your extension, you can share it with others. The two
-primary ways of releasing extensions are via a Git repository or through GitHub
-Releases. Using a public Git repository is the simplest method.
-
-For detailed instructions on both methods, please refer to the
-[Extension Releasing Guide](./releasing.md).
-
-## Conclusion
-
-You've successfully created a Gemini CLI extension! You learned how to:
-
-- Bootstrap a new extension from a template.
-- Add custom tools with an MCP server.
-- Create convenient custom commands.
-- Provide persistent context to the model.
-- Bundle specialized Agent Skills.
-- Link your extension for local development.
-
-From here, you can explore more advanced features and build powerful new
-capabilities into the Gemini CLI.

package/dist/docs/faq.md

@@ -1,154 +0,0 @@
-# Frequently asked questions (FAQ)
-
-This page provides answers to common questions and solutions to frequent
-problems encountered while using Gemini CLI.
-
-## General issues
-
-### Why am I getting an `API error: 429 - Resource exhausted`?
-
-This error indicates that you have exceeded your API request limit. The Gemini
-API has rate limits to prevent abuse and ensure fair usage.
-
-To resolve this, you can:
-
-- **Check your usage:** Review your API usage in the Google AI Studio or your
-  Google Cloud project dashboard.
-- **Optimize your prompts:** If you are making many requests in a short period,
-  try to batch your prompts or introduce delays between requests.
-- **Request a quota increase:** If you consistently need a higher limit, you can
-  request a quota increase from Google.
-
-### Why am I getting an `ERR_REQUIRE_ESM` error when running `npm run start`?
-
-This error typically occurs in Node.js projects when there is a mismatch between
-CommonJS and ES Modules.
-
-This is often due to a misconfiguration in your `package.json` or
-`tsconfig.json`. Ensure that:
-
-1.  Your `package.json` has `"type": "module"`.
-2.  Your `tsconfig.json` has `"module": "NodeNext"` or a compatible setting in
-    the `compilerOptions`.
-
-If the problem persists, try deleting your `node_modules` directory and
-`package-lock.json` file, and then run `npm install` again.
-
-### Why don't I see cached token counts in my stats output?
-
-Cached token information is only displayed when cached tokens are being used.
-This feature is available for API key users (Gemini API key or Google Cloud
-Vertex AI) but not for OAuth users (such as Google Personal/Enterprise accounts
-like Google Gmail or Google Workspace, respectively). This is because the Gemini
-Code Assist API does not support cached content creation. You can still view
-your total token usage using the `/stats` command in Gemini CLI.
-
-## Installation and updates
-
-### How do I update Gemini CLI to the latest version?
-
-If you installed it globally via `npm`, update it using the command
-`npm install -g @didim365/agent-cli@latest`. If you compiled it from source, pull
-the latest changes from the repository, and then rebuild using the command
-`npm run build`.
-
-## Platform-specific issues
-
-### Why does the CLI crash on Windows when I run a command like `chmod +x`?
-
-Commands like `chmod` are specific to Unix-like operating systems (Linux,
-macOS). They are not available on Windows by default.
-
-To resolve this, you can:
-
-- **Use Windows-equivalent commands:** Instead of `chmod`, you can use `icacls`
-  to modify file permissions on Windows.
-- **Use a compatibility layer:** Tools like Git Bash or Windows Subsystem for
-  Linux (WSL) provide a Unix-like environment on Windows where these commands
-  will work.
-
-## Configuration
-
-### How do I configure my `GOOGLE_CLOUD_PROJECT`?
-
-You can configure your Google Cloud Project ID using an environment variable.
-
-Set the `GOOGLE_CLOUD_PROJECT` environment variable in your shell:
-
-```bash
-export GOOGLE_CLOUD_PROJECT="your-project-id"
-```
-
-To make this setting permanent, add this line to your shell's startup file
-(e.g., `~/.bashrc`, `~/.zshrc`).
-
-### What is the best way to store my API keys securely?
-
-Exposing API keys in scripts or checking them into source control is a security
-risk.
-
-To store your API keys securely, you can:
-
-- **Use a `.env` file:** Create a `.env` file in your project's `.gemini`
-  directory (`.gemini/.env`) and store your keys there. Gemini CLI will
-  automatically load these variables.
-- **Use your system's keyring:** For the most secure storage, use your operating
-  system's secret management tool (like macOS Keychain, Windows Credential
-  Manager, or a secret manager on Linux). You can then have your scripts or
-  environment load the key from the secure storage at runtime.
-
-### Where are the Gemini CLI configuration and settings files stored?
-
-The Gemini CLI configuration is stored in two `settings.json` files:
-
-1.  In your home directory: `~/.gemini/settings.json`.
-2.  In your project's root directory: `./.gemini/settings.json`.
-
-Refer to [Gemini CLI Configuration](./get-started/configuration.md) for more
-details.
-
-## Google AI Pro/Ultra and subscription FAQs
-
-### Where can I learn more about my Google AI Pro or Google AI Ultra subscription?
-
-To learn more about your Google AI Pro or Google AI Ultra subscription, visit
-**Manage subscription** in your [subscription settings](https://one.google.com).
-
-### How do I know if I have higher limits for Google AI Pro or Ultra?
-
-If you're subscribed to Google AI Pro or Ultra, you automatically have higher
-limits to Gemini Code Assist and Gemini CLI. These are shared across Gemini CLI
-and agent mode in the IDE. You can confirm you have higher limits by checking if
-you are still subscribed to Google AI Pro or Ultra in your
-[subscription settings](https://one.google.com).
-
-### What is the privacy policy for using Gemini Code Assist or Gemini CLI if I've subscribed to Google AI Pro or Ultra?
-
-To learn more about your privacy policy and terms of service governed by your
-subscription, visit
-[Gemini Code Assist: Terms of Service and Privacy Policies](https://developers.google.com/gemini-code-assist/resources/privacy-notices).
-
-### I've upgraded to Google AI Pro or Ultra but it still says I am hitting quota limits. Is this a bug?
-
-The higher limits in your Google AI Pro or Ultra subscription are for Gemini 2.5
-across both Gemini 2.5 Pro and Flash. They are shared quota across Gemini CLI
-and agent mode in Gemini Code Assist IDE extensions. You can learn more about
-quota limits for Gemini CLI, Gemini Code Assist and agent mode in Gemini Code
-Assist at
-[Quotas and limits](https://developers.google.com/gemini-code-assist/resources/quotas).
-
-### If I upgrade to higher limits for Gemini CLI and Gemini Code Assist by purchasing a Google AI Pro or Ultra subscription, will Gemini start using my data to improve its machine learning models?
-
-Google does not use your data to improve Google's machine learning models if you
-purchase a paid plan. Note: If you decide to remain on the free version of
-Gemini Code Assist, Gemini Code Assist for individuals, you can also opt out of
-using your data to improve Google's machine learning models. See the
-[Gemini Code Assist for individuals privacy notice](https://developers.google.com/gemini-code-assist/resources/privacy-notice-gemini-code-assist-individuals)
-for more information.
-
-## Not seeing your question?
-
-Search the
-[Gemini CLI Q&A discussions on GitHub](https://github.com/google-gemini/gemini-cli/discussions/categories/q-a)
-or
-[start a new discussion on GitHub](https://github.com/google-gemini/gemini-cli/discussions/new?category=q-a)