1 | import { LooseTest } from 'typanion';
|
2 | import { Token } from '../core';
|
3 | import { BaseContext, MiniCli } from './Cli';
|
4 | import { isOptionSymbol } from './options/utils';
|
5 | /**
|
6 | * The usage of a Command.
|
7 | */
|
8 | export type Usage = {
|
9 | /**
|
10 | * The category of the command.
|
11 | *
|
12 | * Included in the detailed usage.
|
13 | */
|
14 | category?: string;
|
15 | /**
|
16 | * The short description of the command, formatted as Markdown.
|
17 | *
|
18 | * Included in the detailed usage.
|
19 | */
|
20 | description?: string;
|
21 | /**
|
22 | * The extended details of the command, formatted as Markdown.
|
23 | *
|
24 | * Included in the detailed usage.
|
25 | */
|
26 | details?: string;
|
27 | /**
|
28 | * Examples of the command represented as an Array of tuples.
|
29 | *
|
30 | * The first element of the tuple represents the description of the example.
|
31 | *
|
32 | * The second element of the tuple represents the command of the example.
|
33 | * If present, the leading `$0` is replaced with `cli.binaryName`.
|
34 | */
|
35 | examples?: Array<[string, string]>;
|
36 | };
|
37 | /**
|
38 | * The definition of a Command.
|
39 | */
|
40 | export type Definition = Usage & {
|
41 | /**
|
42 | * The path of the command, starting with `cli.binaryName`.
|
43 | */
|
44 | path: string;
|
45 | /**
|
46 | * The detailed usage of the command.
|
47 | */
|
48 | usage: string;
|
49 | /**
|
50 | * The various options registered on the command.
|
51 | */
|
52 | options: Array<{
|
53 | preferredName: string;
|
54 | nameSet: Array<string>;
|
55 | definition: string;
|
56 | description?: string;
|
57 | required: boolean;
|
58 | }>;
|
59 | };
|
60 | export type CommandClass<Context extends BaseContext = BaseContext> = {
|
61 | new (): Command<Context>;
|
62 | paths?: Array<Array<string>>;
|
63 | schema?: Array<LooseTest<{
|
64 | [key: string]: unknown;
|
65 | }>>;
|
66 | usage?: Usage;
|
67 | };
|
68 | /**
|
69 | * Base abstract class for CLI commands. The main thing to remember is to
|
70 | * declare an async `execute` member function that will be called when the
|
71 | * command is invoked from the CLI, and optionally a `paths` property to
|
72 | * declare the set of paths under which the command should be exposed.
|
73 | */
|
74 | export declare abstract class Command<Context extends BaseContext = BaseContext> {
|
75 | [`constructor`]: CommandClass<Context>;
|
76 | /**
|
77 | * @deprecated Do not use this; prefer the static `paths` property instead.
|
78 | */
|
79 | paths?: undefined;
|
80 | /**
|
81 | * Defined to prevent a common typo.
|
82 | */
|
83 | static path: never;
|
84 | /**
|
85 | * Paths under which the command should be exposed.
|
86 | */
|
87 | static paths?: Array<Array<string>>;
|
88 | /**
|
89 | * Defines the usage information for the given command.
|
90 | */
|
91 | static Usage(usage: Usage): Usage;
|
92 | /**
|
93 | * Contains the usage information for the command. If undefined, the
|
94 | * command will be hidden from the general listing.
|
95 | */
|
96 | static usage?: Usage;
|
97 | /**
|
98 | * Defines a schema to apply before running the `execute` method. The
|
99 | * schema is expected to be generated by Typanion.
|
100 | *
|
101 | * @see https://github.com/arcanis/typanion
|
102 | */
|
103 | static schema?: Array<LooseTest<{
|
104 | [key: string]: unknown;
|
105 | }>>;
|
106 | /**
|
107 | * Standard function that'll get executed by `Cli#run` and `Cli#runExit`.
|
108 | *
|
109 | * Expected to return an exit code or nothing (which Clipanion will treat
|
110 | * as if 0 had been returned).
|
111 | */
|
112 | abstract execute(): Promise<number | void>;
|
113 | /**
|
114 | * Standard error handler which will simply rethrow the error. Can be used
|
115 | * to add custom logic to handle errors from the command or simply return
|
116 | * the parent class error handling.
|
117 | */
|
118 | catch(error: any): Promise<void>;
|
119 | /**
|
120 | * Predefined that will be set to true if `-h,--help` has been used, in
|
121 | * which case `Command#execute` won't be called.
|
122 | */
|
123 | help: boolean;
|
124 | /**
|
125 | * Predefined variable that will be populated with a miniature API that can
|
126 | * be used to query Clipanion and forward commands.
|
127 | */
|
128 | cli: MiniCli<Context>;
|
129 | /**
|
130 | * Predefined variable that will be populated with the context of the
|
131 | * application.
|
132 | */
|
133 | context: Context;
|
134 | /**
|
135 | * Predefined variable that will be populated with the path that got used
|
136 | * to access the command currently being executed.
|
137 | */
|
138 | path: Array<string>;
|
139 | /**
|
140 | * Predefined variable that will be populated with the tokens found when
|
141 | * interpreting the command line.
|
142 | */
|
143 | tokens: Array<Token>;
|
144 | validateAndExecute(): Promise<number>;
|
145 | /**
|
146 | * Used to detect option definitions.
|
147 | */
|
148 | static isOption: typeof isOptionSymbol;
|
149 | /**
|
150 | * Just an helper to use along with the `paths` fields, to make it
|
151 | * clearer that a command is the default one.
|
152 | *
|
153 | * @example
|
154 | * class MyCommand extends Command {
|
155 | * static paths = [Command.Default];
|
156 | * }
|
157 | */
|
158 | static Default: never[];
|
159 | }
|