@automattic/vip 2.36.2-dev.0 → 2.36.3

package/.eslintrc.js

@@ -0,0 +1,22 @@
+require( '@automattic/eslint-plugin-wpvip/init' );
+
+module.exports = {
+	extends: [
+		'plugin:@automattic/wpvip/recommended',
+		'plugin:@automattic/wpvip/cli',
+		'plugin:@automattic/wpvip/weak-testing',
+		'plugin:@automattic/wpvip/typescript',
+	],
+	rules: {
+		camelcase: 'warn',
+		'jest/no-mocks-import': 'warn',
+		'no-await-in-loop': 'warn',
+		'no-console': 0,
+		'security/detect-object-injection': 0,
+		'security/detect-non-literal-fs-filename': 0,
+		'promise/no-multiple-resolved': 0,
+		'no-unused-vars': 'off',
+		'@typescript-eslint/no-unused-vars': 'warn',
+	},
+	root: true,
+};

package/.prettierignore

@@ -1,4 +1,4 @@
-/CHANGELOG.md
+/docs/CHANGELOG.md
 /__fixtures__/
 /dist/
-/flow-typed/
+/npm-shrinkwrap.json

package/README.md

@@ -1,31 +1,20 @@
-VIP-CLI is your tool for interacting with and managing your VIP applications.
+# VIP-CLI
 
-## Getting started
+VIP-CLI is a tool for interacting with and managing your [WordPress VIP applications](https://wpvip.com/).
 
-First, install the package:
+## Further documentation
 
-```
-npm install -g @automattic/vip
-```
+- [SETUP.md](https://github.com/Automattic/vip-cli/blob/trunk/docs/SETUP.md) for installation and setup instructions, basic usage and environmental variables.
+- [ARCHITECTURE.md](https://github.com/Automattic/vip-cli/blob/trunk/docs/ARCHITECTURE.md) for information on architecture, code structure, data storage and security.
+- [CONTRIBUTING.md](https://github.com/Automattic/vip-cli/blob/trunk/docs/CONTRIBUTING.md) for information on how to contribute patches and features, also issue and pull request labels.
+- [DEBUGGING.md](https://github.com/Automattic/vip-cli/blob/trunk/docs/DEBUGGING.md) for information on how to debug the software.
+- [TESTING.md](https://github.com/Automattic/vip-cli/blob/trunk/docs/TESTING.md) for details on testing the software and individual tasks.
+- [RELEASING.md](https://github.com/Automattic/vip-cli/blob/trunk/docs/RELEASING.md) for details on deploying a new release.
+- [SECURITY.md](https://github.com/Automattic/vip-cli/blob/trunk/docs/SECURITY.md) for information if you **found a security issue**.
 
-The above command may fail in linux if you do not have `make` and `g++` installed. In that case, install them first:
+## Further information
 
-```
-sudo apt install make g++
-```
-
-Then, launch the command and follow the prompts:
-
-```
-vip
-```
-
-If you need more information, check out our [VIP-CLI documentation](https://docs.wpvip.com/technical-references/vip-cli/).
-
-## Contributing
-
-For help with contributing to this project, including instructions for local development, please see [CONTRIBUTING](CONTRIBUTING.md) and [SECURITY](SECURITY.md).
-
-## Analytics
-
-By default, we record information about the usage of this tool using an in-house analytics sytem. If you would prefer to opt-out of this data collection, you can do so via the `DO_NOT_TRACK` environment variable. You may either export it in your shell configuration or specify it on the command line (e.g. `DO_NOT_TRACK=1 vip app list`).
+- In the [WordPress VIP Lobby](https://lobby.vip.wordpress.com/) find announcements related to the [CLI](https://lobby.vip.wordpress.com/?s=vip-cli) and [API](https://lobby.vip.wordpress.com/?s=vip%20go%20api).
+- The [WordPress VIP Documentation](https://docs.wpvip.com/) has instructions related to the [CLI](https://docs.wpvip.com/technical-references/vip-cli/).
+- [Changelog](https://github.com/Automattic/vip-cli/blob/trunk/docs/CHANGELOG.md) file for VIP-CLI is available.
+- [VIP Cloud Changelog](https://wpvipchangelog.wordpress.com/) logs changes to the [CLI](https://wpvipchangelog.wordpress.com/?s=cli) and other aspects of the platform.

package/assets/dev-env.lando.template.yml.ejs

@@ -17,7 +17,7 @@ services:
     type: compose
     services:
       image: ghcr.io/automattic/vip-container-images/dev-tools:0.9
-      command: exit 0
+      command: /bin/true
       volumes:
         - devtools:/dev-tools
         - scripts:/scripts

package/dist/bin/vip-dev-env-purge.js

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+
+/**
+ * External dependencies
+ */
+"use strict";
+
+var _chalk = _interopRequireDefault(require("chalk"));
+var _debug = _interopRequireDefault(require("debug"));
+var _command = _interopRequireDefault(require("../lib/cli/command"));
+var _devEnvironment = require("../lib/constants/dev-environment");
+var _devEnvironmentCli = require("../lib/dev-environment/dev-environment-cli");
+var _devEnvironmentCore = require("../lib/dev-environment/dev-environment-core");
+var _devEnvironmentLando = require("../lib/dev-environment/dev-environment-lando");
+var _tracker = require("../lib/tracker");
+function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
+/**
+ * Internal dependencies
+ */
+const debug = (0, _debug.default)('@automattic/vip:bin:dev-environment');
+const examples = [{
+  usage: `${_devEnvironment.DEV_ENVIRONMENT_FULL_COMMAND} purge`,
+  description: 'Destroys all local dev environments'
+}, {
+  usage: `${_devEnvironment.DEV_ENVIRONMENT_FULL_COMMAND} purge --force`,
+  description: 'Destroys all local dev environments without prompting'
+}];
+(0, _command.default)().option('soft', 'Keep config files needed to start an environment intact').option('force', 'Removes prompt that verifies if user wants to destroy all environments').examples(examples).argv(process.argv, async (arg, opt) => {
+  debug('Args: ', arg, 'Options: ', opt);
+  const allEnvNames = (0, _devEnvironmentCore.getAllEnvironmentNames)();
+  const lando = await (0, _devEnvironmentLando.bootstrapLando)();
+  if (allEnvNames.length === 0) {
+    console.log('No environments to purge!');
+    return;
+  }
+  if (!opt.force) {
+    const purge = await (0, _devEnvironmentCli.promptForBoolean)('Are you sure you want to purge ALL existing dev environments?', true);
+    if (!purge) {
+      return;
+    }
+  }
+  const trackingInfo = {
+    all: true
+  };
+  await (0, _tracker.trackEvent)('dev_env_purge_command_execute', trackingInfo);
+  await (0, _devEnvironmentCli.validateDependencies)(lando, '');
+  const removeFiles = !(opt.soft || false);
+  try {
+    for (const slug of allEnvNames) {
+      try {
+        // eslint-disable-next-line no-await-in-loop
+        await (0, _devEnvironmentCore.destroyEnvironment)(lando, slug, removeFiles);
+        const message = _chalk.default.green('✓') + ' Environment destroyed.\n';
+        console.log(message);
+      } catch (error) {
+        const trackingInfoChild = (0, _devEnvironmentCli.getEnvTrackingInfo)(slug);
+        // eslint-disable-next-line no-await-in-loop
+        await (0, _devEnvironmentCli.handleCLIException)(error, 'dev_env_purge_command_error', trackingInfoChild);
+        process.exitCode = 1;
+      }
+    }
+    await (0, _tracker.trackEvent)('dev_env_purge_command_success', trackingInfo);
+  } catch (error) {
+    await (0, _devEnvironmentCli.handleCLIException)(error, 'dev_env_purge_command_error', trackingInfo);
+    process.exitCode = 1;
+  }
+});

package/dist/bin/vip-dev-env.js

@@ -5,4 +5,4 @@ var _command = _interopRequireDefault(require("../lib/cli/command"));
 function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
 (0, _command.default)({
   requiredArgs: 0
-}).command('create', 'Create a new local dev environment').command('update', 'Update an already created local dev environment').command('start', 'Start a local dev environment').command('stop', 'Stop a local dev environment').command('destroy', 'Remove containers, networks, volumes and configuration files of a local dev environment').command('info', 'Provides basic info about one or multiple local dev environments').command('list', 'Provides basic info about all local dev environments').command('exec', 'Execute a WP-CLI command in local dev environment').command('import', 'Import data into a local WordPress environment').command('shell', 'Spawns a shell in a dev environment').command('logs', 'View logs from a local WordPress environment').command('sync', 'Pull data from production to local development environment').argv(process.argv);
+}).command('create', 'Create a new local dev environment').command('update', 'Update an already created local dev environment').command('start', 'Start a local dev environment').command('stop', 'Stop a local dev environment').command('destroy', 'Remove containers, networks, volumes and configuration files of a local dev environment').command('info', 'Provides basic info about one or multiple local dev environments').command('list', 'Provides basic info about all local dev environments').command('exec', 'Execute a WP-CLI command in local dev environment').command('import', 'Import data into a local WordPress environment').command('shell', 'Spawns a shell in a dev environment').command('logs', 'View logs from a local WordPress environment').command('sync', 'Pull data from production to local development environment').command('purge', 'Destroy all existing environments').argv(process.argv);

package/dist/bin/vip-import-sql.js

@@ -415,7 +415,6 @@ Processing the SQL import for your environment...
 `;
     progressTracker.suffix = `\n${(0, _format.getGlyphForStatus)(status, progressTracker.runningSprite)} ${status === 'running' ? 'Loading remaining steps' : ''}`; // TODO: maybe use progress tracker status
   };
-
   const failWithError = failureError => {
     status = 'failed';
     setProgressTrackerPrefixAndSuffix();

package/dist/bin/vip.js

@@ -4,7 +4,6 @@
 var _chalk = _interopRequireDefault(require("chalk"));
 var _debug = _interopRequireDefault(require("debug"));
 var _enquirer = require("enquirer");
-var _opn = _interopRequireDefault(require("opn"));
 var _command = _interopRequireWildcard(require("../lib/cli/command"));
 var _config = _interopRequireDefault(require("../lib/cli/config"));
 var _token = _interopRequireDefault(require("../lib/token"));
@@ -22,7 +21,7 @@ if (_config.default && _config.default.environment !== 'production') {
 const tokenURL = 'https://dashboard.wpvip.com/me/cli/token';
 const runCmd = async function () {
   const cmd = (0, _command.default)();
-  cmd.command('logout', 'Logout from your current session').command('app', 'List and modify your VIP applications').command('backup', 'Generate a backup for VIP applications').command('cache', 'Manage page cache for your VIP applications').command('config', 'Set configuration for your VIP applications').command('dev-env', 'Use local dev-environment').command('export', 'Export data from your VIP application').command('import', 'Import media or SQL files into your VIP applications').command('logs', 'Get logs from your VIP applications').command('search-replace', 'Perform search and replace tasks on files').command('slowlogs', 'Get slowlogs from your VIP applications').command('db', 'Run operations on your VIP application database').command('sync', 'Sync production to a development environment').command('whoami', 'Display details about the currently logged-in user').command('validate', 'Validate your VIP application and environment').command('wp', 'Run WP CLI commands against an environment');
+  cmd.command('logout', 'Logout from your current session').command('app', 'List and modify your VIP applications').command('backup', 'Generate a backup for VIP applications').command('cache', 'Manage page cache for your VIP applications').command('config', 'Set configuration for your VIP applications').command('dev-env', 'Use local dev-environment').command('export', 'Export data from your VIP application').command('import', 'Import media or SQL files into your VIP applications').command('logs', 'Get logs from your VIP applications').command('search-replace', 'Perform search and replace tasks on files').command('slowlogs', 'Get slowlogs from your VIP applications').command('sync', 'Sync production to a development environment').command('whoami', 'Display details about the currently logged-in user').command('validate', 'Validate your VIP application and environment').command('wp', 'Run WP CLI commands against an environment');
   cmd.argv(process.argv);
 };
 
@@ -66,7 +65,10 @@ const rootCmd = async function () {
       await (0, _tracker.trackEvent)('login_command_browser_cancelled');
       return;
     }
-    (0, _opn.default)(tokenURL, {
+    const {
+      default: open
+    } = await import('open');
+    open(tokenURL, {
       wait: false
     });
     await (0, _tracker.trackEvent)('login_command_browser_opened');

package/dist/commands/export-sql.js

@@ -376,7 +376,7 @@ class ExportSQLCommand {
             error_message: err?.message,
             stack: err?.stack
           });
-          exit.withError('There is an export job already running for this environment: ' + `https://dashboard.wpvip.com/apps/${this.app.id}/${this.env.uniqueLabel}/data/database/backups\n` + 'Currently, we allow only one export job at a time, per site. Please try again later.');
+          exit.withError('There is an export job already running for this environment: ' + `https://dashboard.wpvip.com/apps/${this.app.id}/${this.env.uniqueLabel}/database/backups\n` + 'Currently, we allow only one export job at a time, per site. Please try again later.');
         } else {
           await this.track('error', {
             error_type: 'create_export_job',

package/dist/lib/cli/command.js

@@ -88,7 +88,6 @@ _args.default.argv = async function (argv, cb) {
     options.app = parsedAlias.app;
     options.env = parsedAlias.env; // Can be undefined
   }
-
   const validationError = validateOpts(options);
   if (validationError) {
     const error = validationError.toString();

package/dist/lib/client-file-uploader.js

@@ -38,7 +38,6 @@ require('fetch-retry')(_nodeFetch.default, {
     return Math.pow(2, attempt) * 1000; // 1000, 2000, 4000
   }
 });
-
 const debug = (0, _debug.default)('vip:lib/client-file-uploader');
 
 // Files smaller than COMPRESS_THRESHOLD will not be compressed before upload
@@ -198,7 +197,6 @@ async function uploadUsingPutObject({
     ...fetchOptions.headers,
     'Content-Length': `${fileSize}` // This has to be a string
   };
-
   let readBytes = 0;
   const progressPassThrough = new _stream.PassThrough();
   progressPassThrough.on('data', data => {
@@ -484,7 +482,6 @@ async function uploadPart({
        *   ...so it may not be feasible to include with presigned requests.
        */
     };
-
     fetchOptions.body = (0, _fs.createReadStream)(fileName, {
       start,
       end

package/dist/lib/constants/dev-environment.js

@@ -40,4 +40,4 @@ const DEV_ENVIRONMENT_PHP_VERSIONS = exports.DEV_ENVIRONMENT_PHP_VERSIONS = {
     label: '7.4 (EOL; not supported)'
   }
 };
-const DEV_ENVIRONMENT_VERSION = exports.DEV_ENVIRONMENT_VERSION = '2.0.0';
+const DEV_ENVIRONMENT_VERSION = exports.DEV_ENVIRONMENT_VERSION = '2.0.1';

package/dist/lib/dev-environment/dev-environment-cli.js

@@ -189,7 +189,6 @@ async function getEnvironmentName(options) {
   }
   return DEFAULT_SLUG; // Fall back to the default slug if we don't have any, e.g. during the env creation purpose
 }
-
 function getEnvironmentStartCommand(slug, configurationFileOptions) {
   const isUsingConfigurationFileSlug = Object.keys(configurationFileOptions).length > 0 && configurationFileOptions.slug === slug;
   if (!slug || isUsingConfigurationFileSlug) {
@@ -606,7 +605,6 @@ function processBooleanOption(value) {
   // eslint-disable-next-line @typescript-eslint/no-base-to-string
   return !FALSE_OPTIONS.includes(value.toString().toLowerCase()); // NOSONAR
 }
-
 function processStringOrBooleanOption(value) {
   if (typeof value === 'boolean') {
     return value;

package/dist/lib/site-import/status.js

@@ -342,7 +342,6 @@ ${maybeExitPrompt}
       overallStatus = results.progress?.status ?? 'unknown';
       // This shouldn't be 'unknown'...what should we do here?
     }
-
     progressTracker.stopPrinting();
     setProgressTrackerSuffix();
 

package/docs/ARCHITECTURE.md

@@ -0,0 +1,95 @@
+# Architecture
+
+## Basic functionality
+
+This is a CLI for interacting with and managing your [WordPress VIP applications](https://docs.wpvip.com/technical-references/vip-cli/). Data is inputted and outputted via terminal to the [API offered by WordPress VIP](#communicating-with-wpvip-api) and to/from local filesystem.
+
+For configuration, a few [environmental variables](SETUP.md#environmental-variables) are used and some [configuration files](SETUP.md#configuration-files) as well. No [database](#database) is required.
+
+### Scalability
+
+No specific considerations.
+
+### Communicating with WPVIP API
+
+The CLI communicates primarily with https://api.wpvip.com. An authentication token is required to access the API which the CLI will ask for when executed. Tokens can be retrieved from the [VIP Dashboard](https://dashboard.wpvip.com/).
+
+## Languages & coding standard
+
+Both JavaScript and TypeScript are used to implement the software. **TypeScript should be used for new code.**
+
+We require that the WPVIP defined coding style to be used, defined in [.eslintrc.js](https://github.com/Automattic/vip-cli/blob/trunk/.eslintrc.js).
+
+## Code structure
+
+The code is structured in the following way:
+
+- [.github](https://github.com/Automattic/vip-cli/tree/trunk/.github) — configuration and templates for GitHub.
+- [\_\_fixtures\_\_](https://github.com/Automattic/vip-cli/tree/trunk/__fixtures__) — fixtures for testing package.
+- [\_\_tests\_\_](https://github.com/Automattic/vip-cli/tree/trunk/__tests__) — testing package.
+- [config](https://github.com/Automattic/vip-cli/tree/trunk/config) — configuration files.
+- [docs](https://github.com/Automattic/vip-cli/tree/trunk/docs) — documentation package.
+- [types](https://github.com/Automattic/vip-cli/tree/trunk/types) - for TypeScript.
+- [helpers](https://github.com/Automattic/vip-cli/tree/trunk/helpers) - helper scripts.
+- [src](https://github.com/Automattic/vip-cli/tree/trunk/src) - main source code.
+
+## API interfaces
+
+No APIs are offered.
+
+### GraphQL interfaces
+
+No APIs are offered.
+
+## Feature flags
+
+TODO: Do we apply feature flags in this code? Describe how it works.
+
+## Database
+
+No database is needed.
+
+## Dependency services
+
+VIP-CLI communicates with a few services via APIs:
+
+- [WPVIP API](#communicating-with-wpvip-api).
+- https://public-api.wordpress.com/rest – for analytics (can be [disabled](SETUP.md#analytics)).
+
+## Development
+
+Here are guidelines to ensure we have consistency across the CLI and web interfaces.
+
+### Adding commands
+
+- New command names should use the singular form (e.g. site vs sites).
+- Add new commands to `package.json#bin`.
+- Run `npm link` so that `arg` knows how to spawn the command locally. (Skipping this step will result in `Error: spawn vip-command ENOENT`.)
+
+### Adding libraries
+
+New libraries should generally support both CLI and web contexts, though some cases that won't make sense (e.g. formatting for CLI output). Ensuring the libraries are useful everywhere will allow us to offer consistent experiences regardless of the interface.
+
+### go-search-replace binaries
+
+Some unit tests require some go-search-replace executable binary files to run. Binaries files for
+several OS architectures can be downloaded
+from https://github.com/Automattic/go-search-replace/releases/
+
+If, for some reason, you need to compile these binaries yourself, please follow instructions
+at https://github.com/Automattic/go-search-replace
+
+### Generating the types
+
+If you're an employee of Automattic, you can follow these steps to regenerate the GraphQL types
+used.
+
+1. Get a hold of `schema.gql` and paste it in project root - this is the schema of the endpoint that
+   we communicate with.
+2. Run `npm run typescript:codegen:install-dependencies` - this will install the codegen
+   dependencies without updating `package.json`
+3. Run `npm run typescript:codegen:generate` - this will regenerate the types.
+
+## Alerting
+
+There are no alerts.

package/{CHANGELOG.md → docs/CHANGELOG.md}

@@ -1,5 +1,42 @@
 ## Changelog
 
+### 2.36.3
+
+- build(deps): bump @json2csv/plainjs from 7.0.3 to 7.0.4
+- build(deps-dev): bump nock from 13.3.8 to 13.4.0
+- build(deps-dev): bump the babel group with 2 updates
+- build(deps-dev): bump @automattic/eslint-plugin-wpvip from 0.9.0 to 0.9.1
+- fix(dev-env): `/lando-entrypoint.sh: exec: line 83: exit: not found`
+- build(deps-dev): bump eslint from 8.54.0 to 8.55.0
+- build(deps-dev): bump typescript from 5.3.2 to 5.3.3
+- build(deps-dev): bump the testing group with 1 update
+- chore(deps): update lando to 25fcd83
+- build(deps): bump Automattic/vip-actions from 0.1.2 to 0.2.0
+
+### 2.36.2
+
+- #1558 fix(dev-env): Fix typo on suggested start command after updating env
+- #1557 fix(dev-env): Fix an issue where dev-env-import-sql command execute event was not being tracked
+- #1554 chore(dev-deps): update testing tools
+- #1556 chore(dev-deps): update eslint from 8.52.0 to 8.54.0
+- #1555 chore(deps): replace the deprecated `opn` with `open`
+- #1553 chore(dev-deps): update TypeScript and typings
+- #1578 build(deps-dev): bump @types/semver from 7.5.4 to 7.5.6
+- #1577 Updating ESLint config
+- #1559 Restructure and refine documentation + add missing tests
+- #1591 Fix database backup URL in error message
+- #1537 Add vip dev-env purge command logic
+- #1590 build(deps): bump actions/setup-node from 3 to 4
+- #1589 build(deps): bump actions/checkout from 3 to 4
+- #1592 chore: group dependencies that should be updated together
+- #1594 build(deps-dev): bump the babel group with 4 updates
+- #1593 build(deps-dev): bump the testing group with 1 update
+- #1595 build(deps-dev): bump typescript from 5.2.2 to 5.3.2
+- #1596 build(deps): bump @automattic/vip-go-preflight-checks from 2.0.16 to 2.0.17
+- #1580 build(deps): bump ini from 2.0.0 to 4.1.1
+- #1598 build(deps-dev): bump @automattic/eslint-plugin-wpvip from 0.8.0 to 0.9.0
+- #1597 chore(deps): update Lando
+
 ### 2.36.1
 
 - #1550 chore(deps): replace cli-table with cli-table3

package/docs/CONTRIBUTING.md

@@ -0,0 +1,29 @@
+# Contributing
+
+## Pull requests & issues
+
+We welcome any contributions to this project.
+
+If you have a small bugfix and already have the code available, feel free to [create a pull request](https://github.com/Automattic/vip-cli/compare). If you have a feature suggestion, please [create an issue](https://github.com/Automattic/vip-cli/issues/new). Please follow the instructions provided. Please assign a priority to the issue/pull request according to the definitions found below.
+
+Before writing a patch or a larger chunk of code, please ensure to study the [ARCHITECTURE.md](ARCHITECTURE.md) and [TESTING.md](TESTING.md) files. Ensure that all tests pass before asking for a review of your pull request.
+
+## Priorities
+
+Each GitHub issue and pull request relating to this repository should have a priority label to make prioritizing easier. The definition of each priority is as follows:
+
+- [Critical](https://github.com/Automattic/vip-cli/labels/%5BPri%5D%20Critical): A bug currently affecting normal operation or a security problem that needs to be addressed urgently.
+- [High](https://github.com/Automattic/vip-cli/labels/%5BPri%5D%20High): An issue that is: a) relevant to current goals of the project, b) a bug that needs to addressed soon to maintain stability, or c) a feature often requested.
+- [Normal](https://github.com/Automattic/vip-cli/labels/%5BPri%5D%20Normal): Most issues belong here. These will include features less often requested, new lower priority features, documentation updates, etc.
+- [Low](https://github.com/Automattic/vip-cli/labels/%5BPri%5D%20Low): Features that are good to have belong here.
+
+## Type of change labels
+
+Each GitHub issue and pull-request should have a type of change label associated with it. The definition of these are as follows:
+
+- [Bug](https://github.com/Automattic/vip-cli/labels/%5BType%5D%20Bug): Code change to fix a bug, or a bug report.
+- [Clean up](https://github.com/Automattic/vip-cli/labels/%5B%20Type%20%5D%20Clean%20up): Pull request for general code clean ups.
+- [Documentation](https://github.com/Automattic/vip-cli/labels/%5B%20Type%20%5D%20Documentation): Pull request to update documentation.
+- [Enhancement](https://github.com/Automattic/vip-cli/labels/%5BType%5D%20Enhancement): A general enhancement – new feature, better implementation, new tests and so forth.
+- [Remove feature](https://github.com/Automattic/vip-cli/labels/%5B%20Type%20%5D%20Remove%20feature): Pull request to remove feature code.
+- [Update dependency](https://github.com/Automattic/vip-cli/labels/%5B%20Type%20%5D%20Update%20dependency): Pull request to update one or more dependencies.

package/docs/DEBUGGING.md

@@ -0,0 +1,33 @@
+# Debugging
+
+## Using debugger
+
+A debugger can easily be used to help pinpointing issues with the code. Follow these steps.
+
+1. First, make sure to run the `npm run build:watch`, this will generate source maps
+2. Run the command you want via `node --inspect`, like so: `node --inspect ./dist/bin/vip-dev-env-import-sql.js`
+3. Note the port the debugger is listening on:
+
+```
+Debugger listening on ws://127.0.0.1:9229/db6c03e9-2585-4a08-a1c6-1fee0295c9ff
+For help, see: https://nodejs.org/en/docs/inspector
+```
+
+4. In your editor of choice attach to the debugger. For VSCode: Hit 'Run and Debug' panel, hit the "gear" icon (open launch.json), make your `Attach` configuration entry to look like so:
+   Make sure the `port` matches the port from step 3, and the `runtimeExecutable` matches the exact `node` executable you ran. If you use a version manager like `nvm`, its especially important to check this.
+
+```json
+{
+	"name": "Attach",
+	"port": 9229,
+	"request": "attach",
+	"skipFiles": [ "<node_internals>/**" ],
+	"type": "node",
+	"runtimeExecutable": "/Users/user/.nvm/versions/node/v14.18.2/bin/node"
+}
+```
+
+5. Set your breakpoints, add debug code, and hit the play button.
+6. Confirm that you attached the debugger to continue command execution.
+7. Resolve the problem.
+8. [Optional but recommended] Pay it forward and implement a similar approach to other internal/external tooling.

package/docs/RELEASING.md

@@ -0,0 +1,163 @@
+# Releasing
+
+Please familiarize yourself with the [SETUP.md](SETUP.md) file before releasing.
+
+## New pull requests
+
+Follow these steps for new pull requests:
+
+1. Please note the publishing method (see [below](#releasing-a-new-version)).
+
+1. Ensure when you create your pull request that:
+
+   a. It merges to `trunk`. The release flow for VIP-CLI follows this pattern: **_feature branch -> `trunk` branch_**
+
+   b. The feature branch follows A8C branch naming conventions, e.g.: `add/health-query`, `fix/subsite-mutation`, etc.
+
+   c. The pull request code and description contain no sensitive information. Please do not include any internal links in PRs, changelogs, testing instructions, etc. as this is a public repository.
+
+   d. You have included changelog entry by adding a `## Changelog Description` section to the GitHub pull request description. All changelogs are posted to the [VIP Cloud Changelog P2](https://wpvipchangelog.wordpress.com/) which customers can view and follow.
+
+1. Once you've created your pull request, ensure that:
+
+   a. You have added [all the automated tests required](TESTING.md#automated-testing).
+
+   b. You have completed [manual testing of your change](TESTING.md#manual-testing).
+
+1. If updating a dependency (NPM package or Node), follow the [guidelines on updating dependencies](SETUP.md#updating-dependencies).
+
+1. Have your pull request reviewed by a colleague and approved — especially if it is a large change or a complex addition.
+
+1. Verify that your pull request passes all automated tests.
+
+1. Merge your pull request.
+
+## Preparing for release
+
+A few steps should be completed before releasing:
+
+1. Verify that [all relevant pull requests](https://github.com/Automattic/vip-cli/pulls) are merged.
+
+1. The [changelog](CHANGELOG.md) file in the repository should be [amended](#changelog-generation) to.
+
+1. Please note the publishing method (see [below](#releasing-a-new-version)).
+
+1. Determine strategy to [respond to problems post-deployment](#in-case-of-problems).
+
+1. The release has been tested across macOS, Windows, and Linux.
+
+1. All tests pass and your working directory is clean (we have pre-publish checks to catch this,
+   just-in-case).
+
+1. You have completed [final testing before deployment](TESTING.md#final-testing-before-releasing).
+
+1. The pre-publish [script](https://github.com/Automattic/vip-cli/blob/trunk/helpers/prepublishOnly.js) has been run. This script performs some confidence checks to avoid common mistakes.
+
+1. Finally, release your changes as a [new minor or major NPM version](#releasing-a-new-version).
+
+If you need to publish a security release, see [details below](#patching-old-releases).
+
+### Changelog generation
+
+Run the following to generate a changelog entry for CHANGELOG.md:
+
+```bash
+export LAST_RELEASE_DATE=2021-08-25T13:40:00+02
+gh pr list --search "is:merged sort:updated-desc closed:>$LAST_RELEASE_DATE" | sed -e 's/\s\+\S\+\tMERGED.*$//' -e 's/^/- #/'
+```
+
+## Releasing a new version
+
+You can release either using GitHub Actions or locally.
+
+### Publishing via GitHub Actions (preferred)
+
+This is the preferred method for pushing out the latest release. The workflow runs a bunch of validations, generates a build, bump versions + tags, pushes out to npm, and bumps to the next dev version.
+
+Please keep in mind internal guidelines before releasing.
+
+To release, follow these steps:
+
+1. Initiate the [release process here](https://github.com/Automattic/vip-cli/actions/workflows/npm-prepare-release.yml).
+1. On the right-hand side, select "Run Workflow".
+1. Pick your preferred version bump.
+1. Click `Run Workflow`.
+1. Wait for a pull request to appear. The pull request will update the version number and shall be assigned to you.
+1. When ready, merge the pull request. This will lead to a new version to be [published on npmjs.com](https://www.npmjs.com/package/@automattic/vip).
+1. Another pull request will be created to bump to a development version, also assigned to you. Merge it to finish the process.
+
+#### Versioning Guidelines
+
+- `patch`: for non-breaking changes/bugfixes and small updates.
+- `minor`: for some new features, bug fixes, and other non-breaking changes.
+- `major`: for breaking changes.
+
+#### Note on NPM token
+
+Publishing via the GitHub Action requires that the `NPM_TOKEN` be set correctly in GitHub Actions secrets. This should be an npm token generated for a bot user on [the npm @automattic org](https://www.npmjs.com/settings/automattic) that has publish access to this repo.
+
+### Alternative methods of releasing
+
+#### Publishing locally
+
+To publish locally, follow these steps:
+
+<summary><details>
+
+1. Create a pull request that adds the next version's changelog into `trunk`. Use the Changelog
+   Generate Hint above to generate the changelog, and refer to previous releases to ensure that your
+   format matches.
+1. Merge it after approval.
+1. Make sure `trunk` branch is up-to-date: `git pull`.
+1. Make sure to clean all of your repositories of extra files. Run a dangerous, destructive
+   command `git clean -xfd` to do so.
+1. Run `npm install`.
+1. Set the version (via `npm version minor` or `npm version major` or `npm version patch`)
+1. For most regular releases, this will be `npm version minor`.
+1. Push the tag to GitHub (`git push --tags`)
+1. Push the trunk branch `git push`
+1. Make sure you're part of the Automattic organization in npm
+1. Publish the release to npm (`npm publish --access public`) the script will do some extra checks (
+   node version, branch, etc) to ensure everything is correct. If all looks good, the new version
+   will be published and you can proceed.
+1. Edit [the release on GitHub](https://github.com/Automattic/vip-cli/releases) to include a description
+   of the changes and publish (this can just copy the details from the changelog).
+
+Once released, it's worth running `npm i -g @automattic/vip` to install / upgrade the released version to make sure everything looks good.
+
+</details></summary>
+
+#### Test Releases
+
+Sometimes, we want to release a version we can test before releasing it to the public. In order to that, we need to release it under a tag other than `latest`, usually `next`. By default, `npm` install from the `latest` tag, so if `@next` isn't specified explicitely in the installation command like `npm install @automattic/vip@next`, a user will not get this version.
+
+In order to do that, please follow this:
+
+<summary><details>
+
+1. Manually change the version in `package.json` and `package-lock.json` to a dev version. Example: `1.4.0-dev1`
+1. Run `npm publish --tag next` (When `--tag` is specified, we bypass the usual branch protection that doesn't allow you to publish form a brunch other than `trunk`).
+
+You can repeat this with every new version until you're happy with your version and ready to a public release. We currently don't support multiple branches for multiple versions. When it's the case, this process needs to be done for every version in every branch.
+
+</details></summary>
+
+#### Patching Old Releases
+
+There may be times when we need to push out a critical fix to the most recent release (or several past releases) such as for patching security issues or major bugs. This can be complicated by the fact that we may have some larger changes already merged into the `trunk` branch.
+
+<summary><details>
+
+For these cases:
+
+1. `git checkout` to the tag of the previous release.
+1. Apply the fix (either manually or by cherry-picking).
+1. Follow the release steps outlined above (as a `patch` release).
+
+Then, repeat for any additional versions that we need to patch.
+
+</details></summary>
+
+## In case of problems
+
+TODO: How to revert to a good state in case of problems?