Version 3 (#767)

* chore: v3 prerelease branch

* chore(release): 3.0.0-beta.1 [skip ci]

* feat: ESM support (#759)

* fix: set moduleResolution to Node16

* fix: use file urls

* chore: add types

* feat: support linking CJS plugins into ESM plugins

* chore: integration tests for module interoperability

* test: add CJS/ESM interoperability tests

* fix: e2e tests

* test: isolate cache, config, and data dir for e2e tests

* test: test bug

* test: make less noisy

* test: esm/cjs hooks

* chore: parallelize e2e tests

* chore: typo

* test: parallelize e2e tests

* test: no more hanging tests

* chore: un-parallelize esm-cjs tests

* chore: add DEBUG to esm-cjs interop tests

* chore: add DEBUG to esm-cjs interop tests

* chore: try enabling debug again

* test: fix node 20 tests

* chore: update DEBUG env var

* chore: debug tests

* chore: debug tests

* test: more debugging

* test: more debugging

* test: more debugging

* test: more debugging

* test: more debugging

* test: more debugging

* test: more debugging

* test: use path.join

* test: stop using replace-in-file

* chore: more test debugging

* fix: use path.join when registering ts-node

* test: run in parallel

* test: run tests serially

* fix: dont remove undefined values from tsconfig

* fix: further isolate ts-configs

* feat: throw error when loading ESM paths from linked plugins

* fix: default esm to true

* test: compilation errors

* feat: better developer experience

* fix: add getPluginsList

* chore(release): 2.11.9 [skip ci]

* fix: add getPluginsList to Config interface

* chore(release): 2.11.10 [skip ci]

---------

Co-authored-by: svc-cli-bot <[email protected]>

* chore(release): 3.0.0-beta.2 [skip ci]

* More v3 features (#772)

* fix: set moduleResolution to Node16

* fix: use file urls

* chore: add types

* feat: support linking CJS plugins into ESM plugins

* chore: integration tests for module interoperability

* test: add CJS/ESM interoperability tests

* fix: e2e tests

* test: isolate cache, config, and data dir for e2e tests

* test: test bug

* test: make less noisy

* test: esm/cjs hooks

* chore: parallelize e2e tests

* chore: typo

* test: parallelize e2e tests

* test: no more hanging tests

* chore: un-parallelize esm-cjs tests

* chore: add DEBUG to esm-cjs interop tests

* chore: add DEBUG to esm-cjs interop tests

* chore: try enabling debug again

* test: fix node 20 tests

* chore: update DEBUG env var

* chore: debug tests

* chore: debug tests

* test: more debugging

* test: more debugging

* test: more debugging

* test: more debugging

* test: more debugging

* test: more debugging

* test: more debugging

* test: use path.join

* test: stop using replace-in-file

* chore: more test debugging

* fix: use path.join when registering ts-node

* test: run in parallel

* test: run tests serially

* fix: dont remove undefined values from tsconfig

* fix: further isolate ts-configs

* feat: throw error when loading ESM paths from linked plugins

* fix: default esm to true

* test: compilation errors

* feat: better developer experience

* fix: add getPluginsList

* chore(release): 2.11.9 [skip ci]

* fix: add getPluginsList to Config interface

* chore(release): 2.11.10 [skip ci]

* feat: use exports

* fix: ux class

* fix: add exports for help and perf

* chore: tests

* feat: use Map for config.plugins

* feat: add noCacheDefault

* feat: add exports for Args and Flags

* chore: fix tests

* feat: put permutations into manifest

* fix: add return to execute

* fix: add version to PJSON interface

* feat: drop node 14 and 16 support

* fix: use CLIError for integer flag errors

* fix: skip findRoot for linked plugins

* chore: remove console.log

* fix: dont load core plugin if already loaded as linked or user plugin

* fix: ux export

* chore: making things readonly

* feat: add config export

* test: make tests passing again

* feat: rename cli-ux global to ux global

* chore: go back to node 16 support

* chore: migration guide

* chore: remove source-map register

* test: remove resolution

* chore: update migration guide

* fix: revert link findRoot optimization

* fix: remove unneeded exports

* feat: add PluginLoader

* chore: update migration guide

* chore: merge conflict

* chore: more merge conflicts

* test: recursive mkdir

---------

Co-authored-by: svc-cli-bot <[email protected]>

* chore(release): 3.0.0-beta.3 [skip ci]

* chore(release): 3.0.0-beta.4 [skip ci]

* fix: add main to package.json

* chore(release): 3.0.0-beta.5 [skip ci]

* fix: export CustomOptions

* chore(release): 3.0.0-beta.6 [skip ci]

* fix: interface exports

* chore(release): 3.0.0-beta.7 [skip ci]

* feat: remove ux and interfaces export

* chore(release): 3.0.0-beta.8 [skip ci]

* fix: revert ux changes

* chore(release): 3.0.0-beta.9 [skip ci]

* feat: revert exports changes (#776)

* feat: revert exports changes

* fix: run e2e tests even if linting error

* fix: revert cli-ux dir renaming

* chore(release): 3.0.0-beta.10 [skip ci]

* fix: revert styledJSON change

* chore(release): 3.0.0-beta.11 [skip ci]

* fix: update imports in Config

* chore(release): 3.0.0-beta.12 [skip ci]

* feat: skip ts-node register for ESM plugins (#778)

* feat: skip ts-node register for ESM plugins

* chore: update debug message

* chore(release): 3.0.0-beta.13 [skip ci]

* feat: final v3 features (#779)

* feat: add charAliases

* feat: add Flags.option

* fix: undo default options

* fix: allow bin/dev.js to auto-transpile ESM plugin

* chore: update execute examples

* fix: update tsnode skip logic

* chore: test debugging

* fix: ts-node skip logic

* fix: ts-node skip logic

* feat: cache relativePath and isESM in manifest

* fix: calculate id permutations at runtime to support backwards compatability

* perf: avoid findLegacyRoot for linked plugins

* chore: remove env var

* fix: improve perf metrics

* perf: improve perf debug output

* perf: more debug improvements

* test: compilation errors

* fix: make relativePath OS safe

* test: use sf esm branch

* perf: give full hook path

* chore: test debugging

* chore: test debugging

* chore: test debugging

* test: set shell for e2e tests

* fix: flag types respect defaults

* feat: node protocol

* test: move windows sf integration tests into separate job

* test: update assertion on plugins install test

* test: use correct file path

* test: use -Force

* test: use bash shell

* test: clean up

* test: remove shell option

* test: oclif/config, core v1, and core v2 interop tests

* chore: drop node 16

* test: remove lts/-1

* chore: code review

* chore: add pre core migration guide

* refactor: break up ModuleLoader

* chore: remove unicorn/consistent-function-scoping

* chore: remove unicorn/no-missing-imports

* chore: remove @typescript-eslint/no-empty-function

* chore: remove ban-ts-comment and ban-ts-ignore

* chore: add sort-import rule

* fix: throw error if non-multiple flag provided more than once

* test: mutliples of non-multiple flag test

* test: ut for charAliases (#791)

* test: duplicate aliases tests

* test: extend timeout

* test: split windows esm-cjs tests

* test: parallelize linux interop tests too

* test: typo

* test: use right executor

* test: use right executor for clean up

* chore: update eslint libs (#792)

* chore: update eslint libs

* chore: clean up

* chore: tests and linting

* test: windows paths

* fix: exports

* test: update run import

* chore: replaceAll

* fix: error exit codes

* fix: use es2021

* feat: use ES2022

* fix: use ES2021 again

* test: incorporate flags and args in esm-cjs tests

* test: use correct expected values

---------

Co-authored-by: Shane McLaughlin <[email protected]>

* chore(release): 3.0.0-beta.14 [skip ci]

* fix: allow undefined from flag parser

* chore(release): 3.0.0-beta.15 [skip ci]

* feat: set spinner style

* chore(release): 3.0.0-beta.16 [skip ci]

* test: unset config vars after setting them

* feat: remove ts-node (#794)

* feat: drop ts-node dependency

* test: use --json for config unset

* chore(release): 3.0.0-beta.17 [skip ci]

* fix: use ES2022 (#793)

* fix: use ES2022

* test: use --json for config unset

* feat: stop using getters and setters for flags

* chore: clean up

* feat: expose json flag

* feat: remove pass through getter and setter

* fix: correct order of flags in toCached

* chore: clean up

* fix: flag merge order

* chore: documentation

* test: use oclif/test v3

* feat: set spinner style on windows too

* fix: handle cmd with baseFlags but no flags

* fix: some circular deps

* fix: circular deps in help

* fix: ts-node and config circular deps

* fix: toCached circular dep in help

* chore: organize utils

* test: enforce no circular deps

* chore: remove Flags.json

* chore: add prettier config

* test: add nyc

* test: improve test coverage

* test: windows unit tests

* chore: revert change to automerge.yml

* chore: code review

* perf: parallelize cacheCommand

* chore(release): 3.0.0-beta.18 [skip ci]

* chore: use prettier and lint-staged (#798)

* chore: update prettier config

* chore: prettier and lint-staged

* chore: reformat everything

* chore: deal with reformat aftermath

* chore: update configs and deps

* perf: move ansi-escapes require to top level

* chore: automerge.yml

* chore: unpin eslint-plugin-prettier

* chore: remove prettier plugin

* chore: update lint-staged config

* fix: update util import

* chore(release): 3.0.0-beta.19 [skip ci]

* chore: remove util/index.ts (#802)

* fix: remove tsPath export

* fix: move @types/cli-progress to devDeps

* chore(release): 3.0.0-beta.20 [skip ci]

* fix: force release

* chore(release): 3.0.0-beta.21 [skip ci]

* fix: move styledJson to index

* chore(release): 3.0.0-beta.22 [skip ci]

* feat: collect perf results from outside oclif (#797)

* feat: collect perf results from outside oclif

* chore: pr feedback

* refactor: naming for non-core perf

* chore(release): 3.0.0-beta.23 [skip ci]

* fix: remove OCLIF_NEXT_VERSION

* chore: add prepare for husky install

* test: try false for ignoreScripts

* chore(release): 3.0.0-beta.25 [skip ci]

* test: ignore scripts for external nuts

* chore: use eslint-plugin-perfectionist (#807)

---------

Co-authored-by: svc-cli-bot <[email protected]>
Co-authored-by: Shane McLaughlin <[email protected]>

.commitlintrc.json

@@ -0,0 +1,3 @@
+{
+  "extends": ["@commitlint/config-conventional"]
+}

.eslintrc.json

@@ -0,0 +1,10 @@
+{
+  "extends": ["oclif", "oclif-typescript", "prettier", "plugin:perfectionist/recommended-natural"],
+  "rules": {
+    "unicorn/prefer-module": "off",
+    "unicorn/no-array-reduce": "off",
+    "no-useless-constructor": "off",
+    "perfectionist/sort-object-types": "off",
+    "perfectionist/sort-union-types": "off"
+  }
+}

.github/workflows/automerge.yml

@@ -2,9 +2,10 @@ name: automerge
 on:
   workflow_dispatch:
   schedule:
-    - cron: '17 2,5,8,11 * * *'
+    - cron: "17 2,5,8,11 * * *"
 
 jobs:
   automerge:
-    uses: oclif/github-workflows/.github/workflows/automerge.yml@main
-    secrets: inherit
+    uses: salesforcecli/github-workflows/.github/workflows/automerge.yml@main
+    secrets:
+      SVC_CLI_BOT_GITHUB_TOKEN: ${{ secrets.SVC_CLI_BOT_GITHUB_TOKEN }}

.github/workflows/create-github-release.yml

@@ -24,6 +24,7 @@ jobs:
       # However, if this is a manual release (workflow_dispatch), then we want to disable skip-on-empty
       # This helps recover from forgetting to add semantic commits ('fix:', 'feat:', etc.)
       skip-on-empty: ${{ github.event_name == 'push' }}
+      generate-readme: false
   # docs:
   #   # Most repos won't use this
   #   # Depends on the 'release' job to avoid git collisions, not for any functionality reason

.github/workflows/test.yml

@@ -13,12 +13,15 @@ jobs:
   windows-unit-tests:
     needs: linux-unit-tests
     uses: salesforcecli/github-workflows/.github/workflows/unitTestsWindows.yml@main
-  node14:
+  e2e:
     needs: linux-unit-tests
     strategy:
       matrix:
-        os: ["ubuntu-latest", "windows-latest"]
-        node_version: [14.x]
+        os: [ubuntu-latest, windows-latest]
+        node_version: [lts/*, latest]
+        exclude:
+          - os: windows-latest
+            node_version: lts/*
       fail-fast: false
     runs-on: ${{ matrix.os }}
     steps:
@@ -27,38 +30,77 @@ jobs:
         with:
           node-version: ${{ matrix.node_version }}
           cache: yarn
-      - run: yarn install
+      - uses: salesforcecli/github-workflows/.github/actions/yarnInstallWithRetries@main
       - run: yarn build
-      - run: yarn test
-  e2e:
+      - if: runner.os == 'Windows'
+        run: yarn mocha --forbid-only "test/**/*.e2e.ts" --exclude "test/integration/sf.e2e.ts" --parallel --timeout 1200000
+      - if: runner.os == 'Linux'
+        run: yarn test:e2e
+  windows-sf-e2e:
+    # For whatever reason the windows-latest runner doesn't like it when you shell yarn commands in the sf repo
+    # which is an integral part of the setup for the tests. Instead, we replicate the setup here.
+    needs: linux-unit-tests
+    strategy:
+      fail-fast: false
+    runs-on: windows-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
+        with:
+          node-version: latest
+          cache: yarn
+      - uses: salesforcecli/github-workflows/.github/actions/yarnInstallWithRetries@main
+      - run: yarn build
+      - run: yarn link
+      - run: New-Item -Path D:\a -Name "e2e" -ItemType "directory"
+      - run: New-Item -Path D:\a\e2e -Name "sf.e2e.ts" -ItemType "directory"
+      - run: |
+          git clone https://github.com/salesforcecli/cli.git --branch mdonnalley/esm
+          cd cli
+
+          $Json = Get-Content package.json | ConvertFrom-Json
+          $Json.dependencies | Add-Member -Force -MemberType NoteProperty -Name "@oclif/core" -Value "file:D:\a\core\core"
+          $Json.resolutions | Add-Member -MemberType NoteProperty -Name "@oclif/core" -Value "D:\a\core\core"
+          $Json | ConvertTo-Json -Depth 9 | Out-File package.json
+
+          yarn install --network-timeout 600000
+          yarn link @oclif/core
+          yarn build
+        working-directory: D:\a\e2e\sf.e2e.ts
+      - run: yarn mocha --forbid-only "test/integration/sf.e2e.ts" --parallel --timeout 1200000
+        env:
+          OCLIF_CORE_E2E_SKIP_SETUP: true
+          OCLIF_CORE_E2E_TEST_DIR: D:\a\e2e
+          DEBUG: e2e:*
+  esm-cjs-interop:
     needs: linux-unit-tests
     strategy:
       matrix:
-        os: ["ubuntu-latest", "windows-latest"]
-        node_version: [lts/-1, lts/*, latest]
+        os: [ubuntu-latest, windows-latest]
+        node_version: [lts/*, latest]
+        test: [esm, cjs, precore, coreV1, coreV2]
         exclude:
           - os: windows-latest
             node_version: lts/*
-          - os: windows-latest
-            node_version: lts/-1
       fail-fast: false
     runs-on: ${{ matrix.os }}
+    timeout-minutes: 75
     steps:
       - uses: actions/checkout@v3
       - uses: actions/setup-node@v3
         with:
           node-version: ${{ matrix.node_version }}
           cache: yarn
-      - run: yarn install --network-timeout 600000
+      - uses: salesforcecli/github-workflows/.github/actions/yarnInstallWithRetries@main
       - run: yarn build
-      - run: yarn test:e2e
+      - run: yarn test:esm-cjs --test=${{ matrix.test }}
   nuts:
     needs: linux-unit-tests
     uses: salesforcecli/github-workflows/.github/workflows/externalNut.yml@main
     strategy:
       fail-fast: false
       matrix:
-        os: ["ubuntu-latest", "windows-latest"]
+        os: [ubuntu-latest, windows-latest]
         externalProjectGitUrl:
           - https://github.com/salesforcecli/plugin-auth
           - https://github.com/salesforcecli/plugin-data
@@ -73,6 +115,7 @@ jobs:
       useCache: false
       preSwapCommands: "npx yarn-deduplicate; yarn install"
       preExternalBuildCommands: "shx rm -rf node_modules/@salesforce/sf-plugins-core/node_modules/@oclif/core"
+      ignoreScripts: true
     secrets:
       TESTKIT_AUTH_URL: ${{ secrets.TESTKIT_AUTH_URL }}
       TESTKIT_HUB_USERNAME: ${{ secrets.TESTKIT_HUB_USERNAME }}

.husky/pre-commit

@@ -0,0 +1,4 @@
+#!/bin/sh
+. "$(dirname "$0")/_/husky.sh"
+
+yarn lint-staged --concurrent false

.lintstagedrc.json

@@ -0,0 +1,5 @@
+{
+  "*.json": ["prettier --write"],
+  "*.md": ["prettier --write"],
+  "+(src|test)/**/*.+(ts|js)": ["eslint --fix", "prettier --write"]
+}

.mocharc.json

@@ -3,8 +3,7 @@
   "reporter": "spec",
   "require": [
     "test/helpers/init.js",
-    "ts-node/register",
-    "source-map-support/register"
+    "ts-node/register"
   ],
   "timeout": 60000,
   "watch-extensions": [

.nycrc.json

@@ -0,0 +1,11 @@
+{
+  "check-coverage": true,
+  "lines": 80,
+  "statements": 70,
+  "functions": 70,
+  "branches": 60,
+  "reporter": ["lcov", "text"],
+  "extension": [".ts"],
+  "include": ["**/*.ts"],
+  "exclude": ["**/*.d.ts", "test/**"]
+}

.prettierrc.json

@@ -0,0 +1 @@
+"@oclif/prettier-config"

README.md

@@ -11,7 +11,11 @@ base library for oclif CLIs
 Migrating
 =====
 
-See the [migration guide](./MIGRATION.md) for an overview of breaking changes that occurred between v1 and v2.
+See the [v3 migration guide](./guides/V3_MIGRATION.md) for an overview of breaking changes that occurred between v2 and v3.
+
+See the [v2 migration guide](./guides/V2_MIGRATION.md) for an overview of breaking changes that occurred between v1 and v2.
+
+Migrating from `@oclif/config` and `@oclif/command`? See the [v1 migration guide](./guides/PRE_CORE_MIGRATION.md).
 
 CLI UX
 =====
@@ -28,7 +32,7 @@ You can, however, use `@oclif/core` in a standalone script like this:
 #!/usr/bin/env ts-node
 
 import * as fs from 'fs'
-import {Command, Flags} from '@oclif/core'
+import {Command, Flags, flush, handle} from '@oclif/core'
 
 class LS extends Command {
   static description = 'List the files in a directory.'
@@ -50,10 +54,10 @@ class LS extends Command {
   }
 }
 
-LS.run().then(() => {
-  require('@oclif/core/flush')
-}, () => {
-  require('@oclif/core/handle')
+LS.run().then(async () => {
+  await flush()
+}, async (err) => {
+  await handle(err)
 })
 ```
 

flush.js

@@ -1 +1 @@
-module.exports = require('./lib').flush
+module.exports = require('./lib/cli-ux/flush').flush