@gunshi/bone 1.0.0-rc.6 → 1.0.0-rc.7

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.
Files changed (3) hide show
  1. package/lib/index.d.ts +190 -32
  2. package/lib/index.js +446 -244
  3. package/package.json +32 -33
package/lib/index.js CHANGED
@@ -1,4 +1,4 @@
1
- //#region ../../node_modules/.pnpm/args-tokens@1.0.2/node_modules/args-tokens/lib/parser.js
1
+ // ../../node_modules/.pnpm/args-tokens@1.2.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,8 +200,7 @@ function isLongOptionAndValue(arg) {
200
200
  function hasLongOptionPrefix(arg) {
201
201
  return arg.startsWith(LONG_OPTION_PREFIX) && arg.length > 2;
202
202
  }
203
- //#endregion
204
- //#region ../../node_modules/.pnpm/args-tokens@1.0.2/node_modules/args-tokens/lib/utils.js
203
+ // ../../node_modules/.pnpm/args-tokens@1.2.0/node_modules/args-tokens/lib/utils.js
205
204
  /**
206
205
  * Entry point of utils.
207
206
  *
@@ -231,8 +230,7 @@ function kebabnize(str) {
231
230
  function formatChoices(choices) {
232
231
  return choices.map((value) => JSON.stringify(value)).join(", ");
233
232
  }
234
- //#endregion
235
- //#region ../../node_modules/.pnpm/args-tokens@1.0.2/node_modules/args-tokens/lib/resolver-Cx5Pw6-S.js
233
+ // ../../node_modules/.pnpm/args-tokens@1.2.0/node_modules/args-tokens/lib/resolver-DT0CiD5Y.js
236
234
  /**
237
235
  * Internal definitions shared by the modules of `args-tokens`.
238
236
  *
@@ -268,9 +266,11 @@ const PURE_PARSE = Symbol.for("args-tokens.pureParse");
268
266
  * Each code identifies a validation failure category and is also suitable as an
269
267
  * i18n resource key for localized rendering.
270
268
  *
271
- * {@link resolveArgs} and `parse()` do not report `unknownOption`. An option that is not in the
269
+ * {@link resolveArgs} and `parse()` do not report `unknownOption` or `unexpectedPositional`: a caller
270
+ * that knows what a command takes, such as a CLI framework, reports them. An option that is not in the
272
271
  * schema takes the argument after it as its value, unless that argument is an option, and the value
273
- * is dropped: with no `foo` in the schema, `--foo bar` gives no positional argument.
272
+ * is dropped: with no `foo` in the schema, `--foo bar` gives no positional argument. A positional
273
+ * argument that the schema does not take stays in `positionals`, as the other positional arguments do.
274
274
  */
275
275
  const ArgsValidationErrorKeys = {
276
276
  requiredOption: "err:arg:required-option",
@@ -282,7 +282,8 @@ const ArgsValidationErrorKeys = {
282
282
  unexpectedValue: "err:arg:unexpected-value",
283
283
  missingValue: "err:arg:missing-value",
284
284
  conflict: "err:arg:conflict",
285
- invalidDefault: "err:arg:invalid-default"
285
+ invalidDefault: "err:arg:invalid-default",
286
+ unexpectedPositional: "err:arg:unexpected-positional"
286
287
  };
287
288
  /**
288
289
  * Brand that marks {@link ArgsValidationError} instances.
@@ -1143,8 +1144,7 @@ function checkConflicts(args, explicit, toKebab, actualInputNames) {
1143
1144
  }
1144
1145
  return [];
1145
1146
  }
1146
- //#endregion
1147
- //#region ../../node_modules/.pnpm/args-tokens@1.0.2/node_modules/args-tokens/lib/index.js
1147
+ // ../../node_modules/.pnpm/args-tokens@1.2.0/node_modules/args-tokens/lib/index.js
1148
1148
  /**
1149
1149
  * @author kazuya kawaguchi (a.k.a. kazupon)
1150
1150
  * @license MIT
@@ -1153,8 +1153,7 @@ function checkConflicts(args, explicit, toKebab, actualInputNames) {
1153
1153
  * @author kazuya kawaguchi (a.k.a. kazupon)
1154
1154
  * @license MIT
1155
1155
  */
1156
- //#endregion
1157
- //#region ../gunshi/src/constants.ts
1156
+ // ../gunshi/src/constants.ts
1158
1157
  /**
1159
1158
  * @author kazuya kawaguchi (a.k.a. kazupon)
1160
1159
  * @license MIT
@@ -1176,14 +1175,215 @@ const CLI_OPTIONS_DEFAULT = {
1176
1175
  usageOptionType: false,
1177
1176
  usageOptionValue: true,
1178
1177
  strict: false,
1178
+ strictPositionals: false,
1179
+ helpHint: true,
1180
+ validationErrorExitCode: 1,
1179
1181
  renderHeader: void 0,
1180
1182
  renderUsage: void 0,
1181
1183
  renderValidationErrors: void 0,
1182
1184
  plugins: void 0,
1183
1185
  fallbackToEntry: false
1184
1186
  };
1185
- //#endregion
1186
- //#region ../gunshi/src/utils.ts
1187
+ // ../gunshi/src/error.ts
1188
+ /**
1189
+ * @author kazuya kawaguchi (a.k.a. kazupon)
1190
+ * @license MIT
1191
+ */
1192
+ /**
1193
+ * Command not found error resource keys.
1194
+ */
1195
+ const CommandNotFoundErrorKeys = { notFound: "err:cmd:not-found" };
1196
+ /**
1197
+ * Command resolution error resource keys.
1198
+ *
1199
+ * These errors describe an ambiguity or inconsistency while choosing a command from arguments.
1200
+ * They are kept separate from {@link CommandNotFoundError} so consumers can distinguish a typo
1201
+ * from an input whose command interpretation is not unique.
1202
+ */
1203
+ const CommandResolutionErrorKeys = {
1204
+ ambiguous: "err:cmd:ambiguous",
1205
+ inconsistentOptions: "err:cmd:inconsistent-options",
1206
+ lazySchemaMismatch: "err:cmd:lazy-schema-mismatch"
1207
+ };
1208
+ /**
1209
+ * Brand that marks {@link CommandNotFoundError} instances.
1210
+ *
1211
+ * The brand is looked up in the global symbol registry with `Symbol.for`, so it stays
1212
+ * identical across bundled copies of gunshi (`gunshi`, `@gunshi/plugin`, `@gunshi/bone`)
1213
+ * and across realms. It lets {@link isCommandNotFoundError} recognize errors created by
1214
+ * another copy, where `instanceof` cannot match.
1215
+ */
1216
+ const COMMAND_NOT_FOUND_ERROR_BRAND = Symbol.for("gunshi.CommandNotFoundError");
1217
+ const COMMAND_RESOLUTION_ERROR_BRAND = Symbol.for("gunshi.CommandResolutionError");
1218
+ /**
1219
+ * Error raised when a command cannot be resolved.
1220
+ *
1221
+ * Each instance carries a non-enumerable brand keyed by
1222
+ * `Symbol.for('gunshi.CommandNotFoundError')`, so that {@link isCommandNotFoundError}
1223
+ * recognizes it even when it was created by another bundled copy of gunshi.
1224
+ */
1225
+ var CommandNotFoundError = class extends Error {
1226
+ code;
1227
+ values;
1228
+ commandName;
1229
+ candidates;
1230
+ commandPath;
1231
+ /**
1232
+ * Create a command-not-found error.
1233
+ *
1234
+ * @param message - Fallback error message
1235
+ * @param options - Command-not-found metadata
1236
+ */
1237
+ constructor(message, options) {
1238
+ super(message, { cause: options.cause });
1239
+ this.name = "CommandNotFoundError";
1240
+ this.code = options.code;
1241
+ this.values = options.values || {};
1242
+ this.commandName = options.commandName;
1243
+ this.candidates = options.candidates || [];
1244
+ this.commandPath = options.commandPath || [];
1245
+ Object.defineProperty(this, COMMAND_NOT_FOUND_ERROR_BRAND, {
1246
+ value: true,
1247
+ enumerable: false,
1248
+ writable: false,
1249
+ configurable: false
1250
+ });
1251
+ }
1252
+ };
1253
+ /**
1254
+ * Error raised when command routing cannot produce one consistent command.
1255
+ *
1256
+ * The own registry brand is the cross-bundle contract. Unlike the legacy command-not-found
1257
+ * guard, the new guard deliberately has no name-based fallback because this error type is new and
1258
+ * must not classify arbitrary errors from older versions.
1259
+ */
1260
+ var CommandResolutionError = class extends Error {
1261
+ code;
1262
+ values;
1263
+ commandPath;
1264
+ candidatePaths;
1265
+ /**
1266
+ * Create a command resolution error with structured routing metadata.
1267
+ *
1268
+ * @param message - Human-readable fallback message
1269
+ * @param options - Error code and command-routing metadata
1270
+ */
1271
+ constructor(message, options = {}) {
1272
+ super(message, { cause: options.cause });
1273
+ this.name = "CommandResolutionError";
1274
+ this.code = options.code;
1275
+ this.values = options.values || {};
1276
+ this.commandPath = options.commandPath || [];
1277
+ this.candidatePaths = options.candidatePaths || [];
1278
+ Object.defineProperty(this, COMMAND_RESOLUTION_ERROR_BRAND, {
1279
+ value: true,
1280
+ enumerable: false,
1281
+ writable: false,
1282
+ configurable: false
1283
+ });
1284
+ }
1285
+ };
1286
+ /**
1287
+ * Check whether an error is a {@link CommandNotFoundError}.
1288
+ *
1289
+ * `instanceof` alone is not enough: `@gunshi/plugin` is bundled with its own copy of this
1290
+ * class (`noExternal: ['gunshi/plugin']`), so an error thrown by `gunshi` is never an instance
1291
+ * of the class a plugin imports. Errors from another copy are recognized through the
1292
+ * `Symbol.for('gunshi.CommandNotFoundError')` brand, which does not depend on `error.name`.
1293
+ *
1294
+ * @param error - An unknown error
1295
+ * @returns `true` if the error is a {@link CommandNotFoundError}
1296
+ */
1297
+ function isCommandNotFoundError(error) {
1298
+ if (error instanceof CommandNotFoundError) return true;
1299
+ if (!isRecord(error) || !hasCommandNotFoundErrorShape(error)) return false;
1300
+ if (Object.hasOwn(error, COMMAND_NOT_FOUND_ERROR_BRAND) && error[COMMAND_NOT_FOUND_ERROR_BRAND] === true) return true;
1301
+ return error instanceof Error && error.name === "CommandNotFoundError";
1302
+ }
1303
+ /**
1304
+ * Check whether an error is a {@link CommandResolutionError}.
1305
+ *
1306
+ * @param error - An unknown error
1307
+ * @returns `true` when the error has the command-resolution brand and shape
1308
+ */
1309
+ function isCommandResolutionError(error) {
1310
+ if (error instanceof CommandResolutionError) return true;
1311
+ if (!isRecord(error) || !hasCommandResolutionErrorShape(error)) return false;
1312
+ return Object.hasOwn(error, COMMAND_RESOLUTION_ERROR_BRAND) && error[COMMAND_RESOLUTION_ERROR_BRAND] === true;
1313
+ }
1314
+ /**
1315
+ * Check whether an error is an {@link ArgsValidationError}.
1316
+ *
1317
+ * Prefer this over the `args-tokens` guard of the same name. Both recognize errors from another
1318
+ * bundled copy through the `Symbol.for('args-tokens.ArgsValidationError')` brand that
1319
+ * `args-tokens` 0.29.0 or later sets, including subclasses such as `ArgResolveError` that
1320
+ * override `name` with the argument name. This guard additionally:
1321
+ *
1322
+ * - recognizes direct `ArgsValidationError` instances from copies bundling `args-tokens`
1323
+ * older than 0.29.0, which do not set the brand
1324
+ * - checks that `code` and `values` of an error from another copy have the expected types
1325
+ *
1326
+ * The guard narrows only to {@link ArgsValidationError}: across copies,
1327
+ * `instanceof ArgResolveError` still fails, so do not rely on `type` or `schema` for such errors.
1328
+ *
1329
+ * @param error - An unknown error
1330
+ * @returns `true` if the error is an {@link ArgsValidationError}
1331
+ */
1332
+ function isArgsValidationError(error) {
1333
+ if (error instanceof ArgsValidationError) return true;
1334
+ if (!isRecord(error) || !hasArgsValidationErrorShape(error)) return false;
1335
+ if (isArgsValidationError$1(error)) return true;
1336
+ return error instanceof Error && error.name === "ArgsValidationError";
1337
+ }
1338
+ function isRecord(value) {
1339
+ return typeof value === "object" && value !== null;
1340
+ }
1341
+ function isStringArray(value) {
1342
+ return Array.isArray(value) && value.every((item) => typeof item === "string");
1343
+ }
1344
+ /**
1345
+ * Check whether `code` is an own or inherited property that is a string or `undefined`.
1346
+ *
1347
+ * Constructors always assign `code`, even when the option is omitted.
1348
+ *
1349
+ * @param error - An error from another copy
1350
+ * @returns `true` if `code` has the expected type
1351
+ */
1352
+ function hasOptionalStringCode(error) {
1353
+ return "code" in error && (error.code === void 0 || typeof error.code === "string");
1354
+ }
1355
+ function hasCommandNotFoundErrorShape(error) {
1356
+ return hasOptionalStringCode(error) && isRecord(error.values) && typeof error.commandName === "string" && isStringArray(error.candidates) && isStringArray(error.commandPath);
1357
+ }
1358
+ function hasCommandResolutionErrorShape(error) {
1359
+ return hasOptionalStringCode(error) && isRecord(error.values) && isStringArray(error.commandPath) && Array.isArray(error.candidatePaths) && error.candidatePaths.every((path) => isStringArray(path));
1360
+ }
1361
+ function hasArgsValidationErrorShape(error) {
1362
+ return hasOptionalStringCode(error) && isRecord(error.values);
1363
+ }
1364
+ /**
1365
+ * Check whether a value is an exit code of a failure: an integer from 1 to 255.
1366
+ *
1367
+ * @param value - The value to check
1368
+ * @returns `true` if the value is an exit code of a failure
1369
+ */
1370
+ function isFailureExitCode(value) {
1371
+ return Number.isInteger(value) && value >= 1 && value <= 255;
1372
+ }
1373
+ /**
1374
+ * Check whether validation errors must stop the command before it runs: an unknown command, a command
1375
+ * line that cannot be resolved, an unknown option of `strict`, or a positional argument that the command
1376
+ * does not take, of `strictPositionals`. The global options plugin reports them before `--help` and
1377
+ * `--version`, except an unknown option and a positional argument that the command does not take:
1378
+ * `--help` and `--version` are answered before them, as they are before the other validation errors.
1379
+ *
1380
+ * @param error - An aggregate validation error
1381
+ * @returns `true` if the validation error must be handled with priority
1382
+ */
1383
+ function hasPriorityValidationError(error) {
1384
+ return error?.errors.some((error) => isCommandNotFoundError(error) || isCommandResolutionError(error) || isArgsValidationError(error) && (error.code === ArgsValidationErrorKeys.unknownOption || error.code === ArgsValidationErrorKeys.unexpectedPositional)) ?? false;
1385
+ }
1386
+ // ../gunshi/src/utils.ts
1187
1387
  /**
1188
1388
  * @author kazuya kawaguchi (a.k.a. kazupon)
1189
1389
  * @license MIT
@@ -1250,6 +1450,8 @@ function isLazyCommand(cmd) {
1250
1450
  *
1251
1451
  * If the loader returns a command, the properties of the loaded command take precedence,
1252
1452
  * and the properties that it does not define fall back to the definition that is given to `lazy`.
1453
+ * `run` comes from the loader only, as the definition has none. A loaded command without `run` is resolved
1454
+ * without it, as any command without `run`, which the CLI fails with when it runs, unless it has sub-commands.
1253
1455
  *
1254
1456
  * @param cmd - A {@link Commandable} or {@link LazyCommand} to resolve
1255
1457
  * @param name - Optional name of the command, if not provided, it will use the name from the command itself.
@@ -1265,6 +1467,8 @@ async function resolveLazyCommand(cmd, name, needRunResolving = false) {
1265
1467
  args: cmd.args,
1266
1468
  examples: cmd.examples,
1267
1469
  internal: cmd.internal,
1470
+ aliases: cmd.aliases,
1471
+ deprecated: cmd.deprecated,
1268
1472
  entry: cmd.entry,
1269
1473
  toKebab: cmd.toKebab,
1270
1474
  rendering: cmd.rendering,
@@ -1273,14 +1477,20 @@ async function resolveLazyCommand(cmd, name, needRunResolving = false) {
1273
1477
  if ("resource" in cmd && cmd.resource) baseCommand.resource = cmd.resource;
1274
1478
  command = Object.assign(create(), baseCommand);
1275
1479
  if (needRunResolving) {
1480
+ /**
1481
+ * NOTE(kazupon): the error names the command, by its `commandName` or the name that it is given with.
1482
+ * The lazy command is the loader function, so its `name` is the name of the function, such as
1483
+ * `buildLoader` of a loader in a const.
1484
+ */
1485
+ const commandName = cmd.commandName || name || "(anonymous)";
1276
1486
  const loaded = await cmd();
1277
1487
  if (typeof loaded === "function") command.run = loaded;
1278
- else if (typeof loaded === "object") {
1279
- if (loaded.run == null) throw new TypeError(`'run' is required in command: ${cmd.name || name}`);
1488
+ else if (typeof loaded === "object" && loaded !== null) {
1280
1489
  /**
1281
1490
  * NOTE(kazupon): the loaded command wins, and the definition that is given to `lazy` is the fallback
1282
1491
  * for what the loaded command does not define. A loader that returns `{ run }` keeps the whole definition,
1283
- * like a loader that returns the runner itself.
1492
+ * like a loader that returns the runner itself. A loaded command without `run` is a command without `run`
1493
+ * (#885): the CLI fails with it where it would run, as with any other, or prints the usage of a group.
1284
1494
  */
1285
1495
  command.run = loaded.run;
1286
1496
  command.name = loaded.name ?? cmd.commandName;
@@ -1288,12 +1498,19 @@ async function resolveLazyCommand(cmd, name, needRunResolving = false) {
1288
1498
  command.args = loaded.args ?? cmd.args;
1289
1499
  command.examples = loaded.examples ?? cmd.examples;
1290
1500
  command.internal = loaded.internal ?? cmd.internal;
1501
+ command.aliases = loaded.aliases ?? cmd.aliases;
1502
+ command.deprecated = loaded.deprecated ?? cmd.deprecated;
1291
1503
  command.entry = loaded.entry ?? cmd.entry;
1292
1504
  command.toKebab = loaded.toKebab ?? cmd.toKebab;
1293
1505
  command.rendering = loaded.rendering ?? cmd.rendering;
1294
1506
  command.subCommands = loaded.subCommands || cmd.subCommands;
1295
1507
  if ("resource" in loaded && loaded.resource) command.resource = loaded.resource;
1296
- } else throw new TypeError(`Cannot resolve command: ${cmd.name || name}`);
1508
+ } else
1509
+ /**
1510
+ * NOTE(kazupon): `null` comes here too, though `typeof null` is `'object'` (#883): a loader may return it
1511
+ * for a module that is not found, and it is neither a command nor a runner, as `undefined` is not.
1512
+ */
1513
+ throw new TypeError(`Cannot resolve command: ${commandName}`);
1297
1514
  }
1298
1515
  } else command = Object.assign(create(), cmd);
1299
1516
  if (command.name == null && name) command.name = name;
@@ -1364,8 +1581,7 @@ function deepFreeze(obj, ignores = []) {
1364
1581
  }
1365
1582
  return Object.freeze(obj);
1366
1583
  }
1367
- //#endregion
1368
- //#region ../gunshi/src/context.ts
1584
+ // ../gunshi/src/context.ts
1369
1585
  /**
1370
1586
  * The entry for gunshi context.
1371
1587
  * This module is exported for the purpose of testing the command.
@@ -1400,6 +1616,11 @@ async function createCommandContext({ args = {}, explicit = {}, values = {}, pos
1400
1616
  */
1401
1617
  const env = Object.assign(create(), CLI_OPTIONS_DEFAULT, cliOptions);
1402
1618
  /**
1619
+ * NOTE(kazupon): the exit code of the validation errors is an exit code of a failure, as the `exitCode`
1620
+ * of a `CommandError` is: any other value is replaced with `1`.
1621
+ */
1622
+ if (!isFailureExitCode(env.validationErrorExitCode)) env.validationErrorExitCode = 1;
1623
+ /**
1403
1624
  * apply Command definition's rendering option with highest priority
1404
1625
  */
1405
1626
  if (command.rendering) {
@@ -1460,8 +1681,7 @@ function getCommandName(cmd) {
1460
1681
  else if (typeof cmd === "object") return cmd.name || "(anonymous)";
1461
1682
  else return ANONYMOUS_COMMAND_NAME;
1462
1683
  }
1463
- //#endregion
1464
- //#region ../gunshi/src/decorators.ts
1684
+ // ../gunshi/src/decorators.ts
1465
1685
  /**
1466
1686
  * @author kazuya kawaguchi (a.k.a. kazupon)
1467
1687
  * @license MIT
@@ -1528,195 +1748,7 @@ function createDecorators() {
1528
1748
  }
1529
1749
  });
1530
1750
  }
1531
- //#endregion
1532
- //#region ../gunshi/src/error.ts
1533
- /**
1534
- * @author kazuya kawaguchi (a.k.a. kazupon)
1535
- * @license MIT
1536
- */
1537
- /**
1538
- * Command not found error resource keys.
1539
- */
1540
- const CommandNotFoundErrorKeys = { notFound: "err:cmd:not-found" };
1541
- /**
1542
- * Command resolution error resource keys.
1543
- *
1544
- * These errors describe an ambiguity or inconsistency while choosing a command from arguments.
1545
- * They are kept separate from {@link CommandNotFoundError} so consumers can distinguish a typo
1546
- * from an input whose command interpretation is not unique.
1547
- */
1548
- const CommandResolutionErrorKeys = {
1549
- ambiguous: "err:cmd:ambiguous",
1550
- inconsistentOptions: "err:cmd:inconsistent-options",
1551
- lazySchemaMismatch: "err:cmd:lazy-schema-mismatch"
1552
- };
1553
- /**
1554
- * Brand that marks {@link CommandNotFoundError} instances.
1555
- *
1556
- * The brand is looked up in the global symbol registry with `Symbol.for`, so it stays
1557
- * identical across bundled copies of gunshi (`gunshi`, `@gunshi/plugin`, `@gunshi/bone`)
1558
- * and across realms. It lets {@link isCommandNotFoundError} recognize errors created by
1559
- * another copy, where `instanceof` cannot match.
1560
- */
1561
- const COMMAND_NOT_FOUND_ERROR_BRAND = Symbol.for("gunshi.CommandNotFoundError");
1562
- const COMMAND_RESOLUTION_ERROR_BRAND = Symbol.for("gunshi.CommandResolutionError");
1563
- /**
1564
- * Error raised when a command cannot be resolved.
1565
- *
1566
- * Each instance carries a non-enumerable brand keyed by
1567
- * `Symbol.for('gunshi.CommandNotFoundError')`, so that {@link isCommandNotFoundError}
1568
- * recognizes it even when it was created by another bundled copy of gunshi.
1569
- */
1570
- var CommandNotFoundError = class extends Error {
1571
- code;
1572
- values;
1573
- commandName;
1574
- candidates;
1575
- commandPath;
1576
- /**
1577
- * Create a command-not-found error.
1578
- *
1579
- * @param message - Fallback error message
1580
- * @param options - Command-not-found metadata
1581
- */
1582
- constructor(message, options) {
1583
- super(message, { cause: options.cause });
1584
- this.name = "CommandNotFoundError";
1585
- this.code = options.code;
1586
- this.values = options.values || {};
1587
- this.commandName = options.commandName;
1588
- this.candidates = options.candidates || [];
1589
- this.commandPath = options.commandPath || [];
1590
- Object.defineProperty(this, COMMAND_NOT_FOUND_ERROR_BRAND, {
1591
- value: true,
1592
- enumerable: false,
1593
- writable: false,
1594
- configurable: false
1595
- });
1596
- }
1597
- };
1598
- /**
1599
- * Error raised when command routing cannot produce one consistent command.
1600
- *
1601
- * The own registry brand is the cross-bundle contract. Unlike the legacy command-not-found
1602
- * guard, the new guard deliberately has no name-based fallback because this error type is new and
1603
- * must not classify arbitrary errors from older versions.
1604
- */
1605
- var CommandResolutionError = class extends Error {
1606
- code;
1607
- values;
1608
- commandPath;
1609
- candidatePaths;
1610
- /**
1611
- * Create a command resolution error with structured routing metadata.
1612
- *
1613
- * @param message - Human-readable fallback message
1614
- * @param options - Error code and command-routing metadata
1615
- */
1616
- constructor(message, options = {}) {
1617
- super(message, { cause: options.cause });
1618
- this.name = "CommandResolutionError";
1619
- this.code = options.code;
1620
- this.values = options.values || {};
1621
- this.commandPath = options.commandPath || [];
1622
- this.candidatePaths = options.candidatePaths || [];
1623
- Object.defineProperty(this, COMMAND_RESOLUTION_ERROR_BRAND, {
1624
- value: true,
1625
- enumerable: false,
1626
- writable: false,
1627
- configurable: false
1628
- });
1629
- }
1630
- };
1631
- /**
1632
- * Check whether an error is a {@link CommandNotFoundError}.
1633
- *
1634
- * `instanceof` alone is not enough: `@gunshi/plugin` is bundled with its own copy of this
1635
- * class (`noExternal: ['gunshi/plugin']`), so an error thrown by `gunshi` is never an instance
1636
- * of the class a plugin imports. Errors from another copy are recognized through the
1637
- * `Symbol.for('gunshi.CommandNotFoundError')` brand, which does not depend on `error.name`.
1638
- *
1639
- * @param error - An unknown error
1640
- * @returns `true` if the error is a {@link CommandNotFoundError}
1641
- */
1642
- function isCommandNotFoundError(error) {
1643
- if (error instanceof CommandNotFoundError) return true;
1644
- if (!isRecord(error) || !hasCommandNotFoundErrorShape(error)) return false;
1645
- if (Object.hasOwn(error, COMMAND_NOT_FOUND_ERROR_BRAND) && error[COMMAND_NOT_FOUND_ERROR_BRAND] === true) return true;
1646
- return error instanceof Error && error.name === "CommandNotFoundError";
1647
- }
1648
- /**
1649
- * Check whether an error is a {@link CommandResolutionError}.
1650
- *
1651
- * @param error - An unknown error
1652
- * @returns `true` when the error has the command-resolution brand and shape
1653
- */
1654
- function isCommandResolutionError(error) {
1655
- if (error instanceof CommandResolutionError) return true;
1656
- if (!isRecord(error) || !hasCommandResolutionErrorShape(error)) return false;
1657
- return Object.hasOwn(error, COMMAND_RESOLUTION_ERROR_BRAND) && error[COMMAND_RESOLUTION_ERROR_BRAND] === true;
1658
- }
1659
- /**
1660
- * Check whether an error is an {@link ArgsValidationError}.
1661
- *
1662
- * Prefer this over the `args-tokens` guard of the same name. Both recognize errors from another
1663
- * bundled copy through the `Symbol.for('args-tokens.ArgsValidationError')` brand that
1664
- * `args-tokens` 0.29.0 or later sets, including subclasses such as `ArgResolveError` that
1665
- * override `name` with the argument name. This guard additionally:
1666
- *
1667
- * - recognizes direct `ArgsValidationError` instances from copies bundling `args-tokens`
1668
- * older than 0.29.0, which do not set the brand
1669
- * - checks that `code` and `values` of an error from another copy have the expected types
1670
- *
1671
- * The guard narrows only to {@link ArgsValidationError}: across copies,
1672
- * `instanceof ArgResolveError` still fails, so do not rely on `type` or `schema` for such errors.
1673
- *
1674
- * @param error - An unknown error
1675
- * @returns `true` if the error is an {@link ArgsValidationError}
1676
- */
1677
- function isArgsValidationError(error) {
1678
- if (error instanceof ArgsValidationError) return true;
1679
- if (!isRecord(error) || !hasArgsValidationErrorShape(error)) return false;
1680
- if (isArgsValidationError$1(error)) return true;
1681
- return error instanceof Error && error.name === "ArgsValidationError";
1682
- }
1683
- function isRecord(value) {
1684
- return typeof value === "object" && value !== null;
1685
- }
1686
- function isStringArray(value) {
1687
- return Array.isArray(value) && value.every((item) => typeof item === "string");
1688
- }
1689
- /**
1690
- * Check whether `code` is an own or inherited property that is a string or `undefined`.
1691
- *
1692
- * Constructors always assign `code`, even when the option is omitted.
1693
- *
1694
- * @param error - An error from another copy
1695
- * @returns `true` if `code` has the expected type
1696
- */
1697
- function hasOptionalStringCode(error) {
1698
- return "code" in error && (error.code === void 0 || typeof error.code === "string");
1699
- }
1700
- function hasCommandNotFoundErrorShape(error) {
1701
- return hasOptionalStringCode(error) && isRecord(error.values) && typeof error.commandName === "string" && isStringArray(error.candidates) && isStringArray(error.commandPath);
1702
- }
1703
- function hasCommandResolutionErrorShape(error) {
1704
- return hasOptionalStringCode(error) && isRecord(error.values) && isStringArray(error.commandPath) && Array.isArray(error.candidatePaths) && error.candidatePaths.every((path) => isStringArray(path));
1705
- }
1706
- function hasArgsValidationErrorShape(error) {
1707
- return hasOptionalStringCode(error) && isRecord(error.values);
1708
- }
1709
- /**
1710
- * Check whether validation errors should be handled before version, help, or command execution.
1711
- *
1712
- * @param error - An aggregate validation error
1713
- * @returns `true` if the validation error must be handled with priority
1714
- */
1715
- function hasPriorityValidationError(error) {
1716
- return error?.errors.some((error) => isCommandNotFoundError(error) || isCommandResolutionError(error) || isArgsValidationError(error) && error.code === ArgsValidationErrorKeys.unknownOption) ?? false;
1717
- }
1718
- //#endregion
1719
- //#region ../gunshi/src/plugin/context.ts
1751
+ // ../gunshi/src/plugin/context.ts
1720
1752
  /**
1721
1753
  * @author kazuya kawaguchi (a.k.a. kazupon)
1722
1754
  * @license MIT
@@ -1799,8 +1831,7 @@ function createPluginContext(decorators, initialSubCommands) {
1799
1831
  function findGlobalOptionByShort(globalOptions, short) {
1800
1832
  for (const [name, schema] of globalOptions) if (schema.short === short) return name;
1801
1833
  }
1802
- //#endregion
1803
- //#region ../gunshi/src/plugin/dependency.ts
1834
+ // ../gunshi/src/plugin/dependency.ts
1804
1835
  /**
1805
1836
  * @author kazuya kawaguchi (a.k.a. kazupon)
1806
1837
  * @license MIT
@@ -1841,8 +1872,7 @@ function resolveDependencies(plugins) {
1841
1872
  for (const plugin of plugins) visit(plugin);
1842
1873
  return sorted;
1843
1874
  }
1844
- //#endregion
1845
- //#region ../gunshi/src/cli/args.ts
1875
+ // ../gunshi/src/cli/args.ts
1846
1876
  /**
1847
1877
  * @author kazuya kawaguchi (a.k.a. kazupon)
1848
1878
  * @license MIT
@@ -1882,8 +1912,7 @@ function resolveGlobalOptions(globalOptions, args) {
1882
1912
  } : schema;
1883
1913
  return resolved;
1884
1914
  }
1885
- //#endregion
1886
- //#region ../gunshi/src/cli/core.ts
1915
+ // ../gunshi/src/cli/core.ts
1887
1916
  /**
1888
1917
  * @author kazuya kawaguchi (a.k.a. kazupon)
1889
1918
  * @license MIT
@@ -1916,8 +1945,11 @@ async function cliCore(argv, entry, options, plugins, usageOnly = false) {
1916
1945
  * NOTE(kazupon): a CLI whose user declares no sub-commands has no command tree of its own,
1917
1946
  * so a positional argument must not become a command name just because a plugin added a command.
1918
1947
  * The user can still opt out with an explicit `fallbackToEntry: false`.
1948
+ * An entry command without `run` has nothing to run with the argument: the commands that the plugins
1949
+ * add are the commands of the CLI, so an argument that is not one of them is reported, as when the
1950
+ * user declares them (#874). A lazy entry command and a runner given to `cli()` have something to run.
1919
1951
  */
1920
- if (initialSubCommands.size === 0 && cliOptions.subCommands.size > 0 && options.fallbackToEntry === void 0) cliOptions.fallbackToEntry = true;
1952
+ if (initialSubCommands.size === 0 && cliOptions.subCommands.size > 0 && options.fallbackToEntry === void 0 && (typeof entry === "function" || entry.run != null)) cliOptions.fallbackToEntry = true;
1921
1953
  const tokens = parseArgs(argv);
1922
1954
  const selection = resolveCommandSelection(tokens, entry, cliOptions, pluginContext.globalOptions);
1923
1955
  const resolved = selection.context;
@@ -1943,8 +1975,24 @@ async function cliCore(argv, entry, options, plugins, usageOnly = false) {
1943
1975
  }
1944
1976
  const routingOptions = Object.assign(create(), cliOptions, { subCommands: new Map(cliOptions.subCommands) });
1945
1977
  if (targetLevelSubCommands) cliOptions.subCommands = targetLevelSubCommands;
1946
- const resolvedCommand = isLazyCommand(targetCommand) ? await resolveLazyCommand(targetCommand, targetCommandName, true) : targetCommand;
1947
- if (selection.error == null && isLazyCommand(targetCommand)) {
1978
+ /**
1979
+ * NOTE(kazupon): a lazy command is loaded before the arguments are parsed, so that the arguments of the
1980
+ * loaded command are used. An error of the loading, such as one that the loader throws, is thrown where the
1981
+ * command would run, after the decorators, as an error of `run` is (#885): the global options plugin prints a
1982
+ * `CommandError` with its exit code, and the failure as JSON with `--json`, and `onErrorCommand` sees it.
1983
+ * Until then, the definition given to `lazy` stands for the command, so that its arguments are parsed, and
1984
+ * `--help` prints its usage.
1985
+ */
1986
+ let resolvedCommand;
1987
+ let loadFailure;
1988
+ if (isLazyCommand(targetCommand)) try {
1989
+ resolvedCommand = await resolveLazyCommand(targetCommand, targetCommandName, true);
1990
+ } catch (error) {
1991
+ loadFailure = { error };
1992
+ resolvedCommand = await resolveLazyCommand(targetCommand, targetCommandName);
1993
+ }
1994
+ else resolvedCommand = targetCommand;
1995
+ if (selection.error == null && isLazyCommand(targetCommand) && loadFailure === void 0) {
1948
1996
  const loaded = resolveCommandTreeFromPositionals(getRoutingPositionals(tokens, pluginContext.globalOptions, resolvedCommand), entry, routingOptions);
1949
1997
  if (!sameCommandPath(loaded.commandPath, targetCommandPath)) additionalValidationErrors.push(createLazySchemaMismatchError(targetCommandPath, loaded.commandPath));
1950
1998
  }
@@ -1968,7 +2016,11 @@ async function cliCore(argv, entry, options, plugins, usageOnly = false) {
1968
2016
  toKebab: resolvedCommand.toKebab,
1969
2017
  skipPositional
1970
2018
  });
1971
- const validationError = mergeValidationErrors(error, [...additionalValidationErrors, ...cliOptions.strict && !diagnostic ? createUnknownOptionErrors(findUnknownOptions(args, tokens, { toKebab: resolvedCommand.toKebab })) : []]);
2019
+ const validationError = mergeValidationErrors(error, [
2020
+ ...additionalValidationErrors,
2021
+ ...cliOptions.strict && !diagnostic ? createUnknownOptionErrors(findUnknownOptions(args, tokens, { toKebab: resolvedCommand.toKebab })) : [],
2022
+ ...cliOptions.strictPositionals && !diagnostic && additionalValidationErrors.length === 0 ? createUnexpectedPositionalErrors(findUnexpectedPositionals(args, positionals, skipPositional)) : []
2023
+ ]);
1972
2024
  const commandContext = await createCommandContext({
1973
2025
  args,
1974
2026
  explicit,
@@ -1985,9 +2037,25 @@ async function cliCore(argv, entry, options, plugins, usageOnly = false) {
1985
2037
  validationError,
1986
2038
  cliOptions
1987
2039
  });
2040
+ markDeprecatedCommands(commandContext, collectDeprecatedCommands(routingOptions.subCommands, targetCommandPath, resolvedCommand));
1988
2041
  const reported = trackReported(commandContext);
2042
+ let fallbackRunner = NOOP;
2043
+ if (loadFailure !== void 0) {
2044
+ const { error } = loadFailure;
2045
+ fallbackRunner = () => {
2046
+ throw error;
2047
+ };
2048
+ } else if (resolvedCommand.run == null) {
2049
+ markWithoutRun(commandContext);
2050
+ if (!(targetDepth === 0 ? routingOptions.subCommands.size > 0 : (getCommandSubCommands(resolvedCommand)?.size ?? 0) > 0)) {
2051
+ const commandName = resolvedCommand.name || targetCommandName || "(anonymous)";
2052
+ fallbackRunner = () => {
2053
+ throw new TypeError(`'run' is required in command: ${commandName}`);
2054
+ };
2055
+ }
2056
+ }
1989
2057
  try {
1990
- return await executeCommand(resolvedCommand, commandContext, decorators.commandDecorators);
2058
+ return await executeCommand(resolvedCommand, commandContext, decorators.commandDecorators, fallbackRunner);
1991
2059
  } catch (error) {
1992
2060
  /**
1993
2061
  * NOTE(kazupon): a plugin that has reported the validation errors to the user marks them, as the
@@ -2021,6 +2089,87 @@ function trackReported(ctx) {
2021
2089
  return reported;
2022
2090
  }
2023
2091
  /**
2092
+ * The key of the registry of the command contexts whose command has no `run`. The global options plugin
2093
+ * and the usage renderer plugin read it with `isWithoutRun` of `@gunshi/shared`, by the same registered
2094
+ * symbol, since `gunshi` and the plugins bundle their own copies. Neither is in the public API.
2095
+ */
2096
+ const WITHOUT_RUN = Symbol.for("gunshi.withoutRun");
2097
+ /**
2098
+ * Mark the command context of a run whose command has no `run`.
2099
+ *
2100
+ * NOTE(kazupon): the global options plugin prints the usage of a command that has sub-commands and no
2101
+ * `run`, when it runs without a sub-command, as `--help` does. The plugin cannot tell it from the context,
2102
+ * nor from the runner that it decorates, which the core always wraps, so the core tells it. The command
2103
+ * is checked once it is loaded, so a lazy command whose loader returns a command without `run` is marked
2104
+ * too. The registry is weak, and holds the context of this run only: a nested `cli()` in a hook has a
2105
+ * context of its own.
2106
+ *
2107
+ * @param ctx - The command context of the run
2108
+ */
2109
+ function markWithoutRun(ctx) {
2110
+ const registry = globalThis;
2111
+ (registry[WITHOUT_RUN] ??= /* @__PURE__ */ new WeakSet()).add(ctx);
2112
+ }
2113
+ /**
2114
+ * The key of the registry of the deprecated commands on the path of a run. The global options plugin and the
2115
+ * usage renderer plugin read it with `getDeprecatedCommands` of `@gunshi/shared`, by the same registered
2116
+ * symbol, since `gunshi` and the plugins bundle their own copies. Neither is in the public API.
2117
+ */
2118
+ const DEPRECATED_COMMANDS = Symbol.for("gunshi.deprecatedCommands");
2119
+ /**
2120
+ * Check whether the `deprecated` of a command or an argument marks it as deprecated.
2121
+ *
2122
+ * @param deprecated - The `deprecated` of a command or an argument
2123
+ * @returns `true` for `true` or a text
2124
+ */
2125
+ function isDeprecated(deprecated) {
2126
+ return deprecated === true || typeof deprecated === "string";
2127
+ }
2128
+ /**
2129
+ * Collect the deprecated commands on the path of a run, root first.
2130
+ *
2131
+ * NOTE(kazupon): the command that runs is the loaded one, whose `deprecated` wins over the one of the definition
2132
+ * given to `lazy`. The commands above it are the definitions of the tree, as the routing found them. The entry
2133
+ * command is not on the path.
2134
+ *
2135
+ * @param root - The sub-commands at the top level
2136
+ * @param commandPath - The names of the commands on the path
2137
+ * @param resolvedCommand - The command that runs
2138
+ * @returns The deprecated commands, with their paths
2139
+ */
2140
+ function collectDeprecatedCommands(root, commandPath, resolvedCommand) {
2141
+ const marks = [];
2142
+ let level = root;
2143
+ for (const [index, name] of commandPath.entries()) {
2144
+ const last = index === commandPath.length - 1;
2145
+ const declared = level?.get(name);
2146
+ const command = last ? resolvedCommand : declared;
2147
+ if (command == null) break;
2148
+ if (isDeprecated(command.deprecated)) marks.push({
2149
+ commandPath: commandPath.slice(0, index + 1),
2150
+ deprecated: command.deprecated
2151
+ });
2152
+ level = declared == null ? void 0 : getCommandSubCommands(declared);
2153
+ }
2154
+ return marks;
2155
+ }
2156
+ /**
2157
+ * Mark the command context of a run with the deprecated commands on its path.
2158
+ *
2159
+ * NOTE(kazupon): the context has the command that runs, and not the commands above it, such as the old name of a
2160
+ * renamed group, so the core, which walks the path, tells the plugins which of them are deprecated. The global
2161
+ * options plugin warns of them, and the usage renderer plugin says so in the help. The registry is weak, and
2162
+ * holds the context of this run only.
2163
+ *
2164
+ * @param ctx - The command context of the run
2165
+ * @param marks - The deprecated commands on the path
2166
+ */
2167
+ function markDeprecatedCommands(ctx, marks) {
2168
+ if (marks.length === 0) return;
2169
+ const registry = globalThis;
2170
+ (registry[DEPRECATED_COMMANDS] ??= /* @__PURE__ */ new WeakMap()).set(ctx, marks);
2171
+ }
2172
+ /**
2024
2173
  * Create the decorator that renders the usage of the command instead of running it.
2025
2174
  *
2026
2175
  * NOTE(kazupon): `generate()` of `gunshi/generator` asks the core for a usage. It used to ask by
@@ -2108,14 +2257,16 @@ function findUnknownOptions(args, tokens, options) {
2108
2257
  knownLongOptions.add(optionName);
2109
2258
  /**
2110
2259
  * NOTE(kazupon): a hidden option is still accepted, so it stays a known option. It is left out
2111
- * of the candidates, which are what `@gunshi/plugin-suggestion` offers as "Did you mean".
2260
+ * of the candidates, which are what `@gunshi/plugin-suggestion` offers as "Did you mean". So is a
2261
+ * deprecated option, which the help leaves out too, and so is the negated form of either.
2112
2262
  */
2113
- if (!schema.hidden) addLongOptionCandidate(optionName);
2263
+ const offered = !schema.hidden && !isDeprecated(schema.deprecated);
2264
+ if (offered) addLongOptionCandidate(optionName);
2114
2265
  if (schema.short) knownShortOptions.add(schema.short);
2115
2266
  if (schema.type === "boolean" && schema.negatable) {
2116
2267
  const negatableOptionName = `${NEGATABLE_OPTION_PREFIX}${optionName}`;
2117
2268
  knownNegatableOptions.add(negatableOptionName);
2118
- if (!schema.hidden) addLongOptionCandidate(negatableOptionName);
2269
+ if (offered) addLongOptionCandidate(negatableOptionName);
2119
2270
  }
2120
2271
  }
2121
2272
  const unknownOptions = [];
@@ -2149,6 +2300,30 @@ function createUnknownOptionErrors(unknownOptions) {
2149
2300
  });
2150
2301
  });
2151
2302
  }
2303
+ /**
2304
+ * Find the positional arguments that the command does not take: the ones after its command path that its
2305
+ * positional arguments do not take. A positional argument with `multiple` takes all of them.
2306
+ *
2307
+ * NOTE(kazupon): args-tokens gives the positional arguments after the command path to the positional
2308
+ * arguments of the command in the order they are declared, so the declared ones take the first of them,
2309
+ * as many as they are, an optional one included, and the rest are left over.
2310
+ *
2311
+ * @param args - The arguments of the command
2312
+ * @param positionals - The positional arguments, the command path included
2313
+ * @param skipPositional - The index of the last command name in `positionals`
2314
+ * @returns The positional arguments that are left over
2315
+ */
2316
+ function findUnexpectedPositionals(args, positionals, skipPositional) {
2317
+ const declared = Object.values(args).filter((schema) => schema.type === "positional");
2318
+ if (declared.some((schema) => schema.multiple)) return [];
2319
+ return positionals.slice(skipPositional + 1 + declared.length);
2320
+ }
2321
+ function createUnexpectedPositionalErrors(positionals) {
2322
+ return positionals.map((rawName) => new ArgsValidationError(`Unexpected positional argument: ${rawName}`, {
2323
+ code: ArgsValidationErrorKeys.unexpectedPositional,
2324
+ values: { rawName }
2325
+ }));
2326
+ }
2152
2327
  function mergeValidationErrors(error, additionalErrors) {
2153
2328
  if (additionalErrors.length === 0) return error;
2154
2329
  return new AggregateError(error ? [...error.errors, ...additionalErrors] : additionalErrors, error?.message || additionalErrors[0]?.message);
@@ -2253,8 +2428,8 @@ function resolveCommandTreeFromPositionals(positionals, entry, options) {
2253
2428
  let depth = 0;
2254
2429
  for (let i = 0; i < positionals.length; i++) {
2255
2430
  const token = positionals[i];
2256
- const cmd = currentSubCommands.get(token);
2257
- if (cmd == null) {
2431
+ const found = findSubCommand(currentSubCommands, token);
2432
+ if (found == null) {
2258
2433
  if (depth === 0) {
2259
2434
  if (options.fallbackToEntry) return resolveAsEntry();
2260
2435
  const parent = resolveAsEntry();
@@ -2286,12 +2461,13 @@ function resolveCommandTreeFromPositionals(positionals, entry, options) {
2286
2461
  parentSubCommands: currentSubCommands
2287
2462
  };
2288
2463
  }
2464
+ const [key, cmd] = found;
2289
2465
  let resolved = cmd;
2290
- if (typeof cmd === "function" && cmd.commandName == null) resolved = Object.assign((...args) => cmd(...args), cmd, { commandName: token });
2291
- else if (typeof cmd === "object" && cmd.name == null) resolved = Object.assign(create(), cmd, { name: token });
2466
+ if (typeof cmd === "function" && cmd.commandName == null) resolved = Object.assign((...args) => cmd(...args), cmd, { commandName: key });
2467
+ else if (typeof cmd === "object" && cmd.name == null) resolved = Object.assign(create(), cmd, { name: key });
2292
2468
  resolvedCommand = resolved;
2293
- resolvedName = token;
2294
- commandPath.push(token);
2469
+ resolvedName = key;
2470
+ commandPath.push(key);
2295
2471
  depth++;
2296
2472
  const nestedSubCommands = getCommandSubCommands(cmd);
2297
2473
  if (nestedSubCommands && nestedSubCommands.size > 0) currentSubCommands = nestedSubCommands;
@@ -2378,9 +2554,9 @@ function collectRoutingCandidates(rawPositionals, root) {
2378
2554
  const seen = /* @__PURE__ */ new Set();
2379
2555
  function collect(commands, offset, parentPath) {
2380
2556
  for (let index = offset; index < rawPositionals.length; index++) {
2381
- const name = rawPositionals[index];
2382
- const command = commands.get(name);
2383
- if (command == null) continue;
2557
+ const found = findSubCommand(commands, rawPositionals[index]);
2558
+ if (found == null) continue;
2559
+ const [name, command] = found;
2384
2560
  const path = [...parentPath, name];
2385
2561
  const key = JSON.stringify(path);
2386
2562
  const normalized = normalizeCommandReference(command, name);
@@ -2398,6 +2574,30 @@ function collectRoutingCandidates(rawPositionals, root) {
2398
2574
  collect(root, 0, []);
2399
2575
  return candidates;
2400
2576
  }
2577
+ /**
2578
+ * Find the sub-command that a word of the command line names: the sub-command whose name is the word, or else the
2579
+ * one that has the word among its {@linkcode Command.aliases | aliases}.
2580
+ *
2581
+ * NOTE(kazupon): a name wins over an alias, so that an alias never hides a sub-command. A lazy command has the
2582
+ * aliases of its definition, as it is not loaded yet. Two sub-commands that give the same alias are a mistake in
2583
+ * their definitions, which is thrown as a `TypeError`, as a name given twice in an array of `subCommands` is.
2584
+ *
2585
+ * @param commands - The sub-commands of a level, by their names
2586
+ * @param word - The word of the command line
2587
+ * @returns The name of the sub-command and the sub-command, or `undefined` when no sub-command is named so
2588
+ */
2589
+ function findSubCommand(commands, word) {
2590
+ const command = commands.get(word);
2591
+ if (command != null) return [word, command];
2592
+ let found;
2593
+ for (const [name, candidate] of commands) {
2594
+ const aliases = candidate.aliases;
2595
+ if (!Array.isArray(aliases) || !aliases.includes(word)) continue;
2596
+ if (found) throw new TypeError(`Alias '${word}' is given to more than one command: '${found[0]}' and '${name}'`);
2597
+ found = [name, candidate];
2598
+ }
2599
+ return found;
2600
+ }
2401
2601
  function normalizeCommandReference(command, name) {
2402
2602
  if (typeof command === "function" && command.commandName == null) return Object.assign((...args) => command(...args), command, { commandName: name });
2403
2603
  if (typeof command === "object" && command.name == null) return Object.assign(create(), command, { name });
@@ -2567,7 +2767,13 @@ function createCommandNotFoundError(resolved) {
2567
2767
  code: CommandNotFoundErrorKeys.notFound,
2568
2768
  values: { commandName },
2569
2769
  commandName,
2570
- candidates: [...resolved.parentSubCommands?.keys() || []],
2770
+ /**
2771
+ * NOTE(kazupon): the candidates are what `@gunshi/plugin-suggestion` offers as "Did you mean". An internal
2772
+ * command is left out of them, as the help, shell completion and the help as JSON leave it out: it still
2773
+ * runs when it is typed, but nothing shows it to the user. So is a deprecated command, whose replacement is
2774
+ * what to offer.
2775
+ */
2776
+ candidates: [...resolved.parentSubCommands || []].filter(([, command]) => !command.internal && !isDeprecated(command.deprecated)).map(([name]) => name),
2571
2777
  commandPath: resolved.parentCommandPath || []
2572
2778
  });
2573
2779
  }
@@ -2583,8 +2789,8 @@ function getPluginExtensions(plugins) {
2583
2789
  }
2584
2790
  return extensions;
2585
2791
  }
2586
- async function executeCommand(cmd, ctx, decorators) {
2587
- const commandRunner = cmd.run || NOOP;
2792
+ async function executeCommand(cmd, ctx, decorators, fallbackRunner = NOOP) {
2793
+ const commandRunner = cmd.run || fallbackRunner;
2588
2794
  const baseRunner = (ctx) => {
2589
2795
  if (hasPriorityValidationError(ctx.validationError)) throw ctx.validationError;
2590
2796
  return commandRunner(ctx);
@@ -2604,8 +2810,7 @@ async function executeCommand(cmd, ctx, decorators) {
2604
2810
  throw error;
2605
2811
  }
2606
2812
  }
2607
- //#endregion
2608
- //#region ../gunshi/src/cli/bone.ts
2813
+ // ../gunshi/src/cli/bone.ts
2609
2814
  /**
2610
2815
  * @author kazuya kawaguchi (a.k.a. kazupon)
2611
2816
  * @license MIT
@@ -2624,17 +2829,14 @@ async function executeCommand(cmd, ctx, decorators) {
2624
2829
  async function cli(args, entry, options = {}) {
2625
2830
  return cliCore(args, entry, options, []);
2626
2831
  }
2627
- //#endregion
2628
- //#region ../gunshi/src/bone.ts
2832
+ // ../gunshi/src/bone.ts
2629
2833
  /**
2630
2834
  * @author kazuya kawaguchi (a.k.a. kazupon)
2631
2835
  * @license MIT
2632
2836
  */
2633
- //#endregion
2634
- //#region src/index.ts
2837
+ // src/index.ts
2635
2838
  /**
2636
2839
  * @author kazuya kawaguchi (a.k.a. kazupon)
2637
2840
  * @license MIT
2638
2841
  */
2639
- //#endregion
2640
2842
  export { cli };