@gunshi/bone 1.0.0-rc.7 → 1.0.0-rc.9
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/lib/index.d.ts +110 -9
- package/lib/index.js +15 -5
- package/package.json +5 -5
package/lib/index.d.ts
CHANGED
|
@@ -982,7 +982,7 @@ interface CommandEnvironment<G extends GunshiParamsConstraint = DefaultGunshiPar
|
|
|
982
982
|
*/
|
|
983
983
|
cwd: string | undefined;
|
|
984
984
|
/**
|
|
985
|
-
*
|
|
985
|
+
* The name of the CLI, given to `cli()` as `name`.
|
|
986
986
|
*
|
|
987
987
|
* @see {@linkcode CliOptions.name}
|
|
988
988
|
*/
|
|
@@ -1144,7 +1144,11 @@ interface CliOptions<G extends GunshiParamsConstraint = DefaultGunshiParams> {
|
|
|
1144
1144
|
*/
|
|
1145
1145
|
cwd?: string;
|
|
1146
1146
|
/**
|
|
1147
|
-
*
|
|
1147
|
+
* The name of the CLI, as it is run, such as `todo`.
|
|
1148
|
+
*
|
|
1149
|
+
* The usage line and the help as JSON start with it, and so do the command that the errors point to
|
|
1150
|
+
* for the help and `next` of the errors of `--json`. Without it, the usage line starts with `COMMAND`,
|
|
1151
|
+
* and the others with `<COMMAND>`, a placeholder for how the CLI was run.
|
|
1148
1152
|
*/
|
|
1149
1153
|
name?: string;
|
|
1150
1154
|
/**
|
|
@@ -1273,11 +1277,12 @@ interface CliOptions<G extends GunshiParamsConstraint = DefaultGunshiParams> {
|
|
|
1273
1277
|
/**
|
|
1274
1278
|
* The exit code of the validation errors, such as `2`, the exit code of a usage error in many
|
|
1275
1279
|
* command-line tools. They are the errors of the arguments: a missing or invalid argument, an unknown
|
|
1276
|
-
* command or a command line that cannot be resolved, an unknown option
|
|
1277
|
-
* argument that the command does not take
|
|
1278
|
-
* that does not spread `jsonArgs`.
|
|
1279
|
-
* the
|
|
1280
|
-
*
|
|
1280
|
+
* command or a command line that cannot be resolved, an unknown option, only with `strict`, a
|
|
1281
|
+
* positional argument that the command does not take, only with `strictPositionals`, and `--json`
|
|
1282
|
+
* given to a command that does not spread `jsonArgs`. Without `strict`, an unknown option is ignored
|
|
1283
|
+
* and the command runs, so to end it with this exit code too, give `strict: true` as well. With the
|
|
1284
|
+
* global options plugin, the exit code is set to it when the errors are printed, as text or as JSON,
|
|
1285
|
+
* before {@linkcode CliOptions.onErrorCommand} is called, which can still change it.
|
|
1281
1286
|
*
|
|
1282
1287
|
* It is an integer from `1` to `255`, as the `exitCode` of a `CommandError` is, and any other value is
|
|
1283
1288
|
* replaced with `1`. It does not change the exit code of a `CommandError`, nor of any other error that a
|
|
@@ -1832,11 +1837,90 @@ type RendererDecorator<T, G extends GunshiParamsConstraint = DefaultGunshiParams
|
|
|
1832
1837
|
* @since v0.27.0
|
|
1833
1838
|
*/
|
|
1834
1839
|
type ValidationErrorsDecorator<G extends GunshiParamsConstraint = DefaultGunshiParams> = (baseRenderer: (ctx: Readonly<CommandContext<G>>, error: AggregateError) => Promise<string>, ctx: Readonly<CommandContext<G>>, error: AggregateError) => Promise<string>;
|
|
1840
|
+
/**
|
|
1841
|
+
* The keys that people write in an argument, from another library or by a typo, with the key of Gunshi to use
|
|
1842
|
+
* instead
|
|
1843
|
+
*
|
|
1844
|
+
* NOTE(kazupon): keep it short. A key is here when people write it, as the apps that use Gunshi did with `alias`
|
|
1845
|
+
* and `array` (#930). The i18n plugin keeps a copy of it (`packages/plugin-i18n/src/helpers.ts`): change both.
|
|
1846
|
+
*
|
|
1847
|
+
* @internal
|
|
1848
|
+
*/
|
|
1849
|
+
type ArgKeyHints = {
|
|
1850
|
+
alias: 'short';
|
|
1851
|
+
array: 'multiple';
|
|
1852
|
+
desc: 'description';
|
|
1853
|
+
require: 'required';
|
|
1854
|
+
};
|
|
1855
|
+
/**
|
|
1856
|
+
* The message for a key that an argument does not have, with the key to use instead when {@link ArgKeyHints} has
|
|
1857
|
+
* one
|
|
1858
|
+
*
|
|
1859
|
+
* @internal
|
|
1860
|
+
*/
|
|
1861
|
+
type UnknownArgKeyMessage<P> = `'${P & string}' is not a key of an argument${P extends keyof ArgKeyHints ? `: use '${ArgKeyHints[P]}'` : ''}`;
|
|
1862
|
+
/**
|
|
1863
|
+
* The keys of all the members of a union of schemas, such as a schema typed as
|
|
1864
|
+
* `{ type: 'string'; require: true } | { type: 'number' }`: `keyof` of a union has only the keys that every member
|
|
1865
|
+
* has
|
|
1866
|
+
*
|
|
1867
|
+
* @internal
|
|
1868
|
+
*/
|
|
1869
|
+
type KeysOfEach<S> = S extends unknown ? keyof S : never;
|
|
1870
|
+
/**
|
|
1871
|
+
* The keys of each argument that {@link ArgSchema} does not have, mapped to a type that names the key
|
|
1872
|
+
*
|
|
1873
|
+
* NOTE(kazupon): the definition helpers infer the arguments, so a key that an argument does not have, such as
|
|
1874
|
+
* `positional: true` or a misspelled `require`, would type-check and be ignored at run time (#930). A value does not
|
|
1875
|
+
* fit the type, so the error is reported at the key, and says which key an argument does not have, and the key to
|
|
1876
|
+
* use instead for the keys of {@link ArgKeyHints}:
|
|
1877
|
+
* `Type 'true' is not assignable to type 'boolean & { "'require' is not a key of an argument: use 'required'": never; }'`.
|
|
1878
|
+
* The marks of Gunshi, such as the one of `jsonArgs`, are keys that start with `~gunshi.`.
|
|
1879
|
+
*
|
|
1880
|
+
* @internal
|
|
1881
|
+
*/
|
|
1882
|
+
type UnknownArgKeys<A> = { [K in keyof A]: { [P in Exclude<KeysOfEach<A[K]>, keyof ArgSchema | `~gunshi.${string}`>]: { [M in UnknownArgKeyMessage<P>]: never; }; }; };
|
|
1883
|
+
/**
|
|
1884
|
+
* `G`, which a call does not infer from: an indexed access that waits for `G`, as `NoInfer` of TypeScript 5.4 does
|
|
1885
|
+
*
|
|
1886
|
+
* NOTE(kazupon): the first overload of `cli()` infers the arguments of the entry command from its `args`, and takes
|
|
1887
|
+
* `G` as `{ args: A; extensions: {} }` (#931). If `G` were inferred, a command of `define()` would give it from the
|
|
1888
|
+
* keys that the definition does not write, which `define()` types with the default parameters, such as `examples`, and
|
|
1889
|
+
* a command that spreads `jsonArgs` would not fit. Nor is the entry typed as `Command<{ args: A; extensions: {} }>`:
|
|
1890
|
+
* as the first overload, that breaks the inference of `define()` written in the call (#452).
|
|
1891
|
+
*
|
|
1892
|
+
* @typeParam G - The type of the parameters of a command
|
|
1893
|
+
*
|
|
1894
|
+
* @internal
|
|
1895
|
+
*/
|
|
1896
|
+
type NoInferParams<G> = [G][G extends unknown ? 0 : never];
|
|
1897
|
+
/**
|
|
1898
|
+
* A command that the other overloads of `cli()` do not take, such as a command of another copy of the types of gunshi:
|
|
1899
|
+
* its arguments are `Args`, and its runner returns what a runner returns
|
|
1900
|
+
*
|
|
1901
|
+
* NOTE(kazupon): `gunshi` and `@gunshi/definition` bundle their own copies of the types. A command of `define()` types
|
|
1902
|
+
* its `run` with the context of its arguments, and the keys that the definition does not write with the default
|
|
1903
|
+
* parameters. Within one copy, TypeScript compares them by the variance of `CommandContext`, and the command fits;
|
|
1904
|
+
* across the copies, TypeScript compares the structures, and the command fits no other overload. So the runner takes
|
|
1905
|
+
* any arguments here. The arguments are `Args`, and the runner returns what a runner returns, so that an object written
|
|
1906
|
+
* in the call with an argument that is not valid, such as `type: 'numbr'`, is a type error, rather than taken with a
|
|
1907
|
+
* `ctx` of `any` (#931).
|
|
1908
|
+
*
|
|
1909
|
+
* @internal
|
|
1910
|
+
*/
|
|
1911
|
+
type EntryCommandable = Omit<SubCommandable, 'args' | 'run'> & {
|
|
1912
|
+
args?: Args;
|
|
1913
|
+
run?: (...args: any[]) => Awaitable<string | void | JsonResult>;
|
|
1914
|
+
};
|
|
1835
1915
|
/**
|
|
1836
1916
|
* Run the command, without the built-in plugins: `--help` and `--version` print nothing, unless you add the plugins.
|
|
1837
1917
|
* To have them, use `cli` from `gunshi`.
|
|
1838
1918
|
*
|
|
1839
|
-
*
|
|
1919
|
+
* An object written as the entry command is typed by its `args`, as with `define`: `ctx.values` of its `run` are
|
|
1920
|
+
* inferred from them, and a key that an argument does not have is an error.
|
|
1921
|
+
*
|
|
1922
|
+
* @typeParam A - The type of {@linkcode Args | arguments} of the entry command, inferred from its `args`.
|
|
1923
|
+
* @typeParam G - A type extending {@linkcode GunshiParams}, which is not inferred: `{ args: A; extensions: {} }`.
|
|
1840
1924
|
*
|
|
1841
1925
|
* @param args - Command line arguments
|
|
1842
1926
|
* @param entry - A {@link Command | entry command}, an {@link CommandRunner | inline command runner}, or a {@link LazyCommand | lazily-loaded command}
|
|
@@ -1846,7 +1930,9 @@ type ValidationErrorsDecorator<G extends GunshiParamsConstraint = DefaultGunshiP
|
|
|
1846
1930
|
export declare function cli<A extends Args = Args, G extends GunshiParams = {
|
|
1847
1931
|
args: A;
|
|
1848
1932
|
extensions: {};
|
|
1849
|
-
}>(args: string[], entry: Command<
|
|
1933
|
+
}>(args: string[], entry: (Command<NoInferParams<G>> & {
|
|
1934
|
+
args?: A & UnknownArgKeys<A>;
|
|
1935
|
+
}) | CommandRunner<NoInferParams<G>> | LazyCommand<NoInferParams<G>>, options?: CliOptions<NoInferParams<G>>): Promise<string | undefined>;
|
|
1850
1936
|
/**
|
|
1851
1937
|
* Run the command, without the built-in plugins: `--help` and `--version` print nothing, unless you add the plugins.
|
|
1852
1938
|
* To have them, use `cli` from `gunshi`.
|
|
@@ -1874,4 +1960,19 @@ export declare function cli<E extends ExtendContext = ExtendContext, G extends G
|
|
|
1874
1960
|
* @returns A rendered usage or undefined. if you will use {@linkcode CliOptions.usageSilent} option, it will return rendered usage string.
|
|
1875
1961
|
*/
|
|
1876
1962
|
export declare function cli<G extends GunshiParams = DefaultGunshiParams>(args: string[], entry: Command<G> | CommandRunner<G> | LazyCommand<G>, options?: CliOptions<G>): Promise<string | undefined>;
|
|
1963
|
+
/**
|
|
1964
|
+
* Run the command, without the built-in plugins: `--help` and `--version` print nothing, unless you add the plugins.
|
|
1965
|
+
* To have them, use `cli` from `gunshi`.
|
|
1966
|
+
*
|
|
1967
|
+
* This overload takes a command of another copy of the types of gunshi, such as a command of `@gunshi/definition`,
|
|
1968
|
+
* whose types the overloads above cannot compare. `@gunshi/bone` exports no `define`, so a CLI on it defines its
|
|
1969
|
+
* commands with another package. Its arguments are checked as `Args`, and its runner returns what a runner returns. It
|
|
1970
|
+
* must be the last of the overloads.
|
|
1971
|
+
*
|
|
1972
|
+
* @param args - Command line arguments
|
|
1973
|
+
* @param entry - A command-like object (command, command runner, or lazy command)
|
|
1974
|
+
* @param options - A {@link CliOptions | CLI options}
|
|
1975
|
+
* @returns A rendered usage or undefined. if you will use {@linkcode CliOptions.usageSilent} option, it will return rendered usage string.
|
|
1976
|
+
*/
|
|
1977
|
+
export declare function cli(args: string[], entry: EntryCommandable, options?: CliOptions): Promise<string | undefined>;
|
|
1877
1978
|
export type { ArgSchema, ArgToken, ArgValues, Args, Awaitable, CliOptions, Command, CommandCallMode, CommandContext, CommandContextCore, CommandContextExtension, CommandDecorator, CommandEnvironment, CommandExamplesFetcher, CommandLoader, CommandRunner, CommandRunnerResult, Commandable, DefaultGunshiParams, ExtendContext, ExtractArgExplicitlyProvided, ExtractArgs, ExtractExtensions, GunshiParams, GunshiParamsConstraint, HasJsonArgs, JsonResult, LazyCommand, MergeGunshiExtensions, NormalizeToGunshiParams, Prettify, RendererDecorator, RenderingOptions, SubCommandable, ValidationErrorsDecorator };
|
package/lib/index.js
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
// ../../node_modules/.pnpm/args-tokens@1.
|
|
1
|
+
// ../../node_modules/.pnpm/args-tokens@1.3.0/node_modules/args-tokens/lib/parser.js
|
|
2
2
|
/**
|
|
3
3
|
* forked from `nodejs/node` (`pkgjs/parseargs`)
|
|
4
4
|
* repository url: https://github.com/nodejs/node (https://github.com/pkgjs/parseargs)
|
|
@@ -200,7 +200,7 @@ function isLongOptionAndValue(arg) {
|
|
|
200
200
|
function hasLongOptionPrefix(arg) {
|
|
201
201
|
return arg.startsWith(LONG_OPTION_PREFIX) && arg.length > 2;
|
|
202
202
|
}
|
|
203
|
-
// ../../node_modules/.pnpm/args-tokens@1.
|
|
203
|
+
// ../../node_modules/.pnpm/args-tokens@1.3.0/node_modules/args-tokens/lib/utils.js
|
|
204
204
|
/**
|
|
205
205
|
* Entry point of utils.
|
|
206
206
|
*
|
|
@@ -230,7 +230,7 @@ function kebabnize(str) {
|
|
|
230
230
|
function formatChoices(choices) {
|
|
231
231
|
return choices.map((value) => JSON.stringify(value)).join(", ");
|
|
232
232
|
}
|
|
233
|
-
// ../../node_modules/.pnpm/args-tokens@1.
|
|
233
|
+
// ../../node_modules/.pnpm/args-tokens@1.3.0/node_modules/args-tokens/lib/resolver-DWmHKGSL.js
|
|
234
234
|
/**
|
|
235
235
|
* Internal definitions shared by the modules of `args-tokens`.
|
|
236
236
|
*
|
|
@@ -266,6 +266,11 @@ const PURE_PARSE = Symbol.for("args-tokens.pureParse");
|
|
|
266
266
|
* Each code identifies a validation failure category and is also suitable as an
|
|
267
267
|
* i18n resource key for localized rendering.
|
|
268
268
|
*
|
|
269
|
+
* A value that breaks a constraint of the options of a combinator is reported with a code of its
|
|
270
|
+
* own: `tooSmall` and `tooLarge` for `min` and `max` of `number()`, `integer()` and `float()`,
|
|
271
|
+
* `tooShort` and `tooLong` for `minLength` and `maxLength` of `string()`, and `patternMismatch` for
|
|
272
|
+
* its `pattern`. What a `parse` function of your own throws is reported as `customParse`.
|
|
273
|
+
*
|
|
269
274
|
* {@link resolveArgs} and `parse()` do not report `unknownOption` or `unexpectedPositional`: a caller
|
|
270
275
|
* that knows what a command takes, such as a CLI framework, reports them. An option that is not in the
|
|
271
276
|
* schema takes the argument after it as its value, unless that argument is an option, and the value
|
|
@@ -283,7 +288,12 @@ const ArgsValidationErrorKeys = {
|
|
|
283
288
|
missingValue: "err:arg:missing-value",
|
|
284
289
|
conflict: "err:arg:conflict",
|
|
285
290
|
invalidDefault: "err:arg:invalid-default",
|
|
286
|
-
unexpectedPositional: "err:arg:unexpected-positional"
|
|
291
|
+
unexpectedPositional: "err:arg:unexpected-positional",
|
|
292
|
+
tooSmall: "err:arg:too-small",
|
|
293
|
+
tooLarge: "err:arg:too-large",
|
|
294
|
+
tooShort: "err:arg:too-short",
|
|
295
|
+
tooLong: "err:arg:too-long",
|
|
296
|
+
patternMismatch: "err:arg:pattern-mismatch"
|
|
287
297
|
};
|
|
288
298
|
/**
|
|
289
299
|
* Brand that marks {@link ArgsValidationError} instances.
|
|
@@ -1144,7 +1154,7 @@ function checkConflicts(args, explicit, toKebab, actualInputNames) {
|
|
|
1144
1154
|
}
|
|
1145
1155
|
return [];
|
|
1146
1156
|
}
|
|
1147
|
-
// ../../node_modules/.pnpm/args-tokens@1.
|
|
1157
|
+
// ../../node_modules/.pnpm/args-tokens@1.3.0/node_modules/args-tokens/lib/index.js
|
|
1148
1158
|
/**
|
|
1149
1159
|
* @author kazuya kawaguchi (a.k.a. kazupon)
|
|
1150
1160
|
* @license MIT
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@gunshi/bone",
|
|
3
|
-
"version": "1.0.0-rc.
|
|
3
|
+
"version": "1.0.0-rc.9",
|
|
4
4
|
"description": "gunshi minimum",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"cli",
|
|
@@ -48,10 +48,10 @@
|
|
|
48
48
|
"access": "public"
|
|
49
49
|
},
|
|
50
50
|
"devDependencies": {
|
|
51
|
-
"@gunshi/definition": "1.0.0-rc.
|
|
52
|
-
"@gunshi/plugin-global": "1.0.0-rc.
|
|
53
|
-
"@gunshi/plugin-renderer": "1.0.0-rc.
|
|
54
|
-
"gunshi": "1.0.0-rc.
|
|
51
|
+
"@gunshi/definition": "1.0.0-rc.9",
|
|
52
|
+
"@gunshi/plugin-global": "1.0.0-rc.9",
|
|
53
|
+
"@gunshi/plugin-renderer": "1.0.0-rc.9",
|
|
54
|
+
"gunshi": "1.0.0-rc.9",
|
|
55
55
|
"publint": "^0.3.20"
|
|
56
56
|
},
|
|
57
57
|
"engines": {
|