@mcpher/gas-fakes 1.2.9 → 1.2.11

package/README.RU.md

@@ -331,3 +331,31 @@ const getParentsIterator = ({
 - [this file](README.md)
 - [named colors](named-colors.md)
 - [sandbox](sandbox.md)
+
+## <img src="./logo.png" alt="gas-fakes logo" width="50" align="top">  Further Reading
+
+- [getting started](GETTING_STARTED.md) - how to handle authentication for restricted scopes.
+- [readme](README.md)
+- [initial idea and thoughts](https://ramblings.mcpher.com/a-proof-of-concept-implementation-of-apps-script-environment-on-node/)
+- [Inside the volatile world of a Google Document](https://ramblings.mcpher.com/inside-the-volatile-world-of-a-google-document/)
+- [Apps Script Services on Node – using apps script libraries](https://ramblings.mcpher.com/apps-script-services-on-node-using-apps-script-libraries/)
+- [Apps Script environment on Node – more services](https://ramblings.mcpher.com/apps-script-environment-on-node-more-services/)
+- [Turning async into synch on Node using workers](https://ramblings.mcpher.com/turning-async-into-synch-on-node-using-workers/)
+- [All about Apps Script Enums and how to fake them](https://ramblings.mcpher.com/all-about-apps-script-enums-and-how-to-fake-them/)
+- [Russian version](README.RU.md) ([credit Alex Ivanov](https://github.com/oshliaer)) - needs updating
+- [colaborators](collaborators.md) - additional information for collaborators
+- [oddities](oddities.md) - a collection of oddities uncovered during this project
+- [gemini](gemini-observations.md) - some reflections and experiences on using gemini to help code large projects
+- [named colors](named-colors.md)
+- [sandbox](sandbox.md)
+- [named range identity](named-range-identity.md)
+- [adc and restricted scopes](https://ramblings.mcpher.com/how-to-allow-access-to-sensitive-scopes-with-application-default-credentials/)
+- [push test pull](pull-test-push.md)
+- [gas fakes cli](gas-fakes-cli.md)
+- [sharing cache and properties between gas-fakes and live apps script](https://ramblings.mcpher.com/sharing-cache-and-properties-between-gas-fakes-and-live-apps-script/)
+- [gas-fakes-cli now has built in mcp server and gemini extension](https://ramblings.mcpher.com/gas-fakes-cli-now-has-built-in-mcp-server-and-gemini-extension/)
+- [gas-fakes CLI: Run apps script code directly from your terminal](https://ramblings.mcpher.com/gas-fakes-cli-run-apps-script-code-directly-from-your-terminal/)
+- [How to allow access to sensitive scopes with Application Default Credentials](https://ramblings.mcpher.com/how-to-allow-access-to-sensitive-scopes-with-application-default-credentials/)
+- [Supercharge Your Google Apps Script Caching with GasFlexCache](https://ramblings.mcpher.com/supercharge-your-google-apps-script-caching-with-gasflexcache/)
+- [Fake-Sandbox for Google Apps Script: Granular controls.](https://ramblings.mcpher.com/fake-sandbox-for-google-apps-script-granular-controls/)
+- [A Fake-Sandbox for Google Apps Script: Securely Executing Code Generated by Gemini CLI](https://ramblings.mcpher.com/gas-fakes-sandbox/)

package/README.md

@@ -150,6 +150,7 @@ For inspiration on pushing modified files to the IDE, see the togas.sh bash scri
 ## Help
 
 As I mentioned earlier, to take this further, I'm going to need a lot of help to extend the methods and services supported - so if you feel this would be useful to you, and would like to collaborate, please ping me on bruce@mcpher.com and we'll talk.
+
 ## <img src="./logo.png" alt="gas-fakes logo" width="50" align="top">  Further Reading
 
 - [getting started](GETTING_STARTED.md) - how to handle authentication for restricted scopes.
@@ -163,11 +164,17 @@ As I mentioned earlier, to take this further, I'm going to need a lot of help to
 - [Russian version](README.RU.md) ([credit Alex Ivanov](https://github.com/oshliaer)) - needs updating
 - [colaborators](collaborators.md) - additional information for collaborators
 - [oddities](oddities.md) - a collection of oddities uncovered during this project
-- [gemini](gemini.md) - some reflections and experiences on using gemini to help code large projects
+- [gemini](gemini-observations.md) - some reflections and experiences on using gemini to help code large projects
 - [named colors](named-colors.md)
 - [sandbox](sandbox.md)
 - [named range identity](named-range-identity.md)
 - [adc and restricted scopes](https://ramblings.mcpher.com/how-to-allow-access-to-sensitive-scopes-with-application-default-credentials/)
 - [push test pull](pull-test-push.md)
 - [gas fakes cli](gas-fakes-cli.md)
-- [sharing cache and properties between gas-fakes and live apps script](https://ramblings.mcpher.com/sharing-cache-and-properties-between-gas-fakes-and-live-apps-script/)
+- [sharing cache and properties between gas-fakes and live apps script](https://ramblings.mcpher.com/sharing-cache-and-properties-between-gas-fakes-and-live-apps-script/)
+- [gas-fakes-cli now has built in mcp server and gemini extension](https://ramblings.mcpher.com/gas-fakes-cli-now-has-built-in-mcp-server-and-gemini-extension/)
+- [gas-fakes CLI: Run apps script code directly from your terminal](https://ramblings.mcpher.com/gas-fakes-cli-run-apps-script-code-directly-from-your-terminal/)
+- [How to allow access to sensitive scopes with Application Default Credentials](https://ramblings.mcpher.com/how-to-allow-access-to-sensitive-scopes-with-application-default-credentials/)
+- [Supercharge Your Google Apps Script Caching with GasFlexCache](https://ramblings.mcpher.com/supercharge-your-google-apps-script-caching-with-gasflexcache/)
+- [Fake-Sandbox for Google Apps Script: Granular controls.](https://ramblings.mcpher.com/fake-sandbox-for-google-apps-script-granular-controls/)
+- [A Fake-Sandbox for Google Apps Script: Securely Executing Code Generated by Gemini CLI](https://ramblings.mcpher.com/gas-fakes-sandbox/)

package/exgcp.sh

@@ -0,0 +1,47 @@
+#!/bin/bash
+
+# This script reads the GCP_PROJECT_ID from a .env file
+# and exports it as GOOGLE_CLOUD_PROJECT for the current shell session.
+#
+# Usage: source . ./exgcp.sh
+
+# Define the path to your .env file relative to the script's location
+ENV_FILE="$(dirname "$0")/.env"
+
+# Check if the .env file exists
+
+if [ ! -f "$ENV_FILE" ]; then
+  echo "Error: .env file not found at path: $ENV_FILE"
+  # Use 'return' instead of 'exit' so it doesn't close the user's terminal when sourced
+  return 1
+fi
+
+# Read the GCP_PROJECT_ID, remove quotes, and handle potential carriage returns
+GCP_PROJECT_ID_VALUE=$(grep -E '^GCP_PROJECT_ID=' "$ENV_FILE" | cut -d '=' -f2 | tr -d '"\r')
+GEMINI_API_KEY_VALUE=$(grep -E '^GEMINI_API_KEY=' "$ENV_FILE" | cut -d '=' -f2 | tr -d '"\r')
+GEMINI_MODEL_VALUE=$(grep -E '^GEMINI_MODEL=' "$ENV_FILE" | cut -d '=' -f2 | tr -d '"\r')
+
+# Check if a value was extracted
+if [ -z "$GCP_PROJECT_ID_VALUE" ]; then
+  echo "Error: GCP_PROJECT_ID not found or is empty in $ENV_FILE."
+  return 1
+fi
+
+if [ -z "GEMINI_API_KEY_VALUE" ]; then
+  echo "GEMINI_API_KEY not found or is empty in $ENV_FILE."
+else
+  echo "exported: GEMINI_API_KEY"
+  export GEMINI_API_KEY="$GEMINI_API_KEY_VALUE"
+fi  
+
+if [ -z "GEMINI_MODEL_VALUE" ]; then
+  echo "GEMINI_MODEL not found or is empty in $ENV_FILE."
+else
+  echo "exported: GEMINI_MODEL=$GEMINI_MODEL_VALUE"
+  export GEMINI_MODEL="$GEMINI_MODEL_VALUE"
+fi  
+
+# Export the variable for the current session
+export GOOGLE_CLOUD_PROJECT="$GCP_PROJECT_ID_VALUE"
+
+echo "exported: GOOGLE_CLOUD_PROJECT=$GOOGLE_CLOUD_PROJECT"

package/gas-fakes.js

@@ -1,309 +1,510 @@
 #!/usr/bin/env node
 
-/**
- * cli for gas-fakes
- */
+// -----------------------------------------------------------------------------
+// IMPORTS
+// -----------------------------------------------------------------------------
+
 import fs from "fs";
 import path from "path";
+import { exec } from "child_process";
+import { promisify } from "util";
 import { Command } from "commander";
 import dotenv from "dotenv";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import z from "zod";
-import { exec } from "child_process";
-import { promisify } from "util";
+import { z, ZodCatch } from "zod";
 
-const version = "0.0.3";
-
-const program = new Command();
-
-program
-  .name("gas-fakes")
-  .description("CLI tool for gas-fakes")
-  .version(version, "-v, --version", "display the current version");
-
-program
-  .description("Execute Google Apps Script using gas-fakes.")
-  .option(
-    "-f, --filename <string>",
-    "filename of the file including Google Apps Script. When this is used, the option --script is ignored."
-  )
-  .option(
-    "-e, --env <path>",
-    "provide path to your .env file for special options.",
-    "./.env"
-  )
-  .option(
-    "-g, --gfsettings <path>",
-    "provide path to your gasfakes.json file for script options.",
-    "./gasfakes.json"
-  )
-  .option(
-    "-s, --script <string>",
-    "provide Google Apps Script as a string. When this is used, the option --filename is ignored."
-  )
-  .option("-x, --sandbox", "run Google Apps Script in a sandbox.")
-  .option(
-    "-w, --whitelist <string>",
-    "whitelist of file IDs. Set the file IDs in comma-separated list. In this case, the files of the file IDs are used for both read and write. When this is used, the script is run in a sandbox."
-  )
-  .option(
-    "-j, --json <string>",
-    `JSON string including parameters for managing a sandbox. Enclose it with ' or ". When this is used, the option --whitelist is ignored. When this is used, the script is run in a sandbox.`
-  )
-  .option(
-    "-d, --display",
-    `display the created script for executing with gas-fakes. Default is false.`,
-    false
-  )
-  .action((options) => {
-    if (Object.keys(options).length == 0) {
-      program.help();
-    } else {
-      const {
-        filename,
-        script,
-        sandbox,
-        whitelist,
-        json,
-        display,
-        env,
-        gfsettings,
-      } = options;
-      const obj = { sandbox: !!sandbox, display };
-
-      if (!filename && !script && !obj.script) {
-        console.error(
-          "error: Provide the filename or the script of Google Apps Script."
-        );
-        process.exit();
-      }
+// -----------------------------------------------------------------------------
+// CONSTANTS & UTILITIES
+// -----------------------------------------------------------------------------
 
-      if (env) {
-        const envPath = path.resolve(process.cwd(), env);
-        console.log("...using env file in", envPath);
-        dotenv.config({ path: envPath, quiet: true });
-      }
+const VERSION = "0.0.6";
+const MCP_VERSION = "0.0.3";
+const execAsync = promisify(exec);
 
-      // note this must come after any env file fiddling.
-      if (gfsettings) {
-        const gfPath = path.resolve(process.cwd(), gfsettings);
-        console.log("...using gasfakes settings file in", gfPath);
-        obj.gfSettings = gfPath;
-        // override whatever is in env
-        process.env.GF_SETTINGS_PATH = gfPath;
-      }
+/**
+ * Replaces escaped newline characters ('\\n') with actual newlines,
+ * while ignoring newlines inside string literals.
+ * @param {string} text The script text to process.
+ * @returns {string} The processed text.
+ */
+function normalizeScriptNewlines(text) {
+  const regex = /("[^"]*")|('[^']*')|(`[^`]*`)|(\\n)/g;
+  return text.replace(regex, (match, g1, g2, g3, g4) => (g4 ? "\n" : match));
+}
 
-      if (filename) {
-        obj.filename = filename;
-      }
-      if (!obj.script && script) {
-        obj.script = script;
-      }
+// -----------------------------------------------------------------------------
+// SANDBOX SCRIPT GENERATION
+// -----------------------------------------------------------------------------
 
-      // for sandbox
-      if (whitelist) {
-        const ar = whitelist.split(",").map((e) => e.trim());
-        if (ar.length > 0) {
-          obj.whitelistItems = ar;
-        }
-      }
-      if (json) {
-        try {
-          const temp = JSON.parse(json);
-          obj.json_sandbox = temp;
-        } catch (err) {
-          console.error("error: Invalid JSON.");
-          process.exit();
-        }
-      }
-      loadScript(obj);
+/**
+ * Generates the GAS script snippet for whitelisting services.
+ * @param {Array<Object>} services The whitelistServices configuration.
+ * @returns {string[]} An array of script lines.
+ */
+function generateServiceWhitelistScript(services) {
+  if (!services || services.length === 0) return [];
+
+  return services.flatMap(({ className, methodNames }, index) => {
+    if (!className) {
+      console.error("Error: Class name not found in whitelistServices.");
+      process.exit(1);
+    }
+    const serviceVar = `service${index + 1}`;
+    const lines = [
+      `const ${serviceVar} = behavior.sandboxService.${className};`,
+    ];
+    if (methodNames && methodNames.length > 0) {
+      const methods = methodNames.map((name) => `"${name}"`).join(", ");
+      lines.push(`${serviceVar}.setMethodWhitelist([${methods}]);`);
     }
+    return lines;
   });
+}
 
-const execAsync = promisify(exec);
-program
-  .command("mcp")
-  .description("Launch gas-fakes as the MCP server")
-  .action(mcp_server);
-
-program.showHelpAfterError("(add --help for additional information)");
-program.parse();
-
-function __getImportScript(o) {
-  const { scriptText, sandbox, whitelistItems, json_sandbox } = o;
-  if (scriptText.trim() == "") {
-    console.error("error: Google Apps Script was not found.");
-    process.exit();
+/**
+ * Generates the GAS script snippet for blacklisting services.
+ * @param {string[]} services The blacklistServices configuration.
+ * @returns {string[]} An array of script lines.
+ */
+function generateServiceBlacklistScript(services) {
+  if (!services || services.length === 0) return [];
+  return services.map(
+    (service) => `behavior.sandboxService.${service}.enabled = false;`
+  );
+}
+
+/**
+ * Generates the GAS script snippet for whitelisting Drive items.
+ * @param {Array<Object>} items The whitelistItems configuration.
+ * @returns {string} A script string.
+ */
+function generateItemWhitelistScript(items) {
+  if (!items || items.length === 0) return "";
+
+  const whitelistItemsString = items
+    .map(({ itemId = "", read = true, write = false, trash = false }) => {
+      if (!itemId) {
+        console.error("Error: itemId not found in whitelistItems.");
+        process.exit(1);
+      }
+      return `behavior.newIdWhitelistItem("${itemId}").setRead(${read}).setWrite(${write}).setTrash(${trash})`;
+    })
+    .join(",\n        ");
+
+  return `behavior.setIdWhitelist([${whitelistItemsString}]);`;
+}
+
+/**
+ * Constructs the setup script for a sandboxed environment based on configuration.
+ * @param {object} sandboxConfig The sandbox configuration object.
+ * @returns {string[]} An array of GAS script lines for setup.
+ */
+function generateSandboxSetupScript(sandboxConfig) {
+  const script = [
+    "const behavior = ScriptApp.__behavior;",
+    "behavior.sandboxMode = true;",
+    "behavior.strictSandbox = true;",
+  ];
+
+  const { whitelistServices, blacklistServices, whitelistItems } =
+    sandboxConfig;
+
+  script.push(...generateServiceWhitelistScript(whitelistServices));
+  script.push(...generateServiceBlacklistScript(blacklistServices));
+
+  const itemWhitelist = generateItemWhitelistScript(whitelistItems);
+  if (itemWhitelist) {
+    script.push(itemWhitelist);
   }
-  let gasScriptStr = "";
-  const gasScriptAr = [];
-  if (json_sandbox) {
-    gasScriptAr.push(
-      `const behavior = ScriptApp.__behavior;`,
-      `behavior.sandboxMode = true;`,
-      `behavior.strictSandbox = true;`
-    );
-    const { whitelistItems, whitelistServices, blacklistServices } =
-      json_sandbox;
-    if (whitelistServices && whitelistServices.length > 0) {
-      const bl = whitelistServices.flatMap(({ className, methodNames }, i) => {
-        if (!className) {
-          console.error(
-            "error: Class name was not found in whitelistServices."
-          );
-          process.exit();
-        }
-        const k = `s${i + 1}`;
-        const temp = [`const ${k} = behavior.sandboxService.${className};`];
-        if (methodNames && methodNames.length > 0) {
-          temp.push(
-            `${k}.setMethodWhitelist([${methodNames.map((e) => `"${e}"`)}]);`
-          );
-        }
-        return temp;
-      });
-      gasScriptAr.push(...bl);
-    }
-    if (blacklistServices && blacklistServices.length > 0) {
-      const bl = blacklistServices.map(
-        (e) => `behavior.sandboxService.${e}.enabled = false;`
-      );
-      gasScriptAr.push(bl);
-    }
-    if (whitelistItems && whitelistItems.length > 0) {
-      const wl = whitelistItems
-        .map(({ itemId = "", read = true, write = false, trash = false }) => {
-          if (!itemId) {
-            console.error("error: itemId was not found in whitelistItems.");
-            process.exit();
-          }
-          return `behavior.newIdWhitelistItem("${itemId}").setRead(${read}).setWrite(${write}).setTrash(${trash})`;
-        })
-        .join(",");
-      gasScriptAr.push(`behavior.setIdWhitelist([${wl}]);`);
-    }
-    gasScriptAr.push(`\n\n${scriptText}\n\n`, `ScriptApp.__behavior.trash();`);
+
+  return script;
+}
+
+/**
+ * Generates the final, executable script string.
+ * @param {object} options
+ * @param {string} options.scriptText The user's Google Apps Script.
+ * @param {boolean} options.useSandbox Whether to enable basic sandbox mode.
+ * @param {object} [options.sandboxConfig] Detailed sandbox configuration.
+ * @returns {{mainScript: string, gasScript: string}} The script to be executed and the user-facing script part.
+ */
+function generateExecutionScript({ scriptText, useSandbox, sandboxConfig }) {
+  if (!scriptText || scriptText.trim() === "") {
+    console.error("Error: Google Apps Script is empty or was not found.");
+    process.exit(1);
+  }
+
+  let gasScriptLines = [];
+
+  if (sandboxConfig) {
+    gasScriptLines.push(...generateSandboxSetupScript(sandboxConfig));
+    gasScriptLines.push(`\n\n${scriptText}\n\n`);
+    gasScriptLines.push("ScriptApp.__behavior.trash();");
+  } else if (useSandbox) {
+    gasScriptLines.push("ScriptApp.__behavior.sandBoxMode = true;");
+    gasScriptLines.push(`\n\n${scriptText}\n\n`);
+    gasScriptLines.push("ScriptApp.__behavior.trash();");
   } else {
-    if (sandbox && (!whitelistItems || whitelistItems.length === 0)) {
-      gasScriptAr.push(
-        sandbox ? `ScriptApp.__behavior.sandBoxMode = true;` : "",
-        `\n\n${scriptText}\n\n`,
-        sandbox ? `ScriptApp.__behavior.trash();` : ""
-      );
-    } else if (whitelistItems && whitelistItems.length > 0) {
-      const wl = whitelistItems
-        .map((id) => `behavior.newIdWhitelistItem("${id}").setWrite(true)`)
-        .join(",");
-      gasScriptAr.push(
-        `const behavior = ScriptApp.__behavior;`,
-        `behavior.sandboxMode = true;`,
-        `behavior.strictSandbox = true;`,
-        `behavior.setIdWhitelist([${wl}]);``\n\n${scriptText}\n\n`,
-        `ScriptApp.__behavior.trash();`
-      );
-    } else {
-      gasScriptAr.push(scriptText);
-    }
+    gasScriptLines.push(scriptText);
   }
-  const importScriptAr = [
-    `async function runGas() {`,
-    `await import("./main.js");`, // This will trigger the fxInit call
-    ...gasScriptAr,
-    `};`,
-    ``,
-    `runGas();`,
-  ];
-  return {
-    mainScript: importScriptAr.join("\n"),
-    gasScript: gasScriptAr.join("\n"),
-  };
+
+  const gasScript = gasScriptLines.join("\n");
+  const mainScript = [
+    "async function runGas() {",
+    '  await import("./main.js"); // This will trigger the fxInit call',
+    gasScript,
+    "}",
+    "runGas();",
+  ].join("\n");
+
+  return { mainScript, gasScript };
 }
 
-async function loadScript(o) {
-  const { filename, script, display } = o;
+// -----------------------------------------------------------------------------
+// SCRIPT EXECUTION
+// -----------------------------------------------------------------------------
+
+/**
+ * Loads, prepares, and executes the user's Google Apps Script.
+ * @param {object} options The processed CLI options.
+ */
+async function executeGasScript(options) {
+  const {
+    filename,
+    script,
+    display,
+    gfSettings,
+    useSandbox,
+    sandboxConfig,
+    args,
+  } = options;
+
   const scriptText = filename ? fs.readFileSync(filename, "utf8") : script;
-  const { mainScript, gasScript } = __getImportScript({
-    scriptText: scriptText.replace(/\\n/g, "\n"),
-    ...o,
+
+  const { mainScript, gasScript } = generateExecutionScript({
+    scriptText: normalizeScriptNewlines(scriptText),
+    useSandbox,
+    sandboxConfig,
   });
+
   if (display) {
-    console.log(`\n--- script ---\n${gasScript}\n--- /script ---\n`);
+    console.log(
+      `\n--- Generated GAS ---\n${gasScript}\n--- End Generated GAS ---\n`
+    );
   }
-  const gasFunc = new Function(mainScript);
-  // The script needs access to the settings path variable we just created
+
+  // Inject the settings path as a global for the script to access.
   Object.defineProperty(globalThis, "settingsPath", {
-    value: o.gfSettings,
+    value: gfSettings,
     writable: true,
     configurable: true,
   });
-  gasFunc();
+
+  if (args) {
+    const gasFunction = new Function("args", mainScript);
+    await gasFunction(args);
+  } else {
+    const gasFunction = new Function(mainScript);
+    await gasFunction();
+  }
 }
 
-async function mcp_server() {
+// -----------------------------------------------------------------------------
+// MCP SERVER
+// -----------------------------------------------------------------------------
+
+/**
+ * Defines and runs the MCP server for gas-fakes.
+ */
+async function startMcpServer() {
   const server = new McpServer({
     name: "gas-fakes-mcp",
-    version: "0.0.1",
+    version: MCP_VERSION,
   });
 
-  const { name, schema, func } = {
-    name: "run-gas-by-gas-fakes",
-    schema: {
-      description:
-        "Use this to safely run Google Apps Script in a sandbox using gas-fakes.",
-      inputSchema: {
-        script: z.string().describe(`Provide Google Apps Script as a string.`),
-        sandbox: z
-          .boolean()
-          .describe("Use to run Google Apps Script in a sandbox."),
-        whitelist: z
-          .string()
-          .describe(
-            "Use this to use the specific files and folders on Google Drive. whitelist of file IDs. Set the file IDs in comma-separated list. In this case, the files of the file IDs are used for both read and write. When this is used, the script is run in a sandbox."
-          )
-          .optional(),
-        json: z
-          .string()
-          .describe(
-            `Use this to manage the sandbox more if the detailed information about the sandbox is provided. JSON string including parameters for managing a sandbox. Enclose it with ' or ". When this is used, the option "whitelist" is ignored. When this is used, the script is run in a sandbox.`
-          )
-          .optional(),
-      },
-    },
-    func: async (options = {}) => {
-      const { sandbox, whitelist, json } = options;
-      try {
-        const opts = [
-          { v: sandbox, k: "-x" },
-          { v: whitelist, k: "-w" },
-          { v: json, k: "-j" },
-        ].reduce((ar, { v, k }) => {
-          if (v) {
-            ar.push(k != "-x" ? `${k} ${v}` : `${k}`);
-          }
-          return ar;
-        }, []);
-        const scriptArg = JSON.stringify(options.script.toString());
-        const c = `gas-fakes ${opts.join(" ")} -s ${scriptArg.replace(
-          /\\n/g,
-          "\n"
-        )}`;
-        const { stdout } = await execAsync(c);
-        return {
-          content: [{ type: "text", text: stdout || "Done." }],
-          isError: false,
-        };
-      } catch (err) {
-        return {
-          content: [{ type: "text", text: err.message }],
-          isError: true,
-        };
-      }
+  const mcpToolSchema = {
+    description: [
+      `Use this to safely run Google Apps Script in a sandbox using gas-fakes.`,
+      `# Important`,
+      `- Use the extension of the Google Apps Script files as \`js\`. Don't use \`gs\``,
+      `- When you provide the generated Google Apps Script to the tool "gas-fakes" of the MCP server "gas-development-kit-extension", please be careful of the following rule. For example, when you generated a Google Apps Script like \`function sample() { script }\`, please add \`sample();\` to execute the function. Or, you can also create a Google Apps Script without enclosing the script with \`function sample() { script }\`.`,
+    ].join("\n"),
+    inputSchema: {
+      filename: z
+        .string()
+        .describe(
+          `Provide a filename with the path of the file, including Google Apps Script. Write the Google Apps Script into a file and use this.`
+        ),
+      sandbox: z
+        .boolean()
+        .describe("Use to run Google Apps Script in a sandbox."),
+      whitelistRead: z
+        .string()
+        .describe(
+          "Whitelist of file IDs for readonly access (comma-separated). Enables sandbox mode."
+        )
+        .optional(),
+      whitelistReadWrite: z
+        .string()
+        .describe(
+          "Whitelist of file IDs for read/write access (comma-separated). Enables sandbox mode."
+        )
+        .optional(),
+      whitelistReadWriteTrash: z
+        .string()
+        .describe(
+          "Whitelist of file IDs for read/write/trash access (comma-separated). Enables sandbox mode."
+        )
+        .optional(),
+      json: z
+        .object({
+          whitelistItems: z
+            .array(
+              z.object({
+                itemId: z
+                  .string()
+                  .describe("The file or folder ID on Google Drive."),
+                read: z.boolean().optional().default(true),
+                write: z.boolean().optional().default(false),
+                trash: z.boolean().optional().default(false),
+              })
+            )
+            .describe("A list of items to be whitelisted."),
+          whitelistServices: z
+            .array(
+              z.object({
+                className: z
+                  .string()
+                  .describe("The class name of the GAS service."),
+                methodNames: z
+                  .array(z.string())
+                  .describe(
+                    "A list of method names for the class to be whitelisted."
+                  )
+                  .optional(),
+              })
+            )
+            .describe("A list of services to be whitelisted.")
+            .optional(),
+          blacklistServices: z
+            .array(z.string())
+            .describe("A list of GAS services to be blacklisted.")
+            .optional(),
+        })
+        .describe("A JSON object for advanced sandbox configuration.")
+        .optional(),
     },
   };
 
-  server.registerTool(name, schema, func);
+  const mcpToolFunc = async (options = {}) => {
+    const {
+      filename,
+      sandbox,
+      whitelistRead,
+      whitelistReadWrite,
+      whitelistReadWriteTrash,
+      json,
+    } = options;
+
+    if (!filename) {
+      return {
+        content: [
+          { type: "text", text: "Error: `filename` is a required parameter." },
+        ],
+        isError: true,
+      };
+    }
+
+    try {
+      const cliArgs = [];
+      cliArgs.push(`-f "${filename}"`);
+      if (sandbox) cliArgs.push("-x");
+      if (whitelistRead) cliArgs.push(`-w "${whitelistRead}"`);
+      if (whitelistReadWrite) cliArgs.push(`--ww "${whitelistReadWrite}"`);
+      if (whitelistReadWriteTrash)
+        cliArgs.push(`--wt "${whitelistReadWriteTrash}"`);
+      if (json) cliArgs.push(`-j '${JSON.stringify(json)}'`);
+
+      const command = `gas-fakes ${cliArgs.join(" ")}`;
+      const { stdout } = await execAsync(command);
+      return {
+        content: [{ type: "text", text: stdout || "Execution finished." }],
+        isError: false,
+      };
+    } catch (err) {
+      return {
+        content: [{ type: "text", text: err.message }],
+        isError: true,
+      };
+    }
+  };
+
+  server.registerTool("run-gas-by-gas-fakes", mcpToolSchema, mcpToolFunc);
 
   const transport = new StdioServerTransport();
   await server.connect(transport);
 }
+
+// -----------------------------------------------------------------------------
+// CLI DEFINITION & MAIN EXECUTION
+// -----------------------------------------------------------------------------
+
+/**
+ * Parses sandbox-related CLI options into a structured config object.
+ * @param {object} options Raw options from Commander.
+ * @returns {object | undefined} A sandbox configuration object or undefined.
+ */
+function buildSandboxConfig(options) {
+  const { json, whitelistRead, whitelistReadWrite, whitelistReadWriteTrash } =
+    options;
+
+  if (json) {
+    try {
+      return JSON.parse(json);
+    } catch (err) {
+      console.error("Error: Invalid JSON provided to --json option.");
+      process.exit(1);
+    }
+  }
+
+  if (whitelistRead || whitelistReadWrite || whitelistReadWriteTrash) {
+    const config = { whitelistItems: [] };
+    const parseWhitelist = (idString, permissions) => {
+      if (!idString) return;
+      idString.split(",").forEach((id) => {
+        const trimmedId = id.trim();
+        if (trimmedId) {
+          config.whitelistItems.push({ itemId: trimmedId, ...permissions });
+        }
+      });
+    };
+
+    parseWhitelist(whitelistRead, { read: true });
+    parseWhitelist(whitelistReadWrite, { read: true, write: true });
+    parseWhitelist(whitelistReadWriteTrash, {
+      read: true,
+      write: true,
+      trash: true,
+    });
+
+    return config;
+  }
+
+  return undefined;
+}
+
+/**
+ * Sets up and runs the command-line interface.
+ */
+async function main() {
+  const program = new Command();
+
+  program
+    .name("gas-fakes")
+    .description("A CLI tool to execute Google Apps Script with fakes/mocks.")
+    .version(VERSION, "-v, --version", "Display the current version");
+
+  program
+    .description("Execute a Google Apps Script file or string.")
+    .option("-f, --filename <string>", "Path to the Google Apps Script file.")
+    .option(
+      "-s, --script <string>",
+      "A string containing the Google Apps Script."
+    )
+    .option("-e, --env <path>", "Path to a custom .env file.", "./.env")
+    .option(
+      "-g, --gfsettings <path>",
+      "Path to a gasfakes.json settings file.",
+      "./gasfakes.json"
+    )
+    .option("-x, --sandbox", "Run the script in a basic sandbox.")
+    .option(
+      "-w, --whitelistRead <string>",
+      "Comma-separated file IDs for read-only access (enables sandbox)."
+    )
+    .option(
+      "--ww, --whitelistReadWrite <string>",
+      "Comma-separated file IDs for read/write access (enables sandbox)."
+    )
+    .option(
+      "--wt, --whitelistReadWriteTrash <string>",
+      "Comma-separated file IDs for read/write/trash access (enables sandbox)."
+    )
+    .option(
+      "-j, --json <string>",
+      "JSON string for advanced sandbox configuration (overrides whitelist flags)."
+    )
+    .option(
+      "-d, --display",
+      "Display the generated script before execution.",
+      false
+    )
+    .option(
+      "-a, --args <string>",
+      `Arguments for the function of Google Apps Script. Provide it as a JSON string. The name of the argument is "args" as a fixed name. For example, when the function of GAS is \`function sample(args) { script }\`, you can provide the arguments like \`-a '{"key": "value"}'\`.`,
+      null
+    )
+    .action(async (options) => {
+      if (Object.keys(options).length === 0) {
+        program.help();
+        return;
+      }
+
+      const { filename, script, env, gfsettings } = options;
+      if (!filename && !script) {
+        console.error(
+          "Error: You must provide a script via --filename or --script."
+        );
+        process.exit(1);
+      }
+
+      // Load environment variables
+      const envPath = path.resolve(process.cwd(), env);
+      console.log(`...using env file in ${envPath}`);
+      dotenv.config({ path: envPath, quiet: true });
+
+      // Load gasfakes settings
+      const settingsPath = path.resolve(process.cwd(), gfsettings);
+      console.log(`...using gasfakes settings file in ${settingsPath}`);
+      process.env.GF_SETTINGS_PATH = settingsPath;
+
+      const sandboxConfig = buildSandboxConfig(options);
+      const useSandbox = !!options.sandbox || !!sandboxConfig;
+
+      let args = null;
+      if (options.args) {
+        try {
+          args = JSON.parse(options.args);
+        } catch (err) {
+          console.error("Error: Invalid JSON provided to --args option.");
+          process.exit(1);
+        }
+      }
+
+      await executeGasScript({
+        filename,
+        script,
+        display: options.display,
+        useSandbox,
+        sandboxConfig,
+        gfSettings: settingsPath,
+        args,
+      });
+    });
+
+  program
+    .command("mcp")
+    .description("Launch gas-fakes as an MCP server.")
+    .action(startMcpServer);
+
+  program.showHelpAfterError("(add --help for additional information)");
+
+  await program.parseAsync(process.argv);
+}
+
+// Run the main function
+main().catch((err) => {
+  console.error("An unexpected error occurred:", err);
+  process.exit(1);
+});

package/package.json

@@ -30,11 +30,14 @@
   },
   "type": "module",
   "scripts": {
-    "pub": "npm publish --access public"
+    "pub": "npm publish --access public",
+    "includes": "node ./doccreation/include-docs.js",
+    "progress": "cd ./doccreation && bash pipeline.sh",
+    "docs": "npm run includes && npm run progress"
   },
   "name": "@mcpher/gas-fakes",
   "author": "bruce mcpherson",
-  "version": "1.2.9",
+  "version": "1.2.11",
   "license": "MIT",
   "main": "main.js",
   "description": "A proof of concept implementation of Apps Script Environment on Node",

package/src/index.js

@@ -22,5 +22,6 @@ import './services/advforms/app.js'
 import './services/formapp/app.js'
 import './services/slidesapp/app.js'
 import './services/mimetype/app.js'
+import './services/lock/app.js'
 // should be last
 import './services/stores/app.js'

package/src/services/lock/app.js

@@ -0,0 +1,11 @@
+
+
+/**
+ * the idea here is to create an empty global entry for the singleton
+ * but only load it when it is actually used.
+ */
+import { newFakeLockService as maker } from './fakelockservice.js';
+import { lazyLoaderApp } from '../common/lazyloader.js'
+
+let _app = null;
+_app = lazyLoaderApp(_app, 'LockService', maker)

package/src/services/lock/fakelock.js

@@ -0,0 +1,65 @@
+import { Proxies } from '../../support/proxies.js';
+
+
+/**
+ * the lock service us meaningless here as we are running on node single threaded
+ * in apps script this would lock shared code that was being shared by multiple scripts
+ * so this is all provided for compatibility only
+ */
+class FakeLock {
+  constructor(domain) {
+    this.__fakeObjectType = 'Lock';
+    this.__domain = domain
+    this.__locked = false;
+  }
+
+  /**
+   * Returns true if the lock was acquired.
+   * @returns {boolean}
+   */
+  hasLock() {
+    return this.__locked;
+  }
+
+  /**
+   * Releases the lock.
+   */
+  releaseLock() {
+    this.__locked = false;
+  }
+
+  /**
+   * Attempts to acquire the lock.
+   * @param {number} timeoutInMillis 
+   * @returns {boolean}
+   */
+  tryLock(timeoutInMillis) {
+    if (this.hasLock()) {
+      return true;
+    }
+    // In a single-threaded fake, we can't wait. We fail only if timeout is negative.
+    if (timeoutInMillis < 0) {
+      return false;
+    }
+    this.__locked = true;
+    return true;
+  }
+
+  /**
+   * Attempts to acquire the lock, throwing an exception on timeout.
+   * @param {number} timeoutInMillis 
+   */
+  waitLock(timeoutInMillis) {
+    if (this.hasLock()) {
+      return; // Already acquired, no need to wait
+    }
+    // In a single-threaded fake, we can't wait. We fail only if timeout is negative.
+    if (timeoutInMillis < 0) {
+      throw new Error(`Lock timeout: another process was holding the lock for too long.`);
+    }
+    this.__locked = true;
+  }
+}
+
+
+export const newFakeLock = (...args) => Proxies.guard(new FakeLock(...args));

package/src/services/lock/fakelockservice.js

@@ -0,0 +1,37 @@
+import { Proxies } from '../../support/proxies.js';
+import { newFakeLock } from './fakelock.js';
+
+/**
+ * domains of lock supported
+ * @enum {string}
+ */
+const LockDomain = Object.freeze({
+  SCRIPT: 'SCRIPT',
+  USER: 'USER',
+  DOCUMENT: 'DOCUMENT'
+})
+/**
+ * the lock service us meaningless here as we are running on node single threaded
+ * in apps script this would lock shared code that was being shared by multiple scripts
+ * so this is all provided for compatibility only
+ */
+class FakeLockService {
+  constructor() {
+    this.__fakeObjectType = 'LockService';
+  }
+  getDocumentLock () {
+    // Per documentation, this should return null if not in the context of a document.
+    if (ScriptApp.__documentId) {
+      return newFakeLock(LockDomain.DOCUMENT);
+    }
+    return null;
+  }
+  getUserLock () {
+    return newFakeLock(LockDomain.USER) 
+  }
+  getScriptLock () {
+    return newFakeLock(LockDomain.SCRIPT)
+  }
+}
+
+export const newFakeLockService = (...args) => Proxies.guard(new FakeLockService(...args));

package/src/services/spreadsheetapp/fakespreadsheet.js

@@ -42,7 +42,7 @@ export class FakeSpreadsheet {
     const props = [
       "getSpreadsheetTheme",
       "setActiveSheet",
-      "getActiveSheet",
+
       "getBandings",
       "getDataSources",
       "addCollaborator",
@@ -171,8 +171,17 @@ export class FakeSpreadsheet {
         return notYetImplemented(f);
       };
     });
+
+  }
+
+  // note this is a workaround as we don't have the concept of active sheet in a non bound document
+  // so instead we'll just get the first sheet for now
+  // TODO - something better
+  getActiveSheet() {
+    return this.__getFirstSheet();
   }
 
+  
   addDeveloperMetadata(key, value, visibility) {
     const { nargs, matchThrow } = signatureArgs(
       arguments,