chore: documentation

guides/PRE_CORE_MIGRATION.md

@@ -5,6 +5,7 @@ Migrating to `@oclif/core` from the deprecated oclif libraries (`@oclif/config`,
 
 - [Migrating to @oclif/core from deprecated libraries](#migrating-to-oclifcore-from-deprecated-libraries)
   - [Update Imports](#update-imports)
+  - [Update Command Args](#update-command-args)
   - [Update your bin scripts](#update-your-bin-scripts)
   - [Add `main` to your package.json](#add-main-to-your-packagejson)
   - [Restore `-h`, `-v`, and `version`](#restore--h--v-and-version)
@@ -30,6 +31,50 @@ With this import:
 import {Command, Flags, Topic, Help} from '@oclif/core';
 ```
 
+## Update Command Args
+
+We updated the `Command.args` to more closely resemble flags
+
+**Before**
+
+```typescript
+import { Command } from '@oclif/core'
+
+export default MyCommand extends Command {
+  static args = [{name: arg1, description: 'an argument', required: true}]
+
+  public async run(): Promise<void> {
+    const {args} = await this.parse(MyCommand) // args is useless {[name: string]: any}
+  }
+}
+```
+
+**After**
+
+```typescript
+import { Command, Args } from '@oclif/core'
+
+export default MyCommand extends Command {
+  static args = {
+    arg1: Args.string({description: 'an argument', required: true})
+  }
+
+  public async run(): Promise<void> {
+    const {args} = await this.parse(MyCommand) // args is { arg1: string }
+  }
+}
+```
+
+These are the available Args:
+- string
+- integer
+- boolean
+- url
+- file
+- directory
+- custom
+
+
 ## Update your bin scripts
 
 `@oclif/core` now supports separate bin scripts for production and development.

guides/V3_MIGRATION.md

@@ -5,16 +5,18 @@ Migrating to @oclif/core@V3
   - [BREAKING CHANGES ❗](#breaking-changes-)
     - [Dropping node 14 and node 16 support](#dropping-node-14-and-node-16-support)
     - [Bin Scripts for ESM/CJS Interoperability](#bin-scripts-for-esmcjs-interoperability)
+    - [Dropped `ts-node` as a dependency](#dropped-ts-node-as-a-dependency)
     - [`Config.plugins`](#configplugins)
     - [Readonly properties on `Config`](#readonly-properties-on-config)
     - [Private methods on `Plugin`](#private-methods-on-plugin)
     - [`global['cli-ux']` -\> `global.ux`](#globalcli-ux---globalux)
     - [`handle`](#handle)
     - [`noCacheDefault` flag property replaces `isWritingManifest`](#nocachedefault-flag-property-replaces-iswritingmanifest)
   - [Features 🎉](#features-)
-    - [Cache Flexible taxonomy Command Permutations](#cache-flexible-taxonomy-command-permutations)
+    - [Performance Improvements](#performance-improvements)
     - [charAliases Flag Property](#charaliases-flag-property)
     - [Flags.option](#flagsoption)
+    - [Set spinner styles](#set-spinner-styles)
 
 
 ## BREAKING CHANGES ❗
@@ -36,6 +38,10 @@ In order to support ESM and CommonJS plugin interoperability you will need to up
 
 If you'd like to migrate your plugin to ESM, please read our guide [here](https://oclif.io/docs/esm)
 
+### Dropped `ts-node` as a dependency
+
+We removed `ts-node` as a dependency to reduce the package size. By doing this, it means that linked plugin **must** have `ts-node` as a `devDependency` in order for auto-transpilation to work.
+
 ### `Config.plugins`
 `Config.plugins` is now a `Map` where the keys are the plugin names and the values are the loaded `Plugin` instances. Previously it was an array of loaded `Plugin` instances.
 
@@ -113,9 +119,12 @@ export const mySensitiveFlag = Flags.string({
 
 ## Features 🎉
 
-### Cache Flexible taxonomy Command Permutations
+### Performance Improvements
 
-The command permutations for flexible taxonomy are now cached in the oclif.manifest.json allowing for quicker startup times.
+- Cache command permutations for flexible taxonomy in the `oclif.manifest.json`
+- Cache additional command properties (`isESM`, `relativePath`) in the `oclif.manifest.json`
+- Improved accuracy in the `DEBUG=perf` output.
+- Remove `ts-node` from `dependencies` to reduce the package size.
 
 ### charAliases Flag Property
 
@@ -149,3 +158,15 @@ export default class MyCommand extends Command {
   }
 }
 ```
+
+### Set spinner styles
+
+You can now configure the style of the spinner when using `ux.action.start`. See [spinners](https://github.com/oclif/core/blob/main/src/cli-ux/action/spinners.ts) for all the different options.
+
+```typescript
+ux.action.start('starting spinner', 'spinning', {style: 'arc'})
+await ux.wait(2500)
+ux.action.status = 'still going'
+await ux.wait(2500)
+ux.action.stop()
+```

src/flags.ts

@@ -145,12 +145,16 @@ export const help = (opts: Partial<BooleanFlag<boolean>> = {}): BooleanFlag<void
   },
 })
 
+/**
+ * Boolean flag for enabling JSON output. We strongly discourage using this flag directly
+ * and instead recommend setting the `enableJsonFlag` property on the Command class.
+ */
 export const json = (opts: Partial<BooleanFlag<boolean>> = {}): BooleanFlag<boolean> => boolean({
   description: 'Format output as json.',
   helpGroup: 'GLOBAL',
   ...opts,
-  async parse(input, cmd) {
-    if (input) process.env[cmd.config.scopedEnvVarKey('JSON_FLAG_OVERRIDE')] = 'true'
+  async parse(input, {config}) {
+    if (input) process.env[config.scopedEnvVarKey('JSON_FLAG_OVERRIDE')] = 'true'
     return input
   },
 })