@google/clasp 3.0.5-alpha → 3.1.0

package/build/src/core/clasp.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 defines the main `Clasp` class, which orchestrates all core
+// functionalities of the CLI, including configuration management, API
+// interactions, and file operations.
 import path from 'path';
 import Debug from 'debug';
 import { findUpSync } from 'find-up';
@@ -22,7 +38,16 @@ const DEFAULT_CLASP_IGNORE = [
     '.git/**',
     'node_modules/**',
 ];
+/**
+ * Main class for interacting with Google Apps Script projects.
+ * It encapsulates all core functionalities like file management,
+ * project settings, API interactions, and authentication.
+ */
 export class Clasp {
+    /**
+     * Creates an instance of the Clasp class.
+     * @param {ClaspOptions} options - Configuration options for the Clasp instance.
+     */
     constructor(options) {
         debug('Creating clasp instance with options: %O', options);
         this.options = options;
@@ -45,15 +70,30 @@ export class Clasp {
         }
         return undefined;
     }
+    /**
+     * Configures the Clasp instance with a specific Apps Script project ID.
+     * This is a fluent method and returns the `Clasp` instance for chaining.
+     * @param {string} scriptId - The ID of the Apps Script project.
+     * @returns {this} The current Clasp instance.
+     * @throws {Error} If the project is already set.
+     */
     withScriptId(scriptId) {
         if (this.options.project) {
-            throw new Error('Science project already set, create new instance instead');
+            debug('Project is already configured, overriding scriptId with %s', scriptId);
         }
         this.options.project = {
             scriptId,
         };
         return this;
     }
+    /**
+     * Sets the content directory for the project files.
+     * This directory is where clasp looks for source files (e.g., `.js`, `.html`).
+     * If a relative path is provided, it's resolved against the project's root directory.
+     * This is a fluent method and returns the `Clasp` instance for chaining.
+     * @param {string} contentDir - The path to the content directory.
+     * @returns {this} The current Clasp instance.
+     */
     withContentDir(contentDir) {
         if (!path.isAbsolute(contentDir)) {
             contentDir = path.resolve(this.options.files.projectRootDir, contentDir);
@@ -62,38 +102,55 @@ export class Clasp {
         return this;
     }
 }
+/**
+ * Initializes and returns a Clasp instance.
+ * This function searches for project configuration files (`.clasp.json`, `.claspignore`),
+ * loads them if found, or sets up default configurations if not. It then creates
+ * and returns a new `Clasp` object configured with these settings.
+ * @param {InitOptions} options - Options for initializing the Clasp instance.
+ * @returns {Promise<Clasp>} A promise that resolves to a configured Clasp instance.
+ */
 export async function initClaspInstance(options) {
     var _a;
     debug('Initializing clasp instance');
+    // Attempt to find the project root directory and .clasp.json config file.
     const projectRoot = await findProjectRootdDir(options.configFile);
+    // If no .clasp.json is found, set up a default Clasp instance.
     if (!projectRoot) {
+        // Use the provided rootDir option or default to the current working directory.
         const dir = (_a = options.rootDir) !== null && _a !== void 0 ? _a : process.cwd();
         debug(`No project found, defaulting to ${dir}`);
         const rootDir = path.resolve(dir);
+        // Default path for .clasp.json if one were to be created.
         const configFilePath = path.resolve(rootDir, '.clasp.json');
         const ignoreFile = await findIgnoreFile(rootDir, options.ignoreFile);
         const ignoreRules = await loadIgnoreFileOrDefaults(ignoreFile);
+        // Create a Clasp instance with default file settings and no project-specific config.
         return new Clasp({
             credentials: options.credentials,
-            configFilePath,
+            configFilePath, // Path where .clasp.json would be.
             files: {
                 projectRootDir: rootDir,
-                contentDir: rootDir,
+                contentDir: rootDir, // By default, content directory is the root directory.
                 ignoreFilePath: ignoreFile,
                 ignorePatterns: ignoreRules,
-                filePushOrder: [],
-                skipSubdirectories: false,
-                fileExtensions: readFileExtensions({}),
+                filePushOrder: [], // No specific push order.
+                skipSubdirectories: false, // Process subdirectories by default.
+                fileExtensions: readFileExtensions({}), // Default file extensions.
             },
+            // No project options (scriptId, projectId, parentId) as .clasp.json was not found.
         });
     }
+    // If .clasp.json is found, load its configuration.
     debug('Project config found at %s', projectRoot.configPath);
     const ignoreFile = await findIgnoreFile(projectRoot.rootDir, options.ignoreFile);
     const ignoreRules = await loadIgnoreFileOrDefaults(ignoreFile);
     const content = await fs.readFile(projectRoot.configPath, { encoding: 'utf8' });
-    const config = JSON.parse(content);
+    const config = JSON.parse(content); // Parse the JSON content of .clasp.json.
+    // Determine file extensions, push order, and content directory from the loaded config.
     const fileExtensions = readFileExtensions(config);
-    const filePushOrder = config.filePushOrder || [];
+    const filePushOrder = config.filePushOrder || []; // Default to empty array if not specified.
+    // Content directory can be specified by `srcDir` or `rootDir` in .clasp.json, defaulting to project root.
     const contentDir = path.resolve(projectRoot.rootDir, config.srcDir || config.rootDir || '.');
     return new Clasp({
         credentials: options.credentials,
@@ -115,13 +172,14 @@ export async function initClaspInstance(options) {
     });
 }
 function readFileExtensions(config) {
-    let scriptExtensions = ['js', 'gs'];
-    let htmlExtensions = ['html'];
-    let jsonExtensions = ['json'];
+    let scriptExtensions = ['js', 'gs']; // Default script file extensions.
+    let htmlExtensions = ['html']; // Default HTML file extensions.
+    let jsonExtensions = ['json']; // Default JSON file extensions (primarily for appsscript.json).
+    // Support for legacy `fileExtension` setting (singular).
     if (config === null || config === void 0 ? void 0 : config.fileExtension) {
-        // legacy fileExtension setting
         scriptExtensions = [config.fileExtension];
     }
+    // Support for current `scriptExtensions` setting (plural, array).
     if (config === null || config === void 0 ? void 0 : config.scriptExtensions) {
         scriptExtensions = ensureStringArray(config.scriptExtensions);
     }
@@ -131,6 +189,7 @@ function readFileExtensions(config) {
     if (config === null || config === void 0 ? void 0 : config.jsonExtensions) {
         jsonExtensions = ensureStringArray(config.jsonExtensions);
     }
+    // Ensure all extensions are lowercase and start with a dot.
     const fixupExtension = (ext) => {
         ext = ext.toLowerCase().trim();
         if (!ext.startsWith('.')) {

package/build/src/core/files.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 manages the synchronization of files between the local filesystem
+// and the Google Apps Script project. It handles pulling, pushing, collecting
+// local files, watching for changes, and resolving file types and conflicts.
 import path from 'path';
 import chalk from 'chalk';
 import chokidar from 'chokidar';
@@ -25,11 +41,12 @@ async function getLocalFiles(rootDir, ignorePatterns, recursive) {
     let fdirBuilder = new fdir().withBasePath().withRelativePaths();
     if (!recursive) {
         debug('Not recursive, limiting depth to current directory');
-        fdirBuilder = fdirBuilder.withMaxDepth(0);
+        fdirBuilder = fdirBuilder.withMaxDepth(0); // Limit crawling to the current directory if not recursive
     }
     const files = await fdirBuilder.crawl(rootDir).withPromise();
     let filteredFiles;
     if (ignorePatterns && ignorePatterns.length) {
+        // Filter out files that are explicitly ignored by the .claspignore file or default ignore patterns.
         filteredFiles = micromatch.not(files, ignorePatterns, { dot: true });
         debug('Filtered %d files from ignore rules', files.length - filteredFiles.length);
     }
@@ -51,12 +68,15 @@ function createFilenameConflictChecker() {
     const files = new Set();
     return (file) => {
         if (file.type !== 'SERVER_JS') {
-            return file;
+            return file; // Conflict check only applies to SERVER_JS files
         }
         const parsedPath = path.parse(file.localPath);
+        // Create a key based on directory and name (without extension) to detect conflicts
+        // e.g. `src/Code.js` and `src/Code.gs` would conflict.
         const key = path.format({ dir: parsedPath.dir, name: parsedPath.name });
         if (files.has(key)) {
             throw new Error('Conflicting files found', {
+                // TODO: Better error message, show conflicting files
                 cause: {
                     code: 'FILE_CONFLICT',
                     value: key,
@@ -84,19 +104,21 @@ function getFileType(fileName, fileExtensions) {
 function getFileExtension(type, fileExtensions) {
     // TODO - Include project setting override
     const extensionFor = (type, defaultValue) => {
+        // Prioritize the first extension defined for a type in .clasp.json if available.
         if (fileExtensions[type] && fileExtensions[type][0]) {
             return fileExtensions[type][0];
         }
-        return defaultValue;
+        return defaultValue; // Fallback to default if no specific extension is configured.
     };
     switch (type) {
         case 'SERVER_JS':
-            return extensionFor('SERVER_JS', '.js');
+            return extensionFor('SERVER_JS', '.js'); // Default to .js for server-side JavaScript
         case 'JSON':
-            return extensionFor('JSON', '.json');
+            return extensionFor('JSON', '.json'); // Default to .json for JSON files (e.g. appsscript.json)
         case 'HTML':
-            return extensionFor('HTML', '.html');
+            return extensionFor('HTML', '.html'); // Default to .html for HTML files
         default:
+            // This case should ideally not be reached if file types are correctly identified.
             throw new Error('Invalid file type', {
                 cause: {
                     code: 'INVALID_FILE_TYPE',
@@ -124,10 +146,27 @@ function debounceFileChanges(callback, delayMs) {
         }, delayMs);
     };
 }
+/**
+ * Manages operations related to project files, including fetching remote files,
+ * collecting local files based on ignore patterns, watching for local changes,
+ * pushing local changes to the remote project, and pulling remote files
+ * to the local filesystem.
+ */
 export class Files {
+    /**
+     * Constructs a new Files instance.
+     * @param {ClaspOptions} options - Configuration options for file operations.
+     */
     constructor(options) {
         this.options = options;
     }
+    /**
+     * Fetches the content of a script project from Google Drive.
+     * @param {number} [versionNumber] - Optional version number to fetch.
+     * If not specified, the latest version (HEAD) is fetched.
+     * @returns {Promise<ProjectFile[]>} A promise that resolves to an array of project files.
+     * @throws {Error} If there's an API error or authentication/configuration issues.
+     */
     async fetchRemote(versionNumber) {
         var _a;
         debug('Fetching remote files, version %s', versionNumber !== null && versionNumber !== void 0 ? versionNumber : 'HEAD');
@@ -161,6 +200,12 @@ export class Files {
             handleApiError(error);
         }
     }
+    /**
+     * Collects all local files in the project's content directory, respecting ignore patterns.
+     * It reads the content of each file and determines its type.
+     * @returns {Promise<ProjectFile[]>} A promise that resolves to an array of local project files.
+     * @throws {Error} If the project is not configured or there's a file conflict.
+     */
     async collectLocalFiles() {
         var _a;
         debug('Collecting local files');
@@ -193,34 +238,45 @@ export class Files {
         }));
         return files.filter((f) => f !== undefined);
     }
+    /**
+     * Watches for changes in local project files and triggers callbacks.
+     * @param {() => Promise<void> | void} onReady - Callback executed when the watcher is ready.
+     * @param {(files: string[]) => Promise<void> | void} onFilesChanged - Callback executed
+     * when files are added, changed, or deleted, with a debounced list of changed file paths.
+     * @returns {() => Promise<void>} A function that can be called to stop watching.
+     */
     watchLocalFiles(onReady, onFilesChanged) {
         var _a;
         const ignorePatterns = (_a = this.options.files.ignorePatterns) !== null && _a !== void 0 ? _a : [];
-        const collector = debounceFileChanges(onFilesChanged, 500);
+        const collector = debounceFileChanges(onFilesChanged, 500); // Debounce changes to avoid rapid firing
         const onChange = async (path) => {
             debug('Have file changes: %s', path);
-            collector(path);
+            collector(path); // Collect changed paths
         };
         let matcher;
         if (ignorePatterns && ignorePatterns.length) {
+            // Custom matcher function for chokidar to respect .claspignore patterns.
+            // This is necessary because chokidar's `ignored` option expects specific formats.
             matcher = (file, stats) => {
                 if (!(stats === null || stats === void 0 ? void 0 : stats.isFile())) {
-                    return false;
+                    return false; // Only consider files for ignore matching
                 }
+                // Normalize file path relative to project root for consistent matching with ignorePatterns.
                 file = path.relative(this.options.files.projectRootDir, file);
+                // Check if the file is NOT in the list of files to keep (i.e., it should be ignored).
                 const ignore = micromatch.not([file], ignorePatterns, { dot: true }).length === 0;
                 return ignore;
             };
         }
         const watcher = chokidar.watch(this.options.files.contentDir, {
-            persistent: true,
-            ignoreInitial: true,
-            cwd: this.options.files.contentDir,
-            ignored: matcher,
+            persistent: true, // Keep watching until explicitly closed
+            ignoreInitial: true, // Don't trigger 'add' events for existing files on startup
+            cwd: this.options.files.contentDir, // Watch paths relative to contentDir
+            ignored: matcher, // Use custom ignore logic if patterns are present
         });
-        watcher.on('ready', onReady); // Push on start
-        watcher.on('add', onChange);
-        watcher.on('change', onChange);
+        watcher.on('ready', onReady); // Callback when initial scan is complete
+        watcher.on('add', onChange); // On new file addition
+        watcher.on('change', onChange); // On file content change
         watcher.on('unlink', onChange);
         watcher.on('error', err => {
             debug('Unexpected error during watch: %O', err);
@@ -230,16 +286,30 @@ export class Files {
             await watcher.close();
         };
     }
+    /**
+     * Compares local files with remote files (HEAD version) to identify changes.
+     * A file is considered changed if it's new locally or its content differs from the remote version.
+     * @returns {Promise<ProjectFile[]>} A promise that resolves to an array of project files that have changed.
+     */
     async getChangedFiles() {
         const [localFiles, remoteFiles] = await Promise.all([this.collectLocalFiles(), this.fetchRemote()]);
+        // Iterate over local files and compare with their remote counterparts.
         return localFiles.reduce((changed, localFile) => {
             const remote = remoteFiles.find(f => f.localPath === localFile.localPath);
+            // A file is considered changed if it doesn't exist remotely or if its source content differs.
             if (!remote || remote.source !== localFile.source) {
                 changed.push(localFile);
             }
             return changed;
         }, []);
     }
+    /**
+     * Identifies files present in the local content directory that are not tracked
+     * by the Apps Script project (i.e., not in `.claspignore` or `appsscript.json`'s `filePushOrder`
+     * and not matching supported file extensions).
+     * @returns {Promise<string[]>} A promise that resolves to an array of untracked file paths,
+     * collapsed to their common parent directories where applicable.
+     */
     async getUntrackedFiles() {
         debug('Collecting untracked files');
         assertScriptConfigured(this.options);
@@ -252,33 +322,46 @@ export class Files {
         for (const file of projectFiles) {
             debug('Found tracked file %s', file.localPath);
             trackedFiles.add(file.localPath);
-            // Save all parent paths to allow quick lookup.
-            // Allows collapsing the unfiltered files to the common parent directory
+            // Save all parent paths of tracked files to allow quick lookup.
+            // This helps in collapsing untracked file paths to their nearest common untracked parent.
             const dirs = parentDirs(file.localPath);
             dirs.forEach(dir => dirsWithIncludedFiles.add(dir));
         }
+        // Get all files in the content directory without applying ignore rules yet.
         const allFiles = await getUnfilteredLocalFiles(contentDir);
         for (const file of allFiles) {
             const resolvedPath = path.relative(cwd, file);
             if (trackedFiles.has(resolvedPath)) {
-                // Tracked file, skip
+                // If the file is already tracked (i.e., part of the project to be pushed), skip it.
                 continue;
             }
-            // Reduce path to nearest parent directory with no project files included
+            // Reduce path to the nearest parent directory that itself does not contain any tracked files.
+            // This groups untracked files under their common untracked root.
+            // For example, if 'node_modules/lib/a.js' and 'node_modules/lib/b.js' are untracked,
+            // and 'node_modules/lib' contains no tracked files, this will report 'node_modules/lib/'.
             let excludedPath = resolvedPath;
             for (const dir of parentDirs(resolvedPath)) {
                 if (dirsWithIncludedFiles.has(dir)) {
+                    // Stop if we reach a directory that is a parent of some tracked file.
                     break;
                 }
-                excludedPath = path.normalize(`${dir}/`);
+                excludedPath = path.normalize(`${dir}/`); // Mark as directory
             }
-            debug('Found untracked file %s', excludedPath);
+            debug('Found untracked file/directory %s', excludedPath);
             untrackedFiles.add(excludedPath);
         }
         const untrackedFilesArray = Array.from(untrackedFiles);
-        untrackedFilesArray.sort((a, b) => a.localeCompare(b));
+        untrackedFilesArray.sort((a, b) => a.localeCompare(b)); // Sort for consistent output
         return untrackedFilesArray;
     }
+    /**
+     * Pushes local project files to the Google Apps Script project.
+     * Files are sorted according to `filePushOrder` from the manifest if specified.
+     * Handles API errors, including syntax errors in pushed files.
+     * @returns {Promise<ProjectFile[]>} A promise that resolves to an array of files that were pushed.
+     * Returns an empty array if no files were found to push.
+     * @throws {Error} If there's an API error, authentication/configuration issues, or a syntax error in the code.
+     */
     async push() {
         var _a;
         debug('Pushing files');
@@ -295,22 +378,22 @@ export class Files {
         files.sort((a, b) => {
             const indexA = filePushOrder.indexOf(a.localPath);
             const indexB = filePushOrder.indexOf(b.localPath);
+            // If neither file is in the push order, sort them alphabetically.
             if (indexA === -1 && indexB === -1) {
-                // Neither has explicit order, sort by name
                 return a.localPath.localeCompare(b.localPath);
             }
+            // If only file B is in the push order, file B comes first.
             if (indexA === -1) {
-                // B has explicit priority, is first
                 return 1;
             }
+            // If only file A is in the push order, file A comes first.
             if (indexB === -1) {
-                // A has explicit priority, is first
                 return -1;
             }
-            // Both prioritized, use rank
+            // If both files are in the push order, sort by their index in the push order.
             return indexA - indexB;
         });
-        // Start pushing.
+        // Prepare file objects for the Apps Script API request.
         try {
             const scriptFiles = files.map(f => ({
                 name: f.remotePath,
@@ -345,6 +428,13 @@ export class Files {
             handleApiError(error);
         }
     }
+    /**
+     * Checks if any files specified in the `filePushOrder` of the manifest
+     * were not actually pushed. This can help identify misconfigurations.
+     * @param {ProjectFile[]} pushedFiles - An array of files that were successfully pushed.
+     * @returns {void} This method does not return a value but may have side effects (e.g. logging) if implemented.
+     * Currently, it only calculates missing files but doesn't do anything with the result.
+     */
     checkMissingFilesFromPushOrder(pushedFiles) {
         var _a;
         const missingFiles = [];
@@ -355,6 +445,14 @@ export class Files {
             }
         }
     }
+    /**
+     * Fetches remote project files (optionally a specific version) and writes them
+     * to the local filesystem, overwriting existing files.
+     * @param {number} [version] - Optional version number to pull. If not specified,
+     * the latest version (HEAD) is pulled.
+     * @returns {Promise<ProjectFile[]>} A promise that resolves to an array of files that were pulled.
+     * @throws {Error} If there's an API error or authentication/configuration issues.
+     */
     async pull(version) {
         debug('Pulling files');
         assertAuthenticated(this.options);
@@ -371,7 +469,10 @@ export class Files {
                 debug('Skipping empty file.');
                 return;
             }
-            await fs.mkdir(path.dirname(file.localPath), { recursive: true });
+            const localDirname = path.dirname(file.localPath);
+            if (localDirname !== '.') {
+                await fs.mkdir(localDirname, { recursive: true });
+            }
             await fs.writeFile(file.localPath, file.source);
         };
         return await pMap(files, mapper);
@@ -381,25 +482,30 @@ function extractSyntaxError(error, files) {
     var _a;
     let message = error.message;
     let snippet = '';
+    // Try to parse the error message for syntax error details.
+    // Example: "Syntax error: Missing ; before statement. line: 1 file: Code"
     const re = /Syntax error: (.+) line: (\d+) file: (.+)/;
     const [, errorName, lineNum, fileName] = (_a = re.exec(error.message)) !== null && _a !== void 0 ? _a : [];
     if (fileName === undefined) {
+        // If parsing fails, it's not a recognized syntax error format.
         return undefined;
     }
     message = `${errorName} - "${fileName}:${lineNum}"`;
-    // Get formatted code snippet
-    const contextCount = 4;
+    // Attempt to create a code snippet for the error.
+    const contextCount = 4; // Number of lines before and after the error line to include.
     const errFile = files.find((x) => x.remotePath === fileName);
     if (!errFile || !errFile.source) {
+        // If the source file of the error cannot be found, no snippet can be generated.
         return undefined;
     }
     const srcLines = errFile.source.split('\n');
-    const errIndex = Math.max(parseInt(lineNum) - 1, 0);
+    const errIndex = Math.max(parseInt(lineNum) - 1, 0); // 0-based index
     const preIndex = Math.max(errIndex - contextCount, 0);
     const postIndex = Math.min(errIndex + contextCount + 1, srcLines.length);
+    // Format the snippet with dim context lines and a bold error line.
     const preLines = chalk.dim(`  ${srcLines.slice(preIndex, errIndex).join('\n  ')}`);
     const errLine = chalk.bold(`⇒ ${srcLines[errIndex]}`);
     const postLines = chalk.dim(`  ${srcLines.slice(errIndex + 1, postIndex).join('\n  ')}`);
     snippet = preLines + '\n' + errLine + '\n' + postLines;
-    return { message, snippet };
+    return { message, snippet }; // Return the formatted message and snippet.
 }

package/build/src/core/functions.js

@@ -1,11 +1,35 @@
+// 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 `Functions` class, which provides methods for
+// listing and executing functions within a Google Apps Script project.
 import Debug from 'debug';
 import { google } from 'googleapis';
 import { assertAuthenticated, assertScriptConfigured, handleApiError } from './utils.js';
 const debug = Debug('clasp:core');
+/**
+ * Provides methods for interacting with functions within a Google Apps Script project,
+ * such as listing available functions and executing them remotely.
+ */
 export class Functions {
     constructor(options) {
         this.options = options;
     }
+    /**
+     * Retrieves a list of all function names in the Apps Script project.
+     * @returns {Promise<string[]>} A promise that resolves to an array of function names.
+     * @throws {Error} If there's an API error or authentication/configuration issues.
+     */
     async getFunctionNames() {
         debug('Fetching runnable functions');
         assertAuthenticated(this.options);
@@ -21,6 +45,18 @@ export class Functions {
         }
         return files.flatMap(file => { var _a, _b; return (_b = (_a = file.functionSet) === null || _a === void 0 ? void 0 : _a.values) !== null && _b !== void 0 ? _b : []; }).map(func => func.name);
     }
+    /**
+     * Executes a specified function in the Apps Script project.
+     * @param {string} functionName - The name of the function to run.
+     * @param {unknown[]} parameters - An array of parameters to pass to the function.
+     * These will be JSON-stringified.
+     * @param {boolean} [devMode=true] - Whether to run the function in development mode.
+     * Dev mode executes the latest saved code instead of the last deployed version.
+     * @returns {Promise<any>} A promise that resolves to the response from the function execution,
+     * or undefined if an error occurs before the API call.
+     * @throws {Error} If there's an API error, authentication/configuration issues,
+     * or if the function execution itself returns an error.
+     */
     async runFunction(functionName, parameters, devMode = true) {
         debug('Running script function %s', functionName);
         assertAuthenticated(this.options);

package/build/src/core/logs.js

@@ -1,12 +1,41 @@
+// 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 `Logs` class, responsible for fetching log entries
+// from Google Cloud Logging for the associated Apps Script project.
 import Debug from 'debug';
 import { google } from 'googleapis';
 import { fetchWithPages } from './utils.js';
 import { assertAuthenticated, assertGcpProjectConfigured, handleApiError } from './utils.js';
 const debug = Debug('clasp:core');
+/**
+ * Facilitates the retrieval of log entries from Google Cloud Logging
+ * for the Apps Script project associated with the current clasp project.
+ */
 export class Logs {
     constructor(options) {
         this.options = options;
     }
+    /**
+     * Retrieves log entries from Google Cloud Logging for the configured GCP project.
+     * Logs are fetched in descending order of timestamp.
+     * @param {Date} [since] - Optional date to filter logs. Only entries with a timestamp
+     * greater than or equal to this date will be returned.
+     * @returns {Promise<{results: logging_v2.Schema$LogEntry[], partialResults: boolean} | undefined>}
+     * A promise that resolves to an object containing the log entries and a flag indicating
+     * if results are partial (due to pagination limits), or undefined if an error occurs.
+     * @throws {Error} If there's an API error or authentication/configuration issues.
+     */
     async getLogEntries(since) {
         debug('Fetching logs');
         assertAuthenticated(this.options);

package/build/src/core/manifest.js

@@ -1 +1,14 @@
+// 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.
 export {};