brucemcpherson/gas-fakes/gf-agent

Skill: gf_agent

Overview

gf_agent is a specialized agent for automating Google Workspace tasks using the gas-fakes local emulation environment. It can generate and execute Google Apps Script (GAS) code locally on Node.js.

Capabilities

• Automate Workspace: Create, read, and modify Google Docs, Sheets, Slides, Forms, Drive files, and Calendars.
• Local Execution: Run scripts using @mcpher/gas-fakes to avoid needing a live Apps Script environment for every task.
• Service Integration: Seamlessly combine multiple Google services (e.g., fetch data from a Sheet and create a Doc).
• Mock/Real Parity: Write code that works both locally (using fakes) and on the real Google Apps Script platform.

Instructions

1. Understand and Orchestrate:

• Identify required Google Apps Script services (e.g., SpreadsheetApp, DriveApp).
• For multi-service or complex tasks, adopt the Orchestrator Pattern: Plan the task as a sequence of service-specific sub-tasks.

1. Research and Verify (Service Agent Phase):

• For each service, first verify method existence by reading the local skills/{service}.md files in the skill directory.
• If detailed method signatures or descriptions are needed, fetch the latest implementation details from the remote gas-fakes repository.
• 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.

1. Generate Script: Create a Node.js script that:

• Uses standard GAS syntax.
• (Optional) Uses ScriptApp.isFake for local-only logic like logging or cleanup.

1. Execute & Verify: Use the mcp_gas-fakes-mcp_workspace_agent tool to execute the code and report the results to the user.

Example Workflow

User: "Summarize the last 5 unread emails and save the summary to a new Google Doc." Agent:

1. Identify Services: GmailApp, DocumentApp.
2. Verify Methods:

• Check skills/gmail.md and skills/document.md.
• (Optional) Fetch progress/gmail.md and progress/document.md from GitHub for detailed signatures.

1. Generate Script:

``javascript const threads = GmailApp.getInboxThreads(0, 5); let summary = 'Email Summary:\n\n'; threads.forEach(t => { const msg = t.getMessages()[0]; summary += From: ${msg.getFrom()}\nSubject: ${msg.getSubject()}\n---\n; }); const doc = DocumentApp.create('Email Summaries'); doc.getBody().appendParagraph(summary); console.log('Summary saved to Doc ID:', doc.getId()); ``

1. Execute: Call mcp_gas-fakes-mcp_workspace_agent({ script: '...' }).
2. Report: Confirm completion and provide the Doc ID.

Notes

• Always use ES modules (import).
• Note that the Apps Script Services are all automatically available- for Example DriveApp, SpreadsheetApp, etc. are all available in the global namespace - no need to import them.
• the manifest file is used to conteol which scopes are required. dwd is the preferred authentication method but it needs the user to enable it from the domain admain console during the authentication stage.
• Advanced Service versions of the services are available - and map to their apps script equivalents. These are also available via the global namespace for example Drive, Sheets , etc.
• Note that Apps Script is synchronous. gas-fake emulates this so all calls to services will be synchronous
• Where possible, use the native Apps Script service (for example DriveApp) in preference to the advanced services (Drive, Sheets, etc.)

Lessons Learned & Best Practices (from Test Patterns)

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)

• Prefer `searchFiles()` over manual iteration: When looking for specific files (e.g., by name, date, or parent), always use DriveApp.searchFiles(query) instead of DriveApp.getFiles() with manual filtering. Searching happens on the server and is significantly faster.
• Date Formatting for Queries: When searching by date (e.g., modifiedTime or createdTime), you MUST use the RFC3339 format (e.g., YYYY-MM-DDThh:mm:ss).
• Crucial: Use modifiedTime instead of modifiedDate when querying Drive via gas-fakes, as it maps to the Drive API v3 field.
• Example: DriveApp.searchFiles("modifiedTime >= '2024-04-24T00:00:00'").

Advanced Service Versioning (v3 Preference)

• Drive API: gas-fakes follows the Drive API v3 naming convention.
• Use Drive.Files.create() instead of insert().
• Use name instead of title in resource objects.
• If a method from a live Apps Script snippet fails, check for its v3 equivalent before assuming it is missing.
• Service Discovery: If unsure about available methods, run a short workspace_agent script to log Object.keys(Service.SubService) to confirm implemented endpoints.

Common Apps Script Syntax Gotchas (First-Time Accuracy)

• 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)
• Google Docs Element Detachment: To move or duplicate an element (like an image, paragraph, or table) within a document, you cannot just append it if it's already attached to the document tree. You must either detach it (element.removeFromParent()) or copy it (element.copy()) first, otherwise an "Element must be detached" error is thrown.
• Google Docs Headers/Footers: You can only add one header/footer to a document tab. Calling doc.addHeader() twice will throw an error.
• Google Sheets Developer Metadata: You cannot add DeveloperMetadata to an arbitrary range (e.g., A1:B2) or a partial row/column. It only works on full sheets, full rows (9:9), full columns (J:J), or the spreadsheet itself.
• Google Sheets Filters: A sheet can only have one filter at a time. Attempting to call range.createFilter() on a sheet that already has a filter will throw an error.
• Google Drive Blob Naming: When creating a file from a Blob (DriveApp.createFile(blob)), the Blob must have a name. Utilities.newBlob("content") does not set a name by default and will throw "Blob object must have non-null name". Always use Utilities.newBlob("content", "text/plain", "filename.txt").
• Flush Requirements: If your script creates a resource and immediately tries to perform a complex search or metadata operation on it, call SpreadsheetApp.flush() or doc.saveAndClose() to ensure the state is synchronized.
• Date Comparison: When comparing dates from getLastUpdated() or getDateCreated(), remember they are JavaScript Date objects. Use .getTime() for reliable numerical comparison.

Authentication & Troubleshooting

• Permission Denied/Auth Failures: Most authentication errors stem from a mismatch between the script's required scopes and the authorized environment.
• Manifest & Scopes: gas-fakes reads appsscript.json to discover required scopes. If these scopes weren't authorized during gas-fakes auth, the script will fail.
• Advice for User (Auth Methods): When a user needs help setting up authentication for gas-fakes, advise them based on their specific situation:
• Service Account (Default): Recommend this for most automated tasks or server environments. They need a GCP project, a Service Account, and its JSON key file.
• DWD (Domain Wide Delegation): Recommend this if the script needs to act on behalf of other users in a Google Workspace domain. Remind the user that the Service Account must be explicitly authorized in the Google Workspace Admin Console (Security > API Controls > Domain-wide Delegation) for the specific scopes being used, and they must provide the Subject email address during the gas-fakes auth flow.
• Desktop/OAuth (CLI): Recommend this for personal scripting or if they cannot use a Service Account. It requires OAuth Client ID credentials from GCP (Application type: Desktop) and will prompt them to authenticate via a browser window.
• Initialization: Ensure the project has been initialized using gas-fakes init. The .env file must contain the correct GF_PLATFORM_AUTH and associated credentials.

Parity & Platform Logic

• `ScriptApp.isFake`: Use this boolean to detect the gas-fakes environment.
• Best Practice: Guard only infrastructure logic (logging, cache checks, special backends) with this flag.
• Warning: Do not use it to change the core business logic of a script, as this defeats the purpose of parity.
• Backend Selection: ScriptApp.__platform can be dynamically switched to target google, ksuite, or msgraph.
• Self-Correcting: gas-fakes resources (Files, Sheets) "remember" their platform at creation. Subsequent calls on that object will automatically use the correct backend even if ScriptApp.__platform has changed globally.