@automattic/vip-go-internal-cli

Internal CLI tools for the VIP team at Automattic

Usage no npm install needed!

<script type="module">
  import automatticVipGoInternalCli from 'https://cdn.skypack.dev/@automattic/vip-go-internal-cli';
</script>

README

VIP (Internal) CLI

Internal CLI Tools for VIP Go Sandboxes and the internal API.

Installation

Make sure you have an open connection to the Automattic proxy and are able to tunnel local traffic to port 8080.

npm i -g @automattic/vip-go-internal-cli
vipgo config set PROXY=socks://127.0.0.1:8080
vipgo login

Using an Ad blocker?

Make sure you allow HTTPS traffic to pixel.wp.com - the domain the CLI connects to in order to track command usage - otherwise your output will be polluted with the following error:

 ✕  Unexpected error: Please contact the Platform team with the following error:
  Error: connect ECONNREFUSED 0.0.0.0:443
    at TCPConnectWrap.afterConnect [as oncomplete] (net.js:1146:16)

E.g. on PiHole, use sudo pihole -w pixel.wp.com.

Usage

Show available commands:

vipgo --help

You can append --help to any sub-command to see options and sub-sub-commands.

Development

To start hacking:

  1. Clone this repository.
  2. cd to the cloned directory.
  3. Run npm install to install dependencies.
  4. Hack the code.
  5. Build your changes using npm run build.
  6. Manually test your changes by calling node build/bin/vipgo.js {related-command}.

Test

To lint and execute the full test suite:

npm run test

Connecting to local VIP Go API

Note: changing this setting will also affect the installed npm package, and not only your cloned repository. Remember to clear this setting when you are done testing!

Testing in production is not good, so if you need to test against a locally running copy of GOOP, you can prepend a specific env variable to all commands as follows:

VIP_API_URL=http://localhost:2999 ./build/bin/vipgo.js sandbox list

To avoid typing every time, save the variable in your config file:

./build/bin/vipgo.js config set VIP_API_URL=http://localhost:2999

Then re-login with a user id and token valid for your local GOOP installation. By default, the local GOOP development environment will accept user id 1 with an empty API token.

Note 1: Your development version will use the same config as the globally installed module and any changes to the config will impact that.

Note 2: You can use npm link to link your development copy with your globally installed version to simplify development.

Tracks

We track all vipgo commands with the vip_internal_cli_command_triggered Tracks event

While developing locally, the Tracks event name changes to vip_internal_cli_local_command_triggered

In addition to native Tracks parameters, we also track the command name, sub command name, command parameters and GOOP User ID.

Note that sensitive command parameters can be redacted by adding to the TRACKS_UNTRACKED_COMMAND_OPTIONS array in the src/constants.js file.

Publishing a New Release

Major / Minor Versions

  1. npm run publish-please --dry-run to ensure there are no publishing blockers
  2. Note: if some tests are failing, chances are your CLI points to the local GOOP! This will break nock!
  3. Set the version:
    1. npm version patch for non-breaking changes/bugfixes and small updates
    2. npm version minor if there are some new features or breaking changes
  4. git push --tags
  5. npm run publish-please
  6. Edit the release in Github to include a description of the changes. You can use this script to generate the changelog (instructions in its README, but it should be pretty straightforward).
  7. Manually bump the version in package.json to the next patch and append -dev
  8. git push
  9. Post on the VIP Go P2 with details about the new release.
  10. Bump the spec files for the PHP images in the wpvip-dockerfiles repo (example) to update on sandboxes and work with VIP Systems to get it released.

Note: doing the steps 3 and 4 can help with debugging in case someone is running the dev version (via vipgo -V).

Patch Version

For a critical fix (or a small number of fixes), we can git checkout the last release and add/or cherry-pick some changes.

Then bump the version number with npm version patch and npm publish. This is especially nice if there are already some bigger changes in the trunk branch and you don’t want to push a normal release.

It is necessary to update the Rolling Release Doc even if it is a patch version bump.

Caveats

  • We don’t publish the src directory because it's not used and just makes builds larger (skipped via .npmignore).
  • Microsoft Windows users will require Windows 10 or later with a Linux Subsystem installed.
  • When debugging the Site Details commands, in order to make the commands work when pointing to local GOOP and API Gateway, please override the Proxy like in the example given below:
VIP_API_URL=http://localhost:2999 API_GATEWAY_URL=http://localhost:3999 DISABLE_SDS_PROXY=true ./build/bin/vipgo.js site details get <siteId>