@rocketmakers/shell-gcloud 0.1.0

package/README.md

@@ -0,0 +1,3 @@
+## Overview
+
+Contains functions for working with [gcloud](https://cloud.google.com/sdk/gcloud) and [gsutil](https://cloud.google.com/storage/docs/gsutil).

package/lib/base64.d.ts

@@ -0,0 +1,2 @@
+export declare function toBASE64(value: string): string;
+export declare function fromBASE64(encoded: string): string;

package/lib/base64.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toBASE64 = toBASE64;
+exports.fromBASE64 = fromBASE64;
+function toBASE64(value) {
+    return Buffer.from(value).toString('base64');
+}
+function fromBASE64(encoded) {
+    const buff = Buffer.from(encoded, 'base64');
+    return buff.toString('ascii');
+}

package/lib/env.d.ts

@@ -0,0 +1,2 @@
+export declare function cloneEnvironment(): NodeJS.ProcessEnv;
+export declare function isCI(): boolean;

package/lib/env.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.cloneEnvironment = cloneEnvironment;
+exports.isCI = isCI;
+function cloneEnvironment() {
+    return Object.create(process.env);
+}
+function isCI() {
+    return process.env.CI === 'true';
+}

package/lib/gcloud.d.ts

@@ -0,0 +1,95 @@
+import { IShellExecutor } from '@rocketmakers/shell/executor';
+import { IShellOptions } from '@rocketmakers/shell/options';
+/**
+ * Starts an application default login if no application default credentials are already detected.
+ * See https://cloud.google.com/sdk/gcloud/reference/auth/application-default
+ *
+ * This will need user interaction so it is not supported for use in CI.
+ * To authenticate in CI, use setupAuthFromEnvironment().
+ */
+export declare function applicationDefaultLogin(shell: IShellExecutor, options?: IShellOptions): Promise<void>;
+/**
+ * Gets the path to the gcloud executable
+ * @returns The path to the gcloud executable
+ */
+export declare function getBinFolder(shell: IShellExecutor, options?: IShellOptions): Promise<string>;
+/**
+ * Data required to write service account credentials locally and prepare for GCP authentication
+ */
+export interface ISetupGoogleAuth {
+    /** Current system environment variables */
+    env: NodeJS.ProcessEnv;
+    /** Optional base64 encoded GCP service account */
+    credentialsContentBase64?: string;
+}
+/**
+ * Activates service account found at the given credentials path
+ *
+ * @param {string} credentialsPath Path to the GCP service account credentials
+ */
+export declare function activateServiceAccount(shell: IShellExecutor, credentialsPath: string, options?: IShellOptions): Promise<void>;
+/**
+ * Deactivates the currently active service account
+ */
+export declare function deactivateServiceAccount(shell: IShellExecutor, options?: IShellOptions): Promise<void>;
+/**
+ * Activates service account found at the given credentials path
+ *
+ * @param {() => Promise<TActionResult>} action Action to be executed once a google service account is active
+ * @param {string} credentialsPath Path to the GCP service account credentials
+ * @returns {Promise<TActionResult>}
+ */
+export declare function runWithActivatedServiceAccount<TActionResult>(shell: IShellExecutor, action: () => Promise<TActionResult>, credentialsPath: string, options?: IShellOptions): Promise<TActionResult>;
+/**
+ * Data required to upload a directory to a given GCS bucket
+ */
+export interface IUploadDirOptions {
+    /** Path to the local directory to be uploaded */
+    pathToDirectory: string;
+    /** Full path within the bucket to the parent directory */
+    bucketPath: string;
+    /** When set to true, files will be copied to the new location in parallel */
+    multiThread?: boolean;
+    /** When set to true, files will overwrite those in an existing directory of the same name */
+    overwrite?: boolean;
+}
+/**
+ * Uploads the given directory to the specified bucket path
+ *
+ * @param {IUploadDirOptions} options Includes options such as upload files in parallel or overwrite an existing dir with the same name
+ * @returns {Promise<void>}
+ */
+export declare function uploadDirectoryToBucket(shell: IShellExecutor, options: IUploadDirOptions, shellOptions?: IShellOptions): Promise<void>;
+/**
+ * Data required to rename a directory within a GCS bucket
+ */
+export interface IRenameBucketDirOptions {
+    /** Current name of the directory within the bucket */
+    currentName: string;
+    /** Desired new name of the directory within the bucket */
+    newName: string;
+    /** Full path within the bucket to the parent directory */
+    bucketPath: string;
+    /** When set to true, files will be copied to the new location in parallel */
+    multiThread?: boolean;
+    /** When set to true, files will overwrite those in an existing directory of the same name */
+    overwrite?: boolean;
+}
+/**
+ * Rename an existing directory within a gcs bucket
+ *
+ * @param {IRenameBucketDirOptions} options Includes options such as upload files in parallel or overwrite an existing dir with the same name
+ * @returns {Promise<void>}
+ */
+export declare function renameBucketDir(shell: IShellExecutor, options: IRenameBucketDirOptions, shellOptions?: IShellOptions): Promise<void>;
+/**
+ * Writes a google service account key to the file specified by GOOGLE_APPLICATION_CREDENTIALS.
+ *
+ * The GOOGLE_APPLICATION_CREDENTIALS_CONTENT is expected to contain the service account key encoded as base 64.
+ *
+ * @param env The collection of environment variables where the relevant variables are expected
+ * @returns {Promise<{ credentialsPath: string }>}
+ */
+export declare function setupAuthFromEnvironment({ env, credentialsContentBase64: credentialsContent, }: ISetupGoogleAuth): Promise<{
+    credentialsPath: string;
+}>;

package/lib/gcloud.js

@@ -0,0 +1,145 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.applicationDefaultLogin = applicationDefaultLogin;
+exports.getBinFolder = getBinFolder;
+exports.activateServiceAccount = activateServiceAccount;
+exports.deactivateServiceAccount = deactivateServiceAccount;
+exports.runWithActivatedServiceAccount = runWithActivatedServiceAccount;
+exports.uploadDirectoryToBucket = uploadDirectoryToBucket;
+exports.renameBucketDir = renameBucketDir;
+exports.setupAuthFromEnvironment = setupAuthFromEnvironment;
+const tslib_1 = require("tslib");
+const logger_1 = require("@rocketmakers/shell/logger");
+const Prerequisites = tslib_1.__importStar(require("@rocketmakers/shell/prerequisites"));
+const shell_fs_1 = require("@rocketmakers/shell-fs");
+const fs_1 = require("fs");
+const promises_1 = require("fs/promises");
+const os_1 = require("os");
+const path_1 = require("path");
+const base64_1 = require("./base64");
+const gcloud = 'gcloud';
+const gsutil = 'gsutil';
+const logger = (0, logger_1.createLogger)('gcloud-module');
+Prerequisites.register({
+    command: gcloud,
+    description: 'Google Cloud Platform command line tools',
+    docsUrl: 'https://cloud.google.com/sdk/gcloud/',
+}, {
+    command: gsutil,
+    description: 'Google Cloud Storage command line tools',
+    docsUrl: 'https://cloud.google.com/storage/docs/gsutil',
+});
+/**
+ * Starts an application default login if no application default credentials are already detected.
+ * See https://cloud.google.com/sdk/gcloud/reference/auth/application-default
+ *
+ * This will need user interaction so it is not supported for use in CI.
+ * To authenticate in CI, use setupAuthFromEnvironment().
+ */
+async function applicationDefaultLogin(shell, options) {
+    const credentialsJson = (0, path_1.join)((0, os_1.homedir)(), '.config', 'gcloud', 'application_default_credentials.json');
+    if ((0, fs_1.existsSync)(credentialsJson)) {
+        logger.warn('Detected gcloud application default credentials so skipping login. If this is not right then run "gcloud auth application-default revoke".');
+        return;
+    }
+    logger.info('Performing gcloud application default login - your browser will open...');
+    await shell.exec([gcloud, 'auth', 'application-default', 'login'], options);
+}
+/**
+ * Gets the path to the gcloud executable
+ * @returns The path to the gcloud executable
+ */
+async function getBinFolder(shell, options) {
+    return Prerequisites.which(shell, gcloud, options);
+}
+/**
+ * Activates service account found at the given credentials path
+ *
+ * @param {string} credentialsPath Path to the GCP service account credentials
+ */
+async function activateServiceAccount(shell, credentialsPath, options) {
+    await shell.exec([gcloud, 'auth', 'activate-service-account', '--key-file', credentialsPath], options);
+}
+/**
+ * Deactivates the currently active service account
+ */
+async function deactivateServiceAccount(shell, options) {
+    await shell.exec([gcloud, 'auth', 'revoke'], options);
+}
+/**
+ * Activates service account found at the given credentials path
+ *
+ * @param {() => Promise<TActionResult>} action Action to be executed once a google service account is active
+ * @param {string} credentialsPath Path to the GCP service account credentials
+ * @returns {Promise<TActionResult>}
+ */
+async function runWithActivatedServiceAccount(shell, action, credentialsPath, options) {
+    await activateServiceAccount(shell, credentialsPath, options);
+    const res = await action();
+    await deactivateServiceAccount(shell, options);
+    return res;
+}
+/**
+ * Uploads the given directory to the specified bucket path
+ *
+ * @param {IUploadDirOptions} options Includes options such as upload files in parallel or overwrite an existing dir with the same name
+ * @returns {Promise<void>}
+ */
+async function uploadDirectoryToBucket(shell, options, shellOptions) {
+    // -m (allow multi-threading and files to be uploaded in parallel - hangs on mac os)
+    // -n (no overwrite of existing files in bucket)
+    // -r (copy all contents including sub dirs)
+    const gsutilArgs = [
+        `${options.multiThread ? '-m' : ''}`,
+        'cp',
+        `${options.overwrite ? '' : '-n'}`,
+        '-r',
+        `${options.pathToDirectory}`,
+        options.bucketPath,
+    ];
+    await shell.exec(['gsutil', ...gsutilArgs.filter(arg => arg !== '')], shellOptions);
+}
+/**
+ * Rename an existing directory within a gcs bucket
+ *
+ * @param {IRenameBucketDirOptions} options Includes options such as upload files in parallel or overwrite an existing dir with the same name
+ * @returns {Promise<void>}
+ */
+async function renameBucketDir(shell, options, shellOptions) {
+    // -m (allow multi-threading and files to be uploaded in parallel - hangs on mac os)
+    // -n (no overwrite of existing files in bucket)
+    const gsutilArgs = [
+        `${options.multiThread ? '-m' : ''}`,
+        'mv',
+        `${options.overwrite ? '' : '-n'}`,
+        `${options.bucketPath}/${options.currentName}`,
+        `${options.bucketPath}/${options.newName}`,
+    ];
+    await shell.exec(['gsutil', ...gsutilArgs.filter(arg => arg !== '')], shellOptions);
+}
+/**
+ * Writes a google service account key to the file specified by GOOGLE_APPLICATION_CREDENTIALS.
+ *
+ * The GOOGLE_APPLICATION_CREDENTIALS_CONTENT is expected to contain the service account key encoded as base 64.
+ *
+ * @param env The collection of environment variables where the relevant variables are expected
+ * @returns {Promise<{ credentialsPath: string }>}
+ */
+async function setupAuthFromEnvironment({ env, credentialsContentBase64: credentialsContent, }) {
+    const credentialsPath = env.GOOGLE_APPLICATION_CREDENTIALS;
+    if (!credentialsPath) {
+        throw new Error('You need set GOOGLE_APPLICATION_CREDENTIALS to a path in an existing directory so the google service account key can be written to that file');
+    }
+    const credentialsContentBase64 = env.GOOGLE_APPLICATION_CREDENTIALS_CONTENT || credentialsContent;
+    if (!credentialsContentBase64) {
+        throw new Error(`You need to provide the GCP service account key as base64 - either directly or via GOOGLE_APPLICATION_CREDENTIALS_CONTENT - so it can be written to '${credentialsPath}'`);
+    }
+    const credentialsDirPath = (0, shell_fs_1.getDirectoryPathFromFilePath)(credentialsPath);
+    if (credentialsDirPath === undefined || !(0, shell_fs_1.isDirectory)(credentialsDirPath)) {
+        throw new Error(`Not writing GOOGLE_APPLICATION_CREDENTIALS_CONTENT to disk because '${credentialsDirPath}' is not an existing directory.`);
+    }
+    const credentialsDecoded = (0, base64_1.fromBASE64)(credentialsContentBase64);
+    await (0, promises_1.writeFile)(credentialsPath, credentialsDecoded);
+    logger.info(`Written GOOGLE_APPLICATION_CREDENTIALS_CONTENT to '${credentialsPath}'`);
+    return { credentialsPath };
+}

package/lib/run/gcloudAuth.d.ts

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+/**
+ *
+ *  The following script allows you to log into gcloud, which can be particularly useful during CI jobs. GCP service account key can be passed as a script argument or environment variable as below.
+ *  If not running in CI then the script will automatically trigger `gcloud auth application-default login` unless you are already logged in.
+ *
+ *  **Passing credentials for authentication**
+ *  -  When running in CI `GOOGLE_APPLICATION_CREDENTIALS` is a required environment variable,  set as the path to a local file where the base64 decoded key will be written to support authentication.
+ *  -  The base64 encoded service account can either be passed as a script arg using `--base64Key` (see below) or set using the environment variable `GOOGLE_APPLICATION_CREDENTIALS_CONTENT`. When both are provided the env variable will take precedence.
+ *
+ *  Below is an example call:
+ *
+ *  ```bash
+ *  npx rocketmakers-gcloud-auth -l=trace
+ *
+ *  # Run the following to see expected args and valid values
+ *  npx rocketmakers-gcloud-auth --help
+ *
+ *  # --log (-l) - single
+ *  #  > The log level
+ *  #  > Optional Default: "info"
+ *  #  > Must be: trace | debug | info | warn | error | fatal
+ *
+ *  # --base64Key (-k) - single
+ *  #  > The GCP service account key encoded as base64
+ *  #  > Optional Default: ""
+ *  ```
+ *
+ */
+export declare function runGcloudAuth(): Promise<void>;

package/lib/run/gcloudAuth.js

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runGcloudAuth = runGcloudAuth;
+const tslib_1 = require("tslib");
+const Args = tslib_1.__importStar(require("@rocketmakers/shell/args"));
+const logger_1 = require("@rocketmakers/shell/logger");
+const Prerequisites = tslib_1.__importStar(require("@rocketmakers/shell/prerequisites"));
+const shell_executor_1 = require("@rocketmakers/shell-executor");
+const env_1 = require("../env");
+const GoogleCloud = tslib_1.__importStar(require("../gcloud"));
+const logger = (0, logger_1.createLogger)('gcloud-auth');
+const shell = new shell_executor_1.ShellExecutor();
+/**
+ *
+ *  The following script allows you to log into gcloud, which can be particularly useful during CI jobs. GCP service account key can be passed as a script argument or environment variable as below.
+ *  If not running in CI then the script will automatically trigger `gcloud auth application-default login` unless you are already logged in.
+ *
+ *  **Passing credentials for authentication**
+ *  -  When running in CI `GOOGLE_APPLICATION_CREDENTIALS` is a required environment variable,  set as the path to a local file where the base64 decoded key will be written to support authentication.
+ *  -  The base64 encoded service account can either be passed as a script arg using `--base64Key` (see below) or set using the environment variable `GOOGLE_APPLICATION_CREDENTIALS_CONTENT`. When both are provided the env variable will take precedence.
+ *
+ *  Below is an example call:
+ *
+ *  ```bash
+ *  npx rocketmakers-gcloud-auth -l=trace
+ *
+ *  # Run the following to see expected args and valid values
+ *  npx rocketmakers-gcloud-auth --help
+ *
+ *  # --log (-l) - single
+ *  #  > The log level
+ *  #  > Optional Default: "info"
+ *  #  > Must be: trace | debug | info | warn | error | fatal
+ *
+ *  # --base64Key (-k) - single
+ *  #  > The GCP service account key encoded as base64
+ *  #  > Optional Default: ""
+ *  ```
+ *
+ */
+async function runGcloudAuth() {
+    const args = await Args.match({
+        log: Args.single({
+            description: 'The log level',
+            shortName: 'l',
+            defaultValue: process.env.LOG_LEVEL || 'info',
+            validValues: ['trace', 'debug', 'info', 'warn', 'error', 'fatal'],
+        }),
+        base64Key: Args.single({
+            description: 'The GCP service account key encoded as base64',
+            shortName: 'k',
+        }),
+    });
+    if (args === null || args === void 0 ? void 0 : args.log) {
+        (0, logger_1.setDefaultLoggerLevel)(args.log);
+    }
+    if (!args) {
+        if (process.argv.includes('--help')) {
+            return;
+        }
+        throw new Error('There was a problem parsing the arguments');
+    }
+    await Prerequisites.check(shell);
+    await ((0, env_1.isCI)()
+        ? GoogleCloud.setupAuthFromEnvironment({
+            env: (0, env_1.cloneEnvironment)(),
+            credentialsContentBase64: args.base64Key,
+        })
+        : GoogleCloud.applicationDefaultLogin(shell));
+}
+runGcloudAuth()
+    .then(() => logger.info('🚀 Done 🚀'))
+    .catch(err => {
+    logger.fatal(err);
+    process.exit(-1);
+});

package/lib/source/base64.d.ts

@@ -0,0 +1,2 @@
+export declare function toBASE64(value: string): string;
+export declare function fromBASE64(encoded: string): string;

package/lib/source/base64.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toBASE64 = toBASE64;
+exports.fromBASE64 = fromBASE64;
+function toBASE64(value) {
+    return Buffer.from(value).toString('base64');
+}
+function fromBASE64(encoded) {
+    const buff = Buffer.from(encoded, 'base64');
+    return buff.toString('ascii');
+}

package/lib/source/env.d.ts

@@ -0,0 +1,2 @@
+export declare function cloneEnvironment(): NodeJS.ProcessEnv;
+export declare function isCI(): boolean;

package/lib/source/env.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.cloneEnvironment = cloneEnvironment;
+exports.isCI = isCI;
+function cloneEnvironment() {
+    return Object.create(process.env);
+}
+function isCI() {
+    return process.env.CI === 'true';
+}

package/lib/source/gcloud.d.ts

@@ -0,0 +1,103 @@
+import { IShellExecutor } from '@rocketmakers/shell/executor';
+import { IShellOptions } from '@rocketmakers/shell/options';
+/**
+ * Indicates the location of a GKE cluster either as a region or a zone.
+ * This is used to interact with the 'gcloud container clusters' CLI.
+ */
+export interface IClusterLocation {
+    type: 'region' | 'zone';
+    value: string;
+}
+/**
+ * Starts an application default login if no application default credentials are already detected.
+ * See https://cloud.google.com/sdk/gcloud/reference/auth/application-default
+ *
+ * This will need user interaction so it is not supported for use in CI.
+ * To authenticate in CI, use setupAuthFromEnvironment().
+ */
+export declare function applicationDefaultLogin(shell: IShellExecutor, options?: IShellOptions): Promise<void>;
+/**
+ * Gets the path to the gcloud executable
+ * @returns The path to the gcloud executable
+ */
+export declare function getBinFolder(shell: IShellExecutor, options?: IShellOptions): Promise<string>;
+/**
+ * Data required to write service account credentials locally and prepare for GCP authentication
+ */
+export interface ISetupGoogleAuth {
+    /** Current system environment variables */
+    env: NodeJS.ProcessEnv;
+    /** Optional base64 encoded GCP service account */
+    credentialsContentBase64?: string;
+}
+/**
+ * Activates service account found at the given credentials path
+ *
+ * @param {string} credentialsPath Path to the GCP service account credentials
+ */
+export declare function activateServiceAccount(shell: IShellExecutor, credentialsPath: string, options?: IShellOptions): Promise<void>;
+/**
+ * Deactivates the currently active service account
+ */
+export declare function deactivateServiceAccount(shell: IShellExecutor, options?: IShellOptions): Promise<void>;
+/**
+ * Activates service account found at the given credentials path
+ *
+ * @param {() => Promise<TActionResult>} action Action to be executed once a google service account is active
+ * @param {string} credentialsPath Path to the GCP service account credentials
+ * @returns {Promise<TActionResult>}
+ */
+export declare function runWithActivatedServiceAccount<TActionResult>(shell: IShellExecutor, action: () => Promise<TActionResult>, credentialsPath: string, options?: IShellOptions): Promise<TActionResult>;
+/**
+ * Data required to upload a directory to a given GCS bucket
+ */
+export interface IUploadDirOptions {
+    /** Path to the local directory to be uploaded */
+    pathToDirectory: string;
+    /** Full path within the bucket to the parent directory */
+    bucketPath: string;
+    /** When set to true, files will be copied to the new location in parallel */
+    multiThread?: boolean;
+    /** When set to true, files will overwrite those in an existing directory of the same name */
+    overwrite?: boolean;
+}
+/**
+ * Uploads the given directory to the specified bucket path
+ *
+ * @param {IUploadDirOptions} options Includes options such as upload files in parallel or overwrite an existing dir with the same name
+ * @returns {Promise<void>}
+ */
+export declare function uploadDirectoryToBucket(shell: IShellExecutor, options: IUploadDirOptions, shellOptions?: IShellOptions): Promise<void>;
+/**
+ * Data required to rename a directory within a GCS bucket
+ */
+export interface IRenameBucketDirOptions {
+    /** Current name of the directory within the bucket */
+    currentName: string;
+    /** Desired new name of the directory within the bucket */
+    newName: string;
+    /** Full path within the bucket to the parent directory */
+    bucketPath: string;
+    /** When set to true, files will be copied to the new location in parallel */
+    multiThread?: boolean;
+    /** When set to true, files will overwrite those in an existing directory of the same name */
+    overwrite?: boolean;
+}
+/**
+ * Rename an existing director within a gcs bucket
+ *
+ * @param {IRenameBucketDirOptions} options Includes options such as upload files in parallel or overwrite an existing dir with the same name
+ * @returns {Promise<void>}
+ */
+export declare function renameBucketDir(shell: IShellExecutor, options: IRenameBucketDirOptions, shellOptions?: IShellOptions): Promise<void>;
+/**
+ * Writes a google service account key to the file specified by GOOGLE_APPLICATION_CREDENTIALS.
+ *
+ * The GOOGLE_APPLICATION_CREDENTIALS_CONTENT is expected to contain the service account key encoded as base 64.
+ *
+ * @param env The collection of environment variables where the relevant variables are expected
+ * @returns {Promise<{ credentialsPath: string }>}
+ */
+export declare function setupAuthFromEnvironment({ env, credentialsContentBase64: credentialsContent, }: ISetupGoogleAuth): Promise<{
+    credentialsPath: string;
+}>;

package/lib/source/gcloud.js

@@ -0,0 +1,145 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.applicationDefaultLogin = applicationDefaultLogin;
+exports.getBinFolder = getBinFolder;
+exports.activateServiceAccount = activateServiceAccount;
+exports.deactivateServiceAccount = deactivateServiceAccount;
+exports.runWithActivatedServiceAccount = runWithActivatedServiceAccount;
+exports.uploadDirectoryToBucket = uploadDirectoryToBucket;
+exports.renameBucketDir = renameBucketDir;
+exports.setupAuthFromEnvironment = setupAuthFromEnvironment;
+const tslib_1 = require("tslib");
+const logger_1 = require("@rocketmakers/shell/logger");
+const Prerequisites = tslib_1.__importStar(require("@rocketmakers/shell/prerequisites"));
+const shell_fs_1 = require("@rocketmakers/shell-fs");
+const fs_1 = require("fs");
+const promises_1 = require("fs/promises");
+const os_1 = require("os");
+const path_1 = require("path");
+const base64_1 = require("./base64");
+const gcloud = 'gcloud';
+const gsutil = 'gsutil';
+const logger = (0, logger_1.createLogger)('gcloud-module');
+Prerequisites.register({
+    command: gcloud,
+    description: 'Google Cloud Platform command line tools',
+    docsUrl: 'https://cloud.google.com/sdk/gcloud/',
+}, {
+    command: gsutil,
+    description: 'Google Cloud Storage command line tools',
+    docsUrl: 'https://cloud.google.com/storage/docs/gsutil',
+});
+/**
+ * Starts an application default login if no application default credentials are already detected.
+ * See https://cloud.google.com/sdk/gcloud/reference/auth/application-default
+ *
+ * This will need user interaction so it is not supported for use in CI.
+ * To authenticate in CI, use setupAuthFromEnvironment().
+ */
+async function applicationDefaultLogin(shell, options) {
+    const credentialsJson = (0, path_1.join)((0, os_1.homedir)(), '.config', 'gcloud', 'application_default_credentials.json');
+    if ((0, fs_1.existsSync)(credentialsJson)) {
+        logger.warn('Detected gcloud application default credentials so skipping login. If this is not right then run "gcloud auth application-default revoke".');
+        return;
+    }
+    logger.info('Performing gcloud application default login - your browser will open...');
+    await shell.exec([gcloud, 'auth', 'application-default', 'login'], options);
+}
+/**
+ * Gets the path to the gcloud executable
+ * @returns The path to the gcloud executable
+ */
+async function getBinFolder(shell, options) {
+    return Prerequisites.which(shell, gcloud, options);
+}
+/**
+ * Activates service account found at the given credentials path
+ *
+ * @param {string} credentialsPath Path to the GCP service account credentials
+ */
+async function activateServiceAccount(shell, credentialsPath, options) {
+    await shell.exec([gcloud, 'auth', 'activate-service-account', '--key-file', credentialsPath], options);
+}
+/**
+ * Deactivates the currently active service account
+ */
+async function deactivateServiceAccount(shell, options) {
+    await shell.exec([gcloud, 'auth', 'revoke'], options);
+}
+/**
+ * Activates service account found at the given credentials path
+ *
+ * @param {() => Promise<TActionResult>} action Action to be executed once a google service account is active
+ * @param {string} credentialsPath Path to the GCP service account credentials
+ * @returns {Promise<TActionResult>}
+ */
+async function runWithActivatedServiceAccount(shell, action, credentialsPath, options) {
+    await activateServiceAccount(shell, credentialsPath, options);
+    const res = await action();
+    await deactivateServiceAccount(shell, options);
+    return res;
+}
+/**
+ * Uploads the given directory to the specified bucket path
+ *
+ * @param {IUploadDirOptions} options Includes options such as upload files in parallel or overwrite an existing dir with the same name
+ * @returns {Promise<void>}
+ */
+async function uploadDirectoryToBucket(shell, options, shellOptions) {
+    // -m (allow multi-threading and files to be uploaded in parallel - hangs on mac os)
+    // -n (no overwrite of existing files in bucket)
+    // -r (copy all contents including sub dirs)
+    const gsutilArgs = [
+        `${options.multiThread ? '-m' : ''}`,
+        'cp',
+        `${options.overwrite ? '' : '-n'}`,
+        '-r',
+        `${options.pathToDirectory}`,
+        options.bucketPath,
+    ];
+    await shell.exec(['gsutil', ...gsutilArgs.filter(arg => arg !== '')], shellOptions);
+}
+/**
+ * Rename an existing director within a gcs bucket
+ *
+ * @param {IRenameBucketDirOptions} options Includes options such as upload files in parallel or overwrite an existing dir with the same name
+ * @returns {Promise<void>}
+ */
+async function renameBucketDir(shell, options, shellOptions) {
+    // -m (allow multi-threading and files to be uploaded in parallel - hangs on mac os)
+    // -n (no overwrite of existing files in bucket)
+    const gsutilArgs = [
+        `${options.multiThread ? '-m' : ''}`,
+        'mv',
+        `${options.overwrite ? '' : '-n'}`,
+        `${options.bucketPath}/${options.currentName}`,
+        `${options.bucketPath}/${options.newName}`,
+    ];
+    await shell.exec(['gsutil', ...gsutilArgs.filter(arg => arg !== '')], shellOptions);
+}
+/**
+ * Writes a google service account key to the file specified by GOOGLE_APPLICATION_CREDENTIALS.
+ *
+ * The GOOGLE_APPLICATION_CREDENTIALS_CONTENT is expected to contain the service account key encoded as base 64.
+ *
+ * @param env The collection of environment variables where the relevant variables are expected
+ * @returns {Promise<{ credentialsPath: string }>}
+ */
+async function setupAuthFromEnvironment({ env, credentialsContentBase64: credentialsContent, }) {
+    const credentialsPath = env.GOOGLE_APPLICATION_CREDENTIALS;
+    if (!credentialsPath) {
+        throw new Error('You need set GOOGLE_APPLICATION_CREDENTIALS to a path in an existing directory so the google service account key can be written to that file');
+    }
+    const credentialsContentBase64 = env.GOOGLE_APPLICATION_CREDENTIALS_CONTENT || credentialsContent;
+    if (!credentialsContentBase64) {
+        throw new Error(`You need to provide the GCP service account key as base64 - either directly or via GOOGLE_APPLICATION_CREDENTIALS_CONTENT - so it can be written to '${credentialsPath}'`);
+    }
+    const credentialsDirPath = (0, shell_fs_1.getDirectoryPathFromFilePath)(credentialsPath);
+    if (credentialsDirPath === undefined || !(0, shell_fs_1.isDirectory)(credentialsDirPath)) {
+        throw new Error(`Not writing GOOGLE_APPLICATION_CREDENTIALS_CONTENT to disk because '${credentialsDirPath}' is not an existing directory.`);
+    }
+    const credentialsDecoded = (0, base64_1.fromBASE64)(credentialsContentBase64);
+    await (0, promises_1.writeFile)(credentialsPath, credentialsDecoded);
+    logger.info(`Written GOOGLE_APPLICATION_CREDENTIALS_CONTENT to '${credentialsPath}'`);
+    return { credentialsPath };
+}

package/lib/source/run/gcloudAuth.d.ts

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+/**
+ *
+ *  The following script allows you to log into gcloud, which can be particularly useful during CI jobs. GCP service account key can be passed as a script argument or environment variable as below.
+ *  If not running in CI then the script will automatically trigger `gcloud auth application-default login` unless you are already logged in.
+ *
+ *  **Passing credentials for authentication**
+ *  -  When running in CI `GOOGLE_APPLICATION_CREDENTIALS` is a required environment variable,  set as the path to a local file where the base64 decoded key will be written to support authentication.
+ *  -  The base64 encoded service account can either be passed as a script arg using `--base64Key` (see below) or set using the environment variable `GOOGLE_APPLICATION_CREDENTIALS_CONTENT`. When both are provided the env variable will take precedence.
+ *
+ *  Below is an example call:
+ *
+ *  ```bash
+ *  npx rocketmakers-gcloud-auth -l=trace
+ *
+ *  # Run the following to see expected args and valid values
+ *  npx rocketmakers-gcloud-auth --help
+ *
+ *  # --log (-l) - single
+ *  #  > The log level
+ *  #  > Optional Default: "info"
+ *  #  > Must be: trace | debug | info | warn | error | fatal
+ *
+ *  # --base64Key (-k) - single
+ *  #  > The GCP service account key encoded as base64
+ *  #  > Optional Default: ""
+ *  ```
+ *
+ */
+export declare function runGcloudAuth(): Promise<void>;

package/lib/source/run/gcloudAuth.js

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runGcloudAuth = runGcloudAuth;
+const tslib_1 = require("tslib");
+const Args = tslib_1.__importStar(require("@rocketmakers/shell/args"));
+const logger_1 = require("@rocketmakers/shell/logger");
+const Prerequisites = tslib_1.__importStar(require("@rocketmakers/shell/prerequisites"));
+const shell_executor_1 = require("@rocketmakers/shell-executor");
+const env_1 = require("../env");
+const GoogleCloud = tslib_1.__importStar(require("../gcloud"));
+const logger = (0, logger_1.createLogger)('gcloud-auth');
+const shell = new shell_executor_1.ShellExecutor();
+/**
+ *
+ *  The following script allows you to log into gcloud, which can be particularly useful during CI jobs. GCP service account key can be passed as a script argument or environment variable as below.
+ *  If not running in CI then the script will automatically trigger `gcloud auth application-default login` unless you are already logged in.
+ *
+ *  **Passing credentials for authentication**
+ *  -  When running in CI `GOOGLE_APPLICATION_CREDENTIALS` is a required environment variable,  set as the path to a local file where the base64 decoded key will be written to support authentication.
+ *  -  The base64 encoded service account can either be passed as a script arg using `--base64Key` (see below) or set using the environment variable `GOOGLE_APPLICATION_CREDENTIALS_CONTENT`. When both are provided the env variable will take precedence.
+ *
+ *  Below is an example call:
+ *
+ *  ```bash
+ *  npx rocketmakers-gcloud-auth -l=trace
+ *
+ *  # Run the following to see expected args and valid values
+ *  npx rocketmakers-gcloud-auth --help
+ *
+ *  # --log (-l) - single
+ *  #  > The log level
+ *  #  > Optional Default: "info"
+ *  #  > Must be: trace | debug | info | warn | error | fatal
+ *
+ *  # --base64Key (-k) - single
+ *  #  > The GCP service account key encoded as base64
+ *  #  > Optional Default: ""
+ *  ```
+ *
+ */
+async function runGcloudAuth() {
+    const args = await Args.match({
+        log: Args.single({
+            description: 'The log level',
+            shortName: 'l',
+            defaultValue: process.env.LOG_LEVEL || 'info',
+            validValues: ['trace', 'debug', 'info', 'warn', 'error', 'fatal'],
+        }),
+        base64Key: Args.single({
+            description: 'The GCP service account key encoded as base64',
+            shortName: 'k',
+        }),
+    });
+    if (args === null || args === void 0 ? void 0 : args.log) {
+        (0, logger_1.setDefaultLoggerLevel)(args.log);
+    }
+    if (!args) {
+        if (process.argv.includes('--help')) {
+            return;
+        }
+        throw new Error('There was a problem parsing the arguments');
+    }
+    await Prerequisites.check(shell);
+    await ((0, env_1.isCI)()
+        ? GoogleCloud.setupAuthFromEnvironment({
+            env: (0, env_1.cloneEnvironment)(),
+            credentialsContentBase64: args.base64Key,
+        })
+        : GoogleCloud.applicationDefaultLogin(shell));
+}
+runGcloudAuth()
+    .then(() => logger.info('🚀 Done 🚀'))
+    .catch(err => {
+    logger.fatal(err);
+    process.exit(-1);
+});

package/lib/tests/gcloud.test.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/tests/gcloud.test.js

@@ -0,0 +1,90 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const suite_1 = require("@rocketmakers/shell-tests/suite");
+const promises_1 = require("fs/promises");
+const base64_1 = require("../source/base64");
+const gcloud_1 = require("../source/gcloud");
+const packagePaths_1 = require("./packagePaths");
+(0, suite_1.sandboxedTestSuite)({ suiteName: 'gcloud', sandboxRootPath: (0, packagePaths_1.sandboxPath)() }, () => {
+    describe('setupAuthFromEnvironment', () => {
+        const credentialsPath = (0, packagePaths_1.sandboxPath)('credentials.json');
+        const credentialsContent = 'fake credentials';
+        const credentialsContentBase64 = (0, base64_1.toBASE64)(credentialsContent);
+        it('when GOOGLE_APPLICATION_CREDENTIALS and GOOGLE_APPLICATION_CREDENTIALS_CONTENT are set, the credentials are written to the file', async () => {
+            await (0, gcloud_1.setupAuthFromEnvironment)({
+                env: {
+                    GOOGLE_APPLICATION_CREDENTIALS: credentialsPath,
+                    GOOGLE_APPLICATION_CREDENTIALS_CONTENT: credentialsContentBase64,
+                },
+            });
+            const content = await (0, promises_1.readFile)(credentialsPath, { encoding: 'utf8' });
+            expect(content).toEqual(credentialsContent);
+        });
+        it('GOOGLE_APPLICATION_CREDENTIALS_CONTENT overrides the credentialsContentBase64 option', async () => {
+            const specificCredentials = 'some specific content';
+            const specificCredentialsBase64 = (0, base64_1.toBASE64)(specificCredentials);
+            await (0, gcloud_1.setupAuthFromEnvironment)({
+                credentialsContentBase64: specificCredentialsBase64,
+                env: {
+                    GOOGLE_APPLICATION_CREDENTIALS: credentialsPath,
+                    GOOGLE_APPLICATION_CREDENTIALS_CONTENT: credentialsContentBase64,
+                },
+            });
+            const content = await (0, promises_1.readFile)(credentialsPath, { encoding: 'utf8' });
+            expect(content).toEqual(credentialsContent);
+        });
+        it('when credentialsContentBase64 is provided without GOOGLE_APPLICATION_CREDENTIALS_CONTENT, the credentials are written to the file', async () => {
+            const specificCredentials = 'some specific content';
+            const specificCredentialsBase64 = (0, base64_1.toBASE64)(specificCredentials);
+            await (0, gcloud_1.setupAuthFromEnvironment)({
+                credentialsContentBase64: specificCredentialsBase64,
+                env: {
+                    GOOGLE_APPLICATION_CREDENTIALS: credentialsPath,
+                },
+            });
+            const content = await (0, promises_1.readFile)(credentialsPath, { encoding: 'utf8' });
+            expect(content).toEqual(specificCredentials);
+        });
+        it('when GOOGLE_APPLICATION_CREDENTIALS is not set, throws an error', async () => {
+            expect.assertions(1);
+            try {
+                await (0, gcloud_1.setupAuthFromEnvironment)({
+                    env: {
+                        GOOGLE_APPLICATION_CREDENTIALS_CONTENT: credentialsContentBase64,
+                    },
+                });
+            }
+            catch (err) {
+                expect(err.message).toContain('GOOGLE_APPLICATION_CREDENTIALS');
+            }
+        });
+        const notDirectoryPaths = ['/not/a/directory', ''];
+        notDirectoryPaths.forEach(testPath => it(`when GOOGLE_APPLICATION_CREDENTIALS is '${testPath}', throws an error`, async () => {
+            expect.assertions(1);
+            try {
+                await (0, gcloud_1.setupAuthFromEnvironment)({
+                    env: {
+                        GOOGLE_APPLICATION_CREDENTIALS: testPath,
+                        GOOGLE_APPLICATION_CREDENTIALS_CONTENT: credentialsContentBase64,
+                    },
+                });
+            }
+            catch (err) {
+                expect(err.message).toContain('GOOGLE_APPLICATION_CREDENTIALS');
+            }
+        }));
+        it('when GOOGLE_APPLICATION_CREDENTIALS_CONTENT is not set, throws an error', async () => {
+            expect.assertions(1);
+            try {
+                await (0, gcloud_1.setupAuthFromEnvironment)({
+                    env: {
+                        GOOGLE_APPLICATION_CREDENTIALS: credentialsPath,
+                    },
+                });
+            }
+            catch (err) {
+                expect(err.message).toContain('GOOGLE_APPLICATION_CREDENTIALS_CONTENT');
+            }
+        });
+    });
+});

package/lib/tests/packagePaths.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Creates an absolute path based on a relative path from the root of this package
+ * @param parts
+ */
+export declare function packagePath(...parts: string[]): string;
+/**
+ * Creates an absolute path relative to the sandbox testing path
+ * @param parts The parts of the path relative to the testing sandbox path
+ */
+export declare function sandboxPath(...parts: string[]): string;

package/lib/tests/packagePaths.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.packagePath = packagePath;
+exports.sandboxPath = sandboxPath;
+const path_1 = require("path");
+/**
+ * Creates an absolute path based on a relative path from the root of this package
+ * @param parts
+ */
+function packagePath(...parts) {
+    return (0, path_1.resolve)(__dirname, '..', ...parts);
+}
+/**
+ * Creates an absolute path relative to the sandbox testing path
+ * @param parts The parts of the path relative to the testing sandbox path
+ */
+function sandboxPath(...parts) {
+    return (0, path_1.join)(packagePath('_tests-sandbox_'), ...parts);
+}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@rocketmakers/shell-gcloud",
+  "version": "0.1.0",
+  "bin": {
+    "rocketmakers-gcloud-auth": "./lib/run/gcloud-auth.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./lib/gcloud.d.ts",
+      "default": "./lib/gcloud.js"
+    }
+  },
+  "dependencies": {
+    "@rocketmakers/log": "0.1.0",
+    "bunyan": "1.8.12",
+    "tslib": "2.8.1",
+    "@rocketmakers/shell-executor": "0.1.0",
+    "@rocketmakers/shell": "0.1.0",
+    "@rocketmakers/shell-fs": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/jest": "29.5.14",
+    "@types/node": "22.13.9",
+    "eslint": "8.57.1",
+    "jest": "29.7.0",
+    "jest-junit": "16.0.0",
+    "ts-jest": "29.3.0",
+    "typescript": "5.8.2",
+    "@rocketmakers/shell-tests": "0.1.0",
+    "eslint-config-shell": "0.1.0",
+    "tsconfig-shell": "0.1.0"
+  },
+  "directories": {
+    "lib": "lib"
+  },
+  "engines": {
+    "node": " ^20 || ^22"
+  },
+  "files": [
+    "lib/**/*.js",
+    "lib/**/*.d.ts",
+    "!lib/index.js",
+    "!lib/index.d.ts"
+  ],
+  "keywords": [],
+  "license": "MIT",
+  "repository": "Rocketmakers/rocketmakers-packages",
+  "scripts": {
+    "build": "tsc -p .",
+    "lint": "eslint . --ext .ts",
+    "lint-fix": "pnpm lint --fix",
+    "test-integration": "jest --runInBand"
+  }
+}