Prerelease/v2

[mdonnalley]

Breaking Changes

Command Args

We updated the Command.args to more closely resemble flags

Before

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

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

Interfaces

• Removed Interfaces.Command since they were not usable for tests. These are replaced by types that are available under the Command namespace

Interfaces.Command => Command.Cached
Interfaces.Command.Class => Command.Class
Interfaces.Command.Loadable => Command.Lodable

• Removed the following interfaces from the export. Exporting all of these made it difficult to make non-breaking changes when modifying types and/or fixing compilation bugs. We are open to PRs to reintroduce these to the export if they are needed for your project
  • Arg
  • ArgInput
  • ArgToken
  • CLIParseErrorOptions
  • CompletableFlag
  • CompletableOptionFlag
  • Completion
  • CompletionContext
  • Default
  • DefaultContext
  • Definition
  • EnumFlagOptions
  • FlagBase
  • FlagInput
  • FlagOutput
  • FlagToken
  • FlagUsageOptions
  • Input
  • List
  • ListItem
  • Metadata
  • OptionalArg
  • OptionFlagProps
  • OutputArgs
  • OutputFlags
  • ParseFn
  • ParserArg
  • ParserInput
  • ParserOutput
  • ParsingToken
  • RequiredArg

CliUx

We flattened CliUx.ux into ux for ease of use

Before

import {CliUx} from '@oclif/core'

CliUx.ux.log('Hello World')

After

import {ux} from '@oclif/core'

ux.log('Hello World')

CliUx.ux.open

We removed the open method since it was a direct import/export of the open package. If you need this functionality, then you should import open yourself.

Flags

• Flags.custom replaces Flags.build, Flags.enum, and Flags.option
• Removed builtin color flag
• Renamed globalFlags to baseFlags
  • globalFlags was a misleading name because the flags added there weren't actually global to the entire CLI. Instead, they were just flags that would be inherited by any command that extended the command class they were defined in.

Flag and Arg Parsing

• In v1, any input that didn't match a flag definition was assumed to be an argument. This meant that misspelled flags, e.g. --hekp were parsed as arguments, instead of throwing an error. In order to handle this, oclif now assumes that anything that starts with a hypen must be a flag and will throw an error if no corresponding flag definition is found. In other words, your command can no longer accept arguments that begin with a hyphen (fixes Adding strict=false parses a non-existing flag as a arg #526)
• v1 allowed you to return an array from a flag's parse. This was added to support backwards compatibility for flags that separated values by commas (e.g. my-flag=val1,val2). However, this was problematic because it didn't allow the parse to manipulate the individual values. If you need this functionality, you can now set a delimiter option on your flags. By doing so, oclif will split the string on the delimiter before parsing.

ESM/CJS Friendliness

Writing plugins with ESM has always been possible, but it requires a handful of modifications for it to work, especially in the bin scripts. In v2 we've introduced an execute method that the bin scripts can use to avoid having to make changes for ESM of CJS.

CJS bin/dev before

#!/usr/bin/env node

const oclif = require('@oclif/core')

const path = require('path')
const project = path.join(__dirname, '..', 'tsconfig.json')

// In dev mode -> use ts-node and dev plugins
process.env.NODE_ENV = 'development'

require('ts-node').register({project})

// In dev mode, always show stack traces
oclif.settings.debug = true;


// Start the CLI
oclif.run().then(oclif.flush).catch(oclif.Errors.handle)

CJS bin/dev.js after

#!/usr/bin/env node
// eslint-disable-next-line node/shebang
(async () => {
  const oclif = await import('@oclif/core')
  await oclif.execute({type: 'cjs', development: true, dir: __dirname})
})()

ESM bin/dev.js before

#!/usr/bin/env ts-node

/* eslint-disable node/shebang */

import oclif from '@oclif/core'
import path from 'node:path'
import url from 'node:url'
// eslint-disable-next-line node/no-unpublished-import
import {register} from 'ts-node'

// In dev mode -> use ts-node and dev plugins
process.env.NODE_ENV = 'development'

register({
  project: path.join(path.dirname(url.fileURLToPath(import.meta.url)), '..', 'tsconfig.json'),
})

// In dev mode, always show stack traces
oclif.settings.debug = true

// Start the CLI
oclif
.run(process.argv.slice(2), import.meta.url)
.then(oclif.flush)
.catch(oclif.Errors.handle)

ESM bin/dev.js after

#!/usr/bin/env node
// eslint-disable-next-line node/shebang
(async () => {
  const oclif = await import('@oclif/core')
  await oclif.execute({type: 'esm', dir: import.meta.url})
})()

Note that ESM and CJS plugins still require different settings in the tsconfig.json - you will still need to make those modifications yourself.

Other Changes

• Removed dependency on @oclif/screen
• Replaced @oclif/linewrap with wordwrap
• Fixes deprecated property does not work when = is used to provide value #586

TODO

• Remove ux.open method (users can import the open library directly if they need it)
• More unit tests for arg parsing
• Handle will-fix-in-v2 issues
• Update migration guide
• Update oclif.io docs
• Investigate impact on oclif and salesforce plugins
• Remove all usage of PromiseLike
• Deprecate @oclif/screen
• Deprecate @oclif/linewrap

Related

oclif/oclif.github.io#188

[peternhale]

@mdonnalley should we also allow access verification to dir and file as an option?

[peternhale]

@mdonnalley what about decimal numbers?

[peternhale]

Why is the assertion of as string[] necessary?

[mdonnalley]

If you remove it, you get this:

(alias) castArray<string>(input?: string | string[] | undefined): string[]
import castArray
Argument of type 'string[]' is not assignable to parameter of type '[str: string | Uint8Array, encoding?: BufferEncoding | undefined, cb?: ((err?: Error | undefined) => void) | undefined]'.
  Target requires 1 element(s) but source may have fewer.ts(2345)

My understanding is that it means the function expects an array of exactly one element, which isn't guaranteed by string[], hence the need to do as [string]

Personally, this part of the code base falls under the "if it ain't broke don't fix it" category so I'd prefer to leave it as is

[peternhale]

When does a command not have an Id?

[mdonnalley]

@peternhale This is something that Shane discovered while trying to write command-level unit tests without @oclif/test. The command lacks an id anytime you use the static run method, like in this example: https://github.com/oclif/core#usage

In the normal code path, the id is determined based on the file path containing the command class but in this use case, there's no file path so there's no way to determine what the id should be.

In the real world most developers using the static run would add the id prop to their command so this code block would rarely be used. But it's helpful when writing unit tests for commands that aren't mean to be run using the static run method.

[peternhale]

Can conditional types help with these function overloading?

[mdonnalley]

Did you have something specific in mind? I don't think a conditional type would eliminate the need to overload this method. You still need to express that if {exit: false} is provided, then return type is void otherwise it's never

[peternhale]

Return type is missing

[peternhale]

consider number flag?

[mdonnalley]

@peternhale Is there currently a need for it? Generally speaking, I prefer to wait until we have a real use case before adding a new feature

[peternhale]

Consider access checks as an option

[mdonnalley]

@peternhale same question: is there currently a need for it?

[peternhale]

This cannot handle True | Yes. I would suggest testing the lower case of input

[peternhale]

Consider lower case of input here too.