@dgxo/mashadevcli 1.1.0

package/bundle/docs/tools/memory.md

@@ -0,0 +1,35 @@
+# Memory tool (`save_memory`)
+
+The `save_memory` tool allows the Gemini agent to persist specific facts, user
+preferences, and project details across sessions.
+
+## Technical reference
+
+This tool appends information to the `## Gemini Added Memories` section of your
+global `GEMINI.md` file (typically located at `~/.gemini/GEMINI.md`).
+
+### Arguments
+
+- `fact` (string, required): A clear, self-contained statement in natural
+  language.
+
+## Technical behavior
+
+- **Storage:** Appends to the global context file in the user's home directory.
+- **Loading:** The stored facts are automatically included in the hierarchical
+  context system for all future sessions.
+- **Format:** Saves data as a bulleted list item within a dedicated Markdown
+  section.
+
+## Use cases
+
+- Persisting user preferences (for example, "I prefer functional programming").
+- Saving project-wide architectural decisions.
+- Storing frequently used aliases or system configurations.
+
+## Next steps
+
+- Follow the [Memory management guide](../cli/tutorials/memory-management.md)
+  for practical examples.
+- Learn how the [Project context (GEMINI.md)](../cli/gemini-md.md) system loads
+  this information.

package/bundle/docs/tools/planning.md

@@ -0,0 +1,58 @@
+# Gemini CLI planning tools
+
+Planning tools let Gemini CLI switch into a safe, read-only "Plan Mode" for
+researching and planning complex changes, and to signal the finalization of a
+plan to the user.
+
+## 1. `enter_plan_mode` (EnterPlanMode)
+
+`enter_plan_mode` switches the CLI to Plan Mode. This tool is typically called
+by the agent when you ask it to "start a plan" using natural language. In this
+mode, the agent is restricted to read-only tools to allow for safe exploration
+and planning.
+
+> **Note:** This tool is not available when the CLI is in YOLO mode.
+
+- **Tool name:** `enter_plan_mode`
+- **Display name:** Enter Plan Mode
+- **File:** `enter-plan-mode.ts`
+- **Parameters:**
+  - `reason` (string, optional): A short reason explaining why the agent is
+    entering plan mode (for example, "Starting a complex feature
+    implementation").
+- **Behavior:**
+  - Switches the CLI's approval mode to `PLAN`.
+  - Notifies the user that the agent has entered Plan Mode.
+- **Output (`llmContent`):** A message indicating the switch, for example,
+  `Switching to Plan mode.`
+- **Confirmation:** Yes. The user is prompted to confirm entering Plan Mode.
+
+## 2. `exit_plan_mode` (ExitPlanMode)
+
+`exit_plan_mode` signals that the planning phase is complete. It presents the
+finalized plan to the user and requests approval to start the implementation.
+
+- **Tool name:** `exit_plan_mode`
+- **Display name:** Exit Plan Mode
+- **File:** `exit-plan-mode.ts`
+- **Parameters:**
+  - `plan_path` (string, required): The path to the finalized Markdown plan
+    file. This file MUST be located within the project's temporary plans
+    directory (for example, `~/.gemini/tmp/<project>/plans/`).
+- **Behavior:**
+  - Validates that the `plan_path` is within the allowed directory and that the
+    file exists and has content.
+  - Presents the plan to the user for review.
+  - If the user approves the plan:
+    - Switches the CLI's approval mode to the user's chosen approval mode (
+      `DEFAULT` or `AUTO_EDIT`).
+    - Marks the plan as approved for implementation.
+  - If the user rejects the plan:
+    - Stays in Plan Mode.
+    - Returns user feedback to the model to refine the plan.
+- **Output (`llmContent`):**
+  - On approval: A message indicating the plan was approved and the new approval
+    mode.
+  - On rejection: A message containing the user's feedback.
+- **Confirmation:** Yes. Shows the finalized plan and asks for user approval to
+  proceed with implementation.

package/bundle/docs/tools/shell.md

@@ -0,0 +1,216 @@
+# Shell tool (`run_shell_command`)
+
+The `run_shell_command` tool allows the Gemini model to execute commands
+directly on your system's shell. It is the primary mechanism for the agent to
+interact with your environment beyond simple file edits.
+
+## Technical reference
+
+On Windows, commands execute with `powershell.exe -NoProfile -Command`. On other
+platforms, they execute with `bash -c`.
+
+### Arguments
+
+- `command` (string, required): The exact shell command to execute.
+- `description` (string, optional): A brief description shown to the user for
+  confirmation.
+- `dir_path` (string, optional): The absolute path or relative path from
+  workspace root where the command runs.
+- `is_background` (boolean, optional): Whether to move the process to the
+  background immediately after starting.
+
+### Return values
+
+The tool returns a JSON object containing:
+
+- `Command`: The executed string.
+- `Directory`: The execution path.
+- `Stdout` / `Stderr`: The output streams.
+- `Exit Code`: The process return code.
+- `Background PIDs`: PIDs of any started background processes.
+
+## Configuration
+
+You can configure the behavior of the `run_shell_command` tool by modifying your
+`settings.json` file or by using the `/settings` command in the Gemini CLI.
+
+### Enabling interactive commands
+
+To enable interactive commands, you need to set the
+`tools.shell.enableInteractiveShell` setting to `true`. This will use `node-pty`
+for shell command execution, which allows for interactive sessions. If
+`node-pty` is not available, it will fall back to the `child_process`
+implementation, which does not support interactive commands.
+
+**Example `settings.json`:**
+
+```json
+{
+  "tools": {
+    "shell": {
+      "enableInteractiveShell": true
+    }
+  }
+}
+```
+
+### Showing color in output
+
+To show color in the shell output, you need to set the `tools.shell.showColor`
+setting to `true`. **Note: This setting only applies when
+`tools.shell.enableInteractiveShell` is enabled.**
+
+**Example `settings.json`:**
+
+```json
+{
+  "tools": {
+    "shell": {
+      "showColor": true
+    }
+  }
+}
+```
+
+### Setting the pager
+
+You can set a custom pager for the shell output by setting the
+`tools.shell.pager` setting. The default pager is `cat`. **Note: This setting
+only applies when `tools.shell.enableInteractiveShell` is enabled.**
+
+**Example `settings.json`:**
+
+```json
+{
+  "tools": {
+    "shell": {
+      "pager": "less"
+    }
+  }
+}
+```
+
+## Interactive commands
+
+The `run_shell_command` tool now supports interactive commands by integrating a
+pseudo-terminal (pty). This allows you to run commands that require real-time
+user input, such as text editors (`vim`, `nano`), terminal-based UIs (`htop`),
+and interactive version control operations (`git rebase -i`).
+
+When an interactive command is running, you can send input to it from the Gemini
+CLI. To focus on the interactive shell, press `Tab`. The terminal output,
+including complex TUIs, will be rendered correctly.
+
+## Important notes
+
+- **Security:** Be cautious when executing commands, especially those
+  constructed from user input, to prevent security vulnerabilities.
+- **Error handling:** Check the `Stderr`, `Error`, and `Exit Code` fields to
+  determine if a command executed successfully.
+- **Background processes:** When a command is run in the background with `&`,
+  the tool will return immediately and the process will continue to run in the
+  background. The `Background PIDs` field will contain the process ID of the
+  background process.
+
+## Environment variables
+
+When `run_shell_command` executes a command, it sets the `GEMINI_CLI=1`
+environment variable in the subprocess's environment. This allows scripts or
+tools to detect if they are being run from within the Gemini CLI.
+
+## Command restrictions
+
+You can restrict the commands that can be executed by the `run_shell_command`
+tool by using the `tools.core` and `tools.exclude` settings in your
+configuration file.
+
+- `tools.core`: To restrict `run_shell_command` to a specific set of commands,
+  add entries to the `core` list under the `tools` category in the format
+  `run_shell_command(<command>)`. For example,
+  `"tools": {"core": ["run_shell_command(git)"]}` will only allow `git`
+  commands. Including the generic `run_shell_command` acts as a wildcard,
+  allowing any command not explicitly blocked.
+- `tools.exclude` [DEPRECATED]: To block specific commands, use the
+  [Policy Engine](../reference/policy-engine.md). Historically, this setting
+  allowed adding entries to the `exclude` list under the `tools` category in the
+  format `run_shell_command(<command>)`. For example,
+  `"tools": {"exclude": ["run_shell_command(rm)"]}` will block `rm` commands.
+
+The validation logic is designed to be secure and flexible:
+
+1.  **Command chaining disabled**: The tool automatically splits commands
+    chained with `&&`, `||`, or `;` and validates each part separately. If any
+    part of the chain is disallowed, the entire command is blocked.
+2.  **Prefix matching**: The tool uses prefix matching. For example, if you
+    allow `git`, you can run `git status` or `git log`.
+3.  **Blocklist precedence**: The `tools.exclude` list is always checked first.
+    If a command matches a blocked prefix, it will be denied, even if it also
+    matches an allowed prefix in `tools.core`.
+
+### Command restriction examples
+
+**Allow only specific command prefixes**
+
+To allow only `git` and `npm` commands, and block all others:
+
+```json
+{
+  "tools": {
+    "core": ["run_shell_command(git)", "run_shell_command(npm)"]
+  }
+}
+```
+
+- `git status`: Allowed
+- `npm install`: Allowed
+- `ls -l`: Blocked
+
+**Block specific command prefixes**
+
+To block `rm` and allow all other commands:
+
+```json
+{
+  "tools": {
+    "core": ["run_shell_command"],
+    "exclude": ["run_shell_command(rm)"]
+  }
+}
+```
+
+- `rm -rf /`: Blocked
+- `git status`: Allowed
+- `npm install`: Allowed
+
+**Blocklist takes precedence**
+
+If a command prefix is in both `tools.core` and `tools.exclude`, it will be
+blocked.
+
+- **`tools.shell.enableInteractiveShell`**: (boolean) Uses `node-pty` for
+  real-time interaction.
+- **`tools.shell.showColor`**: (boolean) Preserves ANSI colors in output.
+- **`tools.shell.inactivityTimeout`**: (number) Seconds to wait for output
+  before killing the process.
+
+### Command restrictions
+
+You can limit which commands the agent is allowed to request using these
+settings:
+
+- **`tools.core`**: An allowlist of command prefixes (for example,
+  `["git", "npm test"]`).
+- **`tools.exclude`**: A blocklist of command prefixes.
+
+## Use cases
+
+- Running build scripts and test suites.
+- Initializing or managing version control systems.
+- Installing project dependencies.
+- Starting development servers or background watchers.
+
+## Next steps
+
+- Follow the [Shell commands tutorial](../cli/tutorials/shell-commands.md) for
+  practical examples.
+- Learn about [Sandboxing](../cli/sandbox.md) to isolate command execution.

package/bundle/docs/tools/todos.md

@@ -0,0 +1,35 @@
+# Todo tool (`write_todos`)
+
+The `write_todos` tool allows the Gemini agent to maintain an internal list of
+subtasks for multi-step requests.
+
+## Technical reference
+
+The agent uses this tool to manage its execution plan and provide progress
+updates to the CLI interface.
+
+### Arguments
+
+- `todos` (array of objects, required): The complete list of tasks. Each object
+  includes:
+  - `description` (string): Technical description of the task.
+  - `status` (enum): `pending`, `in_progress`, `completed`, or `cancelled`.
+
+## Technical behavior
+
+- **Interface:** Updates the progress indicator above the CLI input prompt.
+- **Exclusivity:** Only one task can be marked `in_progress` at any time.
+- **Persistence:** Todo state is scoped to the current session.
+- **Interaction:** Users can toggle the full list view using **Ctrl+T**.
+
+## Use cases
+
+- Breaking down a complex feature implementation into manageable steps.
+- Coordinating multi-file refactoring tasks.
+- Providing visibility into the agent's current focus during long-running tasks.
+
+## Next steps
+
+- Follow the [Task planning tutorial](../cli/tutorials/task-planning.md) for
+  usage details.
+- Learn about [Session management](../cli/session-management.md) for context.

package/bundle/docs/tools/web-fetch.md

@@ -0,0 +1,35 @@
+# Web fetch tool (`web_fetch`)
+
+The `web_fetch` tool allows the Gemini agent to retrieve and process content
+from specific URLs provided in your prompt.
+
+## Technical reference
+
+The agent uses this tool when you include URLs in your prompt and request
+specific operations like summarization or extraction.
+
+### Arguments
+
+- `prompt` (string, required): A request containing up to 20 valid URLs
+  (starting with `http://` or `https://`) and instructions on how to process
+  them.
+
+## Technical behavior
+
+- **Confirmation:** Triggers a confirmation dialog showing the converted URLs.
+- **Processing:** Uses the Gemini API's `urlContext` for retrieval.
+- **Fallback:** If API access fails, the tool attempts to fetch raw content
+  directly from your local machine.
+- **Formatting:** Returns a synthesized response with source attribution.
+
+## Use cases
+
+- Summarizing technical articles or blog posts.
+- Comparing data between two or more web pages.
+- Extracting specific information from a documentation site.
+
+## Next steps
+
+- Follow the [Web tools guide](../cli/tutorials/web-tools.md) for practical
+  usage examples.
+- See the [Web search tool reference](./web-search.md) for general queries.

package/bundle/docs/tools/web-search.md

@@ -0,0 +1,32 @@
+# Web search tool (`google_web_search`)
+
+The `google_web_search` tool allows the Gemini agent to retrieve up-to-date
+information, news, and facts from the internet via Google Search.
+
+## Technical reference
+
+The agent uses this tool when your request requires knowledge of current events
+or specific online documentation not available in its internal training data.
+
+### Arguments
+
+- `query` (string, required): The search query to be executed.
+
+## Technical behavior
+
+- **Grounding:** Returns a generated summary based on search results.
+- **Citations:** Includes source URIs and titles for factual grounding.
+- **Processing:** The Gemini API processes the search results before returning a
+  synthesized response to the agent.
+
+## Use cases
+
+- Researching the latest version of a software library or API.
+- Finding solutions to recent software bugs or security vulnerabilities.
+- Retrieving news or documentation updated after the model's knowledge cutoff.
+
+## Next steps
+
+- Follow the [Web tools guide](../cli/tutorials/web-tools.md) for practical
+  usage examples.
+- Explore the [Web fetch tool reference](./web-fetch.md) for direct URL access.

package/bundle/docs/update/update-guide.md

@@ -0,0 +1,111 @@
+# Panduan Update Mashadev Fork
+
+## Kenapa Ini Perlu Diperhatiin?
+
+Mashadev adalah **fork** dari `DGameGT/mashadev-cli`. Artinya kode kita
+hidup di dua tempat:
+
+- **Upstream** — repo asli Google yang terus dapat fitur baru
+- **Fork kita** — repo Mashadev dengan branding & customisasi sendiri
+
+Masalahnya: kalau upstream update file yang sama dengan yang kita rename
+(seperti `AppHeader.tsx`), git akan **conflict** — dia bingung mau pakai versi
+mana. Kalau salah handle, rename hilang.
+
+---
+
+## Kenapa Pakai Branch Terpisah?
+
+Semua customisasi Mashadev (rename, branding, fitur custom) harus hidup di
+**branch tersendiri**, bukan di `main`.
+
+Alasannya:
+
+- `main` kita = cerminan upstream → gampang di-update
+- `masha-dev` = tempat semua custom kita tinggal
+- Kalau upstream update, kita tinggal rebase `masha-dev` di atas `main` yang
+  sudah fresh
+
+```
+upstream/main  →  fork/main  →  fork/masha-dev
+                                (semua rename di sini)
+```
+
+---
+
+## Setup Sekali (First Time)
+
+```powershell
+# 1. Tambahkan upstream sebagai remote
+git remote add upstream https://github.com/DGameGT/mashadev-cli.git
+
+# 2. Buat branch khusus untuk semua customisasi Mashadev
+git checkout -b masha-dev
+
+# 3. Commit semua perubahan custom di sini
+git add .
+git commit -m "feat: mashadev branding & customizations"
+```
+
+---
+
+## Cara Update (Setiap Ada Fitur Baru dari Upstream)
+
+```powershell
+# 1. Pindah ke main dulu
+git checkout main
+
+# 2. Pull update terbaru dari Google
+git pull upstream main
+
+# 3. Push ke fork GitHub kita
+git push origin main
+
+# 4. Balik ke branch masha-dev
+git checkout masha-dev
+
+# 5. Rebase di atas main yang sudah update
+git rebase main
+```
+
+### Kalau Ada Conflict Saat Rebase
+
+Git akan berhenti dan menunjukkan file yang conflict. Buka file tersebut, cari
+tanda `<<<<<<`, `======`, `>>>>>>` — itu adalah bagian yang perlu kamu pilih
+atau gabungkan.
+
+```powershell
+# Setelah resolve conflict di file tersebut:
+git add <nama-file>
+git rebase --continue
+
+# Kalau mau batalkan rebase:
+git rebase --abort
+```
+
+---
+
+## File yang Perlu Diperhatiin (Rawan Conflict)
+
+| File              | Perubahan Mashadev               |
+| ----------------- | -------------------------------- |
+| `AppHeader.tsx`   | "Gemini CLI" → "Masha Dev CLI"   |
+| `MainContent.tsx` | Swap ke `Header.tsx` (ASCII art) |
+| `updateCheck.ts`  | Auto-update dimatikan            |
+| `AsciiArt.ts`     | Logo custom                      |
+
+Kalau upstream update file-file ini → **siap-siap resolve conflict**.  
+Kalau upstream update file lain (tools baru, model baru, dll) → **langsung masuk
+mulus**.
+
+---
+
+## Tips
+
+Kalau perubahan Mashadev makin banyak, pertimbangkan bikin script
+`apply-mashadev-branding.sh` yang otomatis re-apply semua rename setelah update.
+Lebih predictable dari resolve conflict manual.
+
+Auto-update CLI (`updateCheck.ts`) sudah dimatikan, jadi tidak akan ada update
+otomatis yang menimpa binary `mashadev`. Tapi update dari upstream tetap harus
+dilakukan **manual** via git seperti panduan ini.