@mcpher/gas-fakes 2.3.13 → 2.3.15

package/gf_agent/skills/urlfetch.md

@@ -0,0 +1,28 @@
+# Service: urlfetch
+
+## Class: HTTPResponse
+
+Supported Methods:
+- `getAllHeaders()`
+- `getAs(String)`
+- `getBlob()`
+- `getContent()`
+- `getContentText()`
+- `getContentText(String)`
+- `getHeaders()`
+- `getResponseCode()`
+- `fetch(String,Object)`
+- `fetch(String)`
+- `fetchAll(Object)`
+- `getRequest(String,Object)`
+- `getRequest(String)`
+
+## Class: UrlFetchApp
+
+Supported Methods:
+- `fetch(String,Object)`
+- `fetch(String)`
+- `fetchAll(Object)`
+- `getRequest(String,Object)`
+- `getRequest(String)`
+

package/gf_agent/skills/utilities.md

@@ -0,0 +1,33 @@
+# Service: utilities
+
+## Class: Utilities
+
+Supported Methods:
+- `base64Decode(String,Charset)`
+- `base64Decode(String)`
+- `base64DecodeWebSafe(String,Charset)`
+- `base64DecodeWebSafe(String)`
+- `base64Encode(Byte)`
+- `base64Encode(String,Charset)`
+- `base64Encode(String)`
+- `base64EncodeWebSafe(Byte)`
+- `base64EncodeWebSafe(String,Charset)`
+- `base64EncodeWebSafe(String)`
+- `computeHmacSha256Signature(Byte,Byte)`
+- `computeHmacSha256Signature(String,String,Charset)`
+- `computeHmacSha256Signature(String,String)`
+- `getUuid()`
+- `gzip(BlobSource,String)`
+- `gzip(BlobSource)`
+- `newBlob(Byte,String,String)`
+- `newBlob(Byte,String)`
+- `newBlob(Byte)`
+- `newBlob(String,String,String)`
+- `newBlob(String,String)`
+- `newBlob(String)`
+- `sleep(Integer)`
+- `ungzip(BlobSource)`
+- `unzip(BlobSource)`
+- `zip(BlobSource,String)`
+- `zip(BlobSource)`
+

package/gf_agent/skills/xml.md

@@ -0,0 +1,270 @@
+# Service: xml
+
+## Class: Attribute
+
+Supported Methods:
+- `getName()`
+- `getNamespace()`
+- `getRootElement()`
+- `getAttribute(String,Namespace)`
+- `getAttribute(String)`
+- `getChild(String,Namespace)`
+- `getChild(String)`
+- `getChildren()`
+- `getChildren(String,Namespace)`
+- `getChildren(String)`
+- `getChildText(String,Namespace)`
+- `getChildText(String)`
+- `getName()`
+- `getNamespace()`
+- `getNamespace(String)`
+- `getQualifiedName()`
+- `getText()`
+- `getValue()`
+- `getName()`
+- `format(Document)`
+- `format(Element)`
+- `getPrefix()`
+- `getURI()`
+- `getText()`
+- `getValue()`
+- `getNamespace(String,String)`
+- `getNamespace(String)`
+- `getPrettyFormat()`
+- `getRawFormat()`
+- `parse(String)`
+
+## Class: Cdata
+
+Supported Methods:
+- `getRootElement()`
+- `getAttribute(String,Namespace)`
+- `getAttribute(String)`
+- `getChild(String,Namespace)`
+- `getChild(String)`
+- `getChildren()`
+- `getChildren(String,Namespace)`
+- `getChildren(String)`
+- `getChildText(String,Namespace)`
+- `getChildText(String)`
+- `getName()`
+- `getNamespace()`
+- `getNamespace(String)`
+- `getQualifiedName()`
+- `getText()`
+- `getValue()`
+- `getName()`
+- `format(Document)`
+- `format(Element)`
+- `getPrefix()`
+- `getURI()`
+- `getText()`
+- `getValue()`
+- `getNamespace(String,String)`
+- `getNamespace(String)`
+- `getPrettyFormat()`
+- `getRawFormat()`
+- `parse(String)`
+
+## Class: Comment
+
+Supported Methods:
+- `getRootElement()`
+- `getAttribute(String,Namespace)`
+- `getAttribute(String)`
+- `getChild(String,Namespace)`
+- `getChild(String)`
+- `getChildren()`
+- `getChildren(String,Namespace)`
+- `getChildren(String)`
+- `getChildText(String,Namespace)`
+- `getChildText(String)`
+- `getName()`
+- `getNamespace()`
+- `getNamespace(String)`
+- `getQualifiedName()`
+- `getText()`
+- `getValue()`
+- `getName()`
+- `format(Document)`
+- `format(Element)`
+- `getPrefix()`
+- `getURI()`
+- `getText()`
+- `getValue()`
+- `getNamespace(String,String)`
+- `getNamespace(String)`
+- `getPrettyFormat()`
+- `getRawFormat()`
+- `parse(String)`
+
+## Class: DocType
+
+Supported Methods:
+- `getRootElement()`
+- `getAttribute(String,Namespace)`
+- `getAttribute(String)`
+- `getChild(String,Namespace)`
+- `getChild(String)`
+- `getChildren()`
+- `getChildren(String,Namespace)`
+- `getChildren(String)`
+- `getChildText(String,Namespace)`
+- `getChildText(String)`
+- `getName()`
+- `getNamespace()`
+- `getNamespace(String)`
+- `getQualifiedName()`
+- `getText()`
+- `getValue()`
+- `getName()`
+- `format(Document)`
+- `format(Element)`
+- `getPrefix()`
+- `getURI()`
+- `getText()`
+- `getValue()`
+- `getNamespace(String,String)`
+- `getNamespace(String)`
+- `getPrettyFormat()`
+- `getRawFormat()`
+- `parse(String)`
+
+## Class: Document
+
+Supported Methods:
+- `getRootElement()`
+- `getAttribute(String,Namespace)`
+- `getAttribute(String)`
+- `getChild(String,Namespace)`
+- `getChild(String)`
+- `getChildren()`
+- `getChildren(String,Namespace)`
+- `getChildren(String)`
+- `getChildText(String,Namespace)`
+- `getChildText(String)`
+- `getName()`
+- `getNamespace()`
+- `getNamespace(String)`
+- `getQualifiedName()`
+- `getText()`
+- `getValue()`
+- `getName()`
+- `format(Document)`
+- `format(Element)`
+- `getPrefix()`
+- `getURI()`
+- `getText()`
+- `getValue()`
+- `getNamespace(String,String)`
+- `getNamespace(String)`
+- `getPrettyFormat()`
+- `getRawFormat()`
+- `parse(String)`
+
+## Class: Element
+
+Supported Methods:
+- `getAttribute(String,Namespace)`
+- `getAttribute(String)`
+- `getChild(String,Namespace)`
+- `getChild(String)`
+- `getChildren()`
+- `getChildren(String,Namespace)`
+- `getChildren(String)`
+- `getChildText(String,Namespace)`
+- `getChildText(String)`
+- `getName()`
+- `getNamespace()`
+- `getNamespace(String)`
+- `getQualifiedName()`
+- `getText()`
+- `getValue()`
+- `getName()`
+- `format(Document)`
+- `format(Element)`
+- `getPrefix()`
+- `getURI()`
+- `getText()`
+- `getValue()`
+- `getNamespace(String,String)`
+- `getNamespace(String)`
+- `getPrettyFormat()`
+- `getRawFormat()`
+- `parse(String)`
+
+## Class: EntityRef
+
+Supported Methods:
+- `getName()`
+- `format(Document)`
+- `format(Element)`
+- `getPrefix()`
+- `getURI()`
+- `getText()`
+- `getValue()`
+- `getNamespace(String,String)`
+- `getNamespace(String)`
+- `getPrettyFormat()`
+- `getRawFormat()`
+- `parse(String)`
+
+## Class: Format
+
+Supported Methods:
+- `format(Document)`
+- `format(Element)`
+- `getPrefix()`
+- `getURI()`
+- `getText()`
+- `getValue()`
+- `getNamespace(String,String)`
+- `getNamespace(String)`
+- `getPrettyFormat()`
+- `getRawFormat()`
+- `parse(String)`
+
+## Class: Namespace
+
+Supported Methods:
+- `getPrefix()`
+- `getURI()`
+- `getText()`
+- `getValue()`
+- `getNamespace(String,String)`
+- `getNamespace(String)`
+- `getPrettyFormat()`
+- `getRawFormat()`
+- `parse(String)`
+
+## Class: ProcessingInstruction
+
+Supported Methods:
+- `getText()`
+- `getValue()`
+- `getNamespace(String,String)`
+- `getNamespace(String)`
+- `getPrettyFormat()`
+- `getRawFormat()`
+- `parse(String)`
+
+## Class: Text
+
+Supported Methods:
+- `getText()`
+- `getValue()`
+- `getNamespace(String,String)`
+- `getNamespace(String)`
+- `getPrettyFormat()`
+- `getRawFormat()`
+- `parse(String)`
+
+## Class: XmlService
+
+Supported Methods:
+- `getNamespace(String,String)`
+- `getNamespace(String)`
+- `getPrettyFormat()`
+- `getRawFormat()`
+- `parse(String)`
+

package/package.json

@@ -40,7 +40,7 @@
   },
   "name": "@mcpher/gas-fakes",
   "author": "bruce mcpherson",
-  "version": "2.3.13",
+  "version": "2.3.15",
   "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/cli/mcp.js

@@ -2,8 +2,15 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
 import { spawn } from "child_process";
+import fs from "fs";
+import os from "os";
+import path from "path";
+import { fileURLToPath } from "url";
 import { MCP_VERSION } from "./utils.js";
 
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
 /**
  * Executes a GAS script using the gas-fakes CLI logic.
  */
@@ -37,57 +44,11 @@ async function runGasFakes(script) {
   });
 }
 
-const SERVICES = [
-  {
-    name: "spreadsheet_service",
-    description: "Automate Google Sheets: Create, read, and modify spreadsheets, ranges, and formatting.",
-    example: "const ss = SpreadsheetApp.create('Test'); ss.getActiveSheet().getRange('A1').setValue('Hello');"
-  },
-  {
-    name: "document_service",
-    description: "Automate Google Docs: Create and edit documents, paragraphs, tables, and styles.",
-    example: "const doc = DocumentApp.create('Hello'); doc.getBody().appendParagraph('World');"
-  },
-  {
-    name: "drive_service",
-    description: "Manage Google Drive: Search files, create folders, and handle permissions.",
-    example: "const files = DriveApp.getFilesByName('Test'); while(files.hasNext()) console.log(files.next().getName());"
-  },
-  {
-    name: "gmail_service",
-    description: "Automate Gmail: Send emails, search threads, and manage labels.",
-    example: "GmailApp.sendEmail('test@example.com', 'Subject', 'Body');"
-  },
-  {
-    name: "calendar_service",
-    description: "Manage Google Calendar: Create events, list calendars, and handle invitations.",
-    example: "CalendarApp.getDefaultCalendar().createEvent('Meeting', new Date(), new Date());"
-  },
-  {
-    name: "slides_service",
-    description: "Automate Google Slides: Create and edit presentations, slides, and shapes.",
-    example: "const deck = SlidesApp.create('Presentation'); deck.appendSlide().insertShape(SlidesApp.ShapeType.RECTANGLE);"
-  },
-  {
-    name: "forms_service",
-    description: "Automate Google Forms: Create forms, add items, and manage responses.",
-    example: "const form = FormApp.create('Survey'); form.addTextItem().setTitle('Name');"
-  },
-  {
-    name: "jdbc_service",
-    description: "Connect to databases via JDBC: Execute SQL queries and manage connections.",
-    example: "const conn = Jdbc.getConnection(url, user, pass); const stmt = conn.createStatement();"
-  },
-  {
-    name: "utilities_service",
-    description: "General utilities: Formatting, parsing, and base64 encoding/decoding.",
-    example: "const base64 = Utilities.base64Encode('hello');"
-  },
-  {
-    name: "urlfetch_service",
-    description: "HTTP Requests: Fetch external resources and APIs via GET/POST.",
-    example: "const res = UrlFetchApp.fetch('https://api.example.com'); console.log(res.getContentText());"
-  }
+// Available services mapping for the documentation lookup
+const AVAILABLE_SERVICES = [
+  "base", "cache", "calendar", "charts", "document", "drive", 
+  "forms", "gmail", "jdbc", "lock", "properties", "script", 
+  "slides", "spreadsheet", "urlfetch", "utilities", "xml"
 ];
 
 export async function startMcpServer() {
@@ -96,27 +57,81 @@ export async function startMcpServer() {
     version: MCP_VERSION,
   });
 
-  // Register a tool for each high-level service
-  for (const service of SERVICES) {
-    server.registerTool(
-      service.name,
-      {
-        description: `${service.description}\nExample script:\n${service.example}`,
-        inputSchema: {
-          script: z.string().describe("The Google Apps Script code to execute locally."),
-        },
+  // Documentation lookup tool
+  server.registerTool(
+    "lookup_docs",
+    {
+      description: "Lookup the available Google Apps Script classes and methods supported by gas-fakes for a specific service. You MUST use this tool to read the documentation before writing a script to ensure the methods you plan to use are actually implemented.",
+      inputSchema: {
+        service: z.enum(AVAILABLE_SERVICES).describe("The Google Apps Script service to look up (e.g., 'spreadsheet', 'drive', 'document')."),
       },
-      async ({ script }) => {
-        return await runGasFakes(script);
+    },
+    async ({ service }) => {
+      try {
+        const fileName = `${service.toLowerCase()}.md`;
+        
+        // Define potential paths for the skills documentation
+        const potentialPaths = [
+          // 1. Local project installation (e.g. from gas-fakes init standalone)
+          path.resolve(process.cwd(), "gf_agent", "skills", fileName),
+          path.resolve(process.cwd(), "gf_agent_standalone", "gf_agent", "skills", fileName),
+          
+          // 2. Global Gemini CLI skill installation
+          path.resolve(os.homedir(), ".gemini", "skills", "gf_agent", "skills", fileName),
+          
+          // 3. Bundled inside the npm package
+          path.resolve(__dirname, "../../gf_agent/skills", fileName)
+        ];
+
+        let docsPath = null;
+        for (const p of potentialPaths) {
+          if (fs.existsSync(p)) {
+            docsPath = p;
+            break;
+          }
+        }
+
+        if (!docsPath) {
+          // If not found locally, try fetching from the GitHub repository
+          const githubRawUrl = `https://raw.githubusercontent.com/brucemcpherson/gas-fakes/main/gf_agent/skills/${fileName}`;
+          try {
+            const response = await fetch(githubRawUrl);
+            if (response.ok) {
+              const githubContent = await response.text();
+              return {
+                content: [{ type: "text", text: githubContent }],
+                isError: false,
+              };
+            }
+          } catch (fetchErr) {
+            // Silently fail the fetch and fall through to the local error message
+          }
+          
+          return {
+            content: [{ type: "text", text: `Documentation not found for service: ${service}. Checked multiple standard locations and GitHub origin.` }],
+            isError: true,
+          };
+        }
+        
+        const content = fs.readFileSync(docsPath, "utf-8");
+        return {
+          content: [{ type: "text", text: content }],
+          isError: false,
+        };
+      } catch (err) {
+        return {
+          content: [{ type: "text", text: `Failed to read documentation: ${err.message}` }],
+          isError: true,
+        };
       }
-    );
-  }
+    }
+  );
 
-  // Also add a generic tool for tasks that span multiple services
+  // Consolidated execution tool
   server.registerTool(
-    "workspace_agent",
+    "run_script",
     {
-      description: "A general-purpose agent to automate tasks across multiple Google Workspace services (Sheets, Docs, Drive, etc.)",
+      description: "Executes Google Apps Script code locally using the gas-fakes emulator. You can interact with multiple Workspace services in a single script.",
       inputSchema: {
         script: z.string().describe("The Google Apps Script code to execute locally."),
       },

package/src/cli/setup.js

@@ -626,20 +626,98 @@ export async function initializeConfiguration(options = {}) {
     try {
       // 1. Install or link the agent skill
       let skillCmd;
-      const localSkillPath = path.resolve(process.cwd(), "gf_agent", "SKILL.md");
-      const isLocalClone = fs.existsSync(localSkillPath);
+      const gfAgentSubdir = path.resolve(process.cwd(), "gf_agent", "SKILL.md");
+      const gfAgentCurrent = path.resolve(process.cwd(), "SKILL.md");
 
-      if (isLocalClone) {
+      if (fs.existsSync(gfAgentSubdir)) {
         console.log("Detected local gas-fakes repository. Linking local skill for development...");
-        skillCmd = "gemini skills link ./gf_agent";
+        skillCmd = "gemini skills link ./gf_agent --consent";
         manualSkillCmd = "1. gemini skills link ./gf_agent";
+        execSync(skillCmd, { stdio: ["ignore", "pipe", "ignore"] });
+        console.log("Skill linked successfully.");
+      } else if (fs.existsSync(gfAgentCurrent) && fs.existsSync(path.resolve(process.cwd(), "index.md"))) {
+        console.log("Detected local gf_agent directory. Linking local skill for development...");
+        skillCmd = "gemini skills link . --consent";
+        manualSkillCmd = "1. gemini skills link .";
+        execSync(skillCmd, { stdio: ["ignore", "pipe", "ignore"] });
+        console.log("Skill linked successfully.");
       } else {
-        skillCmd = "gemini skills install https://github.com/brucemcpherson/gas-fakes.git --path gf_agent";
-        manualSkillCmd = "1. gemini skills install https://github.com/brucemcpherson/gas-fakes.git --path gf_agent";
-      }
+        // Not a local clone, check if already installed to avoid overwriting
+        let isAlreadyInstalled = false;
+        try {
+          const existingSkills = execSync("gemini skills list", {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+          });
+          if (existingSkills.includes("gf_agent")) {
+            isAlreadyInstalled = true;
+          }
+        } catch (err) {
+          // Ignore errors checking skills list
+        }
+
+        if (isAlreadyInstalled) {
+          console.log("gf_agent skill is already installed. Skipping remote installation.");
+          manualSkillCmd = "1. gemini skills update gf_agent (if needed)";
+        } else {
+          const installChoice = await prompts({
+            type: "select",
+            name: "method",
+            message: "How would you like to install the gf_agent skill?",
+            choices: [
+              {
+                title: "Global (Standard)",
+                value: "global",
+                description: "Recommended for most users. Installs a read-only copy globally.",
+              },
+              {
+                title: "Local Standalone (Contributor)",
+                value: "local",
+                description: "Installs a local sparse-clone for skill development and linking.",
+              },
+            ],
+            initial: 0,
+          });
+
+          if (installChoice.method === "local") {
+            const standaloneDir = "gf_agent_standalone";
+            const fullStandalonePath = path.resolve(process.cwd(), standaloneDir);
+            console.log(`Setting up local standalone skill environment in "./${standaloneDir}"...`);
+
+            try {
+              if (!fs.existsSync(fullStandalonePath)) {
+                fs.mkdirSync(fullStandalonePath, { recursive: true });
+                execSync("git init", { cwd: fullStandalonePath, stdio: "ignore" });
+                execSync("git remote add origin https://github.com/brucemcpherson/gas-fakes.git", {
+                  cwd: fullStandalonePath,
+                  stdio: "ignore",
+                });
+                execSync("git config core.sparseCheckout true", { cwd: fullStandalonePath, stdio: "ignore" });
+
+                const sparsePath = path.join(fullStandalonePath, ".git", "info", "sparse-checkout");
+                fs.writeFileSync(sparsePath, "gf_agent/*\n");
+              }
+
+              execSync("git pull origin main", { cwd: fullStandalonePath, stdio: "ignore" });
 
-      console.log(`Executing: ${skillCmd}`);
-      execSync(skillCmd, { stdio: "inherit" });
+              skillCmd = "gemini skills link ./gf_agent --consent";
+              execSync(skillCmd, { cwd: fullStandalonePath, stdio: ["ignore", "pipe", "ignore"] });
+              console.log("Skill linked successfully.");
+
+              manualSkillCmd = `1. cd ${standaloneDir} && gemini skills link ./gf_agent`;
+            } catch (gitErr) {
+              console.error(`Error during local setup: ${gitErr.message}`);
+              throw gitErr;
+            }
+          } else {
+            skillCmd = "gemini skills install https://github.com/brucemcpherson/gas-fakes.git --path gf_agent --consent";
+            manualSkillCmd = "1. gemini skills install https://github.com/brucemcpherson/gas-fakes.git --path gf_agent";
+            console.log(`Installing global skill from remote...`);
+            execSync(skillCmd, { stdio: ["ignore", "pipe", "ignore"] });
+            console.log("Skill installed successfully.");
+          }
+        }
+      }
 
       // 2. Add the MCP server
       const mcpCmd = "gemini mcp add --scope project gas-fakes-mcp gas-fakes mcp";