@google/clasp 3.0.6-alpha → 3.1.0

package/build/src/commands/push.js

@@ -1,3 +1,17 @@
+// Copyright 2019 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 defines the 'push' command for the clasp CLI.
 import path from 'path';
 import { Command } from 'commander';
 import inquirer from 'inquirer';
@@ -7,48 +21,74 @@ export const command = new Command('push')
     .description('Update the remote project')
     .option('-f, --force', 'Forcibly overwrites the remote manifest.')
     .option('-w, --watch', 'Watches for local file changes. Pushes when a non-ignored file changes.')
-    .action(async function (options) {
-    const clasp = this.opts().clasp;
+    .action(async function () {
+    const options = this.optsWithGlobals();
+    const clasp = options.clasp;
     const watch = options.watch;
-    let force = options.force;
+    let force = options.force; // Store the force option, as it can be updated by confirmManifestUpdate
+    // Defines the action to take when a file change is detected (either initially or during watch mode).
     const onChange = async (paths) => {
+        // Check if the manifest file (appsscript.json) is among the changed files.
         const isManifestUpdated = paths.findIndex(p => path.basename(p) === 'appsscript.json') !== -1;
+        // If the manifest is updated and not using --force, prompt the user for confirmation.
         if (isManifestUpdated && !force) {
-            force = await confirmManifestUpdate();
+            force = await confirmManifestUpdate(); // Update force based on user's choice.
             if (!force) {
-                const msg = intl.formatMessage({ id: "TItFfu", defaultMessage: [{ type: 0, value: "Skipping push." }] });
-                console.log(msg);
-                return;
+                // If user declines manifest overwrite, skip the push.
+                if (!options.json) {
+                    const msg = intl.formatMessage({ id: "TItFfu", defaultMessage: [{ type: 0, value: "Skipping push." }] });
+                    console.log(msg);
+                }
+                return; // Exit onChange without pushing.
             }
         }
         const spinnerMsg = intl.formatMessage({ id: "qUq++d", defaultMessage: [{ type: 0, value: "Pushing files..." }] });
+        // Perform the push operation using the core `clasp.files.push()` method.
         const files = await withSpinner(spinnerMsg, async () => {
-            return await clasp.files.push();
+            return clasp.files.push();
         });
+        if (options.json) {
+            console.log(JSON.stringify(files.map(f => f.localPath), null, 2));
+            return;
+        }
+        // Log the result of the push.
         const successMessage = intl.formatMessage({ id: "aD3XSt", defaultMessage: [{ type: 0, value: "Pushed " }, { type: 6, value: "count", options: { "=0": { value: [{ type: 0, value: "no files." }] }, one: { value: [{ type: 0, value: "one file." }] }, other: { value: [{ type: 7 }, { type: 0, value: " files" }] } }, offset: 0, pluralType: "cardinal" }, { type: 0, value: "." }] }, {
             count: files.length,
         });
         console.log(successMessage);
         files.forEach(f => console.log(`└─ ${f.localPath}`));
-        return true;
+        return true; // Indicate that the push was attempted (or successfully skipped by user).
     };
+    // Initial check for pending changes when the command is first run.
     const pendingChanges = await clasp.files.getChangedFiles();
     if (pendingChanges.length) {
+        // If there are changes, map them to their paths and call onChange.
         const paths = pendingChanges.map(f => f.localPath);
         await onChange(paths);
     }
     else {
+        if (options.json) {
+            console.log(JSON.stringify([], null, 2));
+            return;
+        }
+        // If no changes, inform the user.
         const msg = intl.formatMessage({ id: "X/QgBZ", defaultMessage: [{ type: 0, value: "Script is already up to date." }] });
         console.log(msg);
     }
+    // If not in watch mode, exit after the initial push attempt.
     if (!watch) {
         return;
     }
+    // Setup for watch mode.
     const onReady = async () => {
         const msg = intl.formatMessage({ id: "m/C0lF", defaultMessage: [{ type: 0, value: "Waiting for changes..." }] });
         console.log(msg);
     };
+    // Start watching local files. The `onChange` function will be called on subsequent changes.
+    // `watchLocalFiles` returns a function to stop the watcher.
     const stopWatching = await clasp.files.watchLocalFiles(onReady, async (paths) => {
+        // If onChange returns undefined (e.g. user skipped manifest push), it implies we should stop watching.
+        // This can happen if the user cancels the manifest push in interactive mode.
         if (!(await onChange(paths))) {
             stopWatching();
         }

package/build/src/commands/run-function.js

@@ -1,3 +1,17 @@
+// 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 defines the 'run-function' (alias 'run') command for the clasp CLI.
 import chalk from 'chalk';
 import { Command } from 'commander';
 import fuzzy from 'fuzzy';
@@ -10,52 +24,81 @@ export const command = new Command('run-function')
     .argument('[functionName]', 'The name of the function to run')
     .option('--nondev', 'Run script function in non-devMode')
     .option('-p, --params <value>', 'Parameters to pass to the function, as a JSON-encoded array')
-    .action(async function (functionName, options) {
-    var _a, _b;
-    const clasp = this.opts().clasp;
+    .action(async function (functionName) {
+    var _a, _b, _c;
+    const options = this.optsWithGlobals();
+    const clasp = options.clasp;
     const devMode = !options.nondev; // Defaults to true
     let params = [];
     if (options.params) {
+        // Parameters for the function are expected to be a JSON-encoded array.
         params = JSON.parse(options.params);
     }
+    // If no function name is provided and the session is interactive,
+    // fetch all function names from the project and prompt the user to select one.
     if (!functionName && isInteractive()) {
         const allFunctions = await clasp.functions.getFunctionNames();
+        // `inquirer-autocomplete-standalone` provides a fuzzy-searchable list.
         const source = async (input = '') => fuzzy.filter(input, allFunctions).map(element => ({
-            value: element.original,
+            value: element.original, // The original function name is the value.
         }));
         const prompt = intl.formatMessage({ id: "Y8u3Vb", defaultMessage: [{ type: 0, value: "Selection a function name" }] });
         functionName = await autocomplete({
             message: prompt,
-            source,
+            source, // Source function for the autocomplete.
         });
     }
+    // Attempt to run the function.
     try {
-        const { error, response } = await withSpinner(`Running function: ${functionName}`, async () => {
-            return await clasp.functions.runFunction(functionName, params, devMode);
+        // `clasp.functions.runFunction` calls the Apps Script API.
+        const result = await withSpinner(`Running function: ${functionName}`, async () => {
+            return clasp.functions.runFunction(functionName, params, devMode);
         });
-        if (error && error.details) {
-            const { errorMessage, scriptStackTraceElements } = error.details[0];
+        if (options.json) {
+            const output = {
+                response: (_a = result.response) === null || _a === void 0 ? void 0 : _a.result,
+                error: result.error
+                    ? {
+                        code: result.error.code,
+                        message: result.error.message,
+                        details: result.error.details,
+                    }
+                    : undefined,
+            };
+            console.log(JSON.stringify(output, null, 2));
+            return;
+        }
+        // Handle the API response.
+        if (result.error && result.error.details) {
+            // If the API returned an error in the `error.details` field (common for script execution errors).
+            const { errorMessage, scriptStackTraceElements } = result.error.details[0];
             const msg = intl.formatMessage({ id: "1l462L", defaultMessage: [{ type: 0, value: "Exception:" }] });
             console.error(`${chalk.red(msg)}`, errorMessage, scriptStackTraceElements || []);
             return;
         }
-        if (response && response.result !== undefined) {
-            console.log(response.result);
+        if (result.response && result.response.result !== undefined) {
+            // If the function executed successfully and returned a result.
+            console.log(result.response.result);
         }
         else {
+            // If the function execution didn't produce a result or an error in the expected format.
             const msg = intl.formatMessage({ id: "S/0IKk", defaultMessage: [{ type: 0, value: "No response." }] });
             console.log(chalk.red(msg));
         }
     }
     catch (error) {
-        if (((_a = error.cause) === null || _a === void 0 ? void 0 : _a.code) === 'NOT_AUTHORIZED') {
+        // Handle errors thrown by `clasp.functions.runFunction` or other issues.
+        if (((_b = error.cause) === null || _b === void 0 ? void 0 : _b.code) === 'NOT_AUTHORIZED') {
+            // Specific error for lack of permissions.
             const msg = intl.formatMessage({ id: "HZmND2", defaultMessage: [{ type: 0, value: "Unable to run script function. Please make sure you have permission to run the script function." }] });
             this.error(msg);
         }
-        if (((_b = error.cause) === null || _b === void 0 ? void 0 : _b.code) === 'NOT_FOUND') {
+        if (((_c = error.cause) === null || _c === void 0 ? void 0 : _c.code) === 'NOT_FOUND') {
+            // Specific error if the function or script (as API executable) is not found.
             const msg = intl.formatMessage({ id: "4wxpit", defaultMessage: [{ type: 0, value: "Script function not found. Please make sure script is deployed as API executable." }] });
             this.error(msg);
         }
+        // Re-throw other errors to be caught by the global error handler.
         throw error;
     }
 });

package/build/src/commands/setup-logs.js

@@ -1,12 +1,31 @@
+// 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 defines the 'setup-logs' command for the clasp CLI.
 import { Command } from 'commander';
 import { intl } from '../intl.js';
 import { assertGcpProjectConfigured, isInteractive, maybePromptForProjectId } from './utils.js';
 export const command = new Command('setup-logs').description('Setup Cloud Logging').action(async function () {
-    const clasp = this.opts().clasp;
+    const options = this.optsWithGlobals();
+    const clasp = options.clasp;
     if (!clasp.project.projectId && isInteractive()) {
         await maybePromptForProjectId(clasp);
     }
     assertGcpProjectConfigured(clasp);
+    if (options.json) {
+        console.log(JSON.stringify({ success: true }, null, 2));
+        return;
+    }
     const successMessage = intl.formatMessage({ id: "mrsf6I", defaultMessage: [{ type: 0, value: "Script logs are now available in Cloud Logging." }] });
     console.log(successMessage);
 });

package/build/src/commands/show-authorized-user.js

@@ -1,16 +1,43 @@
+// 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 defines the 'show-authorized-user' command for the clasp CLI.
 import { Command } from 'commander';
 import { getUserInfo } from '../auth/auth.js';
 import { intl } from '../intl.js';
 export const command = new Command('show-authorized-user')
     .description('Show information about the current authorizations state.')
     .action(async function () {
-    const auth = this.opts().auth;
+    var _a;
+    const options = this.optsWithGlobals();
+    const auth = options.authInfo;
+    let user = undefined;
+    if (auth.credentials) {
+        user = await getUserInfo(auth.credentials);
+    }
+    if (options.json) {
+        const output = {
+            loggedIn: auth.credentials ? true : false,
+            email: (_a = user === null || user === void 0 ? void 0 : user.email) !== null && _a !== void 0 ? _a : undefined,
+        };
+        console.log(JSON.stringify(output, null, 2));
+        return;
+    }
     if (!auth.credentials) {
         const msg = intl.formatMessage({ id: "ZqMsgV", defaultMessage: [{ type: 0, value: "Not logged in." }] });
         console.log(msg);
         return;
     }
-    const user = await getUserInfo(auth.credentials);
     const msg = intl.formatMessage({ id: "sZ9k34", defaultMessage: [{ type: 5, value: "email", options: { undefined: { value: [{ type: 0, value: "You are logged in as an unknown user." }] }, other: { value: [{ type: 0, value: "You are logged in as " }, { type: 1, value: "email" }, { type: 0, value: "." }] } } }] }, {
         email: user === null || user === void 0 ? void 0 : user.email,
     });

package/build/src/commands/show-file-status.js

@@ -1,12 +1,27 @@
+// 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 defines the 'show-file-status' (alias 'status') command for the
+// clasp CLI.
 import { Command } from 'commander';
 import { intl } from '../intl.js';
 import { withSpinner } from './utils.js';
 export const command = new Command('show-file-status')
     .alias('status')
     .description('Lists files that will be pushed by clasp')
-    .option('--json', 'Show status in JSON form')
-    .action(async function (options) {
+    .action(async function () {
     var _a;
+    const options = this.optsWithGlobals();
     const clasp = this.opts().clasp;
     const outputAsJson = (_a = options === null || options === void 0 ? void 0 : options.json) !== null && _a !== void 0 ? _a : false;
     const spinnerMsg = intl.formatMessage({ id: "3pOneN", defaultMessage: [{ type: 0, value: "Analyzing project files..." }] });

package/build/src/commands/start-mcp.js

@@ -1,3 +1,18 @@
+// 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 defines the 'start-mcp-server' (alias 'mcp') command for the
+// clasp CLI.
 import { Command } from 'commander';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { buildMcpServer } from '../mcp/server.js';
@@ -5,7 +20,8 @@ export const command = new Command('start-mcp-server')
     .alias('mcp')
     .description('Starts an MCP server for interacting with apps script.')
     .action(async function () {
-    const auth = this.opts().auth;
+    const options = this.optsWithGlobals();
+    const auth = options.authInfo;
     const server = buildMcpServer(auth);
     const transport = new StdioServerTransport();
     await server.connect(transport);

package/build/src/commands/tail-logs.js

@@ -1,15 +1,29 @@
+// 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 defines the 'tail-logs' (alias 'logs') command for the clasp CLI.
 import chalk from 'chalk';
 import { Command } from 'commander';
 import { intl } from '../intl.js';
-import { assertGcpProjectConfigured, isInteractive, maybePromptForProjectId, withSpinner } from './utils.js';
+import { assertGcpProjectConfigured, isInteractive, maybePromptForProjectId, withSpinner, } from './utils.js';
 export const command = new Command('tail-logs')
     .alias('logs')
     .description('Print the most recent log entries')
-    .option('--json', 'Show logs in JSON form')
     .option('--watch', 'Watch and print new logs')
     .option('--simplified', 'Hide timestamps with logs')
-    .action(async function (options) {
-    const clasp = this.opts().clasp;
+    .action(async function () {
+    const options = this.optsWithGlobals();
+    const clasp = options.clasp;
     const { json, simplified, watch } = options;
     const seenEntries = new Set();
     let since;
@@ -86,7 +100,8 @@ function formatEntry(entry, options) {
             return undefined;
         }
     }
-    const coloredSeverity = `${severityColor[severity](severity) || severity}`.padEnd(20);
+    const colorizer = severityColor[severity];
+    const coloredSeverity = `${colorizer ? colorizer(severity) : severity}`.padEnd(20);
     functionName = functionName.padEnd(15);
     payloadData = payloadData.padEnd(20);
     const localizedTime = getLocalISODateTime(new Date(timestamp));

package/build/src/commands/update-deployment.js

@@ -1,3 +1,18 @@
+// 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 defines the 'update-deployment' (alias 'redeploy') command for
+// the clasp CLI.
 import { Command } from 'commander';
 import { intl } from '../intl.js';
 import { withSpinner } from './utils.js';
@@ -7,9 +22,11 @@ export const command = new Command('update-deployment')
     .description('Updates a deployment for a project to a new version')
     .option('-V, --versionNumber <version>', 'The project version')
     .option('-d, --description <description>', 'The deployment description')
-    .action(async function (deploymentId, options) {
-    var _a, _b, _c;
-    const clasp = this.opts().clasp;
+    .option('--json', 'Show output in JSON format')
+    .action(async function (deploymentId) {
+    var _a, _b, _c, _d, _e;
+    const options = this.optsWithGlobals();
+    const clasp = options.clasp;
     const description = (_a = options.description) !== null && _a !== void 0 ? _a : '';
     const versionNumber = options.versionNumber ? Number(options.versionNumber) : undefined;
     if (!deploymentId) {
@@ -19,16 +36,25 @@ export const command = new Command('update-deployment')
     try {
         const spinnerMsg = intl.formatMessage({ id: "oL8t7p", defaultMessage: [{ type: 0, value: "Deploying project..." }] });
         const deployment = await withSpinner(spinnerMsg, async () => {
-            return await clasp.project.deploy(description, deploymentId, versionNumber);
+            return clasp.project.deploy(description, deploymentId, versionNumber);
         });
+        if (options.json) {
+            const output = {
+                deploymentId: deployment.deploymentId,
+                versionNumber: (_b = deployment.deploymentConfig) === null || _b === void 0 ? void 0 : _b.versionNumber,
+                description: (_c = deployment.deploymentConfig) === null || _c === void 0 ? void 0 : _c.description,
+            };
+            console.log(JSON.stringify(output, null, 2));
+            return;
+        }
         const successMessage = intl.formatMessage({ id: "wWBE7L", defaultMessage: [{ type: 0, value: "Redeployed " }, { type: 1, value: "deploymentId" }, { type: 0, value: " " }, { type: 5, value: "version", options: { undefined: { value: [{ type: 0, value: "@HEAD" }] }, other: { value: [{ type: 0, value: "@" }, { type: 1, value: "version" }] } } }] }, {
             deploymentId: deployment.deploymentId,
-            version: (_b = deployment.deploymentConfig) === null || _b === void 0 ? void 0 : _b.versionNumber,
+            version: (_d = deployment.deploymentConfig) === null || _d === void 0 ? void 0 : _d.versionNumber,
         });
         console.log(successMessage);
     }
     catch (error) {
-        if (((_c = error.cause) === null || _c === void 0 ? void 0 : _c.code) === 'INVALID_ARGUMENT') {
+        if (((_e = error.cause) === null || _e === void 0 ? void 0 : _e.code) === 'INVALID_ARGUMENT') {
             this.error(error.cause.message);
         }
         throw error;

package/build/src/commands/utils.js

@@ -1,8 +1,29 @@
+// 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 contains utility functions for the clasp CLI commands, such as
+// spinners, URL opening, and configuration assertions.
 import cliTruncate from 'cli-truncate';
 import inquirer from 'inquirer';
 import open from 'open';
 import ora from 'ora';
 import { intl } from '../intl.js';
+/**
+ * Asserts that a script project is configured by checking for a script ID.
+ * Throws an error if the script ID is not set.
+ * @param {Clasp} clasp - The Clasp instance containing project details.
+ * @throws {Error} If `clasp.project.scriptId` is not set.
+ */
 export function assertScriptConfigured(clasp) {
     if (clasp.project.scriptId) {
         return;
@@ -10,6 +31,12 @@ export function assertScriptConfigured(clasp) {
     const msg = intl.formatMessage({ id: "2IuvqO", defaultMessage: [{ type: 0, value: "Script ID is not set, unable to continue." }] });
     throw new Error(msg);
 }
+/**
+ * Asserts that a Google Cloud Platform (GCP) project is configured by checking for a project ID.
+ * Throws an error if the GCP project ID is not set.
+ * @param {Clasp} clasp - The Clasp instance containing project details.
+ * @throws {Error} If `clasp.project.projectId` is not set.
+ */
 export function assertGcpProjectConfigured(clasp) {
     if (clasp.project.projectId) {
         return;
@@ -17,6 +44,13 @@ export function assertGcpProjectConfigured(clasp) {
     const msg = intl.formatMessage({ id: "aD3+By", defaultMessage: [{ type: 0, value: "GCP project ID is not set, unable to continue." }] });
     throw new Error(msg);
 }
+/**
+ * Prompts the user for a Google Cloud Platform (GCP) project ID if one is not already configured
+ * and the environment is interactive. It opens the script's GCP settings page in the browser
+ * to help the user find their project ID.
+ * @param {Clasp} clasp - The Clasp instance.
+ * @returns {Promise<string | undefined>} The GCP project ID if available or entered by the user, otherwise undefined.
+ */
 export async function maybePromptForProjectId(clasp) {
     let projectId = clasp.project.getProjectId();
     if (!projectId && isInteractive()) {
@@ -41,6 +75,14 @@ export async function maybePromptForProjectId(clasp) {
     return projectId;
 }
 const spinner = ora();
+/**
+ * Executes an asynchronous function while displaying a spinner in the console.
+ * The spinner is only shown if the environment is interactive.
+ * @template T
+ * @param {string} message - The message to display next to the spinner.
+ * @param {() => Promise<T>} fn - The asynchronous function to execute.
+ * @returns {Promise<T>} A promise that resolves with the result of the executed function.
+ */
 export async function withSpinner(message, fn) {
     // If not interactive terminal, skip spinner
     if (!isInteractive()) {
@@ -56,17 +98,43 @@ export async function withSpinner(message, fn) {
         }
     }
 }
+/**
+ * Truncates a string to a specified length with an ellipsis if it exceeds the length.
+ * It attempts to truncate on a space and pads the end to maintain the specified length.
+ * @param {string} value - The string to ellipsize.
+ * @param {number} length - The maximum length of the string.
+ * @returns {string} The ellipsized string.
+ */
 export function ellipsize(value, length) {
     return cliTruncate(value, length, { preferTruncationOnSpace: true }).padEnd(length);
 }
+/**
+ * Environment flags for clasp, primarily used for testing purposes
+ * to simulate or disable interactive states or browser presence.
+ * @property {boolean} isInteractive - Whether the current environment is an interactive TTY.
+ * @property {boolean} isBrowserPresent - Whether a browser is considered available to open URLs.
+ */
 // Exporting and wrapping to allow it to be toggled in tests
 export const claspEnv = {
     isInteractive: process.stdout.isTTY,
     isBrowserPresent: process.stdout.isTTY,
 };
+/**
+ * Checks if the current environment is interactive (i.e., a TTY).
+ * Relies on `claspEnv.isInteractive`.
+ * @returns {boolean} True if interactive, false otherwise.
+ */
 export function isInteractive() {
     return claspEnv.isInteractive;
 }
+/**
+ * Opens a URL in the default web browser if available.
+ * If a browser is not considered present (e.g., in some CI environments, or for testing),
+ * it logs a message asking the user to open the URL manually.
+ * @param {string} url - The URL to open.
+ * @returns {Promise<void | import('open').ChildProcess>} A promise that resolves when the URL is opened,
+ * or void if a browser is not present. The child process from `open` is returned if a browser is used.
+ */
 export async function openUrl(url) {
     if (!claspEnv.isBrowserPresent) {
         const msg = intl.formatMessage({ id: "kvR0OI", defaultMessage: [{ type: 0, value: "Open " }, { type: 1, value: "url" }, { type: 0, value: " in your browser to continue." }] }, {

package/build/src/constants.js

@@ -1,3 +1,18 @@
+// Copyright 2020 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 defines project-wide constants, such as the project name and
+// manifest file names, to ensure consistency across the codebase.
 // Names / Paths
 export const PROJECT_NAME = 'clasp';
 export const PROJECT_MANIFEST_BASENAME = 'appsscript';

package/build/src/core/apis.js

@@ -1,6 +1,16 @@
-/**
- * Google API Types
- */
+// Copyright 2018 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 is a list of all public Advanced Services.
  *