-
Notifications
You must be signed in to change notification settings - Fork 70
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
* 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 <shane.mclaughlin@salesforce.com>
- Loading branch information
1 parent
c1423d5
commit bd2461b
Showing
104 changed files
with
4,244 additions
and
2,791 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,14 @@ | ||
| { | ||
| "extends": [ | ||
| "oclif", | ||
| "oclif-typescript" | ||
| ], | ||
| "rules": { | ||
| "sort-imports": "error", | ||
| "unicorn/prefer-module": "off", | ||
| "unicorn/import-style": "error", | ||
| "unicorn/no-array-reduce": "off", | ||
| "unicorn/prefer-array-some": "off", | ||
| "no-useless-constructor": "off" | ||
| } | ||
| } |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,182 @@ | ||
| Migrating to @oclif/core from deprecated libraries | ||
| ============== | ||
|
|
||
| Migrating to `@oclif/core` from the deprecated oclif libraries (`@oclif/config`, `@oclif/command`, `@oclif/error`, `@oclif/parser`) is relatively straight forward. | ||
|
|
||
| - [Migrating to @oclif/core from deprecated libraries](#migrating-to-oclifcore-from-deprecated-libraries) | ||
| - [Update Imports](#update-imports) | ||
| - [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) | ||
| - [Configure the `topicSeparator`](#configure-the-topicseparator) | ||
| - [Update `this.parse` to `await this.parse`](#update-thisparse-to-await-thisparse) | ||
| - [Update `default` property on flag definitions](#update-default-property-on-flag-definitions) | ||
| - [Replace cli-ux library with `ux`](#replace-cli-ux-library-with-ux) | ||
| - [Single command CLIs](#single-command-clis) | ||
|
|
||
| ## Update Imports | ||
|
|
||
| Replace imports from the old libraries with `@oclif/core`. For example, | ||
|
|
||
| ```typescript | ||
| import Help from '@oclif/plugin-help'; | ||
| import {Topic} from '@oclif/config'; | ||
| import {Command, Flags} from '@oclif/command' | ||
| ``` | ||
|
|
||
| With this import: | ||
|
|
||
| ```typescript | ||
| import {Command, Flags, Topic, Help} from '@oclif/core'; | ||
| ``` | ||
|
|
||
| ## Update your bin scripts | ||
|
|
||
| `@oclif/core` now supports separate bin scripts for production and development. | ||
|
|
||
| You can copy these new bin scripts directly from our [example repository](https://github.com/oclif/hello-world/tree/main/bin). | ||
|
|
||
| ## Add `main` to your package.json | ||
|
|
||
| We recommend that all oclif plugins specify the `main` field in their package.json so that we can begin working on supporting Yarn v2. | ||
|
|
||
| ```json | ||
| { | ||
| "main": "lib/index.js" | ||
| } | ||
| ``` | ||
|
|
||
| All plugins will be required to have this field in the next major version of `@oclif/core`. | ||
|
|
||
| ## Restore `-h`, `-v`, and `version` | ||
|
|
||
| `@oclif/config` automatically added `-h` as a short flag for `--help`, `-v` as a short flag for `--version`, and `version` as an alias for `--version`. | ||
|
|
||
| `@oclif/core` removes these so you can now use those flags for whatever you want! However, we've added a way to restore that functionality if you want to keep it. | ||
|
|
||
| Simply add the `additionalHelpFlags` and `additionalVersionFlags` properties to the oclif section of your package.json: | ||
|
|
||
| ```json | ||
| { | ||
| "oclif": { | ||
| "additionalHelpFlags": ["-h"], | ||
| "additionalVersionFlags": ["-v"] | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| To get the `version` command, install `@oclif/plugin-version` into your CLI: | ||
|
|
||
| ```json | ||
| { | ||
| "dependencies": { | ||
| "@oclif/plugin-version": "^3" | ||
| }, | ||
| "oclif": { | ||
| "plugins": [ | ||
| "@oclif/plugin-version" | ||
| ] | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| ## Configure the `topicSeparator` | ||
|
|
||
| By default, the `topicSeparator` is set to a colon (`:`) to maintain backwards compatibility with existing CLIs. If you prefer, you can now set it to a space. | ||
|
|
||
| For colons: | ||
| ```json | ||
| { | ||
| "oclif": { | ||
| "topicSeparator": ":" | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| For spaces: | ||
| ```json | ||
| { | ||
| "oclif": { | ||
| "topicSeparator": " " | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| **NOTE: Using colons always works, even if you set the `topicSeparator` to spaces.** This means that you can enable spaces in your CLI without introducing a breaking change to your users. | ||
|
|
||
| ## Update `this.parse` to `await this.parse` | ||
|
|
||
| The `parse` method on `Command` is now asynchronous (more [here](https://oclif.io/blog/#async-command-parsing)). So you'll now need to `await` any calls to `this.parse`: | ||
|
|
||
| `const { args, flags } = this.parse(MyCommand)` => `const { args, flags } = await this.parse(MyCommand)` | ||
|
|
||
| ## Update `default` property on flag definitions | ||
|
|
||
| The `default` property on flag definitions is now asynchronous. So you'll now need to await those. | ||
|
|
||
| Example: | ||
|
|
||
| ```typescript | ||
| import {Command, Flags} from '@oclif/core' | ||
| import {readFile} from 'fs/promises' | ||
|
|
||
| function getTeam(): Promise<string> { | ||
| return readFile('team.txt', 'utf-8') | ||
| } | ||
|
|
||
| export const team = Flags.build({ | ||
| char: 't', | ||
| description: 'team to use', | ||
| default: () => getTeam(), | ||
| }) | ||
|
|
||
| export class MyCLI extends Command { | ||
| static flags = { | ||
| team: team(), | ||
| } | ||
|
|
||
| async run() { | ||
| const {flags} = this.parse(MyCLI) | ||
| if (flags.team) console.log(`--team is ${flags.team}`) | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| ## Replace cli-ux library with `ux` | ||
|
|
||
| The [`cli-ux` library](https://github.com/oclif/cli-ux) has also been moved into `@oclif/core` in order to break a complex circular dependency between the two projects. | ||
|
|
||
| All the exports that were available from `cli-ux` are now available under the `ux` namespace, with the exception of the `cli` export which was identical to the `ux` export. | ||
|
|
||
| Old: | ||
|
|
||
| ```typescript | ||
| import { cli } from 'cli-ux` | ||
|
|
||
| cli.log('hello world') | ||
| cli.action.start('doing things') | ||
| cli.action.stop() | ||
| ``` | ||
|
|
||
| New: | ||
|
|
||
| ```typescript | ||
| import { ux } from '@oclif/core` | ||
|
|
||
| ux.log('hello world') | ||
| ux.action.start('doing things') | ||
| ux.action.stop() | ||
| ``` | ||
|
|
||
| ## Single command CLIs | ||
|
|
||
| Single command CLIs now are configured in a different way. To ensure your migrated CLI work as before, you have to add the following to your `oclif` configuration in the `package.json`: | ||
|
|
||
| ```json | ||
| "oclif": { | ||
| "default": ".", | ||
| "commands": "./lib" | ||
| } | ||
| ``` | ||
|
|
||
| Where `./lib` points to the folder in which your `tsconfig.json` is configured to output to (if you are using TypeScript), and your single command CLI entrypoint `index.(ts|js)` is located. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.