@google/clasp 2.4.2 → 3.0.0-alpha1

package/build/src/index.js

@@ -18,364 +18,26 @@
 /**
  * clasp - The Apps Script CLI
  */
-import { program } from 'commander';
+import Debug from 'debug';
 import loudRejection from 'loud-rejection';
-import { dirname } from 'path';
-import { readPackageUpSync } from 'read-pkg-up';
-import { fileURLToPath } from 'url';
-import fs from 'fs-extra';
-import { ClaspError } from './clasp-error.js';
-import apis from './commands/apis.js';
-import clone from './commands/clone.js';
-import create from './commands/create.js';
-import defaultCmd from './commands/default.js';
-import deploy from './commands/deploy.js';
-import deployments from './commands/deployments.js';
-import list from './commands/list.js';
-import login from './commands/login.js';
-import logout from './commands/logout.js';
-import logs from './commands/logs.js';
-import openCmd from './commands/open.js';
-import pull from './commands/pull.js';
-import push from './commands/push.js';
-import run from './commands/run.js';
-import setting from './commands/setting.js';
-import status from './commands/status.js';
-import undeploy from './commands/undeploy.js';
-import version from './commands/version.js';
-import versions from './commands/versions.js';
-import { Conf } from './conf.js';
-import { PROJECT_NAME } from './constants.js';
-import { spinner, stopSpinner } from './utils.js';
-const __dirname = dirname(fileURLToPath(import.meta.url));
-// instantiate the config singleton (and loads environment variables as a side effect)
-const config = Conf.get();
+import { makeProgram } from './commands/program.js';
+const debug = Debug('clasp:cli');
 // Ensure any unhandled exception won't go unnoticed
 loudRejection();
-const manifest = readPackageUpSync({ cwd: __dirname });
-// CLI
-/**
- * Set global CLI configurations
- */
-program.storeOptionsAsProperties(false);
-/**
- * Displays clasp version
- */
-program.version(manifest ? manifest.packageJson.version : 'unknown', '-v, --version', 'output the current version');
-program.name(PROJECT_NAME).usage('<command> [options]').description(`${PROJECT_NAME} - The Apps Script CLI`);
-/**
- * Path to an auth file, or to a folder with a '.clasprc.json' file.
- */
-program
-    .option('-A, --auth <file>', "path to an auth file or a folder with a '.clasprc.json' file.")
-    .on('option:auth', (auth) => {
-    config.auth = auth;
-});
-/**
- * Path to an ignore file, or to a folder with a '.claspignore'.
- */
-program
-    .option('-I, --ignore <file>', "path to an ignore file or a folder with a '.claspignore' file.")
-    .on('option:ignore', (ignore) => {
-    config.ignore = ignore;
-});
-/**
- * Path to a project file, or to a folder with a '.clasp.json'.
- */
-program
-    .option('-P, --project <file>', "path to a project file or to a folder with a '.clasp.json' file.")
-    .on('option:project', (path) => {
-    const stats = fs.lstatSync(path);
-    if (stats.isDirectory()) {
-        config.projectRootDirectory = path;
+const program = makeProgram();
+try {
+    debug('Running clasp with args: %s', process.argv.join(' '));
+    // User input is provided from the process' arguments
+    await program.parseAsync(process.argv);
+}
+catch (error) {
+    debug('Error: %O', error);
+    if (error instanceof Error) {
+        process.exitCode = 1;
+        console.error(error.message);
     }
     else {
-        config.projectConfig = path;
+        process.exitCode = 1;
+        console.error('Unknown error', error);
     }
-});
-/**
- * Logs the user in. Saves the client credentials to an rc file.
- * @name login
- * @param {string?} [--no-localhost] Do not run a local server, manually enter code instead.
- * @param {string?} [--creds] Relative path to credentials (from GCP).
- * @example login (uses default clasp credentials)
- * @example login --creds credentials.json (uses your credentials file).
- * @see test
- */
-program
-    .command('login')
-    .description('Log in to script.google.com')
-    .option('--no-localhost', 'Do not run a local server, manually enter code instead')
-    .option('--creds <file>', 'Relative path to credentials (from GCP).')
-    .option('--status', 'Print who is logged in')
-    .action(login);
-/**
- * Logs out the user by deleteing client credentials.
- * @name logout
- * @example logout
- */
-program.command('logout').description('Log out').action(logout);
-/**
- * Creates a new script project.
- * @name create
- * @param {string?} [--title] An optional project title.
- * @param {string?} [--parentId] An optional project parent Id. The Drive ID of a parent file
- *   that the created script project is bound to. This is usually the ID of a
- *   Google Doc, Google Sheet, Google Form, or Google Slides file. If not set, a
- *   standalone script project is created.
- *   https://drive.google.com/open?id=<ID>
- * @param {string?} [--rootDir] Local root directory that store your project files.
- * @example create
- * @example create "My Script"
- * @example create "My Script" "1D_Gxyv*****************************NXO7o"
- * @see https://developers.google.com/apps-script/api/reference/rest/v1/projects/create
- */
-program
-    .command('create')
-    .description('Create a script')
-    .option('--type <type>', 'Creates a new Apps Script project attached to a new Document, Spreadsheet, Presentation, Form, or as a standalone script, web app, or API.')
-    .option('--title <title>', 'The project title.')
-    .option('--parentId <id>', 'A project parent Id.')
-    .option('--rootDir <rootDir>', 'Local root directory in which clasp will store your project files.')
-    .action(create);
-/**
- * Fetches a project and saves the script id locally.
- * @param {string?} [scriptId] The script ID to clone.
- * @param {string?} [versionNumber] The version of the script to clone.
- * @param {string?} [--rootDir] Local root directory that store your project files.
- */
-program
-    .command('clone [scriptId] [versionNumber]')
-    .description('Clone a project')
-    .option('--rootDir <rootDir>', 'Local root directory in which clasp will store your project files.')
-    .action(clone);
-/**
- * Fetches a project from either a provided or saved script id.
- * Updates local files with Apps Script project.
- * @name pull
- * @example pull
- */
-program
-    .command('pull')
-    .description('Fetch a remote project')
-    .option('--versionNumber <version>', 'The version number of the project to retrieve.')
-    .action(pull);
-/**
- * Force writes all local files to the script management server.
- * @name push
- * @desc Ignores files:
- * - That start with a .
- * - That don't have an accepted file extension
- * - That are ignored (filename matches a glob pattern in the ignore file)
- * @example push
- * @example push --force
- * @example push --watch
- */
-program
-    .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(push);
-/**
- * Lists files that will be written to the server on `push`.
- * @name status
- * @desc Ignores files:
- * - That start with a .
- * - That don't have an accepted file extension
- * - That are ignored (filename matches a glob pattern in the ignore file)
- * @example status
- */
-program
-    .command('status')
-    .description('Lists files that will be pushed by clasp')
-    .option('--json', 'Show status in JSON form')
-    .action(status);
-/**
- * Opens the `clasp` project on script.google.com. Provide a `scriptId` to open a different script.
- * @name open
- * @param {string?} [scriptId] The optional script project to open.
- * @example open
- * @example open [scriptId]
- */
-program
-    .command('open [scriptId]')
-    .description('Open a script')
-    .option('--webapp', 'Open web application in the browser')
-    .option('--creds', 'Open the URL to create credentials')
-    .option('--addon', 'List parent IDs and open the URL of the first one')
-    .option('--deploymentId <id>', 'Use custom deployment ID with webapp')
-    .action(openCmd);
-/**
- * List deployments of a script
- * @name deployments
- * @example deployments
- */
-program.command('deployments').description('List deployment ids of a script').action(deployments);
-/**
- * Creates a version and deploys a script.
- * The response gives the version of the deployment.
- * @name deploy
- * @example deploy (create new deployment and new version)
- * @example deploy --versionNumber 4 (create new deployment)
- * @example deploy --description "Updates sidebar logo." (deploy with description)
- * @example deploy --deploymentId 123 (create new version)
- * @example deploy -V 7 -d "Updates sidebar logo." -i 456
- */
-program
-    .command('deploy')
-    .description('Deploy a project')
-    .option('-V, --versionNumber <version>', 'The project version') // We can't use `version` in subcommand
-    .option('-d, --description <description>', 'The deployment description')
-    .option('-i, --deploymentId <id>', 'The deployment ID to redeploy')
-    .action(deploy);
-/**
- * Undeploys a deployment of a script.
- * @name undeploy
- * @param {string?} [deploymentId] The deployment ID.
- * @param {boolean?} all Setup StackDriver logs.
- * @example "undeploy" (undeploy the last deployment.)
- * @example "undeploy 123"
- * @example "undeploy --all"
- */
-program
-    .command('undeploy [deploymentId]')
-    .description('Undeploy a deployment of a project')
-    .option('-a, --all', 'Undeploy all deployments')
-    .action(undeploy);
-/**
- * Creates an immutable version of the script.
- * @name version
- * @param {string?} description The description of the script version.
- * @example version
- * @example version "Bump the version."
- */
-program.command('version [description]').description('Creates an immutable version of the script').action(version);
-/**
- * List versions of a script.
- * @name versions
- * @example versions
- */
-program.command('versions').description('List versions of a script').action(versions);
-/**
- * Lists your most recent 10 Apps Script projects.
- * @name list
- * @example list # helloworld1 - xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx ...
- * @todo Add --all flag to list all projects.
- */
-program
-    .command('list')
-    .description('List App Scripts projects')
-    .option('--noShorten', 'Do not shorten long names', false)
-    .action(list);
-/**
- * Prints StackDriver logs.
- * @name logs
- * @param {boolean?} json Output logs in json format.
- * @param {boolean?} open Open StackDriver logs in a browser.
- * @param {boolean?} setup Setup StackDriver logs.
- */
-program
-    .command('logs')
-    .description('Shows the StackDriver logs')
-    .option('--json', 'Show logs in JSON form')
-    .option('--open', 'Open the StackDriver logs in the browser')
-    .option('--setup', 'Setup StackDriver logs')
-    .option('--watch', 'Watch and print new logs')
-    .option('--simplified', 'Hide timestamps with logs')
-    .action(logs);
-/**
- * Remotely executes an Apps Script function.
- * This function runs your script in the cloud. You must supply
- * the functionName params. For now, it can
- * only run functions that do not require other authorization.
- * @name run
- * @param {string} functionName The function in the script that you want to run.
- * @param {boolean?} nondev Run script function in non-devMode.
- * @example run 'sendEmail'
- * @see https://developers.google.com/apps-script/api/reference/rest/v1/scripts/run
- * @requires `clasp login --creds` to be run beforehand.
- */
-program
-    .command('run [functionName]')
-    .description('Run a function in your Apps Scripts project')
-    .option('--nondev', 'Run script function in non-devMode')
-    .option('-p, --params [StringArray]', 'Add parameters required for the function as a JSON String Array')
-    .action(run);
-/**
- * List, enable, or disable APIs for your project.
- * Currently, only list is supported.
- * @name apis
- * @example apis list
- * @example apis enable drive
- */
-program
-    .command('apis')
-    .description(`List, enable, or disable APIs
-  list
-  enable <api>
-  disable <api>`)
-    .option('--open', 'Open the API Console in the browser')
-    .action(apis);
-/**
- * Update .clasp.json settings file.
- * If `newValue` is omitted, it returns the current setting value
- * If `settingKey` is omitted, it returns all keys in .clasp.json
- * @name setting
- * @param {string?} settingKey They key in .clasp.json you want to change
- * @param {string?} newValue The new value for the setting
- * @example setting
- * @example setting scriptId
- * @example setting scriptId new-id
- */
-program
-    .command('setting [settingKey] [newValue]')
-    .alias('settings')
-    .description('Update <settingKey> in .clasp.json')
-    .action(setting);
-/**
- * All other commands are given a help message.
- * @example random
- */
-program.command('*', { isDefault: true }).description('Any other command is not supported').action(defaultCmd);
-/**
- * @internal
- * Displays clasp paths
- */
-program
-    .command('paths')
-    .description('List current config files path')
-    .action(() => {
-    console.log('project', config.projectConfig);
-    console.log('ignore', config.ignore);
-    console.log('auth', config.auth);
-});
-const [_bin, _sourcePath, ...args] = process.argv;
-// Defaults to help if commands are not provided
-if (args.length === 0) {
-    program.outputHelp();
 }
-(async () => {
-    try {
-        // User input is provided from the process' arguments
-        await program.parseAsync(process.argv);
-        stopSpinner();
-    }
-    catch (error) {
-        spinner.stop();
-        if (error instanceof ClaspError) {
-            // ClaspError handles process.exitCode
-            console.error(error.message);
-        }
-        else if (error instanceof Error) {
-            process.exitCode = 1;
-            console.error(error.message);
-        }
-        else {
-            process.exitCode = 1;
-            console.error('Unknown error', error);
-        }
-    }
-    spinner.clear();
-})();
-//# sourceMappingURL=index.js.map

package/build/src/intl.js

@@ -0,0 +1,34 @@
+import { createIntl, createIntlCache } from '@formatjs/intl';
+import Debug from 'debug';
+const debug = Debug('clasp:intl');
+function isDefined(item) {
+    return item !== null && item !== undefined;
+}
+function getLocale() {
+    const envLocales = [process.env.LC_ALL, process.env.LC_CTYPE, process.env.LANG].filter(isDefined);
+    for (const envLocale of envLocales) {
+        try {
+            // Attempt to normalize the locale string (e.g., "en_US" to "en-US")
+            const normalizedLocale = new Intl.Locale(envLocale).toString();
+            return normalizedLocale;
+        }
+        catch (_error) {
+            // Ignore invalid locale strings and try the next one
+            debug('Invalid locale string: %s', envLocale);
+        }
+    }
+    return 'en';
+}
+function loadMessages(_locale) {
+    // TODO - L10N not implemented yet.
+    return {};
+}
+const cache = createIntlCache();
+const locale = getLocale();
+debug('Using locale: %s', locale);
+export const intl = createIntl({
+    // Locale of the application
+    locale,
+    defaultLocale: 'en',
+    messages: loadMessages(locale),
+}, cache);

package/docs/README.md

@@ -2,8 +2,5 @@
 
 This folder contains advanced guides for `clasp`.
 
-- [Develop clasp](/docs/develop.md): Build, Run, and Test the CLI.
+- [Configuration](/docs/config-files.md): Learn about the configuration files used by clasp.
 - [Run](/docs/run.md): Execute Apps Script remotely with `clasp run`.
-- [Running locally](/docs/running-locally.md): Install and use clasp as a local dependency.
-- [Settings](/docs/settings.md): Set up JSON autocompletion and `.gs` syntax highlighting.
-- [TypeScript](/docs/typescript.md): Learn how to develop Apps Script in TypeScript.

package/docs/config-files.md

@@ -12,9 +12,9 @@ Typescript configuration file | `<rootDir>/tsconfig.json` | Used for user specif
 
 ## Environment variables
 
-Environment variables can be set in order to specify the location of the following configutation files:
+Environment variables can be set in order to specify the location of the following configuration files:
 
-File | Environment varaiable | Comment
+File | Environment variable | Comment
 --- | --- | ---
 Clasp project file | `clasp_config_project` | The filename must start with a dot '.'
 Clasp ignore file | `clasp_config_ignore` |
@@ -22,9 +22,9 @@ Google Auth file | `clasp_config_auth` | The filename must start with a dot '.'
 
 ## Command line options
 
-Command line options can be used in order to specify the location of the following configutation files:
+Command line options can be used in order to specify the location of the following configuration files:
 
-File | Environment varaiable | Comment
+File | Environment variable | Comment
 --- | --- | ---
 Clasp project file | `-P <path>` or `--project <path>` | The filename must start with a dot '.'
 Clasp ignore file | `-I <path>` or `--ignore <path>` |
@@ -53,4 +53,3 @@ list | | | Read |
 logs | ??? | | Read | ???
 run | Read | | Read | ???
 apis | ??? | | Read | ???
-setting | Read | | ??? | ???

package/docs/run.md

@@ -4,9 +4,9 @@
 
 ### Prerequisites
 
-To use `clasp run`, you need to complete 4 steps:
+To use `clasp run`, you need to complete 5 steps:
 
-- Set up a **Project ID**.
+- Set up the **Project ID** in your `.clasp.json` if missing.
 - Create an **OAuth Client ID** (Other). Download as `creds.json`.
 - `clasp login --creds creds.json` with this downloaded file.
 - Add the following to `appsscript.json`:
@@ -15,6 +15,7 @@ To use `clasp run`, you need to complete 4 steps:
     "access": "ANYONE"
   }
   ```
+- Deploy your project as an API Executable if necessary
 
 #### Setup Instructions
 
@@ -27,16 +28,26 @@ To use `clasp run`, you need to complete 4 steps:
 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`.
-    - `clasp open`
-    - In the menu, click `Resources > Cloud Platform project...`
-    - Paste `Project number` in `Change Project` and click `Set Project`
+    - Run `clasp open`
+    - 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`
 1. Use your own OAuth 2 client. Create one by following these instructions:
     - `clasp open --creds`
     - Press **Create credentials** > **OAuth client ID**
     - Application type: **Desktop App**
     - **Create** > **OK**
     - Download the file (⬇), move it to your directory, and name it `creds.json`. Please keep this file secret!
-1. Call `clasp login --creds creds.json`
+1. Call `clasp login --user <name> --creds creds.json`
+1. Add the following to `appsscript.json`:
+      ```json
+      "executionApi": {
+        "access": "ANYONE"
+      }
+      ```
+1. If you use Google Workspace, enable `Apps Script API`
+    - Open `https://console.cloud.google.com/marketplace/product/google/script.googleapis.com?project=[PROJECT_ID]`
+    - Press ENABLE button
 
 ### Run a function
 
@@ -47,6 +58,14 @@ After setup, you can remotely execute Apps Script functions from `clasp`:
 - The result is displayed in the output.
 - You can also run functions directly. i.e. `clasp run helloWorld`.
 
+If you get an "Script API executable not published/deployed." error, deploy your script as an API Executable:
+
+- Run `clasp open`
+- Click `Deploy > New deployment`
+- Select type ⚙ > API Executable
+- Type a `Description`
+- Click `Deploy`
+
 ### Run a function that requires scopes
 
 Many Apps Script functions require special OAuth Scopes (Gmail, Drive, etc.).
@@ -57,4 +76,4 @@ To run functions that use these scopes, you must add the scopes to your Apps Scr
 - `File > Project Properties > Scopes`
 - Add these scopes to your `appsscript.json`.
 - Log in again: `clasp login --creds creds.json`. This will add these scopes to your credentials.
-- `clasp run sendMail`
+- `clasp run --user <name> sendMail`