@google/clasp 3.0.6-alpha → 3.1.1

package/build/src/experiments.js

@@ -1,3 +1,26 @@
+// Copyright 2025 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+// This file provides functionality for managing experimental features in clasp
+// through environment variables, allowing features to be toggled on or off.
+/**
+ * Checks if an experimental feature is enabled via environment variables.
+ * The environment variable is expected to be in the format `CLASP_EXPERIMENT_NAME_IN_UPPERCASE`.
+ * Truthy values are 'true' (case-insensitive) or '1'.
+ * @param {string} experimentName - The name of the experiment (e.g., "enable_user_hints").
+ * @param {boolean} [defaultValue=false] - The default value if the environment variable is not set.
+ * @returns {boolean} True if the experiment is enabled, false otherwise.
+ */
 export function isEnabled(experimentName, defaultValue = false) {
     const envVarName = `CLASP_${experimentName.toUpperCase()}`;
     const envVarValue = process.env[envVarName];

package/build/src/index.js

@@ -1,4 +1,6 @@
 #!/usr/bin/env node
+// This file is the main entry point for the clasp CLI. It sets up the command
+// parsing, executes the appropriate command, and handles top-level errors.
 /**
  * @license
  * Copyright Google Inc.

package/build/src/intl.js

@@ -1,3 +1,19 @@
+// Copyright 2025 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+// This file sets up internationalization (i18n) for the clasp CLI using
+// @formatjs/intl. It detects the user's locale and provides an `intl`
+// object for formatting localized messages.
 import { createIntl, createIntlCache } from '@formatjs/intl';
 import Debug from 'debug';
 const debug = Debug('clasp:intl');
@@ -27,6 +43,18 @@ const cache = createIntlCache();
 const locale = getLocale();
 const localTimeZone = Intl.DateTimeFormat().resolvedOptions().timeZone;
 debug('Using locale: %s', locale);
+/**
+ * Internationalization instance configured with the user's detected locale
+ * (or 'en' as default). This object is used for formatting localized messages,
+ * dates, numbers, etc., throughout the application.
+ * It is created using `@formatjs/intl`.
+ *
+ * Example usage:
+ * ```
+ * import {intl} from './intl.js';
+ * const message = intl.formatMessage({defaultMessage: "Hello, world!"});
+ * ```
+ */
 export const intl = createIntl({
     // Locale of the application
     locale,

package/build/src/mcp/server.js

@@ -1,3 +1,19 @@
+// Copyright 2025 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+// This file builds and configures a Model Context Protocol (MCP) server
+// that exposes clasp functionalities (like push, pull, create, clone, list)
+// as remotely callable tools for programmatic interaction.
 import path from 'path';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { mkdir } from 'fs/promises';
@@ -5,6 +21,24 @@ import { z } from 'zod';
 import { getDefaultProjectName } from '../commands/create-script.js';
 import { getVersion } from '../commands/program.js';
 import { initClaspInstance } from '../core/clasp.js';
+/**
+ * Builds and configures an MCP (Model Context Protocol) server with tools
+ * for interacting with Google Apps Script projects via clasp functionalities.
+ *
+ * The server exposes tools such as:
+ * - `push_files`: Pushes local project files to the remote Apps Script project.
+ * - `pull_files`: Pulls remote Apps Script project files to the local filesystem.
+ * - `create_project`: Creates a new Apps Script project.
+ * - `clone_project`: Clones an existing Apps Script project to a local directory.
+ * - `list_projects`: Lists Apps Script projects accessible to the authenticated user.
+ *
+ * Each tool is defined with a description, input schema (using Zod),
+ * and an asynchronous handler that executes the corresponding clasp logic.
+ *
+ * @param {AuthInfo} auth - Authentication information containing the OAuth2 credentials
+ *                          required by clasp to interact with Google APIs.
+ * @returns {McpServer} The configured MCP server instance.
+ */
 export function buildMcpServer(auth) {
     const server = new McpServer({
         name: 'Clasp',
@@ -21,6 +55,7 @@ export function buildMcpServer(auth) {
         idempotentHint: false,
         readOnlyHint: false,
     }, async ({ projectDir }) => {
+        // Validate required input.
         if (!projectDir) {
             return {
                 isError: true,
@@ -32,20 +67,24 @@ export function buildMcpServer(auth) {
                 ],
             };
         }
+        // Initialize a Clasp instance scoped to the provided project directory.
         const clasp = await initClaspInstance({
             credentials: auth.credentials,
-            configFile: projectDir,
-            rootDir: projectDir,
+            configFile: projectDir, // Tells initClaspInstance to look for .clasp.json in this dir.
+            rootDir: projectDir, // Fallback root if .clasp.json isn't immediately found.
         });
         try {
+            // Execute the push operation.
             const files = await clasp.files.push();
+            // Format the list of pushed files for the MCP response.
             const fileList = files.map(file => ({
                 type: 'text',
                 text: `Updated file: ${path.resolve(file.localPath)}`,
             }));
             return {
-                status: 'success',
+                status: 'success', // Indicate successful execution.
                 content: [
+                    // Human-readable output.
                     {
                         type: 'text',
                         text: `Pushed project in ${projectDir} to remote server successfully.`,
@@ -53,6 +92,7 @@ export function buildMcpServer(auth) {
                     ...fileList,
                 ],
                 structuredContent: {
+                    // Machine-readable output.
                     scriptId: clasp.project.scriptId,
                     projectDir: projectDir,
                     files: files.map(file => path.resolve(file.localPath)),
@@ -60,6 +100,7 @@ export function buildMcpServer(auth) {
             };
         }
         catch (err) {
+            // Handle errors during the push operation.
             return {
                 isError: true,
                 content: [
@@ -82,6 +123,7 @@ export function buildMcpServer(auth) {
         idempotentHint: false,
         readOnlyHint: false,
     }, async ({ projectDir }) => {
+        // Validate required input.
         if (!projectDir) {
             return {
                 isError: true,
@@ -93,19 +135,23 @@ export function buildMcpServer(auth) {
                 ],
             };
         }
+        // Initialize a Clasp instance for the specified project directory.
         const clasp = await initClaspInstance({
             credentials: auth.credentials,
             configFile: projectDir,
             rootDir: projectDir,
         });
         try {
+            // Execute the pull operation.
             const files = await clasp.files.pull();
+            // Format the list of pulled files for the MCP response.
             const fileList = files.map(file => ({
                 type: 'text',
                 text: `Updated file: ${path.resolve(file.localPath)}`,
             }));
             return {
                 content: [
+                    // Human-readable output.
                     {
                         type: 'text',
                         text: `Pushed project in ${projectDir} to remote server successfully.`,
@@ -113,6 +159,7 @@ export function buildMcpServer(auth) {
                     ...fileList,
                 ],
                 structuredContent: {
+                    // Machine-readable output.
                     scriptId: clasp.project.scriptId,
                     projectDir: projectDir,
                     files: files.map(file => path.resolve(file.localPath)),
@@ -120,6 +167,7 @@ export function buildMcpServer(auth) {
             };
         }
         catch (err) {
+            // Handle errors during the pull operation.
             return {
                 isError: true,
                 content: [
@@ -148,6 +196,7 @@ export function buildMcpServer(auth) {
         idempotentHint: false,
         readOnlyHint: false,
     }, async ({ projectDir, sourceDir, projectName }) => {
+        // Validate required input.
         if (!projectDir) {
             return {
                 isError: true,
@@ -159,19 +208,27 @@ export function buildMcpServer(auth) {
                 ],
             };
         }
+        // Ensure the project directory exists.
         await mkdir(projectDir, { recursive: true });
+        // If projectName is not provided, infer it from the project directory name.
         if (!projectName) {
             projectName = getDefaultProjectName(projectDir);
         }
+        // Initialize a Clasp instance. Since it's a new project,
+        // .clasp.json might not exist yet, so rootDir helps locate where it would be.
         const clasp = await initClaspInstance({
             credentials: auth.credentials,
-            configFile: projectDir,
+            configFile: projectDir, // Will look for .clasp.json here or create it.
             rootDir: projectDir,
         });
-        clasp.withContentDir(sourceDir !== null && sourceDir !== void 0 ? sourceDir : '.');
+        // Set the content directory (where .js, .html files will go) if specified.
+        clasp.withContentDir(sourceDir !== null && sourceDir !== void 0 ? sourceDir : '.'); // Defaults to projectDir if sourceDir is not given.
         try {
+            // Create the new Apps Script project remotely.
             const id = await clasp.project.createScript(projectName);
+            // Pull the initial files (e.g., appsscript.json, Code.js) from the new project.
             const files = await clasp.files.pull();
+            // Write the .clasp.json file with the new script ID and other settings.
             await clasp.project.updateSettings();
             const fileList = files.map(file => ({
                 type: 'text',
@@ -179,6 +236,7 @@ export function buildMcpServer(auth) {
             }));
             return {
                 content: [
+                    // Human-readable output.
                     {
                         type: 'text',
                         text: `Created project ${id} in ${projectDir} successfully.`,
@@ -186,6 +244,7 @@ export function buildMcpServer(auth) {
                     ...fileList,
                 ],
                 structuredContent: {
+                    // Machine-readable output.
                     scriptId: id,
                     projectDir: projectDir,
                     files: files.map(file => path.resolve(file.localPath)),
@@ -193,6 +252,7 @@ export function buildMcpServer(auth) {
             };
         }
         catch (err) {
+            // Handle errors during project creation or initial pull.
             return {
                 isError: true,
                 content: [
@@ -218,6 +278,7 @@ export function buildMcpServer(auth) {
         idempotentHint: false,
         readOnlyHint: false,
     }, async ({ projectDir, sourceDir, scriptId }) => {
+        // Validate required inputs.
         if (!projectDir) {
             return {
                 isError: true,
@@ -229,8 +290,10 @@ export function buildMcpServer(auth) {
                 ],
             };
         }
+        // Ensure the local project directory exists.
         await mkdir(projectDir, { recursive: true });
         if (!scriptId) {
+            // Script ID is essential for cloning.
             return {
                 isError: true,
                 content: [
@@ -241,14 +304,18 @@ export function buildMcpServer(auth) {
                 ],
             };
         }
+        // Initialize Clasp instance for the new local project directory.
         const clasp = await initClaspInstance({
             credentials: auth.credentials,
             configFile: projectDir,
             rootDir: projectDir,
         });
+        // Configure the Clasp instance with the target script ID and content directory.
         clasp.withContentDir(sourceDir !== null && sourceDir !== void 0 ? sourceDir : '.').withScriptId(scriptId);
         try {
+            // Pull files from the specified remote script ID.
             const files = await clasp.files.pull();
+            // Create/update the .clasp.json file with the cloned script's ID and settings.
             clasp.project.updateSettings();
             const fileList = files.map(file => ({
                 type: 'text',
@@ -256,6 +323,7 @@ export function buildMcpServer(auth) {
             }));
             return {
                 content: [
+                    // Human-readable output.
                     {
                         type: 'text',
                         text: `Cloned project ${scriptId} in ${projectDir} successfully.`,
@@ -263,6 +331,7 @@ export function buildMcpServer(auth) {
                     ...fileList,
                 ],
                 structuredContent: {
+                    // Machine-readable output.
                     scriptId: scriptId,
                     projectDir: projectDir,
                     files: files.map(file => path.resolve(file.localPath)),
@@ -270,6 +339,7 @@ export function buildMcpServer(auth) {
             };
         }
         catch (err) {
+            // Handle errors during cloning.
             return {
                 isError: true,
                 content: [
@@ -288,17 +358,21 @@ export function buildMcpServer(auth) {
         idempotentHint: false,
         readOnlyHint: false,
     }, async () => {
+        // Initialize a Clasp instance (doesn't need a specific project directory for listing).
         const clasp = await initClaspInstance({
             credentials: auth.credentials,
         });
         try {
+            // Fetch the list of scripts.
             const scripts = await clasp.project.listScripts();
+            // Format the script list for the MCP response.
             const scriptList = scripts.results.map(script => ({
                 type: 'text',
-                text: `${script.name} (${script.id})`,
+                text: `${script.name} (${script.id})`, // Display name and ID.
             }));
             return {
                 content: [
+                    // Human-readable output.
                     {
                         type: 'text',
                         text: `Found ${scripts.results.length} Apps Script projects (script ID in parentheses):`,
@@ -306,6 +380,7 @@ export function buildMcpServer(auth) {
                     ...scriptList,
                 ],
                 structuredContent: {
+                    // Machine-readable output.
                     scripts: scripts.results.map(script => ({
                         scriptId: script.id,
                         name: script.name,
@@ -314,6 +389,7 @@ export function buildMcpServer(auth) {
             };
         }
         catch (err) {
+            // Handle errors during listing.
             return {
                 isError: true,
                 content: [

package/docs/run.md

@@ -24,11 +24,17 @@ To use `clasp run`, you need to complete 5 steps:
 1. Add a `projectId` to your `.clasp.json`. You can find your Project ID via:
     - [Create a GCP project](https://cloud.google.com/resource-manager/docs/creating-managing-projects)
     - Record the `Project ID` and `Project number`. (Example: `my-sample-project-191923.` and `314053285323`)
-    - Run the command with your `Project ID`: `clasp setting projectId <PROJECT_ID>`
+    - Manually add the `Project ID` to your `.clasp.json` file.
+      ```json
+      {
+        "scriptId": "...",
+        "projectId": "my-sample-project-191923"
+      }
+      ```
 1. Set the `projectId` to your Apps Script project
     - Open `https://console.developers.google.com/apis/credentials/consent?project=[PROJECT_ID]`
     - Set `Application name` to `clasp project` and click `save`.
-    - Run `clasp open`
+    - Run `clasp open-script`
     - In the menu, click `⚙️ Project Settings > Google Cloud Platform (GCP) Project`
     - If the `Project Number` is missing,
       - Click `Change Project`, paste the PROJECT_NUMBER, and click `Set project`
@@ -61,7 +67,7 @@ After setup, you can remotely execute Apps Script functions from `clasp`:
 
 If you get an "Script API executable not published/deployed." error, deploy your script as an API Executable:
 
-- Run `clasp open`
+- Run `clasp open-script`
 - Click `Deploy > New deployment`
 - Select type ⚙ > API Executable
 - Type a `Description`
@@ -73,7 +79,7 @@ Many Apps Script functions require special OAuth Scopes (Gmail, Drive, etc.).
 
 To run functions that use these scopes, you must add the scopes to your Apps Script manifest and `clasp login` again.
 
-- `clasp open`
+- `clasp open-script`
 - `File > Project Properties > Scopes`
 - Add these [scopes to your `appsscript.json`](https://developers.google.com/apps-script/concepts/scopes#set-explicit).
 - Log in again: `clasp login --user <name> --use-project-scopes --creds creds.json`. This will add these scopes to your credentials.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@google/clasp",
-  "version": "3.0.6-alpha",
+  "version": "3.1.1",
   "description": "Develop Apps Script Projects locally",
   "type": "module",
   "exports": "./build/src/index.js",
@@ -22,7 +22,7 @@
     "prepare": "npm run compile",
     "lint": "npm run check",
     "test": "mocha",
-    "test:coverage": "c8 mocha",
+    "test:coverage": "c8 --reports-dir coverage --reporter=text --reporter=html --reporter=lcov mocha",
     "prettier": "biome format src test --write",
     "check": "biome check src test && npm run compile",
     "clean": "rm -rf build",
@@ -56,6 +56,7 @@
   "license": "Apache-2.0",
   "dependencies": {
     "@formatjs/intl": "^3.1.6",
+    "@modelcontextprotocol/sdk": "^1.12.1",
     "chalk": "^5.4.1",
     "chokidar": "^4.0.3",
     "cli-truncate": "^4.0.0",
@@ -72,7 +73,6 @@
     "inquirer-autocomplete-standalone": "^0.8.1",
     "loud-rejection": "^2.2.0",
     "micromatch": "^4.0.8",
-    "@modelcontextprotocol/sdk": "^1.12.1",
     "normalize-path": "^3.0.0",
     "open": "^10.1.2",
     "ora": "^8.1.1",