@dgxo/mashadevcli 1.1.0

package/bundle/docs/examples/proxy-script.md

@@ -0,0 +1,83 @@
+# Example proxy script
+
+The following is an example of a proxy script that can be used with the
+`GEMINI_SANDBOX_PROXY_COMMAND` environment variable. This script only allows
+`HTTPS` connections to `example.com:443` and declines all other requests.
+
+```javascript
+#!/usr/bin/env node
+
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+// Example proxy server that listens on :::8877 and only allows HTTPS connections to example.com.
+// Set `GEMINI_SANDBOX_PROXY_COMMAND=scripts/example-proxy.js` to run proxy alongside sandbox
+// Test via `curl https://example.com` inside sandbox (in shell mode or via shell tool)
+
+import http from 'node:http';
+import net from 'node:net';
+import { URL } from 'node:url';
+import console from 'node:console';
+
+const PROXY_PORT = 8877;
+const ALLOWED_DOMAINS = ['example.com', 'googleapis.com'];
+const ALLOWED_PORT = '443';
+
+const server = http.createServer((req, res) => {
+  // Deny all requests other than CONNECT for HTTPS
+  console.log(
+    `[PROXY] Denying non-CONNECT request for: ${req.method} ${req.url}`,
+  );
+  res.writeHead(405, { 'Content-Type': 'text/plain' });
+  res.end('Method Not Allowed');
+});
+
+server.on('connect', (req, clientSocket, head) => {
+  // req.url will be in the format "hostname:port" for a CONNECT request.
+  const { port, hostname } = new URL(`http://${req.url}`);
+
+  console.log(`[PROXY] Intercepted CONNECT request for: ${hostname}:${port}`);
+
+  if (
+    ALLOWED_DOMAINS.some(
+      (domain) => hostname == domain || hostname.endsWith(`.${domain}`),
+    ) &&
+    port === ALLOWED_PORT
+  ) {
+    console.log(`[PROXY] Allowing connection to ${hostname}:${port}`);
+
+    // Establish a TCP connection to the original destination.
+    const serverSocket = net.connect(port, hostname, () => {
+      clientSocket.write('HTTP/1.1 200 Connection Established\r\n\r\n');
+      // Create a tunnel by piping data between the client and the destination server.
+      serverSocket.write(head);
+      serverSocket.pipe(clientSocket);
+      clientSocket.pipe(serverSocket);
+    });
+
+    serverSocket.on('error', (err) => {
+      console.error(`[PROXY] Error connecting to destination: ${err.message}`);
+      clientSocket.end(`HTTP/1.1 502 Bad Gateway\r\n\r\n`);
+    });
+  } else {
+    console.log(`[PROXY] Denying connection to ${hostname}:${port}`);
+    clientSocket.end('HTTP/1.1 403 Forbidden\r\n\r\n');
+  }
+
+  clientSocket.on('error', (err) => {
+    // This can happen if the client hangs up.
+    console.error(`[PROXY] Client socket error: ${err.message}`);
+  });
+});
+
+server.listen(PROXY_PORT, () => {
+  const address = server.address();
+  console.log(`[PROXY] Proxy listening on ${address.address}:${address.port}`);
+  console.log(
+    `[PROXY] Allowing HTTPS connections to domains: ${ALLOWED_DOMAINS.join(', ')}`,
+  );
+});
+```

package/bundle/docs/extensions/best-practices.md

@@ -0,0 +1,188 @@
+# Gemini CLI extension best practices
+
+This guide covers best practices for developing, securing, and maintaining
+Gemini CLI extensions.
+
+## Development
+
+Developing extensions for Gemini CLI is a lightweight, iterative process. Use
+these strategies to build robust and efficient extensions.
+
+### Structure your extension
+
+While simple extensions may contain only a few files, we recommend a organized
+structure for complex projects.
+
+```text
+my-extension/
+├── package.json
+├── tsconfig.json
+├── gemini-extension.json
+├── src/
+│   ├── index.ts
+│   └── tools/
+└── dist/
+```
+
+- **Use TypeScript:** We strongly recommend using TypeScript for type safety and
+  improved developer experience.
+- **Separate source and build:** Keep your source code in `src/` and output
+  build artifacts to `dist/`.
+- **Bundle dependencies:** If your extension has many dependencies, bundle them
+  using a tool like `esbuild` to reduce installation time and avoid conflicts.
+
+### Iterate with `link`
+
+Use the `gemini extensions link` command to develop locally without reinstalling
+your extension after every change.
+
+```bash
+cd my-extension
+gemini extensions link .
+```
+
+Changes to your code are immediately available in the CLI after you rebuild the
+project and restart the session.
+
+### Use `GEMINI.md` effectively
+
+Your `GEMINI.md` file provides essential context to the model.
+
+- **Focus on goals:** Explain the high-level purpose of the extension and how to
+  interact with its tools.
+- **Be concise:** Avoid dumping exhaustive documentation into the file. Use
+  clear, direct language.
+- **Provide examples:** Include brief examples of how the model should use
+  specific tools or commands.
+
+## Security
+
+Follow the principle of least privilege and rigorous input validation when
+building extensions.
+
+### Minimal permissions
+
+Only request the permissions your MCP server needs to function. Avoid giving the
+model broad access (such as full shell access) if restricted tools are
+sufficient.
+
+If your extension uses powerful tools like `run_shell_command`, restrict them in
+your `gemini-extension.json` file:
+
+```json
+{
+  "name": "my-safe-extension",
+  "excludeTools": ["run_shell_command(rm -rf *)"]
+}
+```
+
+This ensures the CLI blocks dangerous commands even if the model attempts to
+execute them.
+
+### Validate inputs
+
+Your MCP server runs on the user's machine. Always validate tool inputs to
+prevent arbitrary code execution or unauthorized filesystem access.
+
+```typescript
+// Example: Validating paths
+if (!path.resolve(inputPath).startsWith(path.resolve(allowedDir) + path.sep)) {
+  throw new Error('Access denied');
+}
+```
+
+### Secure sensitive settings
+
+If your extension requires API keys or other secrets, use the `sensitive: true`
+option in your manifest. This ensures keys are stored in the system keychain and
+obfuscated in the CLI output.
+
+```json
+"settings": [
+  {
+    "name": "API Key",
+    "envVar": "MY_API_KEY",
+    "sensitive": true
+  }
+]
+```
+
+## Release
+
+Follow standard versioning and release practices to ensure a smooth experience
+for your users.
+
+### Semantic versioning
+
+Follow [Semantic Versioning (SemVer)](https://semver.org/) to communicate
+changes clearly.
+
+- **Major:** Breaking changes (e.g., renaming tools or changing arguments).
+- **Minor:** New features (e.g., adding new tools or commands).
+- **Patch:** Bug fixes and performance improvements.
+
+### Release channels
+
+Use Git branches to manage release channels. This lets users choose between
+stability and the latest features.
+
+```bash
+# Install the stable version (default branch)
+gemini extensions install github.com/user/repo
+
+# Install the development version
+gemini extensions install github.com/user/repo --ref dev
+```
+
+### Clean artifacts
+
+When using GitHub Releases, ensure your archives only contain necessary files
+(such as `dist/`, `gemini-extension.json`, and `package.json`). Exclude
+`node_modules/` and `src/` to minimize download size.
+
+## Test and verify
+
+Test your extension thoroughly before releasing it to users.
+
+- **Manual verification:** Use `gemini extensions link` to test your extension
+  in a live CLI session. Verify that tools appear in the debug console (F12) and
+  that custom commands resolve correctly.
+- **Automated testing:** If your extension includes an MCP server, write unit
+  tests for your tool logic using a framework like Vitest or Jest. You can test
+  MCP tools in isolation by mocking the transport layer.
+
+## Troubleshooting
+
+Use these tips to diagnose and fix common extension issues.
+
+### Extension not loading
+
+If your extension doesn't appear in `/extensions list`:
+
+- **Check the manifest:** Ensure `gemini-extension.json` is in the root
+  directory and contains valid JSON.
+- **Verify the name:** The `name` field in the manifest must match the extension
+  directory name exactly.
+- **Restart the CLI:** Extensions are loaded at the start of a session. Restart
+  Gemini CLI after making changes to the manifest or linking a new extension.
+
+### MCP server failures
+
+If your tools aren't working as expected:
+
+- **Check the logs:** View the CLI logs to see if the MCP server failed to
+  start.
+- **Test the command:** Run the server's `command` and `args` directly in your
+  terminal to ensure it starts correctly outside of Gemini CLI.
+- **Debug console:** In interactive mode, press **F12** to open the debug
+  console and inspect tool calls and responses.
+
+### Command conflicts
+
+If a custom command isn't responding:
+
+- **Check precedence:** Remember that user and project commands take precedence
+  over extension commands. Use the prefixed name (e.g., `/extension.command`) to
+  verify the extension's version.
+- **Help command:** Run `/help` to see a list of all available commands and
+  their sources.

package/bundle/docs/extensions/index.md

@@ -0,0 +1,61 @@
+# Gemini CLI extensions
+
+Gemini CLI extensions package prompts, MCP servers, custom commands, themes,
+hooks, sub-agents, and agent skills into a familiar and user-friendly format.
+With extensions, you can expand the capabilities of Gemini CLI and share those
+capabilities with others. They are designed to be easily installable and
+shareable.
+
+To see what's possible, browse the
+[Gemini CLI extension gallery](https://geminicli.com/extensions/browse/).
+
+## Choose your path
+
+Choose the guide that best fits your needs.
+
+### I want to use extensions
+
+Learn how to discover, install, and manage extensions to enhance your Gemini CLI
+experience.
+
+- **[Manage extensions](#manage-extensions):** List and verify your installed
+  extensions.
+- **[Install extensions](#installation):** Add new capabilities from GitHub or
+  local paths.
+
+### I want to build extensions
+
+Learn how to create, test, and share your own extensions with the community.
+
+- **[Build extensions](writing-extensions.md):** Create your first extension
+  from a template.
+- **[Best practices](best-practices.md):** Learn how to build secure and
+  reliable extensions.
+- **[Publish to the gallery](releasing.md):** Share your work with the world.
+
+## Manage extensions
+
+Use the interactive `/extensions` command to verify your installed extensions
+and their status:
+
+```bash
+/extensions list
+```
+
+You can also manage extensions from your terminal using the `gemini extensions`
+command group:
+
+```bash
+gemini extensions list
+```
+
+## Installation
+
+Install an extension by providing its GitHub repository URL. For example:
+
+```bash
+gemini extensions install https://github.com/gemini-cli-extensions/workspace
+```
+
+For more advanced installation options, see the
+[Extension reference](reference.md#install-an-extension).

package/bundle/docs/extensions/reference.md

@@ -0,0 +1,333 @@
+# Extension reference
+
+This guide covers the `gemini extensions` commands and the structure of the
+`gemini-extension.json` configuration file.
+
+## Manage extensions
+
+Use the `gemini extensions` command group to manage your extensions from the
+terminal.
+
+Note that commands like `gemini extensions install` are not supported within the
+CLI's interactive mode. However, you can use the `/extensions list` command to
+view installed extensions. All management operations, including updates to slash
+commands, take effect only after you restart the CLI session.
+
+### Install an extension
+
+Install an extension by providing its GitHub repository URL or a local file
+path.
+
+Gemini CLI creates a copy of the extension during installation. You must run
+`gemini extensions update` to pull changes from the source. To install from
+GitHub, you must have `git` installed on your machine.
+
+```bash
+gemini extensions install <source> [--ref <ref>] [--auto-update] [--pre-release] [--consent]
+```
+
+- `<source>`: The GitHub URL or local path of the extension.
+- `--ref`: The git ref (branch, tag, or commit) to install.
+- `--auto-update`: Enable automatic updates for this extension.
+- `--pre-release`: Enable installation of pre-release versions.
+- `--consent`: Acknowledge security risks and skip the confirmation prompt.
+
+### Uninstall an extension
+
+To uninstall one or more extensions, use the `uninstall` command:
+
+```bash
+gemini extensions uninstall <name...>
+```
+
+### Disable an extension
+
+Extensions are enabled globally by default. You can disable an extension
+entirely or for a specific workspace.
+
+```bash
+gemini extensions disable <name> [--scope <scope>]
+```
+
+- `<name>`: The name of the extension to disable.
+- `--scope`: The scope to disable the extension in (`user` or `workspace`).
+
+### Enable an extension
+
+Re-enable a disabled extension using the `enable` command:
+
+```bash
+gemini extensions enable <name> [--scope <scope>]
+```
+
+- `<name>`: The name of the extension to enable.
+- `--scope`: The scope to enable the extension in (`user` or `workspace`).
+
+### Update an extension
+
+Update an extension to the version specified in its `gemini-extension.json`
+file.
+
+```bash
+gemini extensions update <name>
+```
+
+To update all installed extensions at once:
+
+```bash
+gemini extensions update --all
+```
+
+### Create an extension from a template
+
+Create a new extension directory using a built-in template.
+
+```bash
+gemini extensions new <path> [template]
+```
+
+- `<path>`: The directory to create.
+- `[template]`: The template to use (e.g., `mcp-server`, `context`,
+  `custom-commands`).
+
+### Link a local extension
+
+Create a symbolic link between your development directory and the Gemini CLI
+extensions directory. This lets you test changes immediately without
+reinstalling.
+
+```bash
+gemini extensions link <path>
+```
+
+## Extension format
+
+Gemini CLI loads extensions from `<home>/.gemini/extensions`. Each extension
+must have a `gemini-extension.json` file in its root directory.
+
+### `gemini-extension.json`
+
+The manifest file defines the extension's behavior and configuration.
+
+```json
+{
+  "name": "my-extension",
+  "version": "1.0.0",
+  "description": "My awesome extension",
+  "mcpServers": {
+    "my-server": {
+      "command": "node",
+      "args": ["${extensionPath}/my-server.js"],
+      "cwd": "${extensionPath}"
+    }
+  },
+  "contextFileName": "GEMINI.md",
+  "excludeTools": ["run_shell_command"],
+  "plan": {
+    "directory": ".gemini/plans"
+  }
+}
+```
+
+- `name`: The name of the extension. This is used to uniquely identify the
+  extension and for conflict resolution when extension commands have the same
+  name as user or project commands. The name should be lowercase or numbers and
+  use dashes instead of underscores or spaces. This is how users will refer to
+  your extension in the CLI. Note that we expect this name to match the
+  extension directory name.
+- `version`: The version of the extension.
+- `description`: A short description of the extension. This will be displayed on
+  [geminicli.com/extensions](https://geminicli.com/extensions).
+- `mcpServers`: A map of MCP servers to settings. The key is the name of the
+  server, and the value is the server configuration. These servers will be
+  loaded on startup just like MCP servers defined in a
+  [`settings.json` file](../reference/configuration.md). If both an extension
+  and a `settings.json` file define an MCP server with the same name, the server
+  defined in the `settings.json` file takes precedence.
+  - Note that all MCP server configuration options are supported except for
+    `trust`.
+  - For portability, you should use `${extensionPath}` to refer to files within
+    your extension directory.
+  - Separate your executable and its arguments using `command` and `args`
+    instead of putting them both in `command`.
+- `contextFileName`: The name of the file that contains the context for the
+  extension. This will be used to load the context from the extension directory.
+  If this property is not used but a `GEMINI.md` file is present in your
+  extension directory, then that file will be loaded.
+- `excludeTools`: An array of tool names to exclude from the model. You can also
+  specify command-specific restrictions for tools that support it, like the
+  `run_shell_command` tool. For example,
+  `"excludeTools": ["run_shell_command(rm -rf)"]` will block the `rm -rf`
+  command. Note that this differs from the MCP server `excludeTools`
+  functionality, which can be listed in the MCP server config.
+- `plan`: Planning features configuration.
+  - `directory`: The directory where planning artifacts are stored. This serves
+    as a fallback if the user hasn't specified a plan directory in their
+    settings. If not specified by either the extension or the user, the default
+    is `~/.gemini/tmp/<project>/<session-id>/plans/`.
+
+When Gemini CLI starts, it loads all the extensions and merges their
+configurations. If there are any conflicts, the workspace configuration takes
+precedence.
+
+### Extension settings
+
+Extensions can define settings that users provide during installation, such as
+API keys or URLs. These values are stored in a `.env` file within the extension
+directory.
+
+To define settings, add a `settings` array to your manifest:
+
+```json
+{
+  "name": "my-api-extension",
+  "version": "1.0.0",
+  "settings": [
+    {
+      "name": "API Key",
+      "description": "Your API key for the service.",
+      "envVar": "MY_API_KEY",
+      "sensitive": true
+    }
+  ]
+}
+```
+
+- `name`: The setting's display name.
+- `description`: A clear explanation of the setting.
+- `envVar`: The environment variable name where the value is stored.
+- `sensitive`: If `true`, the value is stored in the system keychain and
+  obfuscated in the UI.
+
+To update an extension's settings:
+
+```bash
+gemini extensions config <name> [setting] [--scope <scope>]
+```
+
+### Custom commands
+
+Provide [custom commands](../cli/custom-commands.md) by placing TOML files in a
+`commands/` subdirectory. Gemini CLI uses the directory structure to determine
+the command name.
+
+For an extension named `gcp`:
+
+- `commands/deploy.toml` becomes `/deploy`
+- `commands/gcs/sync.toml` becomes `/gcs:sync` (namespaced with a colon)
+
+### Hooks
+
+Intercept and customize CLI behavior using [hooks](../hooks/index.md). Define
+hooks in a `hooks/hooks.json` file within your extension directory. Note that
+hooks are not defined in the `gemini-extension.json` manifest.
+
+### Agent skills
+
+Bundle [agent skills](../cli/skills.md) to provide specialized workflows. Place
+skill definitions in a `skills/` directory. For example,
+`skills/security-audit/SKILL.md` exposes a `security-audit` skill.
+
+### Sub-agents
+
+> **Note:** Sub-agents are a preview feature currently under active development.
+
+Provide [sub-agents](../core/subagents.md) that users can delegate tasks to. Add
+agent definition files (`.md`) to an `agents/` directory in your extension root.
+
+### <a id="policy-engine"></a>Policy Engine
+
+Extensions can contribute policy rules and safety checkers to the Gemini CLI
+[Policy Engine](../reference/policy-engine.md). These rules are defined in
+`.toml` files and take effect when the extension is activated.
+
+To add policies, create a `policies/` directory in your extension's root and
+place your `.toml` policy files inside it. Gemini CLI automatically loads all
+`.toml` files from this directory.
+
+Rules contributed by extensions run in their own tier (tier 2), alongside
+workspace-defined policies. This tier has higher priority than the default rules
+but lower priority than user or admin policies.
+
+> **Warning:** For security, Gemini CLI ignores any `allow` decisions or `yolo`
+> mode configurations in extension policies. This ensures that an extension
+> cannot automatically approve tool calls or bypass security measures without
+> your confirmation.
+
+**Example `policies.toml`**
+
+```toml
+[[rule]]
+toolName = "my_server__dangerous_tool"
+decision = "ask_user"
+priority = 100
+
+[[safety_checker]]
+toolName = "my_server__write_data"
+priority = 200
+[safety_checker.checker]
+type = "in-process"
+name = "allowed-path"
+required_context = ["environment"]
+```
+
+### Themes
+
+Extensions can provide custom themes to personalize the CLI UI. Themes are
+defined in the `themes` array in `gemini-extension.json`.
+
+**Example**
+
+```json
+{
+  "name": "my-green-extension",
+  "version": "1.0.0",
+  "themes": [
+    {
+      "name": "shades-of-green",
+      "type": "custom",
+      "background": {
+        "primary": "#1a362a"
+      },
+      "text": {
+        "primary": "#a6e3a1",
+        "secondary": "#6e8e7a",
+        "link": "#89e689"
+      },
+      "status": {
+        "success": "#76c076",
+        "warning": "#d9e689",
+        "error": "#b34e4e"
+      },
+      "border": {
+        "default": "#4a6c5a"
+      },
+      "ui": {
+        "comment": "#6e8e7a"
+      }
+    }
+  ]
+}
+```
+
+Custom themes provided by extensions can be selected using the `/theme` command
+or by setting the `ui.theme` property in your `settings.json` file. Note that
+when referring to a theme from an extension, the extension name is appended to
+the theme name in parentheses, e.g., `shades-of-green (my-green-extension)`.
+
+### Conflict resolution
+
+Extension commands have the lowest precedence. If an extension command name
+conflicts with a user or project command, the extension command is prefixed with
+the extension name (e.g., `/gcp.deploy`) using a dot separator.
+
+## Variables
+
+Gemini CLI supports variable substitution in `gemini-extension.json` and
+`hooks/hooks.json`.
+
+| Variable           | Description                                     |
+| :----------------- | :---------------------------------------------- |
+| `${extensionPath}` | The absolute path to the extension's directory. |
+| `${workspacePath}` | The absolute path to the current workspace.     |
+| `${/}`             | The platform-specific path separator.           |