/gas-execution

name: gas-execution
description: Guidelines for writing and executing Google Apps Script code using ggsrun and finding documentation via workspace-developer. Use when developing or running GAS applications.

Google Apps Script Execution and Development Skill

Follow these guidelines when writing, reviewing, and executing Google Apps Script (GAS) applications:

Script Execution via ggsrun

• **Execution Tool (`exe1`)**: Always prefer the `exe1` tool of the `ggsrun` MCP server to synchronize local code/directories and run the entry function in a single transaction.
• **Opt-in Log Retrieval (Default Off)**: To guarantee sub-second execution, `ggsrun` does **not** fetch logs from Cloud Logging by default. If you need to inspect `Logger.log()` or `console.log()` outputs, you must explicitly set the `log: true` parameter (or use the `--log` / `-l` flag in CLI mode). Note that enabling log retrieval adds a 5–10 second delay to allow Google's indexing.
• **Clock-Drift Immunity**: `ggsrun` queries Cloud Logging using a wide past window (`timestamp >= startTime - 60m`) and **completely omits any future upper bounds** (`timestamp <= ...`). This makes the query completely immune to local clock drift (e.g., when the host machine's clock is minutes or hours behind the actual time). Do not worry about clock discrepancies when retrieving logs.
• **Post-Detection Multi-Poll Buffer**: Due to Google's parallel logging nodes, `console.log` and `Logger.log` can index several seconds apart. Once `ggsrun` detects the first log entry for the current Apps Script `process_id`, it automatically queries 4 more times at 2.0-second intervals (providing an 8.0-second stabilization window) to capture all lagging streams.
• **TUI On-Demand Async Log Injection**: When executing via the TUI (`ggsrun fd`), the execution result is displayed **instantly** without waiting. An overlay modal then prompts: *"Do you want to retrieve execution logs from Cloud Logging?"*. If you select Yes, logs are fetched in a background goroutine and dynamically injected into the active text view.
• **In-Memory Sandbox (`sandbox`)**: For secure execution, pass the path of your whitelist configuration JSON (e.g. `sandbox: "sandbox_config.json"`) to `exe1`. This instructs `ggsrun` to generate a separate sandbox guard file (`_for_sandbox_gas.gs`) containing the whitelists, which is evaluated first alphabetically by the GAS V8 engine. The user's execution scripts only undergo static token replacement (e.g., `SpreadsheetApp` -> `_wrappedSpreadsheetApp`), meaning their line numbers remain completely unchanged. If an error occurs, the line numbers in the stack trace will match your local source files exactly, allowing you to debug directly.
• **Auto-Cleanup & Resilient Rollback**: `ggsrun` performs an in-memory backup of the remote project state (including all script files and the `appsscript.json` manifest). On execution completion, runtime sandboxing halts, or process interrupts (`Ctrl+C`), `ggsrun` automatically rolls back all file changes on the remote script project, leaving your codebase 100% clean and pristine. This cleanup behavior is enabled by default. To bypass this cleanup and leave the uploaded files in the remote project, use the `undeleteScript: true` option (or `--undeleteScript` / `--ud` flag in CLI mode).
• **Intelligent Manifest Merging**: When executing scripts that require Advanced Services or custom dependencies, you can upload a local `appsscript.json` manifest. `ggsrun` will automatically merge your dependencies (e.g., `enabledAdvancedServices` or custom `libraries`) with the remote project's existing manifest without breaking critical configurations like `executionApi` or `webapp` needed for execution.
• **Self-Healing Recovery**: If a script execution is interrupted and the remote project is left in an inconsistent state, you can run the `ggsrun recover` command to immediately restore the project to the pristine ggsrun state.
• **Designing Return Values**: The execution response displays only the value returned by the `return` statement of the executed function. Design your script to return a meaningful value representing the execution result.
• **Detailed Logs**: You can return detailed logs or execution summaries as the final return string to provide context and results to the user.
• **JSON Serialization**: If returning structured data (such as objects, arrays, or status maps), use `JSON.stringify()` to serialize it before returning.

Other ggsrun MCP Server Tools

Beyond the stateful script execution (`exe1`), you can leverage the following tools from the `ggsrun-mcp` server for managing files, projects, and directories on Google Drive:

1. `searchfiles`

• **Purpose**: Search for files or folders in Google Drive using standard Drive API v3 queries, with optional local regex filtering on filenames.
• **Usage Guide**: Specify the `query` (e.g., `name = 'MyScript' and trashed = false` or `mimeType = 'application/vnd.google-apps.folder'`). Optionally provide a `regex` pattern to filter result names.
• **Example Case**: Finding the folder ID named "Backup" or discovering spreadsheet files with a matching pattern:
• Arguments: `{ "query": "mimeType = 'application/vnd.google-apps.spreadsheet' and trashed = false", "regex": "^Production_.*" }`

2. `filelist`

• **Purpose**: Perform exact matches by File Name or resolve filenames by File ID on Google Drive.
• **Usage Guide**: Use `searchbyname` to find IDs matching an exact name, or `searchbyid` to get the metadata of a specific ID.
• **Example Case**: Quick lookup of a target Spreadsheet ID before execution:
• Arguments: `{ "searchbyname": "TargetSpreadsheet" }`

3. `download`

• **Purpose**: Download files or entire recursive folder structures to your local system, supporting on-the-fly Google Workspace format export.
• **Usage Guide**: Provide the target `fileid`. Use the `extension` parameter to convert Google Docs, Sheets, Slides, or Drawings to l