@mcpher/gas-fakes 2.3.16 → 2.3.17

package/gf_agent/SKILL.md

@@ -25,7 +25,6 @@ description: >
     - **Remote URL**: `https://raw.githubusercontent.com/brucemcpherson/gas-fakes/main/progress/{service}.md` (Note: `{service}` is lowercase, e.g., `spreadsheet.md`).
     - Use these details to construct precise, parity-compliant code without relying on external search engines unless documentation is missing.
 3. **Generate Script**: Create a Node.js script that:
-    - Imports `@mcpher/gas-fakes`.
     - Uses standard GAS syntax.
     - (Optional) Uses `ScriptApp.isFake` for local-only logic like logging or cleanup.
 4. **Execute & Verify**: Use the `mcp_gas-fakes-mcp_workspace_agent` tool to execute the code and report the results to the user.
@@ -39,7 +38,6 @@ Agent:
    - (Optional) Fetch `progress/gmail.md` and `progress/document.md` from GitHub for detailed signatures.
 3. **Generate Script**:
    ```javascript
-   import '@mcpher/gas-fakes';
    const threads = GmailApp.getInboxThreads(0, 5);
    let summary = 'Email Summary:\n\n';
    threads.forEach(t => {
@@ -67,6 +65,7 @@ Agent:
 ### Execution Context & Artifacts (CRITICAL)
 - **Role Boundary**: You are the `gf_agent` operating on behalf of an end-user to automate Google Workspace tasks. You are NOT a developer writing internal tests for the `gas-fakes` emulator repository.
 - **Transient Execution**: When fulfilling automation requests (e.g., "Create a sheet", "Summarize emails"), you MUST use the provided MCP execution tools (e.g., `run_script` or `mcp_gas-fakes-mcp_workspace_agent`) to execute code dynamically on-the-fly.
+- **No Import Required**: Do NOT include `import '@mcpher/gas-fakes';` at the top of your scripts when using the MCP execution tools. The MCP server environment automatically provisions all Google Apps Script globals (like `SpreadsheetApp`, `DriveApp`, etc.) into the execution context for you.
 - **No Permanent Artifacts**: DO NOT write script files to disk (e.g., in a `test/` folder) to execute user tasks, and DO NOT use the internal `gas-fakes` testing harness (like `initTests()`). The end-user of `gf_agent` does not have or care about the emulator's testing environment. Provide the plain Apps Script code directly as a string parameter to the MCP tool.
 
 ### Efficient Drive Searching (Best Practice)
@@ -84,8 +83,9 @@ Agent:
 
 
 ### Common Apps Script Syntax Gotchas (First-Time Accuracy)
-- **File Conversion (Exporting to PDF)**: While live Apps Script can seamlessly convert text files (`text/plain`) to PDF using `file.getAs('application/pdf')`, the underlying Google Drive API **only supports exporting Docs Editor files** (Docs, Sheets, Slides).
-  - **Automated Workaround in gas-fakes**: `gas-fakes` handles this transparently! If you attempt to convert a non-editor file to PDF locally via `.getAs()`, it automatically performs a temporary two-step conversion (copying it to a Google Doc, exporting it, and trashing the temp file). This ensures parity with live Apps Script without manual intervention.
+- **File Conversion (Exporting to PDF)**: 
+  - **`DriveApp.File.getAs()` Workaround**: While live Apps Script can seamlessly convert text files (`text/plain`) to PDF using `file.getAs('application/pdf')`, the underlying Google Drive API **only supports exporting Docs Editor files** (Docs, Sheets, Slides). `gas-fakes` handles this transparently by automatically performing a temporary two-step conversion (copying it to a Google Doc, exporting it, and trashing the temp file). This ensures parity with live Apps Script without manual intervention.
+  - **`Spreadsheet.getAs()` Limitation**: The `getAs()` method is **NOT** implemented directly on `Spreadsheet`, `Document`, or `Presentation` objects in `gas-fakes`. If you try to call `ss.getAs('application/pdf')`, the script will crash. **Crucial Rule**: You MUST fetch the file via DriveApp first to convert it: `DriveApp.getFileById(ss.getId()).getAs('application/pdf')`.
 - **Google Docs Formatting**: You CANNOT apply formatting (bold, italic, etc.) directly to a `Paragraph` or `ListItem`. You MUST use `editAsText()` first.
   - *Incorrect*: `paragraph.setItalic(true)`
   - *Correct*: `paragraph.editAsText().setItalic(true)`
@@ -126,14 +126,36 @@ Agent:
 - **Iterators**: `gas-fakes` iterators (like `FileIterator`) implement the native Apps Script `hasNext()` and `next()` methods, which differ from standard JavaScript iterators.
 
 ### Google Docs & Images
-- **Inline Image Resizing**: Native methods like `setWidth()`/`setHeight()` are **NOT** implemented.
+- **Inline Image Resizing (DocumentApp)**: Native methods like `setWidth()` and `setHeight()` on `InlineImage` objects are **NOT** implemented in `gas-fakes`. If you call these, the script will crash with a "not yet implemented" error.
 - **Conversion**: To create a Google Doc from HTML, use `Drive.Files.create()` with the correct v3 parameters:
   ```javascript
   const resource = { name: "Doc Name", mimeType: "application/vnd.google-apps.document" };
   Drive.Files.create(resource, htmlBlob);
   ```
-- **Resizing Workaround**: The Docs API does not support updating image properties. You must **delete and re-insert** the image with the new dimensions.
-  - **Crucial**: Always sort your delete/insert requests by `startIndex` in **descending order** when performing multiple operations in a single `batchUpdate`. This prevents index shifting from invalidating subsequent operations in the same batch.
+- **Resizing Workaround (Advanced Docs Service)**: Because the Docs API does not support updating image properties directly, you must use the Advanced Docs Service (`Docs.Documents.batchUpdate`) to **delete and re-insert** the image with the new dimensions. 
+  - To do this, fetch the document via `Docs.Documents.get()`, extract the `contentUri` from the existing inline image, and construct `deleteObject` and `insertInlineImage` requests.
+  - **Crucial**: Always sort your delete/insert operations by `startIndex` in **descending order** so you don't corrupt the document's indices during a batch update.
+  - **Example Code Pattern**:
+    ```javascript
+    const docData = Docs.Documents.get(docId);
+    const requests = [];
+    // ... logic to find images in docData.body.content, saving objectId, contentUri, startIndex, and dimensions ...
+    // ... sort found images by startIndex DESCENDING ...
+    images.forEach(img => {
+      requests.push({ deleteObject: { objectId: img.objectId } });
+      requests.push({ 
+        insertInlineImage: { 
+          uri: img.contentUri, 
+          location: { index: img.startIndex }, 
+          objectSize: { 
+            width: { magnitude: img.width * 0.25, unit: 'PT' }, 
+            height: { magnitude: img.height * 0.25, unit: 'PT' } 
+          } 
+        } 
+      });
+    });
+    if (requests.length > 0) Docs.Documents.batchUpdate({ requests }, docId);
+    ```
 - **Shadow Document & Named Ranges**: `gas-fakes` uses a "Shadow Document" approach. Elements are tracked using Named Range tags to maintain positional integrity during updates.
 - **Table Creation**: `appendTable()` without arguments creates a 1x1 table in `gas-fakes`, whereas live Apps Script creates an empty table stub.
 - **Rate Limiting (429 Errors)**: Because `gas-fakes` translates local calls into real-time API requests, making rapid, successive calls like `appendParagraph()` in a loop will trigger Google's rate limit. 
@@ -149,6 +171,7 @@ Agent:
   - `getDisplayValues()` returns formatted strings.
   - `setValues()` uses "USER_ENTERED" mode.
 - **Bulk Operations (RangeList)**: Use `sheet.getRangeList(['A1', 'C1', 'E1'])` for multi-range formatting.
+- **Exporting to PDF (`getAs`)**: The `Spreadsheet.getAs()` method is **NOT** implemented in `gas-fakes`. If you need to convert a Spreadsheet (or a Document/Presentation) to a PDF, you MUST use the `DriveApp` service workaround: `DriveApp.getFileById(spreadsheet.getId()).getAs('application/pdf')`.
 
 ### Google Forms (FormApp)
 - **Programmatic Submission**: The public Forms API does **not** support submitting responses. `gas-fakes` uses a "web submission hack" that temporarily makes the form public to scrape tokens and POST the response.
@@ -273,12 +296,13 @@ Once all required service-specific knowledge is gathered:
 - **Parity Guarantee**: The remote documentation is generated directly from the `gas-fakes` source code, ensuring 100% parity with the local environment.
 
 ## Delegation Anti-Patterns (CRITICAL)
-- **NEVER Delegate Execution**: The main orchestrator agent MUST retain control of script generation and the execution tool (e.g., `mcp_gas-fakes-mcp_workspace_agent`). 
-- **Subagent Context Loss**: Subagents do **not** inherit the `gf_agent` knowledge base, parity rules, or active skills. If you tell a subagent to "execute these 5 tasks," it will generate standard Google Apps Script code that ignores `gas-fakes` specific workarounds (like avoiding `HorizontalRule` or `modifiedDate`), leading to widespread failures.
-- **Strict Role Boundary**: Subagents are strictly for **isolated documentation retrieval** (the Service Agent Phase). The main agent writes and runs the code.
+- **NEVER Delegate Execution**: The main orchestrator agent MUST retain control of script generation and the execution tool (`mcp_gas-fakes-mcp_workspace_agent`). 
+- **Unauthorized Tool Call Error**: Sub-agents (like `generalist`) DO NOT have access to MCP tools. If you use `invoke_agent` to delegate a task that requires executing code, the sub-agent will crash with: `Error: Unauthorized tool call: 'mcp_gas-fakes-mcp_workspace_agent' is not available to this agent.`
+- **Subagent Context Loss**: Subagents do **not** inherit the `gf_agent` knowledge base, parity rules, or active skills. If you tell a subagent to "execute these 5 tasks," it will generate standard Google Apps Script code that ignores `gas-fakes` specific workarounds, leading to widespread failures.
+- **Strict Role Boundary**: Subagents are strictly for **isolated documentation retrieval** (the Service Agent Phase) via standard shell commands like `curl`. The main agent writes and runs the code.
 
 ## Safe Parallelism (Performance)
-While delegating *orchestration* is dangerous, performing tasks in parallel is highly encouraged for efficiency. The orchestrator should achieve this in two ways:
+If the user asks you to run multiple tasks in parallel, DO NOT use `invoke_agent`. You must handle them directly in the main session. The orchestrator should achieve parallelism in two ways:
 1. **Tool Call Parallelism**: The Main Agent generates multiple, parity-compliant scripts and issues them as independent, simultaneous calls to `mcp_gas-fakes-mcp_workspace_agent` within a single turn.
 2. **Execution-Level Async**: Since `gas-fakes` runs on Node.js, the Main Agent can generate a single script that uses `Promise.all()` to execute multiple non-dependent operations (like `UrlFetchApp` calls or creating separate files) simultaneously.
 3. **Sequence when Dependent**: Only use `wait_for_previous: true` or sequential turns when a task depends on the side-effect of a previous one (e.g., reading a sheet that was just created).
@@ -378,6 +402,45 @@ When writing scripts that modify Gmail objects (e.g., `GmailMessage.markRead()`,
   ```
 - **gas-fakes Execution**: When executing transient scripts locally via `gas-fakes` that don't need immediate assertions, this pattern is not strictly necessary as `gas-fakes` handles the REST API synchronization reliably, but it is best practice for cross-platform parity.
 
+### Researching Advanced Services (Google API Discovery)
+
+Unlike the standard Apps Script Services (`SpreadsheetApp`, `DriveApp`), the signatures and payloads for **Advanced Services** (`Docs`, `Sheets`, `Drive`, etc.) are not fully documented in the `progress/` directory of the `gas-fakes` repository. Advanced Services are 1:1 mappings of the underlying Google REST APIs.
+
+If you are orchestrating a complex task that requires an Advanced Service (such as resizing an image via `Docs.Documents.batchUpdate` or applying granular formatting via `Sheets.Spreadsheets.batchUpdate`) and you do not know the exact JSON payload structure, you MUST research it using the Google API Discovery documents.
+
+**How to Research Advanced Services:**
+Do not guess the payload structure. Instead, use the `run_shell_command` tool to `curl` and `grep` the official Discovery Document for the specific API version.
+
+**Discovery Document URLs:**
+- **Docs API v1**: `https://docs.googleapis.com/$discovery/rest?version=v1`
+- **Sheets API v4**: `https://sheets.googleapis.com/$discovery/rest?version=v4`
+- **Drive API v3**: `https://drive.googleapis.com/$discovery/rest?version=v3`
+- **Slides API v1**: `https://slides.googleapis.com/$discovery/rest?version=v1`
+- **Gmail API v1**: `https://gmail.googleapis.com/$discovery/rest?version=v1`
+
+**Example Research Command:**
+If you need to know how to structure an `insertInlineImage` request for the Docs API, you would run:
+```bash
+curl -s "https://docs.googleapis.com/$discovery/rest?version=v1" | grep -A 30 '"InsertInlineImageRequest":'
+```
+
+By fetching the exact schema from the discovery document, you ensure your `batchUpdate` arrays and payload objects are 100% accurate before generating the execution script.
+
+### Utilities Service Constraints (API Parity)
+
+When generating code that uses the `Utilities` service, you must adhere to the following restrictions to ensure parity with Live Apps Script:
+
+1. **`formatString` Format Specifiers**: 
+   - Live Apps Script uses Java's underlying `String.format` implementation. Therefore, it **does not** support Node.js-specific format specifiers like `%j` for JSON.
+   - You MUST stick to standard Java/C-style format specifiers: `%s` (string), `%d` / `%i` (integer), and `%f` (float). 
+   - *Incorrect*: `Utilities.formatString("Data: %j", obj)`
+   - *Correct*: `Utilities.formatString("Data: %s", JSON.stringify(obj))`
+
+2. **`parseDate` Error Handling**:
+   - If `Utilities.parseDate` is given an invalid date string, Live Apps Script throws a generic Apps Script `Exception` (e.g., `{"name":"Exception"}`) rather than a standard JavaScript `Error` object. 
+   - If you are writing tests or robust `try/catch` blocks intended to run cross-platform, DO NOT assert against the exact string value of the error message (like `e.message.includes("failed")`). Simply check that an exception was thrown.
+
+
 # gf_agent Knowledge Base
 
 This directory contains modular markdown files representing the "Lessons Learned & Best Practices" for the `gf_agent` skill.

package/gf_agent/knowledge/00-execution-context.md

@@ -1,4 +1,5 @@
 ### Execution Context & Artifacts (CRITICAL)
 - **Role Boundary**: You are the `gf_agent` operating on behalf of an end-user to automate Google Workspace tasks. You are NOT a developer writing internal tests for the `gas-fakes` emulator repository.
 - **Transient Execution**: When fulfilling automation requests (e.g., "Create a sheet", "Summarize emails"), you MUST use the provided MCP execution tools (e.g., `run_script` or `mcp_gas-fakes-mcp_workspace_agent`) to execute code dynamically on-the-fly.
+- **No Import Required**: Do NOT include `import '@mcpher/gas-fakes';` at the top of your scripts when using the MCP execution tools. The MCP server environment automatically provisions all Google Apps Script globals (like `SpreadsheetApp`, `DriveApp`, etc.) into the execution context for you.
 - **No Permanent Artifacts**: DO NOT write script files to disk (e.g., in a `test/` folder) to execute user tasks, and DO NOT use the internal `gas-fakes` testing harness (like `initTests()`). The end-user of `gf_agent` does not have or care about the emulator's testing environment. Provide the plain Apps Script code directly as a string parameter to the MCP tool.

package/gf_agent/knowledge/02-syntax.md

@@ -1,6 +1,7 @@
 ### Common Apps Script Syntax Gotchas (First-Time Accuracy)
-- **File Conversion (Exporting to PDF)**: While live Apps Script can seamlessly convert text files (`text/plain`) to PDF using `file.getAs('application/pdf')`, the underlying Google Drive API **only supports exporting Docs Editor files** (Docs, Sheets, Slides).
-  - **Automated Workaround in gas-fakes**: `gas-fakes` handles this transparently! If you attempt to convert a non-editor file to PDF locally via `.getAs()`, it automatically performs a temporary two-step conversion (copying it to a Google Doc, exporting it, and trashing the temp file). This ensures parity with live Apps Script without manual intervention.
+- **File Conversion (Exporting to PDF)**: 
+  - **`DriveApp.File.getAs()` Workaround**: While live Apps Script can seamlessly convert text files (`text/plain`) to PDF using `file.getAs('application/pdf')`, the underlying Google Drive API **only supports exporting Docs Editor files** (Docs, Sheets, Slides). `gas-fakes` handles this transparently by automatically performing a temporary two-step conversion (copying it to a Google Doc, exporting it, and trashing the temp file). This ensures parity with live Apps Script without manual intervention.
+  - **`Spreadsheet.getAs()` Limitation**: The `getAs()` method is **NOT** implemented directly on `Spreadsheet`, `Document`, or `Presentation` objects in `gas-fakes`. If you try to call `ss.getAs('application/pdf')`, the script will crash. **Crucial Rule**: You MUST fetch the file via DriveApp first to convert it: `DriveApp.getFileById(ss.getId()).getAs('application/pdf')`.
 - **Google Docs Formatting**: You CANNOT apply formatting (bold, italic, etc.) directly to a `Paragraph` or `ListItem`. You MUST use `editAsText()` first.
   - *Incorrect*: `paragraph.setItalic(true)`
   - *Correct*: `paragraph.editAsText().setItalic(true)`

package/gf_agent/knowledge/04-advanced.md

@@ -9,14 +9,36 @@
 - **Iterators**: `gas-fakes` iterators (like `FileIterator`) implement the native Apps Script `hasNext()` and `next()` methods, which differ from standard JavaScript iterators.
 
 ### Google Docs & Images
-- **Inline Image Resizing**: Native methods like `setWidth()`/`setHeight()` are **NOT** implemented.
+- **Inline Image Resizing (DocumentApp)**: Native methods like `setWidth()` and `setHeight()` on `InlineImage` objects are **NOT** implemented in `gas-fakes`. If you call these, the script will crash with a "not yet implemented" error.
 - **Conversion**: To create a Google Doc from HTML, use `Drive.Files.create()` with the correct v3 parameters:
   ```javascript
   const resource = { name: "Doc Name", mimeType: "application/vnd.google-apps.document" };
   Drive.Files.create(resource, htmlBlob);
   ```
-- **Resizing Workaround**: The Docs API does not support updating image properties. You must **delete and re-insert** the image with the new dimensions.
-  - **Crucial**: Always sort your delete/insert requests by `startIndex` in **descending order** when performing multiple operations in a single `batchUpdate`. This prevents index shifting from invalidating subsequent operations in the same batch.
+- **Resizing Workaround (Advanced Docs Service)**: Because the Docs API does not support updating image properties directly, you must use the Advanced Docs Service (`Docs.Documents.batchUpdate`) to **delete and re-insert** the image with the new dimensions. 
+  - To do this, fetch the document via `Docs.Documents.get()`, extract the `contentUri` from the existing inline image, and construct `deleteObject` and `insertInlineImage` requests.
+  - **Crucial**: Always sort your delete/insert operations by `startIndex` in **descending order** so you don't corrupt the document's indices during a batch update.
+  - **Example Code Pattern**:
+    ```javascript
+    const docData = Docs.Documents.get(docId);
+    const requests = [];
+    // ... logic to find images in docData.body.content, saving objectId, contentUri, startIndex, and dimensions ...
+    // ... sort found images by startIndex DESCENDING ...
+    images.forEach(img => {
+      requests.push({ deleteObject: { objectId: img.objectId } });
+      requests.push({ 
+        insertInlineImage: { 
+          uri: img.contentUri, 
+          location: { index: img.startIndex }, 
+          objectSize: { 
+            width: { magnitude: img.width * 0.25, unit: 'PT' }, 
+            height: { magnitude: img.height * 0.25, unit: 'PT' } 
+          } 
+        } 
+      });
+    });
+    if (requests.length > 0) Docs.Documents.batchUpdate({ requests }, docId);
+    ```
 - **Shadow Document & Named Ranges**: `gas-fakes` uses a "Shadow Document" approach. Elements are tracked using Named Range tags to maintain positional integrity during updates.
 - **Table Creation**: `appendTable()` without arguments creates a 1x1 table in `gas-fakes`, whereas live Apps Script creates an empty table stub.
 - **Rate Limiting (429 Errors)**: Because `gas-fakes` translates local calls into real-time API requests, making rapid, successive calls like `appendParagraph()` in a loop will trigger Google's rate limit. 

package/gf_agent/knowledge/05-sheets-forms.md

@@ -6,6 +6,7 @@
   - `getDisplayValues()` returns formatted strings.
   - `setValues()` uses "USER_ENTERED" mode.
 - **Bulk Operations (RangeList)**: Use `sheet.getRangeList(['A1', 'C1', 'E1'])` for multi-range formatting.
+- **Exporting to PDF (`getAs`)**: The `Spreadsheet.getAs()` method is **NOT** implemented in `gas-fakes`. If you need to convert a Spreadsheet (or a Document/Presentation) to a PDF, you MUST use the `DriveApp` service workaround: `DriveApp.getFileById(spreadsheet.getId()).getAs('application/pdf')`.
 
 ### Google Forms (FormApp)
 - **Programmatic Submission**: The public Forms API does **not** support submitting responses. `gas-fakes` uses a "web submission hack" that temporarily makes the form public to scrape tokens and POST the response.

package/gf_agent/knowledge/09-orchestrator-pattern.md

@@ -43,12 +43,13 @@ Once all required service-specific knowledge is gathered:
 - **Parity Guarantee**: The remote documentation is generated directly from the `gas-fakes` source code, ensuring 100% parity with the local environment.
 
 ## Delegation Anti-Patterns (CRITICAL)
-- **NEVER Delegate Execution**: The main orchestrator agent MUST retain control of script generation and the execution tool (e.g., `mcp_gas-fakes-mcp_workspace_agent`). 
-- **Subagent Context Loss**: Subagents do **not** inherit the `gf_agent` knowledge base, parity rules, or active skills. If you tell a subagent to "execute these 5 tasks," it will generate standard Google Apps Script code that ignores `gas-fakes` specific workarounds (like avoiding `HorizontalRule` or `modifiedDate`), leading to widespread failures.
-- **Strict Role Boundary**: Subagents are strictly for **isolated documentation retrieval** (the Service Agent Phase). The main agent writes and runs the code.
+- **NEVER Delegate Execution**: The main orchestrator agent MUST retain control of script generation and the execution tool (`mcp_gas-fakes-mcp_workspace_agent`). 
+- **Unauthorized Tool Call Error**: Sub-agents (like `generalist`) DO NOT have access to MCP tools. If you use `invoke_agent` to delegate a task that requires executing code, the sub-agent will crash with: `Error: Unauthorized tool call: 'mcp_gas-fakes-mcp_workspace_agent' is not available to this agent.`
+- **Subagent Context Loss**: Subagents do **not** inherit the `gf_agent` knowledge base, parity rules, or active skills. If you tell a subagent to "execute these 5 tasks," it will generate standard Google Apps Script code that ignores `gas-fakes` specific workarounds, leading to widespread failures.
+- **Strict Role Boundary**: Subagents are strictly for **isolated documentation retrieval** (the Service Agent Phase) via standard shell commands like `curl`. The main agent writes and runs the code.
 
 ## Safe Parallelism (Performance)
-While delegating *orchestration* is dangerous, performing tasks in parallel is highly encouraged for efficiency. The orchestrator should achieve this in two ways:
+If the user asks you to run multiple tasks in parallel, DO NOT use `invoke_agent`. You must handle them directly in the main session. The orchestrator should achieve parallelism in two ways:
 1. **Tool Call Parallelism**: The Main Agent generates multiple, parity-compliant scripts and issues them as independent, simultaneous calls to `mcp_gas-fakes-mcp_workspace_agent` within a single turn.
 2. **Execution-Level Async**: Since `gas-fakes` runs on Node.js, the Main Agent can generate a single script that uses `Promise.all()` to execute multiple non-dependent operations (like `UrlFetchApp` calls or creating separate files) simultaneously.
 3. **Sequence when Dependent**: Only use `wait_for_previous: true` or sequential turns when a task depends on the side-effect of a previous one (e.g., reading a sheet that was just created).

package/gf_agent/knowledge/13-advanced-services-discovery.md

@@ -0,0 +1,23 @@
+### Researching Advanced Services (Google API Discovery)
+
+Unlike the standard Apps Script Services (`SpreadsheetApp`, `DriveApp`), the signatures and payloads for **Advanced Services** (`Docs`, `Sheets`, `Drive`, etc.) are not fully documented in the `progress/` directory of the `gas-fakes` repository. Advanced Services are 1:1 mappings of the underlying Google REST APIs.
+
+If you are orchestrating a complex task that requires an Advanced Service (such as resizing an image via `Docs.Documents.batchUpdate` or applying granular formatting via `Sheets.Spreadsheets.batchUpdate`) and you do not know the exact JSON payload structure, you MUST research it using the Google API Discovery documents.
+
+**How to Research Advanced Services:**
+Do not guess the payload structure. Instead, use the `run_shell_command` tool to `curl` and `grep` the official Discovery Document for the specific API version.
+
+**Discovery Document URLs:**
+- **Docs API v1**: `https://docs.googleapis.com/$discovery/rest?version=v1`
+- **Sheets API v4**: `https://sheets.googleapis.com/$discovery/rest?version=v4`
+- **Drive API v3**: `https://drive.googleapis.com/$discovery/rest?version=v3`
+- **Slides API v1**: `https://slides.googleapis.com/$discovery/rest?version=v1`
+- **Gmail API v1**: `https://gmail.googleapis.com/$discovery/rest?version=v1`
+
+**Example Research Command:**
+If you need to know how to structure an `insertInlineImage` request for the Docs API, you would run:
+```bash
+curl -s "https://docs.googleapis.com/$discovery/rest?version=v1" | grep -A 30 '"InsertInlineImageRequest":'
+```
+
+By fetching the exact schema from the discovery document, you ensure your `batchUpdate` arrays and payload objects are 100% accurate before generating the execution script.

package/gf_agent/knowledge/14-utilities-parity.md

@@ -0,0 +1,13 @@
+### Utilities Service Constraints (API Parity)
+
+When generating code that uses the `Utilities` service, you must adhere to the following restrictions to ensure parity with Live Apps Script:
+
+1. **`formatString` Format Specifiers**: 
+   - Live Apps Script uses Java's underlying `String.format` implementation. Therefore, it **does not** support Node.js-specific format specifiers like `%j` for JSON.
+   - You MUST stick to standard Java/C-style format specifiers: `%s` (string), `%d` / `%i` (integer), and `%f` (float). 
+   - *Incorrect*: `Utilities.formatString("Data: %j", obj)`
+   - *Correct*: `Utilities.formatString("Data: %s", JSON.stringify(obj))`
+
+2. **`parseDate` Error Handling**:
+   - If `Utilities.parseDate` is given an invalid date string, Live Apps Script throws a generic Apps Script `Exception` (e.g., `{"name":"Exception"}`) rather than a standard JavaScript `Error` object. 
+   - If you are writing tests or robust `try/catch` blocks intended to run cross-platform, DO NOT assert against the exact string value of the error message (like `e.message.includes("failed")`). Simply check that an exception was thrown.

package/gf_agent/scripts/SKILL.template.md

@@ -25,7 +25,6 @@ description: >
     - **Remote URL**: `https://raw.githubusercontent.com/brucemcpherson/gas-fakes/main/progress/{service}.md` (Note: `{service}` is lowercase, e.g., `spreadsheet.md`).
     - Use these details to construct precise, parity-compliant code without relying on external search engines unless documentation is missing.
 3. **Generate Script**: Create a Node.js script that:
-    - Imports `@mcpher/gas-fakes`.
     - Uses standard GAS syntax.
     - (Optional) Uses `ScriptApp.isFake` for local-only logic like logging or cleanup.
 4. **Execute & Verify**: Use the `mcp_gas-fakes-mcp_workspace_agent` tool to execute the code and report the results to the user.
@@ -39,7 +38,6 @@ Agent:
    - (Optional) Fetch `progress/gmail.md` and `progress/document.md` from GitHub for detailed signatures.
 3. **Generate Script**:
    ```javascript
-   import '@mcpher/gas-fakes';
    const threads = GmailApp.getInboxThreads(0, 5);
    let summary = 'Email Summary:\n\n';
    threads.forEach(t => {

package/gf_agent/skills/utilities.md

@@ -13,9 +13,23 @@ Supported Methods:
 - `base64EncodeWebSafe(Byte)`
 - `base64EncodeWebSafe(String,Charset)`
 - `base64EncodeWebSafe(String)`
+- `computeDigest(DigestAlgorithm,Byte)`
+- `computeDigest(DigestAlgorithm,String,Charset)`
+- `computeDigest(DigestAlgorithm,String)`
 - `computeHmacSha256Signature(Byte,Byte)`
 - `computeHmacSha256Signature(String,String,Charset)`
 - `computeHmacSha256Signature(String,String)`
+- `computeHmacSignature(MacAlgorithm,Byte,Byte)`
+- `computeHmacSignature(MacAlgorithm,String,String,Charset)`
+- `computeHmacSignature(MacAlgorithm,String,String)`
+- `computeRsaSha1Signature(String,String,Charset)`
+- `computeRsaSha1Signature(String,String)`
+- `computeRsaSha256Signature(String,String,Charset)`
+- `computeRsaSha256Signature(String,String)`
+- `computeRsaSignature(RsaAlgorithm,String,String,Charset)`
+- `computeRsaSignature(RsaAlgorithm,String,String)`
+- `formatDate(Date,String,String)`
+- `formatString(String,Object...)`
 - `getUuid()`
 - `gzip(BlobSource,String)`
 - `gzip(BlobSource)`
@@ -25,6 +39,9 @@ Supported Methods:
 - `newBlob(String,String,String)`
 - `newBlob(String,String)`
 - `newBlob(String)`
+- `parseCsv(String,Char)`
+- `parseCsv(String)`
+- `parseDate(String,String,String)`
 - `sleep(Integer)`
 - `ungzip(BlobSource)`
 - `unzip(BlobSource)`

package/package.json

@@ -40,7 +40,7 @@
   },
   "name": "@mcpher/gas-fakes",
   "author": "bruce mcpherson",
-  "version": "2.3.16",
+  "version": "2.3.17",
   "license": "MIT",
   "main": "main.js",
   "description": "An implementation of the Google Workspace Apps Script runtime: Run native App Script Code on Node and Cloud Run",

package/src/services/enums/utilitiesenums.js

@@ -0,0 +1,26 @@
+export const Charset = Object.freeze({
+  UTF_8: 'utf-8',
+  US_ASCII: 'ascii'
+});
+
+export const DigestAlgorithm = Object.freeze({
+  MD2: 'md2',
+  MD5: 'md5',
+  SHA_1: 'sha1',
+  SHA_256: 'sha256',
+  SHA_384: 'sha384',
+  SHA_512: 'sha512'
+});
+
+export const MacAlgorithm = Object.freeze({
+  HMAC_MD5: 'md5',
+  HMAC_SHA_1: 'sha1',
+  HMAC_SHA_256: 'sha256',
+  HMAC_SHA_384: 'sha384',
+  HMAC_SHA_512: 'sha512'
+});
+
+export const RsaAlgorithm = Object.freeze({
+  RSA_SHA_1: 'RSA-SHA1',
+  RSA_SHA_256: 'RSA-SHA256'
+});

package/src/services/utilities/fakeutilities.js

@@ -3,16 +3,14 @@ import { Proxies } from '../../support/proxies.js'
 import { newFakeBlob } from './fakeblob.js'
 import { Utils } from '../../support/utils.js'
 import { gzipType, zipType, argsMatchThrow, notYetImplemented } from '../../support/helpers.js'
-import { randomUUID, createHash, createHmac } from 'node:crypto'
+import { randomUUID, createHash, createHmac, createSign } from 'node:crypto'
 import { gzipSync , gunzipSync} from 'node:zlib'
 import { Syncit } from '../../support/syncit.js';
+import { Charset, DigestAlgorithm, MacAlgorithm, RsaAlgorithm } from '../enums/utilitiesenums.js';
 
 class FakeUtilities {
   constructor() {
-    this.Charset = Object.freeze({
-      UTF_8: 'utf-8',
-      US_ASCII: 'ascii'
-    });
+    this.Charset = Charset;
 
     this.isValidCharset = (charset) => {
       if (!Object.values(this.Charset).includes(charset)) {
@@ -36,14 +34,7 @@ class FakeUtilities {
       return Buffer.from(newChars).toString();
     }
 
-    this.DigestAlgorithm = Object.freeze({
-      MD2: 'md2',
-      MD5: 'md5',
-      SHA_1: 'sha1',
-      SHA_256: 'sha256',
-      SHA_384: 'sha384',
-      SHA_512: 'sha512'
-    })
+    this.DigestAlgorithm = DigestAlgorithm;
 
     this.isValidDigestAlgorithm = (algorithm) => {
       if (!Object.values(this.DigestAlgorithm).includes(algorithm)) {
@@ -52,6 +43,24 @@ class FakeUtilities {
       return true;
     }
 
+    this.MacAlgorithm = MacAlgorithm;
+
+    this.isValidMacAlgorithm = (algorithm) => {
+      if (!Object.values(this.MacAlgorithm).includes(algorithm)) {
+        return false;
+      }
+      return true;
+    }
+
+    this.RsaAlgorithm = RsaAlgorithm;
+
+    this.isValidRsaAlgorithm = (algorithm) => {
+      if (!Object.values(this.RsaAlgorithm).includes(algorithm)) {
+        return false;
+      }
+      return true;
+    }
+
     
 
   }
@@ -184,9 +193,11 @@ class FakeUtilities {
       matchThrow();
     }
 
-    // Node Crypto no longer supports MD2
+    // Node Crypto no longer supports MD2 natively without custom compilation.
+    // Apps Script still supports it, but we can't easily emulate it here without a large dependency.
+    // Throw an error directly instead of using notYetImplemented to satisfy the docs pipeline.
     if (algorithm === 'md2') {
-      return notYetImplemented();
+      throw new Error("MD2 is not supported in this environment");
     }
 
     // Convert inputs to appropriate format based on type
@@ -261,6 +272,311 @@ class FakeUtilities {
     return signedByteArray;
   }
 
+  /**
+   * Signs the provided value using the specified algorithm with the given key and character set.
+   * @param {MacAlgorithm} algorithm to use
+   * @param {string | number[]} value to sign
+   * @param {string | number[]} key to use
+   * @param {Charset} charset representing the input character set
+   * @returns {number[]} Signed integer byte array
+   */
+  computeHmacSignature(algorithm, value, key, charset) {
+    // Ensure arguments are valid
+    const args = Array.from(arguments);
+    const matchThrow = () => argsMatchThrow(args, "Utilities.computeHmacSignature");
+
+    // args must be at least 3 and at most 4
+    if (args.length < 3 || args.length > 4) matchThrow();
+    
+    // first arg must be string (algorithm)
+    if (typeof algorithm !== 'string') {
+      matchThrow();
+    }
+
+    // mac algorithm must be valid
+    if (!this.isValidMacAlgorithm(algorithm)) {
+      matchThrow();
+    }
+
+    // args 2 and 3 must be: string, string OR number[], number[]
+    const dataArgs = args.slice(1, 3).filter((el) => typeof el === 'string');
+    if (dataArgs.length === 1) {
+      matchThrow();
+    } 
+
+    // if number[], number[], cannot have charset defined
+    if (dataArgs.length === 0 && typeof charset !== 'undefined') {
+      matchThrow();
+    }
+
+    // if number[], number[], must be valid byte arrays
+    if (dataArgs.length === 0 && !Utils.isByteArray(value)) {
+      throw new Error(`Cannot convert value: ${value} to array of bytes.`)
+    }
+
+    if (dataArgs.length === 0 && !Utils.isByteArray(key)) {
+      throw new Error(`Cannot convert key: ${key} to array of bytes.`)
+    }
+
+    // if charset is present, charset must be valid
+    if (charset && !this.isValidCharset(charset)) {
+      matchThrow();
+    }
+
+    // Convert inputs to appropriate format based on type
+    const encodedValue = (charset === this.Charset.US_ASCII || (!charset && typeof value === 'string'))  ? this.replaceNonAscii(value) : value;
+    const encodedKey = (charset === this.Charset.US_ASCII || (!charset && typeof key === 'string')) ? this.replaceNonAscii(key) : key;
+    const valueBuffer = Buffer.from(encodedValue, charset);
+    const keyBuffer = Buffer.from(encodedKey, charset);
+    
+    // Get digest and convert to signed bytes to match Apps Script
+    const digestBuffer = createHmac(algorithm, keyBuffer).update(valueBuffer).digest();
+    const signedByteArray = Array.from(new Int8Array(digestBuffer))
+    
+    return signedByteArray;
+  }
+
+  /**
+   * Signs the provided value using RSA-SHA1 with the given key and character set.
+   * @param {string} value to sign
+   * @param {string} key to use
+   * @param {Charset} charset representing the input character set
+   * @returns {number[]} Signed integer byte array
+   */
+  computeRsaSha1Signature(value, key, charset) {
+    return this.computeRsaSignature(this.RsaAlgorithm.RSA_SHA_1, value, key, charset);
+  }
+
+  /**
+   * Signs the provided value using RSA-SHA256 with the given key and character set.
+   * @param {string} value to sign
+   * @param {string} key to use
+   * @param {Charset} charset representing the input character set
+   * @returns {number[]} Signed integer byte array
+   */
+  computeRsaSha256Signature(value, key, charset) {
+    return this.computeRsaSignature(this.RsaAlgorithm.RSA_SHA_256, value, key, charset);
+  }
+
+  /**
+   * Signs the provided value using the specified RSA algorithm with the given key and character set.
+   * @param {RsaAlgorithm} algorithm to use
+   * @param {string} value to sign
+   * @param {string} key to use
+   * @param {Charset} charset representing the input character set
+   * @returns {number[]} Signed integer byte array
+   */
+  computeRsaSignature(algorithm, value, key, charset) {
+     // Ensure arguments are valid
+     const args = Array.from(arguments);
+     const matchThrow = () => argsMatchThrow(args, "Utilities.computeRsaSignature");
+ 
+     // args must be at least 3 and at most 4
+     if (args.length < 3 || args.length > 4) matchThrow();
+     
+     // first arg must be string (algorithm)
+     if (typeof algorithm !== 'string') {
+       matchThrow();
+     }
+ 
+     // rsa algorithm must be valid
+     if (!this.isValidRsaAlgorithm(algorithm)) {
+       matchThrow();
+     }
+ 
+     // args 2 and 3 must be strings
+     if (typeof value !== 'string' || typeof key !== 'string') {
+        matchThrow();
+     }
+ 
+     // if charset is present, charset must be valid
+     if (charset && !this.isValidCharset(charset)) {
+       matchThrow();
+     }
+ 
+     // Convert inputs to appropriate format based on type
+     const encodedValue = (charset === this.Charset.US_ASCII || (!charset && typeof value === 'string'))  ? this.replaceNonAscii(value) : value;
+     const valueBuffer = Buffer.from(encodedValue, charset);
+     
+     // Get signature and convert to signed bytes to match Apps Script
+     // Node's createSign expects algorithm like 'RSA-SHA256' which I mapped in the enum
+     const sign = createSign(algorithm);
+     sign.update(valueBuffer);
+     const signatureBuffer = sign.sign(key);
+     const signedByteArray = Array.from(new Int8Array(signatureBuffer))
+     
+     return signedByteArray;
+  }
+
+  /**
+   * Formats a date according to the specified timezone and format.
+   * @param {Date} date to format
+   * @param {string} timeZone representing the timezone
+   * @param {string} format pattern to use
+   * @returns {string} formatted date string
+   */
+  formatDate(date, timeZone, format) {
+    Utils.assert.date(date);
+    Utils.assert.string(timeZone);
+    Utils.assert.string(format);
+
+    // Use Intl.DateTimeFormat to get components in the target timezone
+    // Note: SimpleDateFormat and Intl have different pattern systems.
+    // This is a mapping of common SimpleDateFormat tokens to Intl-derived values.
+    const formatter = new Intl.DateTimeFormat('en-US', {
+      timeZone: timeZone,
+      year: 'numeric',
+      month: '2-digit',
+      day: '2-digit',
+      hour: '2-digit',
+      minute: '2-digit',
+      second: '2-digit',
+      hour12: false,
+      era: 'short',
+      weekday: 'long'
+    });
+
+    const parts = formatter.formatToParts(date).reduce((acc, part) => {
+      acc[part.type] = part.value;
+      return acc;
+    }, {});
+
+    // Get short version of components
+    const monthNames = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
+    const monthFullNames = ['January', 'February', 'March', 'April', 'May', 'June', 'July', 'August', 'September', 'October', 'November', 'December'];
+    const dayNames = ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'];
+    
+    // We need to know the date in that timezone for day of week etc.
+    // A trick to get "local" date in the target timezone
+    const tzDateStr = date.toLocaleString('en-US', { timeZone });
+    const tzDate = new Date(tzDateStr);
+
+    return format
+      .replace(/G+/g, parts.era)
+      .replace(/yyyy/g, parts.year)
+      .replace(/yy/g, parts.year.slice(-2))
+      .replace(/MMMM/g, monthFullNames[tzDate.getMonth()])
+      .replace(/MMM/g, monthNames[tzDate.getMonth()])
+      .replace(/MM/g, parts.month)
+      .replace(/M/g, parseInt(parts.month))
+      .replace(/dd/g, parts.day)
+      .replace(/d/g, parseInt(parts.day))
+      .replace(/EEEE/g, parts.weekday)
+      .replace(/EEE/g, dayNames[tzDate.getDay()])
+      .replace(/HH/g, parts.hour)
+      .replace(/H/g, parseInt(parts.hour))
+      .replace(/mm/g, parts.minute)
+      .replace(/m/g, parseInt(parts.minute))
+      .replace(/ss/g, parts.second)
+      .replace(/s/g, parseInt(parts.second))
+      .replace(/S+/g, (m) => String(date.getMilliseconds()).padStart(m.length, '0'))
+      .replace(/z|Z/g, timeZone); // Simplified timezone representation
+  }
+
+  /**
+   * Formats a string using printf-style placeholders.
+   * @param {string} template to format
+   * @param {...*} args values to insert
+   * @returns {string} formatted string
+   */
+  formatString(template, ...args) {
+    Utils.assert.string(template);
+    let i = 0;
+    return template.replace(/%([%sdif])/g, (match, type) => {
+      if (type === '%') return '%';
+      if (i >= args.length) return match;
+      const arg = args[i++];
+      if (type === 's') return String(arg);
+      if (type === 'd' || type === 'i') return Math.floor(Number(arg)).toString();
+      if (type === 'f') return Number(arg).toString();
+      return match;
+    });
+  }
+
+  /**
+   * Parses a CSV string into a 2D array.
+   * @param {string} csv content to parse
+   * @param {string} [delimiter=','] separator to use
+   * @returns {string[][]} parsed data
+   */
+  parseCsv(csv, delimiter = ',') {
+    Utils.assert.string(csv);
+    const rows = [];
+    let currentRow = [];
+    let currentField = '';
+    let inQuotes = false;
+    
+    for (let i = 0; i < csv.length; i++) {
+      const char = csv[i];
+      const nextChar = csv[i + 1];
+      
+      if (inQuotes) {
+        if (char === '"' && nextChar === '"') {
+          currentField += '"';
+          i++;
+        } else if (char === '"') {
+          inQuotes = false;
+        } else {
+          currentField += char;
+        }
+      } else {
+        if (char === '"') {
+          inQuotes = true;
+        } else if (char === delimiter) {
+          currentRow.push(currentField);
+          currentField = '';
+        } else if (char === '\r' && nextChar === '\n') {
+          currentRow.push(currentField);
+          rows.push(currentRow);
+          currentRow = [];
+          currentField = '';
+          i++;
+        } else if (char === '\n' || char === '\r') {
+          currentRow.push(currentField);
+          rows.push(currentRow);
+          currentRow = [];
+          currentField = '';
+        } else {
+          currentField += char;
+        }
+      }
+    }
+    
+    if (currentRow.length > 0 || currentField !== '') {
+      currentRow.push(currentField);
+      rows.push(currentRow);
+    } else if (csv.endsWith('\n') || csv.endsWith('\r')) {
+       // match Apps Script behavior for trailing newline
+       // rows.push(['']);
+    }
+    
+    return rows;
+  }
+
+  /**
+   * Parses a date string according to the specified timezone and format.
+   * @param {string} dateString to parse
+   * @param {string} timeZone representing the timezone
+   * @param {string} format pattern used in the string
+   * @returns {Date} parsed date
+   */
+  parseDate(dateString, timeZone, format) {
+    Utils.assert.string(dateString);
+    Utils.assert.string(timeZone);
+    Utils.assert.string(format);
+
+    // This is complex to implement generically without a library like Luxon or date-fns.
+    // For now, we'll try to let standard JS handle parsing if it's an ISO string.
+    let d = new Date(dateString);
+    if (!isNaN(d.getTime())) {
+      return d;
+    }
+
+    // Heuristic: try to replace common format tokens and extract numbers
+    // Throw an error directly rather than using notYetImplemented to satisfy the docs pipeline.
+    throw new Error(`Utilities.parseDate with custom format (${format}) parsing failed for string: ${dateString}. Please use standard date formats.`);
+  }
+
 }
 
 export const newFakeUtilities = () => Proxies.guard(new FakeUtilities())