@gunshi/bone 1.0.0-rc.10 → 1.0.0-rc.11

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 CHANGED
@@ -1402,6 +1402,19 @@ interface CommandContext<G extends GunshiParamsConstraint = DefaultGunshiParams>
1402
1402
  * Command rest arguments, that is the remaining argument not resolved by the optional command option delimiter `--`.
1403
1403
  */
1404
1404
  rest: string[];
1405
+ /**
1406
+ * The arguments that the command does not take, as they are given and in order, for a command with
1407
+ * {@linkcode Command.passthrough | passthrough} to pass on to another program: the options that it does not
1408
+ * declare, with the arguments that they take as their values, the positional arguments that it does not take,
1409
+ * and the arguments after `--`, at the end and without `--` itself.
1410
+ *
1411
+ * `app exec run.js --watch src -- --env x`, for `exec` with the positional argument `script`, gives
1412
+ * `['--watch', 'src', '--env', 'x']`. The arguments after `--` are in {@linkcode CommandContext.rest | rest}
1413
+ * too: pass this on in place of `rest`, not with it.
1414
+ *
1415
+ * It is an empty array for a command without `passthrough`.
1416
+ */
1417
+ passthrough: string[];
1405
1418
  /**
1406
1419
  * Original command line arguments.
1407
1420
  * This argument is passed from `cli` function.
@@ -1600,6 +1613,34 @@ interface Command<G extends GunshiParamsConstraint = DefaultGunshiParams> {
1600
1613
  * the aliases that the spread copies off the old name. It has no effect on the entry command.
1601
1614
  */
1602
1615
  deprecated?: boolean | string;
1616
+ /**
1617
+ * Whether the command passes the arguments that it does not take on to another program: `true`, or the text that
1618
+ * tells what they are, such as `'The arguments for the script'`, which the help shows.
1619
+ *
1620
+ * Such a command reports neither an option that it does not declare, whatever {@linkcode CliOptions.strict} says,
1621
+ * nor a positional argument that it does not take, whatever {@linkcode CliOptions.strictPositionals} says.
1622
+ * {@linkcode CommandContext.passthrough | ctx.passthrough} has them, as they are given and in order, with the
1623
+ * arguments after `--` at the end. The options that it declares, the global options such as `--help` included,
1624
+ * are read as before and are not passed on: to give `--help` to the other program, give it after `--`. A short
1625
+ * option group with an option that the command does not declare is passed on whole, such as `-qk` for a command
1626
+ * that declares `-q` and not `-k`: `-q` is read too, and the other program gets it in the group. The other errors
1627
+ * of the arguments are reported as before.
1628
+ *
1629
+ * An option that the command does not declare takes the next argument as its value, unless it has a value of its
1630
+ * own, such as `--bail=3`, or the next argument is an option or `--`. Both are passed on, and a positional argument
1631
+ * that the command declares does not get it: give the positional arguments of the command before the options of
1632
+ * the other program that take no value, such as `exec run.js --watch`, not `exec --watch run.js`.
1633
+ *
1634
+ * The help shows it at the end of the usage, as `[ARGUMENTS ...]`, and the text in the ARGUMENTS section, which the
1635
+ * i18n plugin translates with the key `passthrough` of the command. With the global options plugin, `--json` is
1636
+ * passed on too when the command declares no `json` argument: `jsonArgs`, or a `json` argument of its own, takes
1637
+ * `--json`. Without one, `--help --json` and `--version --json` are still answered by gunshi, as JSON, and the help
1638
+ * as JSON has `passthrough`.
1639
+ *
1640
+ * A lazy command takes it from the loaded command, and from the definition given to `lazy` when the loaded
1641
+ * command does not set it, or when the loader returns a runner.
1642
+ */
1643
+ passthrough?: boolean | string;
1603
1644
  /**
1604
1645
  * Whether this command is an entry command.
1605
1646
  *
@@ -1705,6 +1746,10 @@ interface SubCommandable {
1705
1746
  * see {@link Command.deprecated}
1706
1747
  */
1707
1748
  deprecated?: boolean | string;
1749
+ /**
1750
+ * see {@link Command.passthrough}
1751
+ */
1752
+ passthrough?: boolean | string;
1708
1753
  /**
1709
1754
  * see {@link Command.entry}
1710
1755
  */
package/lib/index.js CHANGED
@@ -1,4 +1,4 @@
1
- // ../../node_modules/.pnpm/args-tokens@1.3.0/node_modules/args-tokens/lib/parser.js
1
+ // ../../node_modules/.pnpm/args-tokens@1.4.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)
@@ -12,6 +12,7 @@ const HYPHEN_CODE = HYPHEN_CHAR.codePointAt(0);
12
12
  const EQUAL_CHAR = "=";
13
13
  const EQUAL_CODE = EQUAL_CHAR.codePointAt(0);
14
14
  const TERMINATOR = "--";
15
+ const ARRAY_ITERATOR = Array.prototype[Symbol.iterator];
15
16
  const SHORT_OPTION_PREFIX = HYPHEN_CHAR;
16
17
  const LONG_OPTION_PREFIX = "--";
17
18
  /**
@@ -35,13 +36,16 @@ const LONG_OPTION_PREFIX = "--";
35
36
  function parseArgs(args, options = {}) {
36
37
  const { allowCompatible = false } = options;
37
38
  const tokens = [];
38
- const remainings = [...args];
39
+ const list = Array.isArray(args) && args[Symbol.iterator] === ARRAY_ITERATOR ? args : [...args];
40
+ let next = 0;
41
+ let pieces = [];
42
+ let piece = 0;
39
43
  let index = -1;
40
44
  let groupCount = 0;
41
45
  let hasShortGroupValue = false;
42
46
  let shortGroupValueInline = true;
43
- while (remainings.length > 0) {
44
- const arg = remainings.shift();
47
+ while (piece < pieces.length || next < list.length) {
48
+ const arg = piece < pieces.length ? pieces[piece++] : list[next++];
45
49
  if (arg == void 0) break;
46
50
  if (groupCount > 0) groupCount--;
47
51
  else index++;
@@ -50,14 +54,16 @@ function parseArgs(args, options = {}) {
50
54
  kind: "option-terminator",
51
55
  index
52
56
  });
53
- const mapped = remainings.map((arg) => {
54
- return {
55
- kind: "positional",
56
- index: ++index,
57
- value: arg
58
- };
57
+ while (piece < pieces.length) tokens.push({
58
+ kind: "positional",
59
+ index: ++index,
60
+ value: pieces[piece++]
61
+ });
62
+ while (next < list.length) tokens.push({
63
+ kind: "positional",
64
+ index: ++index,
65
+ value: list[next++]
59
66
  });
60
- tokens.push(...mapped);
61
67
  break;
62
68
  }
63
69
  if (isShortOption(arg)) {
@@ -74,7 +80,7 @@ function parseArgs(args, options = {}) {
74
80
  inlineValue
75
81
  });
76
82
  if (groupCount === 1 && hasShortGroupValue) {
77
- value = remainings.shift();
83
+ value = piece < pieces.length ? pieces[piece++] : list[next++];
78
84
  inlineValue = shortGroupValueInline;
79
85
  hasShortGroupValue = false;
80
86
  tokens.push({
@@ -113,7 +119,8 @@ function parseArgs(args, options = {}) {
113
119
  hasShortGroupValue = separated;
114
120
  shortGroupValueInline = !dashed;
115
121
  if (separated) expanded.push(shortValue);
116
- remainings.unshift(...expanded);
122
+ pieces = piece < pieces.length ? [...expanded, ...pieces.slice(piece)] : expanded;
123
+ piece = 0;
117
124
  groupCount = expanded.length;
118
125
  continue;
119
126
  }
@@ -200,7 +207,7 @@ function isLongOptionAndValue(arg) {
200
207
  function hasLongOptionPrefix(arg) {
201
208
  return arg.startsWith(LONG_OPTION_PREFIX) && arg.length > 2;
202
209
  }
203
- // ../../node_modules/.pnpm/args-tokens@1.3.0/node_modules/args-tokens/lib/utils.js
210
+ // ../../node_modules/.pnpm/args-tokens@1.4.0/node_modules/args-tokens/lib/utils.js
204
211
  /**
205
212
  * Entry point of utils.
206
213
  *
@@ -219,7 +226,17 @@ function hasLongOptionPrefix(arg) {
219
226
  * @returns Converted string into kebab-case.
220
227
  */
221
228
  function kebabnize(str) {
222
- return str.replace(/[A-Z]/g, (match, offset) => (offset > 0 ? "-" : "") + match.toLowerCase());
229
+ if (typeof str !== "string") return str.replace(/[A-Z]/g, (match, offset) => (offset > 0 ? "-" : "") + match.toLowerCase());
230
+ let result = "";
231
+ let start = 0;
232
+ for (let i = 0; i < str.length; i++) {
233
+ const code = str.charCodeAt(i);
234
+ if (code >= 65 && code <= 90) {
235
+ result += `${str.slice(start, i)}${i > 0 ? "-" : ""}${String.fromCharCode(code + 32)}`;
236
+ start = i + 1;
237
+ }
238
+ }
239
+ return start === 0 ? str : result + str.slice(start);
223
240
  }
224
241
  /**
225
242
  * Format allowed argument choices for validation error values and fallback messages.
@@ -230,7 +247,7 @@ function kebabnize(str) {
230
247
  function formatChoices(choices) {
231
248
  return choices.map((value) => JSON.stringify(value)).join(", ");
232
249
  }
233
- // ../../node_modules/.pnpm/args-tokens@1.3.0/node_modules/args-tokens/lib/resolver-DWmHKGSL.js
250
+ // ../../node_modules/.pnpm/args-tokens@1.4.0/node_modules/args-tokens/lib/resolver-Cv1fPkMG.js
234
251
  /**
235
252
  * Internal definitions shared by the modules of `args-tokens`.
236
253
  *
@@ -376,74 +393,35 @@ const ARG_TYPES = /* @__PURE__ */ new Set([
376
393
  "positional",
377
394
  "custom"
378
395
  ]);
379
- /**
380
- * Resolve command line arguments.
381
- *
382
- * @typeParam A - {@link Args | Arguments}, which is an object that defines the command line arguments.
383
- *
384
- * @param args - An arguments that contains {@link ArgSchema | arguments schema}.
385
- * @param tokens - An array of {@link ArgToken | tokens}.
386
- * @param resolveArgs - An arguments that contains {@link ResolveArgs | resolve arguments}.
387
- * @returns An object that contains the values of the arguments, positional arguments, rest arguments, {@link AggregateError | validation errors}, and explicit provision status.
388
- *
389
- * @example
390
- * ```typescript
391
- * // passed tokens: --port 3000
392
- *
393
- * const { values, explicit } = resolveArgs({
394
- * port: {
395
- * type: 'number',
396
- * default: 8080
397
- * },
398
- * host: {
399
- * type: 'string',
400
- * default: 'localhost'
401
- * }
402
- * }, parsedTokens)
403
- *
404
- * values.port // 3000
405
- * values.host // 'localhost'
406
- *
407
- * explicit.port // true (explicitly provided)
408
- * explicit.host // false (not provided, fallback to default)
409
- * ```
410
- */
411
- function resolveArgs(args, tokens, { shortGrouping = false, skipPositional = SKIP_POSITIONAL_DEFAULT, toKebab = false } = {}) {
396
+ function resolveArgs(args, tokens, { shortGrouping = false, skipPositional = SKIP_POSITIONAL_DEFAULT, toKebab = false, passthrough = false } = {}) {
412
397
  const skipPositionalIndex = typeof skipPositional === "number" ? Math.max(skipPositional, SKIP_POSITIONAL_DEFAULT) : SKIP_POSITIONAL_DEFAULT;
413
398
  const rest = [];
399
+ const takenValues = passthrough ? [] : void 0;
414
400
  const optionTokens = [];
415
401
  const positionalTokens = [];
416
402
  const argEntries = Object.entries(args);
417
403
  let currentLongOption;
418
404
  let currentShortOption;
419
- const expandableShortOptions = [];
405
+ let shortLetters;
420
406
  function getOptionName(rawArg, schema) {
421
407
  return toKebab || schema.toKebab ? kebabnize(rawArg) : rawArg;
422
408
  }
423
- function checkLongTokenName(option, schema, token) {
424
- if (token.rawName == void 0 || !hasLongOptionPrefix(token.rawName)) return false;
425
- return token.name === option || isNegatedToken(token, option, schema);
426
- }
427
409
  function toShortValue() {
428
- if (expandableShortOptions.length === 0) return;
429
- else {
430
- let value = "";
431
- for (let i = 0; i < expandableShortOptions.length; i++) value += expandableShortOptions[i].name ?? "";
432
- expandableShortOptions.length = 0;
433
- return value;
434
- }
410
+ const value = shortLetters;
411
+ shortLetters = void 0;
412
+ return value;
435
413
  }
436
414
  function applyLongOptionValue(value) {
437
415
  if (currentLongOption) {
438
416
  currentLongOption.value = value;
439
- optionTokens.push({ ...currentLongOption });
417
+ optionTokens.push(currentLongOption);
440
418
  currentLongOption = void 0;
441
419
  }
442
420
  }
443
421
  function applyShortOptionValue(value) {
444
422
  if (currentShortOption) {
445
423
  currentShortOption.value = value ?? toShortValue();
446
- optionTokens.push({ ...currentShortOption });
424
+ optionTokens.push(currentShortOption);
447
425
  currentShortOption = void 0;
448
426
  }
449
427
  }
@@ -451,7 +429,6 @@ function resolveArgs(args, tokens, { shortGrouping = false, skipPositional = SKI
451
429
  * analyze phase to resolve value
452
430
  * separate tokens into positionals, long and short options, after that resolve values
453
431
  */
454
- const schemas = Object.values(args);
455
432
  const booleanLongOptionNames = /* @__PURE__ */ new Set();
456
433
  for (let i = 0; i < argEntries.length; i++) {
457
434
  const entry = argEntries[i];
@@ -476,15 +453,21 @@ function resolveArgs(args, tokens, { shortGrouping = false, skipPositional = SKI
476
453
  continue;
477
454
  }
478
455
  if (currentShortOption) {
479
- if (schemas.find((schema) => schema.short === currentShortOption.name && schema.type === "boolean") || expandableShortOptions.length > 0) {
456
+ if (isBooleanShortOption(argEntries, currentShortOption.name) || shortLetters !== void 0) {
480
457
  positionalTokens.push({ ...token });
481
458
  applyShortOptionValue();
482
- } else applyShortOptionValue(token.value);
459
+ } else {
460
+ applyShortOptionValue(token.value);
461
+ if (takenValues !== void 0) takenValues.push(optionTokens.length - 1, token.index);
462
+ }
483
463
  } else if (currentLongOption) {
484
464
  if (booleanLongOptionNames.has(currentLongOption.name)) {
485
465
  positionalTokens.push({ ...token });
486
466
  applyLongOptionValue();
487
- } else applyLongOptionValue(token.value);
467
+ } else {
468
+ applyLongOptionValue(token.value);
469
+ if (takenValues !== void 0) takenValues.push(optionTokens.length - 1, token.index);
470
+ }
488
471
  } else positionalTokens.push({ ...token });
489
472
  } else if (token.kind === "option") {
490
473
  if (token.rawName) {
@@ -498,12 +481,12 @@ function resolveArgs(args, tokens, { shortGrouping = false, skipPositional = SKI
498
481
  if (currentShortOption.index === token.index) {
499
482
  if (shortGrouping) {
500
483
  currentShortOption.value = token.value;
501
- optionTokens.push({ ...currentShortOption });
484
+ optionTokens.push(currentShortOption);
502
485
  currentShortOption = { ...token };
503
- } else expandableShortOptions.push({ ...token });
486
+ } else shortLetters = (shortLetters ?? "") + (token.name ?? "");
504
487
  } else {
505
488
  currentShortOption.value = toShortValue();
506
- optionTokens.push({ ...currentShortOption });
489
+ optionTokens.push(currentShortOption);
507
490
  currentShortOption = { ...token };
508
491
  }
509
492
  applyLongOptionValue();
@@ -517,7 +500,7 @@ function resolveArgs(args, tokens, { shortGrouping = false, skipPositional = SKI
517
500
  const letters = toShortValue();
518
501
  currentShortOption.value = letters === void 0 ? token.value : `${letters}${token.inlineValue ? "=" : ""}${token.value ?? ""}`;
519
502
  currentShortOption.inlineValue = token.inlineValue;
520
- optionTokens.push({ ...currentShortOption });
503
+ optionTokens.push(currentShortOption);
521
504
  currentShortOption = void 0;
522
505
  }
523
506
  applyLongOptionValue();
@@ -538,10 +521,10 @@ function resolveArgs(args, tokens, { shortGrouping = false, skipPositional = SKI
538
521
  */
539
522
  const values = Object.create(null);
540
523
  const errors = [];
524
+ const matched = passthrough ? new Uint8Array(optionTokens.length) : void 0;
541
525
  const explicit = Object.create(null);
542
- const actualInputNames = /* @__PURE__ */ new Map();
543
526
  let requiredPositionalsAfter;
544
- const positionalItemCount = tokens.filter((token) => token.kind === "positional").length;
527
+ const positionalItemCount = skipPositionalIndex > SKIP_POSITIONAL_DEFAULT ? countPositionalTokens(tokens) : 0;
545
528
  function getPositionalSkipIndex() {
546
529
  return Math.min(skipPositionalIndex, positionalItemCount);
547
530
  }
@@ -605,9 +588,15 @@ function resolveArgs(args, tokens, { shortGrouping = false, skipPositional = SKI
605
588
  continue;
606
589
  }
607
590
  if (schema.required) {
608
- if (!optionTokens.find((token) => {
609
- return schema.short && token.name === schema.short && token.rawName != void 0 && isShortOption(token.rawName) || checkLongTokenName(arg, schema, token);
610
- })) {
591
+ let found = false;
592
+ for (let i = 0; i < optionTokens.length; i++) {
593
+ const token = optionTokens[i];
594
+ if (schema.short && token.name === schema.short && token.rawName != void 0 && isShortOption(token.rawName) || checkLongTokenName(arg, schema, token)) {
595
+ found = true;
596
+ break;
597
+ }
598
+ }
599
+ if (!found) {
611
600
  errors.push(createRequireError(rawArg, arg, schema));
612
601
  continue;
613
602
  }
@@ -616,10 +605,8 @@ function resolveArgs(args, tokens, { shortGrouping = false, skipPositional = SKI
616
605
  for (let i = 0; i < optionTokens.length; i++) {
617
606
  const token = optionTokens[i];
618
607
  if (checkLongTokenName(arg, schema, token) || schema.short === token.name && token.rawName != void 0 && isShortOption(token.rawName)) {
608
+ if (matched !== void 0) matched[i] = 1;
619
609
  explicit[rawArg] = true;
620
- const rawName = token.rawName;
621
- const actualInputName = isShortOption(rawName) ? `-${token.name}` : rawName;
622
- actualInputNames.set(rawArg, actualInputName);
623
610
  const missing = schema.type !== "boolean" && token.value === void 0;
624
611
  if (!missing) {
625
612
  const invalid = validateRequire(token, rawArg, arg, schema);
@@ -644,15 +631,130 @@ function resolveArgs(args, tokens, { shortGrouping = false, skipPositional = SKI
644
631
  else values[rawArg] = getDefaultValue(schema);
645
632
  }
646
633
  }
647
- const conflictErrors = checkConflicts(args, explicit, toKebab, actualInputNames);
648
- errors.push(...conflictErrors);
649
- return {
634
+ if (hasGivenConflicts(argEntries, explicit)) errors.push(...checkConflicts(args, explicit, toKebab, findActualInputNames(argEntries, optionTokens, toKebab)));
635
+ const positionals = positionalTokens.map((token) => token.value);
636
+ const error = errors.length > 0 ? new AggregateError(errors) : void 0;
637
+ if (matched === void 0 || takenValues === void 0) return {
650
638
  values,
651
- positionals: positionalTokens.map((token) => token.value),
639
+ positionals,
652
640
  rest,
653
- error: errors.length > 0 ? new AggregateError(errors) : void 0,
641
+ error,
654
642
  explicit
655
643
  };
644
+ return {
645
+ values,
646
+ positionals,
647
+ rest,
648
+ error,
649
+ explicit,
650
+ passthroughIndices: collectPassthroughIndices(tokens, optionTokens, matched, takenValues, positionalTokens, Math.max(positionalsCount, skipPositionalIndex > SKIP_POSITIONAL_DEFAULT ? Math.floor(skipPositionalIndex) + 1 : 0), rest.length)
651
+ };
652
+ }
653
+ /**
654
+ * Check whether an option token is the long form of an option, or its negated form.
655
+ *
656
+ * @param option - The option name used on the command line (after `toKebab` conversion)
657
+ * @param schema - The argument schema
658
+ * @param token - The option token
659
+ * @returns Whether the token is the long form or the negated form of the option.
660
+ */
661
+ function checkLongTokenName(option, schema, token) {
662
+ if (token.rawName == void 0 || !hasLongOptionPrefix(token.rawName)) return false;
663
+ return token.name === option || isNegatedToken(token, option, schema);
664
+ }
665
+ /**
666
+ * Check whether a given argument has `conflicts`, as {@link checkConflicts} checks them. It reads
667
+ * the schemas as they are now, since a `parse` function may change them.
668
+ *
669
+ * @param argEntries - The argument schemas
670
+ * @param explicit - Whether each argument is given
671
+ * @returns Whether `checkConflicts()` may find a conflict.
672
+ */
673
+ function hasGivenConflicts(argEntries, explicit) {
674
+ for (let i = 0; i < argEntries.length; i++) if (argEntries[i][1].conflicts && explicit[argEntries[i][0]]) return true;
675
+ return false;
676
+ }
677
+ /**
678
+ * Find the name as given of each option of the schema, such as `-v` or `--verbose`: the name of the
679
+ * last option token that matches it, as `resolveArgs()` matches the tokens to read the values.
680
+ *
681
+ * @param argEntries - The argument schemas
682
+ * @param optionTokens - The option tokens
683
+ * @param toKebab - Whether every option name is converted to kebab-case
684
+ * @returns The names as given, by the keys of the schema.
685
+ */
686
+ function findActualInputNames(argEntries, optionTokens, toKebab) {
687
+ const names = /* @__PURE__ */ new Map();
688
+ for (let i = 0; i < argEntries.length; i++) {
689
+ const rawArg = argEntries[i][0];
690
+ const schema = argEntries[i][1];
691
+ if (schema.type === "positional") continue;
692
+ const option = toKebab || schema.toKebab ? kebabnize(rawArg) : rawArg;
693
+ for (let j = 0; j < optionTokens.length; j++) {
694
+ const token = optionTokens[j];
695
+ if (checkLongTokenName(option, schema, token) || schema.short === token.name && token.rawName != void 0 && isShortOption(token.rawName)) {
696
+ const rawName = token.rawName;
697
+ names.set(rawArg, isShortOption(rawName) ? `-${token.name}` : rawName);
698
+ }
699
+ }
700
+ }
701
+ return names;
702
+ }
703
+ /**
704
+ * Check whether a schema has a boolean option with a short name.
705
+ *
706
+ * @param argEntries - The entries of the schema
707
+ * @param name - The short name
708
+ * @returns Whether a boolean option of the schema has the short name.
709
+ */
710
+ function isBooleanShortOption(argEntries, name) {
711
+ for (let i = 0; i < argEntries.length; i++) {
712
+ const schema = argEntries[i][1];
713
+ if (schema.short === name && schema.type === "boolean") return true;
714
+ }
715
+ return false;
716
+ }
717
+ /**
718
+ * Count the positional tokens.
719
+ *
720
+ * @param tokens - The tokens
721
+ * @returns How many of the tokens are positional.
722
+ */
723
+ function countPositionalTokens(tokens) {
724
+ let count = 0;
725
+ for (let i = 0; i < tokens.length; i++) if (tokens[i].kind === "positional") count++;
726
+ return count;
727
+ }
728
+ /**
729
+ * Collect the indexes of the arguments that the schema does not take, for `passthrough`.
730
+ *
731
+ * Each argument is marked by its index: an option token that does not match the schema, with the
732
+ * token that it takes as its value; the positional arguments that the schema does not take; and
733
+ * the arguments after `--`, which are the last tokens, one for each argument in `rest`. The tokens
734
+ * of a short option group have the index of the group, so the group is marked when one of its
735
+ * tokens does not match; without `shortGrouping`, the group has only the token of its first
736
+ * option. The marked indexes are then read in order.
737
+ *
738
+ * @param tokens - The tokens given to `resolveArgs()`
739
+ * @param optionTokens - The option tokens, each with its value
740
+ * @param matched - Whether each option token matches the schema
741
+ * @param takenValues - For each option token that takes a positional argument as its value, the
742
+ * position of the option token in `optionTokens`, then the index of the argument
743
+ * @param positionalTokens - The positional tokens before `--`, without the ones taken as values
744
+ * @param taken - How many of `positionalTokens` are skipped or taken by the schema, from the first
745
+ * @param restCount - How many arguments are after `--`
746
+ * @returns The indexes, in ascending order, each once
747
+ */
748
+ function collectPassthroughIndices(tokens, optionTokens, matched, takenValues, positionalTokens, taken, restCount) {
749
+ const count = tokens.length === 0 ? 0 : tokens[tokens.length - 1].index + 1;
750
+ const given = new Uint8Array(count);
751
+ for (let i = 0; i < optionTokens.length; i++) if (matched[i] === 0) given[optionTokens[i].index] = 1;
752
+ for (let i = 0; i < takenValues.length; i += 2) if (matched[takenValues[i]] === 0) given[takenValues[i + 1]] = 1;
753
+ for (let i = taken; i < positionalTokens.length; i++) given[positionalTokens[i].index] = 1;
754
+ for (let i = tokens.length - restCount; i < tokens.length; i++) given[tokens[i].index] = 1;
755
+ const indices = [];
756
+ for (let i = 0; i < count; i++) if (given[i] === 1) indices.push(i);
757
+ return indices;
656
758
  }
657
759
  /**
658
760
  * Check whether an option token is the negated form (`--no-<option>`) of a negatable boolean option.
@@ -1154,7 +1256,7 @@ function checkConflicts(args, explicit, toKebab, actualInputNames) {
1154
1256
  }
1155
1257
  return [];
1156
1258
  }
1157
- // ../../node_modules/.pnpm/args-tokens@1.3.0/node_modules/args-tokens/lib/index.js
1259
+ // ../../node_modules/.pnpm/args-tokens@1.4.0/node_modules/args-tokens/lib/index.js
1158
1260
  /**
1159
1261
  * @author kazuya kawaguchi (a.k.a. kazupon)
1160
1262
  * @license MIT
@@ -1479,6 +1581,7 @@ async function resolveLazyCommand(cmd, name, needRunResolving = false) {
1479
1581
  internal: cmd.internal,
1480
1582
  aliases: cmd.aliases,
1481
1583
  deprecated: cmd.deprecated,
1584
+ passthrough: cmd.passthrough,
1482
1585
  entry: cmd.entry,
1483
1586
  toKebab: cmd.toKebab,
1484
1587
  rendering: cmd.rendering,
@@ -1510,6 +1613,7 @@ async function resolveLazyCommand(cmd, name, needRunResolving = false) {
1510
1613
  command.internal = loaded.internal ?? cmd.internal;
1511
1614
  command.aliases = loaded.aliases ?? cmd.aliases;
1512
1615
  command.deprecated = loaded.deprecated ?? cmd.deprecated;
1616
+ command.passthrough = loaded.passthrough ?? cmd.passthrough;
1513
1617
  command.entry = loaded.entry ?? cmd.entry;
1514
1618
  command.toKebab = loaded.toKebab ?? cmd.toKebab;
1515
1619
  command.rendering = loaded.rendering ?? cmd.rendering;
@@ -1613,7 +1717,7 @@ function deepFreeze(obj, ignores = []) {
1613
1717
  * @param param - A {@link CommandContextParams | parameters} to create a command context.
1614
1718
  * @returns A {@link CommandContext | command context}, which is readonly.
1615
1719
  */
1616
- async function createCommandContext({ args = {}, explicit = {}, values = {}, positionals = [], rest = [], argv = [], tokens = [], command = {}, extensions = {}, cliOptions = {}, callMode = "entry", commandPath = [], omitted = false, validationError }) {
1720
+ async function createCommandContext({ args = {}, explicit = {}, values = {}, positionals = [], rest = [], passthrough = [], argv = [], tokens = [], command = {}, extensions = {}, cliOptions = {}, callMode = "entry", commandPath = [], omitted = false, validationError }) {
1617
1721
  /**
1618
1722
  * normailize the options schema and values, to avoid prototype pollution
1619
1723
  */
@@ -1662,6 +1766,7 @@ async function createCommandContext({ args = {}, explicit = {}, values = {}, pos
1662
1766
  values,
1663
1767
  positionals,
1664
1768
  rest,
1769
+ passthrough,
1665
1770
  _: argv,
1666
1771
  tokens,
1667
1772
  toKebab: command.toKebab,
@@ -2014,8 +2119,17 @@ async function cliCore(argv, entry, options, plugins, usageOnly = false) {
2014
2119
  */
2015
2120
  cliOptions.globalOptions = resolveEffectiveGlobalOptions(pluginContext.globalOptions, commandArgs, args);
2016
2121
  const skipPositional = resolveSkipPositional(tokens, pluginContext.globalOptions, resolvedCommand, targetDepth);
2122
+ /**
2123
+ * NOTE(kazupon): a command with `passthrough` passes the arguments that it does not take on to another program,
2124
+ * so they are not errors. args-tokens tells which ones they are, as only the resolver knows which arguments the
2125
+ * options take as their values, and gives their indexes in `argv`, which keep them as they were given: a short
2126
+ * option group with an option that the command does not declare, such as `-qk`, is passed on whole. The
2127
+ * `passthrough` of the command is read once, so that the arguments and the mark for the plugins agree.
2128
+ */
2129
+ const passthroughOfCommand = resolvedCommand.passthrough;
2130
+ const passthrough = isPassthrough(passthroughOfCommand);
2017
2131
  const diagnostic = selection.diagnostic === true;
2018
- const { explicit, values, positionals, rest, error } = diagnostic ? {
2132
+ const { explicit, values, positionals, rest, error, passthroughIndices } = diagnostic ? {
2019
2133
  explicit: create(),
2020
2134
  values: create(),
2021
2135
  positionals: [],
@@ -2024,15 +2138,16 @@ async function cliCore(argv, entry, options, plugins, usageOnly = false) {
2024
2138
  } : resolveArgs(args, tokens, {
2025
2139
  shortGrouping: true,
2026
2140
  toKebab: resolvedCommand.toKebab,
2027
- skipPositional
2141
+ skipPositional,
2142
+ passthrough
2028
2143
  });
2029
2144
  const validationError = mergeValidationErrors(error, [
2030
2145
  ...additionalValidationErrors,
2031
- ...cliOptions.strict && !diagnostic ? createUnknownOptionErrors(findUnknownOptions(args, tokens, {
2146
+ ...cliOptions.strict && !diagnostic && !passthrough ? createUnknownOptionErrors(findUnknownOptions(args, tokens, {
2032
2147
  toKebab: resolvedCommand.toKebab,
2033
2148
  suggestedValues: findSuggestedValues(args, argv, tokens, error, { toKebab: resolvedCommand.toKebab })
2034
2149
  })) : [],
2035
- ...cliOptions.strictPositionals && !diagnostic && additionalValidationErrors.length === 0 ? createUnexpectedPositionalErrors(findUnexpectedPositionals(args, positionals, skipPositional)) : []
2150
+ ...cliOptions.strictPositionals && !diagnostic && !passthrough && additionalValidationErrors.length === 0 ? createUnexpectedPositionalErrors(findUnexpectedPositionals(args, positionals, skipPositional)) : []
2036
2151
  ]);
2037
2152
  const commandContext = await createCommandContext({
2038
2153
  args,
@@ -2040,6 +2155,7 @@ async function cliCore(argv, entry, options, plugins, usageOnly = false) {
2040
2155
  values,
2041
2156
  positionals,
2042
2157
  rest,
2158
+ passthrough: passthroughIndices?.map((index) => argv[index]) ?? [],
2043
2159
  argv,
2044
2160
  tokens,
2045
2161
  omitted: targetOmitted,
@@ -2051,6 +2167,7 @@ async function cliCore(argv, entry, options, plugins, usageOnly = false) {
2051
2167
  cliOptions
2052
2168
  });
2053
2169
  markDeprecatedCommands(commandContext, collectDeprecatedCommands(routingOptions.subCommands, targetCommandPath, resolvedCommand));
2170
+ markPassthrough(commandContext, passthroughOfCommand);
2054
2171
  const reported = trackReported(commandContext);
2055
2172
  let fallbackRunner = NOOP;
2056
2173
  if (loadFailure !== void 0) {
@@ -2183,6 +2300,39 @@ function markDeprecatedCommands(ctx, marks) {
2183
2300
  (registry[DEPRECATED_COMMANDS] ??= /* @__PURE__ */ new WeakMap()).set(ctx, marks);
2184
2301
  }
2185
2302
  /**
2303
+ * The key of the registry of the command contexts whose command passes the arguments that it does not take on to
2304
+ * another program, with its `passthrough`. The global options plugin and the usage renderer plugin read it with
2305
+ * `getPassthrough` of `@gunshi/shared`, by the same registered symbol, since `gunshi` and the plugins bundle their
2306
+ * own copies. Neither is in the public API.
2307
+ */
2308
+ const PASSTHROUGH = Symbol.for("gunshi.passthrough");
2309
+ /**
2310
+ * Check whether the `passthrough` of a command makes it pass the arguments that it does not take on.
2311
+ *
2312
+ * @param passthrough - The `passthrough` of a command
2313
+ * @returns `true` for `true` or a text
2314
+ */
2315
+ function isPassthrough(passthrough) {
2316
+ return passthrough === true || typeof passthrough === "string";
2317
+ }
2318
+ /**
2319
+ * Mark the command context of a run whose command passes the arguments that it does not take on, with its
2320
+ * `passthrough`.
2321
+ *
2322
+ * NOTE(kazupon): the context has the arguments that the command passes on, and not whether it passes them on,
2323
+ * which its help and the help as JSON tell even when there are none, so the core tells the plugins. The command is
2324
+ * checked once it is loaded, so a lazy command is marked by the `passthrough` of the loaded command. The registry is
2325
+ * weak, and holds the context of this run only.
2326
+ *
2327
+ * @param ctx - The command context of the run
2328
+ * @param passthrough - The `passthrough` of the command that runs
2329
+ */
2330
+ function markPassthrough(ctx, passthrough) {
2331
+ if (!isPassthrough(passthrough)) return;
2332
+ const registry = globalThis;
2333
+ (registry[PASSTHROUGH] ??= /* @__PURE__ */ new WeakMap()).set(ctx, passthrough);
2334
+ }
2335
+ /**
2186
2336
  * Create the decorator that renders the usage of the command instead of running it.
2187
2337
  *
2188
2338
  * NOTE(kazupon): `generate()` of `gunshi/generator` asks the core for a usage. It used to ask by
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@gunshi/bone",
3
- "version": "1.0.0-rc.10",
3
+ "version": "1.0.0-rc.11",
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.10",
52
- "@gunshi/plugin-global": "1.0.0-rc.10",
53
- "@gunshi/plugin-renderer": "1.0.0-rc.10",
54
- "gunshi": "1.0.0-rc.10",
51
+ "@gunshi/definition": "1.0.0-rc.11",
52
+ "@gunshi/plugin-global": "1.0.0-rc.11",
53
+ "@gunshi/plugin-renderer": "1.0.0-rc.11",
54
+ "gunshi": "1.0.0-rc.11",
55
55
  "publint": "^0.3.20"
56
56
  },
57
57
  "engines": {