feat: final v3 features

.eslintrc

@@ -5,7 +5,6 @@
   ],
   "rules": {
     "unicorn/prefer-module": "off",
-    "unicorn/prefer-node-protocol": "off",
     "unicorn/import-style": "off",
     "unicorn/consistent-function-scoping": "off",
     "unicorn/no-array-reduce": "off",

.github/workflows/test.yml

@@ -17,13 +17,11 @@ jobs:
     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]
         exclude:
           - os: windows-latest
             node_version: lts/*
-          - os: windows-latest
-            node_version: lts/-1
       fail-fast: false
     runs-on: ${{ matrix.os }}
     steps:
@@ -34,18 +32,56 @@ jobs:
           cache: yarn
       - run: yarn install --network-timeout 600000
       - 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
+      - run: yarn install --network-timeout 600000
+      - 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]
         exclude:
           - os: windows-latest
             node_version: lts/*
-          - os: windows-latest
-            node_version: lts/-1
       fail-fast: false
     runs-on: ${{ matrix.os }}
     timeout-minutes: 60
@@ -64,7 +100,7 @@ jobs:
     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

guides/V3_MIGRATION.md

@@ -13,6 +13,8 @@ Migrating to @oclif/core@V3
     - [`noCacheDefault` flag property replaces `isWritingManifest`](#nocachedefault-flag-property-replaces-iswritingmanifest)
   - [Features 🎉](#features-)
     - [Cache Flexible taxonomy Command Permutations](#cache-flexible-taxonomy-command-permutations)
+    - [charAliases Flag Property](#charaliases-flag-property)
+    - [Flags.option](#flagsoption)
 
 
 ## BREAKING CHANGES ❗
@@ -114,3 +116,36 @@ export const mySensitiveFlag = Flags.string({
 ### Cache Flexible taxonomy Command Permutations
 
 The command permutations for flexible taxonomy are now cached in the oclif.manifest.json allowing for quicker startup times.
+
+### charAliases Flag Property
+
+You can now define single character flag aliases using the `charAliases` property.
+
+### Flags.option
+
+There's a new flag type that infers the flag's type from the provided options.
+
+In v2 you would have needed to do something like this,
+
+```typescript
+type Options = 'foo' | 'bar'
+export default class MyCommand extends Command {
+  static flags = {
+    name: Flags.custom<Options>({
+      options: ['foo', 'bar'],
+    })(),
+  }
+}
+```
+
+Now in v3 you can do this,
+
+```typescript
+export default class MyCommand extends Command {
+  static flags = {
+    name: Flags.option({
+      options: ['foo', 'bar'] as const,
+    })(),
+  }
+}
+```

package.json

@@ -52,7 +52,6 @@
     "@types/nock": "^11.1.0",
     "@types/node": "^16",
     "@types/node-notifier": "^8.0.2",
-    "@types/proxyquire": "^1.3.28",
     "@types/shelljs": "^0.8.12",
     "@types/slice-ansi": "^4.0.0",
     "@types/strip-ansi": "^5.2.1",
@@ -72,15 +71,14 @@
     "husky": "6",
     "mocha": "^10.2.0",
     "nock": "^13.3.0",
-    "proxyquire": "^2.1.3",
     "shelljs": "^0.8.5",
     "shx": "^0.3.4",
     "sinon": "^11.1.2",
     "tsd": "^0.25.0",
     "typescript": "^4.9.5"
   },
   "engines": {
-    "node": ">=16.0.0"
+    "node": ">=18.0.0"
   },
   "files": [
     "/lib",

src/args.ts

@@ -1,4 +1,4 @@
-import {URL} from 'url'
+import {URL} from 'node:url'
 import {Arg, ArgDefinition} from './interfaces/parser'
 import {Command} from './command'
 import {dirExists, fileExists, isNotFalsy} from './util'

src/cli-ux/action/base.ts

@@ -1,4 +1,4 @@
-import {inspect} from 'util'
+import {inspect} from 'node:util'
 import {castArray} from '../../util'
 import {stderr, stdout} from '../stream'
 

src/cli-ux/index.ts

@@ -1,5 +1,5 @@
 import * as Errors from '../errors'
-import * as util from 'util'
+import {format as utilFormat} from 'node:util'
 import * as chalk from 'chalk'
 import {ActionBase} from './action/base'
 import {config, Config} from './config'
@@ -71,18 +71,18 @@ export class ux {
 
   public static trace(format: string, ...args: string[]): void {
     if (this.config.outputLevel === 'trace') {
-      stdout.write(util.format(format, ...args) + '\n')
+      stdout.write(utilFormat(format, ...args) + '\n')
     }
   }
 
   public static debug(format: string, ...args: string[]): void {
     if (['trace', 'debug'].includes(this.config.outputLevel)) {
-      stdout.write(util.format(format, ...args) + '\n')
+      stdout.write(utilFormat(format, ...args) + '\n')
     }
   }
 
   public static info(format: string, ...args: string[]): void {
-    stdout.write(util.format(format, ...args) + '\n')
+    stdout.write(utilFormat(format, ...args) + '\n')
   }
 
   public static log(format?: string, ...args: string[]): void {

src/cli-ux/styled/object.ts

@@ -1,5 +1,5 @@
 import * as chalk from 'chalk'
-import * as util from 'util'
+import {inspect} from 'node:util'
 
 // eslint-disable-next-line @typescript-eslint/explicit-module-boundary-types
 export default function styledObject(obj: any, keys?: string[]): string {
@@ -10,11 +10,11 @@ export default function styledObject(obj: any, keys?: string[]): string {
     if (typeof obj === 'string' || typeof obj === 'number') return obj
     if (typeof obj === 'object') {
       return Object.keys(obj)
-      .map(k => k + ': ' + util.inspect(obj[k]))
+      .map(k => k + ': ' + inspect(obj[k]))
       .join(', ')
     }
 
-    return util.inspect(obj)
+    return inspect(obj)
   }
 
   const logKeyValue = (key: string, value: any): string => {

src/cli-ux/styled/table.ts

@@ -4,7 +4,7 @@ import {stdtermwidth} from '../../screen'
 import * as chalk from 'chalk'
 import {capitalize, sumBy} from '../../util'
 import {safeDump} from 'js-yaml'
-import {inspect} from 'util'
+import {inspect} from 'node:util'
 import {stdout} from '../stream'
 
 const sw = require('string-width')

src/command.ts

@@ -1,24 +1,24 @@
-import {fileURLToPath} from 'url'
+import {fileURLToPath} from 'node:url'
 import * as chalk from 'chalk'
-import {format, inspect} from 'util'
+import {format, inspect} from 'node:util'
 import {ux} from './cli-ux'
 import {Config} from './config'
 import * as Errors from './errors'
 import {PrettyPrintableError} from './errors'
 import * as Parser from './parser'
 import {
-  BooleanFlagProps,
-  CompletableFlag,
-  Deprecation,
   Arg as IArg,
   ArgInput,
+  ArgOutput,
+  ArgProps,
+  BooleanFlagProps,
+  Deprecation,
+  Flag as IFlag,
   FlagInput,
   FlagOutput,
   Input,
-  ArgProps,
   OptionFlagProps,
   ParserOutput,
-  ArgOutput,
 } from './interfaces/parser'
 import {formatCommandDeprecationWarning, formatFlagDeprecationWarning, toConfiguredId, normalizeArgv} from './help/util'
 import {Plugin} from './interfaces/plugin'
@@ -315,7 +315,7 @@ export abstract class Command {
       }
 
       const deprecateAliases = flagDef?.deprecateAliases
-      const aliases = (flagDef?.aliases ?? []).map(a => a.length === 1 ? `-${a}` : `--${a}`)
+      const aliases = ([...flagDef?.aliases ?? [], ...flagDef?.charAliases ?? []]).map(a => a.length === 1 ? `-${a}` : `--${a}`)
       if (deprecateAliases && aliases.length > 0) {
         const foundAliases = aliases.filter(alias => this.argv.some(a => a.startsWith(alias)))
         for (const alias of foundAliases) {
@@ -435,9 +435,11 @@ export namespace Command {
     hasDynamicHelp?: boolean;
     permutations?: string[]
     aliasPermutations?: string[];
+    isESM?: boolean;
+    relativePath?: string[];
   }
 
-  export type Flag = CompletableFlag<any>
+  export type Flag = IFlag<any>
 
   export namespace Flag {
     export type Cached = Omit<Flag, 'parse' | 'input'> & (BooleanFlagProps | OptionFlagProps)