diff --git a/package.json b/package.json index b1e81d7cc..161b24151 100644 --- a/package.json +++ b/package.json @@ -1,7 +1,7 @@ { "name": "@oclif/core", "description": "base library for oclif CLIs", - "version": "4.5.5", + "version": "4.5.6-autocomplete.0", "author": "Salesforce", "bugs": "https://github.com/oclif/core/issues", "dependencies": { diff --git a/src/interfaces/index.ts b/src/interfaces/index.ts index 4b49296e9..2c6261f07 100644 --- a/src/interfaces/index.ts +++ b/src/interfaces/index.ts @@ -12,6 +12,7 @@ export type { ArgDefinition, ArgInput, BooleanFlag, + Completion, CustomOptions, Deprecation, Flag, diff --git a/src/interfaces/parser.ts b/src/interfaces/parser.ts index f88a56683..02bec2038 100644 --- a/src/interfaces/parser.ts +++ b/src/interfaces/parser.ts @@ -231,6 +231,21 @@ export type OptionFlagProps = FlagProps & { * Should only be used on one flag at a time. */ allowStdin?: boolean | 'only' + /** + * Optional dynamic completion configuration. + * Provides intelligent autocomplete suggestions for flag values based on context. + * Requires autocomplete plugin to be installed. + * + * @example + * ```typescript + * completion: { + * options: async (ctx) => { + * return ['option1', 'option2', 'option3'] + * } + * } + * ``` + */ + completion?: Completion } export type FlagParserContext = Command & {token: FlagToken} @@ -439,6 +454,33 @@ export type ParserInput = { '--'?: boolean | undefined } +/** + * Completion configuration for a flag + */ +export type Completion = { + /** + * Function that returns completion options + * + * @returns Promise resolving to array of completion strings + * + * @example + * ```typescript + * static flags = { + * 'target-org': Flags.string({ + * description: 'Target org', + * completion: { + * options: async () => { + * const orgs = await getAuthenticatedOrgs() + * return orgs.map(o => o.alias) + * } + * } + * }) + * } + * ``` + */ + options(): Promise +} + export type ParserContext = Command & { token?: FlagToken | ArgToken | undefined } diff --git a/test/interfaces/parser.test.ts b/test/interfaces/parser.test.ts new file mode 100644 index 000000000..5b9149580 --- /dev/null +++ b/test/interfaces/parser.test.ts @@ -0,0 +1,29 @@ +import {expect} from 'chai' + +import * as Interfaces from '../../src/interfaces' + +describe('Completion types', () => { + it('allows completion property on OptionFlag', () => { + const completion: Interfaces.Completion = { + async options() { + return ['option1', 'option2'] + }, + } + + expect(completion).to.exist + expect(completion.options).to.be.a('function') + }) + + it('completion function returns promise of strings', async () => { + const completion: Interfaces.Completion = { + async options() { + return ['a', 'b', 'c'] + }, + } + + const result = await completion.options() + + expect(result).to.be.an('array') + expect(result).to.deep.equal(['a', 'b', 'c']) + }) +})