@optique/run 1.0.0-dev.429 → 1.0.0-dev.432

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 (5) hide show
  1. package/dist/run.cjs +152 -71
  2. package/dist/run.d.cts +58 -77
  3. package/dist/run.d.ts +58 -77
  4. package/dist/run.js +153 -72
  5. package/package.json +2 -2
package/dist/run.cjs CHANGED
@@ -8,97 +8,112 @@ function run(parserOrProgram, options = {}) {
8
8
  return runImpl(parserOrProgram, options);
9
9
  }
10
10
  function runSync(parserOrProgram, options = {}) {
11
+ const contexts = options.contexts;
12
+ if (contexts && contexts.length > 0) {
13
+ const isProgram = "parser" in parserOrProgram && "metadata" in parserOrProgram;
14
+ let parser;
15
+ let programMetadata;
16
+ if (isProgram) {
17
+ const program = parserOrProgram;
18
+ parser = program.parser;
19
+ if (!options.programName) options = {
20
+ ...options,
21
+ programName: program.metadata.name
22
+ };
23
+ programMetadata = {
24
+ brief: program.metadata.brief,
25
+ description: program.metadata.description,
26
+ examples: program.metadata.examples,
27
+ author: program.metadata.author,
28
+ bugs: program.metadata.bugs,
29
+ footer: program.metadata.footer
30
+ };
31
+ } else parser = parserOrProgram;
32
+ const { programName, args, coreOptions } = buildCoreOptions(options, programMetadata);
33
+ const contextOptions = {};
34
+ for (const key of Object.keys(options)) if (!knownRunOptionsKeys.has(key)) contextOptions[key] = options[key];
35
+ const runWithOptions = {
36
+ ...coreOptions,
37
+ ...contextOptions,
38
+ args
39
+ };
40
+ return (0, __optique_core_facade.runWithSync)(parser, programName, contexts, runWithOptions);
41
+ }
11
42
  return runImpl(parserOrProgram, options);
12
43
  }
13
44
  function runAsync(parserOrProgram, options = {}) {
14
45
  const result = runImpl(parserOrProgram, options);
15
46
  return Promise.resolve(result);
16
47
  }
17
- function runImpl(parserOrProgram, options = {}) {
18
- const isProgram = "parser" in parserOrProgram && "metadata" in parserOrProgram;
19
- let parser;
20
- let programNameFromProgram;
21
- let programMetadata;
22
- if (isProgram) {
23
- const program = parserOrProgram;
24
- parser = program.parser;
25
- programNameFromProgram = program.metadata.name;
26
- programMetadata = {
27
- brief: program.metadata.brief,
28
- description: program.metadata.description,
29
- examples: program.metadata.examples,
30
- author: program.metadata.author,
31
- bugs: program.metadata.bugs,
32
- footer: program.metadata.footer
48
+ /**
49
+ * Builds core run options from the simplified RunOptions format.
50
+ *
51
+ * Converts the user-friendly RunOptions (string-based help/version/completion)
52
+ * into the verbose CoreRunOptions format expected by `runParser()`, `runWith()`,
53
+ * and `runWithSync()` from `@optique/core/facade`.
54
+ *
55
+ * @internal
56
+ */
57
+ function buildCoreOptions(options, programMetadata) {
58
+ const { programName = node_path.default.basename(node_process.default.argv[1] || "cli"), args = node_process.default.argv.slice(2), colors = node_process.default.stdout.isTTY, maxWidth = node_process.default.stdout.columns, showDefault, showChoices, sectionOrder, help, version, completion, aboveError = "usage", errorExitCode = 1, brief = programMetadata?.brief, description = programMetadata?.description, examples = programMetadata?.examples, author = programMetadata?.author, bugs = programMetadata?.bugs, footer = programMetadata?.footer } = options;
59
+ const onShow = () => node_process.default.exit(0);
60
+ const helpConfig = (() => {
61
+ if (!help) return void 0;
62
+ if (typeof help === "string") switch (help) {
63
+ case "command": return {
64
+ command: true,
65
+ onShow
66
+ };
67
+ case "option": return {
68
+ option: true,
69
+ onShow
70
+ };
71
+ case "both": return {
72
+ command: true,
73
+ option: true,
74
+ onShow
75
+ };
76
+ }
77
+ return {
78
+ ...help,
79
+ onShow
33
80
  };
34
- } else parser = parserOrProgram;
35
- const { programName = programNameFromProgram ?? node_path.default.basename(node_process.default.argv[1] || "cli"), args = node_process.default.argv.slice(2), colors = node_process.default.stdout.isTTY, maxWidth = node_process.default.stdout.columns, showDefault, showChoices, sectionOrder, help, version, completion, aboveError = "usage", errorExitCode = 1, brief = programMetadata?.brief, description = programMetadata?.description, examples = programMetadata?.examples, author = programMetadata?.author, bugs = programMetadata?.bugs, footer = programMetadata?.footer } = options;
36
- const helpConfig = help ? typeof help === "string" ? {
37
- mode: help,
38
- onShow: () => node_process.default.exit(0)
39
- } : {
40
- mode: help.mode,
41
- group: help.group,
42
- onShow: () => node_process.default.exit(0)
43
- } : void 0;
81
+ })();
44
82
  const versionConfig = (() => {
45
83
  if (!version) return void 0;
46
84
  if (typeof version === "string") return {
47
- mode: "option",
48
85
  value: version,
49
- onShow: () => node_process.default.exit(0)
50
- };
51
- const mode = version.mode ?? "option";
52
- if (mode === "command" || mode === "both") return {
53
- mode,
54
- value: version.value,
55
- group: version.group,
56
- onShow: () => node_process.default.exit(0)
86
+ option: true,
87
+ onShow
57
88
  };
58
89
  return {
59
- mode,
60
- value: version.value,
61
- onShow: () => node_process.default.exit(0)
90
+ ...version,
91
+ onShow
62
92
  };
63
93
  })();
64
94
  const completionConfig = (() => {
65
95
  if (!completion) return void 0;
66
- const onShow = () => node_process.default.exit(0);
67
- if (typeof completion === "string") return {
68
- mode: completion,
69
- name: "both",
70
- helpVisibility: "both",
71
- onShow
72
- };
73
- const mode = completion.mode ?? "both";
74
- const shells = completion.shells;
75
- const cGroup = completion.group;
76
- if (completion.name === "singular") return {
77
- mode,
78
- shells,
79
- ...cGroup != null && { group: cGroup },
80
- name: "singular",
81
- helpVisibility: completion.helpVisibility ?? "singular",
82
- onShow
83
- };
84
- if (completion.name === "plural") return {
85
- mode,
86
- shells,
87
- ...cGroup != null && { group: cGroup },
88
- name: "plural",
89
- helpVisibility: completion.helpVisibility ?? "plural",
90
- onShow
91
- };
96
+ if (typeof completion === "string") switch (completion) {
97
+ case "command": return {
98
+ command: true,
99
+ onShow
100
+ };
101
+ case "option": return {
102
+ option: true,
103
+ onShow
104
+ };
105
+ case "both": return {
106
+ command: true,
107
+ option: true,
108
+ onShow
109
+ };
110
+ }
92
111
  return {
93
- mode,
94
- shells,
95
- ...cGroup != null && { group: cGroup },
96
- name: "both",
97
- helpVisibility: completion.helpVisibility ?? "both",
112
+ ...completion,
98
113
  onShow
99
114
  };
100
115
  })();
101
- return (0, __optique_core_facade.runParser)(parser, programName, args, {
116
+ const coreOptions = {
102
117
  stderr(line) {
103
118
  node_process.default.stderr.write(`${line}\n`);
104
119
  },
@@ -123,7 +138,73 @@ function runImpl(parserOrProgram, options = {}) {
123
138
  onError() {
124
139
  return node_process.default.exit(errorExitCode);
125
140
  }
126
- });
141
+ };
142
+ return {
143
+ programName,
144
+ args,
145
+ coreOptions
146
+ };
147
+ }
148
+ /**
149
+ * Set of known RunOptions field names. Used by `runImpl()` to separate
150
+ * RunOptions fields from context-required options via rest-spread.
151
+ */
152
+ const knownRunOptionsKeys = new Set([
153
+ "programName",
154
+ "args",
155
+ "colors",
156
+ "maxWidth",
157
+ "showDefault",
158
+ "showChoices",
159
+ "sectionOrder",
160
+ "help",
161
+ "version",
162
+ "completion",
163
+ "aboveError",
164
+ "errorExitCode",
165
+ "brief",
166
+ "description",
167
+ "examples",
168
+ "author",
169
+ "bugs",
170
+ "footer",
171
+ "contexts"
172
+ ]);
173
+ function runImpl(parserOrProgram, options = {}) {
174
+ const isProgram = "parser" in parserOrProgram && "metadata" in parserOrProgram;
175
+ let parser;
176
+ let programMetadata;
177
+ if (isProgram) {
178
+ const program = parserOrProgram;
179
+ parser = program.parser;
180
+ const programNameFromProgram = program.metadata.name;
181
+ programMetadata = {
182
+ brief: program.metadata.brief,
183
+ description: program.metadata.description,
184
+ examples: program.metadata.examples,
185
+ author: program.metadata.author,
186
+ bugs: program.metadata.bugs,
187
+ footer: program.metadata.footer
188
+ };
189
+ if (!options.programName) options = {
190
+ ...options,
191
+ programName: programNameFromProgram
192
+ };
193
+ } else parser = parserOrProgram;
194
+ const contexts = options.contexts;
195
+ if (contexts && contexts.length > 0) {
196
+ const { programName: programName$1, args: args$1, coreOptions: coreOptions$1 } = buildCoreOptions(options, programMetadata);
197
+ const contextOptions = {};
198
+ for (const key of Object.keys(options)) if (!knownRunOptionsKeys.has(key)) contextOptions[key] = options[key];
199
+ const runWithOptions = {
200
+ ...coreOptions$1,
201
+ ...contextOptions,
202
+ args: args$1
203
+ };
204
+ return (0, __optique_core_facade.runWith)(parser, programName$1, contexts, runWithOptions);
205
+ }
206
+ const { programName, args, coreOptions } = buildCoreOptions(options, programMetadata);
207
+ return (0, __optique_core_facade.runParser)(parser, programName, args, coreOptions);
127
208
  }
128
209
 
129
210
  //#endregion
package/dist/run.d.cts CHANGED
@@ -1,4 +1,6 @@
1
1
  import { ShellCompletion } from "@optique/core/completion";
2
+ import { SourceContext } from "@optique/core/context";
3
+ import { CommandSubConfig, ExtractRequiredOptions, OptionSubConfig } from "@optique/core/facade";
2
4
  import { InferMode, InferValue, Mode, ModeValue, Parser } from "@optique/core/parser";
3
5
  import { Program } from "@optique/core/program";
4
6
  import { DocSection, ShowChoicesOptions, ShowDefaultOptions } from "@optique/core/doc";
@@ -82,63 +84,66 @@ interface RunOptions {
82
84
  * - `"command"`: Only the `help` subcommand is available
83
85
  * - `"option"`: Only the `--help` option is available
84
86
  * - `"both"`: Both `help` subcommand and `--help` option are available
85
- * - `object`: Advanced configuration with mode and group
86
- * - `mode`: "command" | "both"
87
- * - `group`: Group label for help command in help output (optional)
87
+ * - `object`: Advanced configuration with `command` and/or `option`
88
+ * sub-configs. At least one of `command` or `option` must be specified.
88
89
  *
89
90
  * When not provided, help functionality is disabled.
91
+ *
92
+ * @since 1.0.0
90
93
  */
91
- readonly help?: "command" | "option" | "both" | {
92
- readonly mode: "command" | "both";
93
- /**
94
- * Group label for the help command in help output.
95
- * @since 0.10.0
96
- */
97
- readonly group?: string;
98
- };
94
+ readonly help?: "command" | "option" | "both" | (({
95
+ readonly command: true | CommandSubConfig;
96
+ readonly option?: true | OptionSubConfig;
97
+ } | {
98
+ readonly option: true | OptionSubConfig;
99
+ readonly command?: true | CommandSubConfig;
100
+ }));
99
101
  /**
100
102
  * Version configuration. Determines how version is made available:
101
103
  *
102
104
  * - `string`: Version value with default `"option"` mode (--version only)
103
- * - `object`: Advanced configuration with version value and mode
104
- * - `value`: The version string to display
105
- * - `mode`: "command" | "option" | "both" (default: "option")
106
- * - `group`: Group label for version command in help output (only
107
- * when mode is "command" or "both")
105
+ * - `object`: Advanced configuration with version value and `command`
106
+ * and/or `option` sub-configs. At least one of `command` or `option`
107
+ * must be specified.
108
108
  *
109
109
  * When not provided, version functionality is disabled.
110
+ *
111
+ * @since 1.0.0
110
112
  */
111
- readonly version?: string | {
113
+ readonly version?: string | ({
112
114
  readonly value: string;
113
- readonly mode: "command" | "both";
114
- /**
115
- * Group label for the version command in help output.
116
- * @since 0.10.0
117
- */
118
- readonly group?: string;
115
+ } & ({
116
+ readonly command: true | CommandSubConfig;
117
+ readonly option?: true | OptionSubConfig;
119
118
  } | {
120
- readonly value: string;
121
- readonly mode?: "option";
122
- readonly group?: never;
123
- };
119
+ readonly option: true | OptionSubConfig;
120
+ readonly command?: true | CommandSubConfig;
121
+ }));
124
122
  /**
125
- * Completion configuration. Determines how shell completion is made available:
123
+ * Completion configuration. Determines how shell completion is made
124
+ * available:
126
125
  *
127
126
  * - `"command"`: Only the `completion` subcommand is available
128
127
  * - `"option"`: Only the `--completion` option is available
129
- * - `"both"`: Both `completion` subcommand and `--completion` option are available
130
- * - `object`: Advanced configuration with mode and custom shells
131
- * - `mode`: "command" | "option" | "both" (default: "both")
132
- * - `name`: "singular" | "plural" | "both" (default: "both")
133
- * - `helpVisibility`: "singular" | "plural" | "both" | "none"
134
- * (default: matches `name`)
135
- * - `shells`: Custom shell completions (optional)
128
+ * - `"both"`: Both `completion` subcommand and `--completion` option
129
+ * are available
130
+ * - `object`: Advanced configuration with `command` and/or `option`
131
+ * sub-configs and optional custom shells. At least one of `command`
132
+ * or `option` must be specified.
136
133
  *
137
134
  * When not provided, completion functionality is disabled.
138
135
  *
139
- * @since 0.6.0
136
+ * @since 1.0.0
140
137
  */
141
- readonly completion?: "command" | "option" | "both" | CompletionOptions;
138
+ readonly completion?: "command" | "option" | "both" | ({
139
+ readonly shells?: Record<string, ShellCompletion>;
140
+ } & ({
141
+ readonly command: true | CommandSubConfig;
142
+ readonly option?: true | OptionSubConfig;
143
+ } | {
144
+ readonly option: true | OptionSubConfig;
145
+ readonly command?: true | CommandSubConfig;
146
+ }));
142
147
  /**
143
148
  * What to display above error messages:
144
149
  *
@@ -191,49 +196,16 @@ interface RunOptions {
191
196
  * @since 0.4.0
192
197
  */
193
198
  readonly footer?: Message;
194
- }
195
- type CompletionHelpVisibility = "singular" | "plural" | "both" | "none";
196
- type CompletionOptionsBase = {
197
- readonly mode?: "command" | "both";
198
- /**
199
- * Group label for the completion command in help output.
200
- * @since 0.10.0
201
- */
202
- readonly group?: string;
203
- readonly shells?: Record<string, ShellCompletion>;
204
- } | {
205
- readonly mode: "option";
206
- readonly group?: never;
207
- readonly shells?: Record<string, ShellCompletion>;
208
- };
209
- type CompletionOptionsBoth = CompletionOptionsBase & {
210
- readonly name?: "both";
211
199
  /**
212
- * Controls which completion aliases are shown in help and usage output.
200
+ * Source contexts to use for two-phase parsing. When provided, the
201
+ * runner delegates to `runWith()` (or `runWithSync()` for sync parsers)
202
+ * from `@optique/core/facade`, which handles annotation collection and
203
+ * multi-phase parsing automatically.
213
204
  *
214
- * @since 0.10.0
215
- */
216
- readonly helpVisibility?: CompletionHelpVisibility;
217
- };
218
- type CompletionOptionsSingular = CompletionOptionsBase & {
219
- readonly name: "singular";
220
- /**
221
- * Controls which completion aliases are shown in help and usage output.
222
- *
223
- * @since 0.10.0
224
- */
225
- readonly helpVisibility?: "singular" | "none";
226
- };
227
- type CompletionOptionsPlural = CompletionOptionsBase & {
228
- readonly name: "plural";
229
- /**
230
- * Controls which completion aliases are shown in help and usage output.
231
- *
232
- * @since 0.10.0
205
+ * @since 1.0.0
233
206
  */
234
- readonly helpVisibility?: "plural" | "none";
235
- };
236
- type CompletionOptions = CompletionOptionsBoth | CompletionOptionsSingular | CompletionOptionsPlural;
207
+ readonly contexts?: readonly SourceContext<unknown>[];
208
+ }
237
209
  /**
238
210
  * Runs a command-line parser with automatic process integration.
239
211
  *
@@ -299,6 +271,9 @@ type CompletionOptions = CompletionOptionsBoth | CompletionOptionsSingular | Com
299
271
  *
300
272
  * @since 0.11.0 Added support for {@link Program} objects.
301
273
  */
274
+ declare function run<T extends Parser<Mode, unknown, unknown>, TContexts extends readonly SourceContext<unknown>[]>(parser: T, options: RunOptions & {
275
+ readonly contexts: TContexts;
276
+ } & ExtractRequiredOptions<TContexts, InferValue<T>>): Promise<InferValue<T>>;
302
277
  declare function run<T>(program: Program<"sync", T>, options?: RunOptions): T;
303
278
  declare function run<T>(program: Program<"async", T>, options?: RunOptions): Promise<T>;
304
279
  declare function run<T extends Parser<"sync", unknown, unknown>>(parser: T, options?: RunOptions): InferValue<T>;
@@ -317,6 +292,9 @@ declare function run<T extends Parser<Mode, unknown, unknown>>(parser: T, option
317
292
  * @returns The parsed result if successful.
318
293
  * @since 0.9.0
319
294
  */
295
+ declare function runSync<T extends Parser<"sync", unknown, unknown>, TContexts extends readonly SourceContext<unknown>[]>(parser: T, options: RunOptions & {
296
+ readonly contexts: TContexts;
297
+ } & ExtractRequiredOptions<TContexts, InferValue<T>>): InferValue<T>;
320
298
  declare function runSync<T>(program: Program<"sync", T>, options?: RunOptions): T;
321
299
  declare function runSync<T extends Parser<"sync", unknown, unknown>>(parser: T, options?: RunOptions): InferValue<T>;
322
300
  /**
@@ -332,6 +310,9 @@ declare function runSync<T extends Parser<"sync", unknown, unknown>>(parser: T,
332
310
  * @returns A Promise of the parsed result if successful.
333
311
  * @since 0.9.0
334
312
  */
313
+ declare function runAsync<T extends Parser<Mode, unknown, unknown>, TContexts extends readonly SourceContext<unknown>[]>(parser: T, options: RunOptions & {
314
+ readonly contexts: TContexts;
315
+ } & ExtractRequiredOptions<TContexts, InferValue<T>>): Promise<InferValue<T>>;
335
316
  declare function runAsync<T>(program: Program<"sync", T>, options?: RunOptions): Promise<T>;
336
317
  declare function runAsync<T>(program: Program<"async", T>, options?: RunOptions): Promise<T>;
337
318
  declare function runAsync<T extends Parser<Mode, unknown, unknown>>(parser: T, options?: RunOptions): Promise<InferValue<T>>;
package/dist/run.d.ts CHANGED
@@ -1,5 +1,7 @@
1
+ import { CommandSubConfig, ExtractRequiredOptions, OptionSubConfig } from "@optique/core/facade";
1
2
  import { Message } from "@optique/core/message";
2
3
  import { ShellCompletion } from "@optique/core/completion";
4
+ import { SourceContext } from "@optique/core/context";
3
5
  import { InferMode, InferValue, Mode, ModeValue, Parser } from "@optique/core/parser";
4
6
  import { Program } from "@optique/core/program";
5
7
  import { DocSection, ShowChoicesOptions, ShowDefaultOptions } from "@optique/core/doc";
@@ -82,63 +84,66 @@ interface RunOptions {
82
84
  * - `"command"`: Only the `help` subcommand is available
83
85
  * - `"option"`: Only the `--help` option is available
84
86
  * - `"both"`: Both `help` subcommand and `--help` option are available
85
- * - `object`: Advanced configuration with mode and group
86
- * - `mode`: "command" | "both"
87
- * - `group`: Group label for help command in help output (optional)
87
+ * - `object`: Advanced configuration with `command` and/or `option`
88
+ * sub-configs. At least one of `command` or `option` must be specified.
88
89
  *
89
90
  * When not provided, help functionality is disabled.
91
+ *
92
+ * @since 1.0.0
90
93
  */
91
- readonly help?: "command" | "option" | "both" | {
92
- readonly mode: "command" | "both";
93
- /**
94
- * Group label for the help command in help output.
95
- * @since 0.10.0
96
- */
97
- readonly group?: string;
98
- };
94
+ readonly help?: "command" | "option" | "both" | (({
95
+ readonly command: true | CommandSubConfig;
96
+ readonly option?: true | OptionSubConfig;
97
+ } | {
98
+ readonly option: true | OptionSubConfig;
99
+ readonly command?: true | CommandSubConfig;
100
+ }));
99
101
  /**
100
102
  * Version configuration. Determines how version is made available:
101
103
  *
102
104
  * - `string`: Version value with default `"option"` mode (--version only)
103
- * - `object`: Advanced configuration with version value and mode
104
- * - `value`: The version string to display
105
- * - `mode`: "command" | "option" | "both" (default: "option")
106
- * - `group`: Group label for version command in help output (only
107
- * when mode is "command" or "both")
105
+ * - `object`: Advanced configuration with version value and `command`
106
+ * and/or `option` sub-configs. At least one of `command` or `option`
107
+ * must be specified.
108
108
  *
109
109
  * When not provided, version functionality is disabled.
110
+ *
111
+ * @since 1.0.0
110
112
  */
111
- readonly version?: string | {
113
+ readonly version?: string | ({
112
114
  readonly value: string;
113
- readonly mode: "command" | "both";
114
- /**
115
- * Group label for the version command in help output.
116
- * @since 0.10.0
117
- */
118
- readonly group?: string;
115
+ } & ({
116
+ readonly command: true | CommandSubConfig;
117
+ readonly option?: true | OptionSubConfig;
119
118
  } | {
120
- readonly value: string;
121
- readonly mode?: "option";
122
- readonly group?: never;
123
- };
119
+ readonly option: true | OptionSubConfig;
120
+ readonly command?: true | CommandSubConfig;
121
+ }));
124
122
  /**
125
- * Completion configuration. Determines how shell completion is made available:
123
+ * Completion configuration. Determines how shell completion is made
124
+ * available:
126
125
  *
127
126
  * - `"command"`: Only the `completion` subcommand is available
128
127
  * - `"option"`: Only the `--completion` option is available
129
- * - `"both"`: Both `completion` subcommand and `--completion` option are available
130
- * - `object`: Advanced configuration with mode and custom shells
131
- * - `mode`: "command" | "option" | "both" (default: "both")
132
- * - `name`: "singular" | "plural" | "both" (default: "both")
133
- * - `helpVisibility`: "singular" | "plural" | "both" | "none"
134
- * (default: matches `name`)
135
- * - `shells`: Custom shell completions (optional)
128
+ * - `"both"`: Both `completion` subcommand and `--completion` option
129
+ * are available
130
+ * - `object`: Advanced configuration with `command` and/or `option`
131
+ * sub-configs and optional custom shells. At least one of `command`
132
+ * or `option` must be specified.
136
133
  *
137
134
  * When not provided, completion functionality is disabled.
138
135
  *
139
- * @since 0.6.0
136
+ * @since 1.0.0
140
137
  */
141
- readonly completion?: "command" | "option" | "both" | CompletionOptions;
138
+ readonly completion?: "command" | "option" | "both" | ({
139
+ readonly shells?: Record<string, ShellCompletion>;
140
+ } & ({
141
+ readonly command: true | CommandSubConfig;
142
+ readonly option?: true | OptionSubConfig;
143
+ } | {
144
+ readonly option: true | OptionSubConfig;
145
+ readonly command?: true | CommandSubConfig;
146
+ }));
142
147
  /**
143
148
  * What to display above error messages:
144
149
  *
@@ -191,49 +196,16 @@ interface RunOptions {
191
196
  * @since 0.4.0
192
197
  */
193
198
  readonly footer?: Message;
194
- }
195
- type CompletionHelpVisibility = "singular" | "plural" | "both" | "none";
196
- type CompletionOptionsBase = {
197
- readonly mode?: "command" | "both";
198
- /**
199
- * Group label for the completion command in help output.
200
- * @since 0.10.0
201
- */
202
- readonly group?: string;
203
- readonly shells?: Record<string, ShellCompletion>;
204
- } | {
205
- readonly mode: "option";
206
- readonly group?: never;
207
- readonly shells?: Record<string, ShellCompletion>;
208
- };
209
- type CompletionOptionsBoth = CompletionOptionsBase & {
210
- readonly name?: "both";
211
199
  /**
212
- * Controls which completion aliases are shown in help and usage output.
200
+ * Source contexts to use for two-phase parsing. When provided, the
201
+ * runner delegates to `runWith()` (or `runWithSync()` for sync parsers)
202
+ * from `@optique/core/facade`, which handles annotation collection and
203
+ * multi-phase parsing automatically.
213
204
  *
214
- * @since 0.10.0
215
- */
216
- readonly helpVisibility?: CompletionHelpVisibility;
217
- };
218
- type CompletionOptionsSingular = CompletionOptionsBase & {
219
- readonly name: "singular";
220
- /**
221
- * Controls which completion aliases are shown in help and usage output.
222
- *
223
- * @since 0.10.0
224
- */
225
- readonly helpVisibility?: "singular" | "none";
226
- };
227
- type CompletionOptionsPlural = CompletionOptionsBase & {
228
- readonly name: "plural";
229
- /**
230
- * Controls which completion aliases are shown in help and usage output.
231
- *
232
- * @since 0.10.0
205
+ * @since 1.0.0
233
206
  */
234
- readonly helpVisibility?: "plural" | "none";
235
- };
236
- type CompletionOptions = CompletionOptionsBoth | CompletionOptionsSingular | CompletionOptionsPlural;
207
+ readonly contexts?: readonly SourceContext<unknown>[];
208
+ }
237
209
  /**
238
210
  * Runs a command-line parser with automatic process integration.
239
211
  *
@@ -299,6 +271,9 @@ type CompletionOptions = CompletionOptionsBoth | CompletionOptionsSingular | Com
299
271
  *
300
272
  * @since 0.11.0 Added support for {@link Program} objects.
301
273
  */
274
+ declare function run<T extends Parser<Mode, unknown, unknown>, TContexts extends readonly SourceContext<unknown>[]>(parser: T, options: RunOptions & {
275
+ readonly contexts: TContexts;
276
+ } & ExtractRequiredOptions<TContexts, InferValue<T>>): Promise<InferValue<T>>;
302
277
  declare function run<T>(program: Program<"sync", T>, options?: RunOptions): T;
303
278
  declare function run<T>(program: Program<"async", T>, options?: RunOptions): Promise<T>;
304
279
  declare function run<T extends Parser<"sync", unknown, unknown>>(parser: T, options?: RunOptions): InferValue<T>;
@@ -317,6 +292,9 @@ declare function run<T extends Parser<Mode, unknown, unknown>>(parser: T, option
317
292
  * @returns The parsed result if successful.
318
293
  * @since 0.9.0
319
294
  */
295
+ declare function runSync<T extends Parser<"sync", unknown, unknown>, TContexts extends readonly SourceContext<unknown>[]>(parser: T, options: RunOptions & {
296
+ readonly contexts: TContexts;
297
+ } & ExtractRequiredOptions<TContexts, InferValue<T>>): InferValue<T>;
320
298
  declare function runSync<T>(program: Program<"sync", T>, options?: RunOptions): T;
321
299
  declare function runSync<T extends Parser<"sync", unknown, unknown>>(parser: T, options?: RunOptions): InferValue<T>;
322
300
  /**
@@ -332,6 +310,9 @@ declare function runSync<T extends Parser<"sync", unknown, unknown>>(parser: T,
332
310
  * @returns A Promise of the parsed result if successful.
333
311
  * @since 0.9.0
334
312
  */
313
+ declare function runAsync<T extends Parser<Mode, unknown, unknown>, TContexts extends readonly SourceContext<unknown>[]>(parser: T, options: RunOptions & {
314
+ readonly contexts: TContexts;
315
+ } & ExtractRequiredOptions<TContexts, InferValue<T>>): Promise<InferValue<T>>;
335
316
  declare function runAsync<T>(program: Program<"sync", T>, options?: RunOptions): Promise<T>;
336
317
  declare function runAsync<T>(program: Program<"async", T>, options?: RunOptions): Promise<T>;
337
318
  declare function runAsync<T extends Parser<Mode, unknown, unknown>>(parser: T, options?: RunOptions): Promise<InferValue<T>>;
package/dist/run.js CHANGED
@@ -1,4 +1,4 @@
1
- import { runParser } from "@optique/core/facade";
1
+ import { runParser, runWith, runWithSync } from "@optique/core/facade";
2
2
  import path from "node:path";
3
3
  import process from "node:process";
4
4
 
@@ -7,97 +7,112 @@ function run(parserOrProgram, options = {}) {
7
7
  return runImpl(parserOrProgram, options);
8
8
  }
9
9
  function runSync(parserOrProgram, options = {}) {
10
+ const contexts = options.contexts;
11
+ if (contexts && contexts.length > 0) {
12
+ const isProgram = "parser" in parserOrProgram && "metadata" in parserOrProgram;
13
+ let parser;
14
+ let programMetadata;
15
+ if (isProgram) {
16
+ const program = parserOrProgram;
17
+ parser = program.parser;
18
+ if (!options.programName) options = {
19
+ ...options,
20
+ programName: program.metadata.name
21
+ };
22
+ programMetadata = {
23
+ brief: program.metadata.brief,
24
+ description: program.metadata.description,
25
+ examples: program.metadata.examples,
26
+ author: program.metadata.author,
27
+ bugs: program.metadata.bugs,
28
+ footer: program.metadata.footer
29
+ };
30
+ } else parser = parserOrProgram;
31
+ const { programName, args, coreOptions } = buildCoreOptions(options, programMetadata);
32
+ const contextOptions = {};
33
+ for (const key of Object.keys(options)) if (!knownRunOptionsKeys.has(key)) contextOptions[key] = options[key];
34
+ const runWithOptions = {
35
+ ...coreOptions,
36
+ ...contextOptions,
37
+ args
38
+ };
39
+ return runWithSync(parser, programName, contexts, runWithOptions);
40
+ }
10
41
  return runImpl(parserOrProgram, options);
11
42
  }
12
43
  function runAsync(parserOrProgram, options = {}) {
13
44
  const result = runImpl(parserOrProgram, options);
14
45
  return Promise.resolve(result);
15
46
  }
16
- function runImpl(parserOrProgram, options = {}) {
17
- const isProgram = "parser" in parserOrProgram && "metadata" in parserOrProgram;
18
- let parser;
19
- let programNameFromProgram;
20
- let programMetadata;
21
- if (isProgram) {
22
- const program = parserOrProgram;
23
- parser = program.parser;
24
- programNameFromProgram = program.metadata.name;
25
- programMetadata = {
26
- brief: program.metadata.brief,
27
- description: program.metadata.description,
28
- examples: program.metadata.examples,
29
- author: program.metadata.author,
30
- bugs: program.metadata.bugs,
31
- footer: program.metadata.footer
47
+ /**
48
+ * Builds core run options from the simplified RunOptions format.
49
+ *
50
+ * Converts the user-friendly RunOptions (string-based help/version/completion)
51
+ * into the verbose CoreRunOptions format expected by `runParser()`, `runWith()`,
52
+ * and `runWithSync()` from `@optique/core/facade`.
53
+ *
54
+ * @internal
55
+ */
56
+ function buildCoreOptions(options, programMetadata) {
57
+ const { programName = path.basename(process.argv[1] || "cli"), args = process.argv.slice(2), colors = process.stdout.isTTY, maxWidth = process.stdout.columns, showDefault, showChoices, sectionOrder, help, version, completion, aboveError = "usage", errorExitCode = 1, brief = programMetadata?.brief, description = programMetadata?.description, examples = programMetadata?.examples, author = programMetadata?.author, bugs = programMetadata?.bugs, footer = programMetadata?.footer } = options;
58
+ const onShow = () => process.exit(0);
59
+ const helpConfig = (() => {
60
+ if (!help) return void 0;
61
+ if (typeof help === "string") switch (help) {
62
+ case "command": return {
63
+ command: true,
64
+ onShow
65
+ };
66
+ case "option": return {
67
+ option: true,
68
+ onShow
69
+ };
70
+ case "both": return {
71
+ command: true,
72
+ option: true,
73
+ onShow
74
+ };
75
+ }
76
+ return {
77
+ ...help,
78
+ onShow
32
79
  };
33
- } else parser = parserOrProgram;
34
- const { programName = programNameFromProgram ?? path.basename(process.argv[1] || "cli"), args = process.argv.slice(2), colors = process.stdout.isTTY, maxWidth = process.stdout.columns, showDefault, showChoices, sectionOrder, help, version, completion, aboveError = "usage", errorExitCode = 1, brief = programMetadata?.brief, description = programMetadata?.description, examples = programMetadata?.examples, author = programMetadata?.author, bugs = programMetadata?.bugs, footer = programMetadata?.footer } = options;
35
- const helpConfig = help ? typeof help === "string" ? {
36
- mode: help,
37
- onShow: () => process.exit(0)
38
- } : {
39
- mode: help.mode,
40
- group: help.group,
41
- onShow: () => process.exit(0)
42
- } : void 0;
80
+ })();
43
81
  const versionConfig = (() => {
44
82
  if (!version) return void 0;
45
83
  if (typeof version === "string") return {
46
- mode: "option",
47
84
  value: version,
48
- onShow: () => process.exit(0)
49
- };
50
- const mode = version.mode ?? "option";
51
- if (mode === "command" || mode === "both") return {
52
- mode,
53
- value: version.value,
54
- group: version.group,
55
- onShow: () => process.exit(0)
85
+ option: true,
86
+ onShow
56
87
  };
57
88
  return {
58
- mode,
59
- value: version.value,
60
- onShow: () => process.exit(0)
89
+ ...version,
90
+ onShow
61
91
  };
62
92
  })();
63
93
  const completionConfig = (() => {
64
94
  if (!completion) return void 0;
65
- const onShow = () => process.exit(0);
66
- if (typeof completion === "string") return {
67
- mode: completion,
68
- name: "both",
69
- helpVisibility: "both",
70
- onShow
71
- };
72
- const mode = completion.mode ?? "both";
73
- const shells = completion.shells;
74
- const cGroup = completion.group;
75
- if (completion.name === "singular") return {
76
- mode,
77
- shells,
78
- ...cGroup != null && { group: cGroup },
79
- name: "singular",
80
- helpVisibility: completion.helpVisibility ?? "singular",
81
- onShow
82
- };
83
- if (completion.name === "plural") return {
84
- mode,
85
- shells,
86
- ...cGroup != null && { group: cGroup },
87
- name: "plural",
88
- helpVisibility: completion.helpVisibility ?? "plural",
89
- onShow
90
- };
95
+ if (typeof completion === "string") switch (completion) {
96
+ case "command": return {
97
+ command: true,
98
+ onShow
99
+ };
100
+ case "option": return {
101
+ option: true,
102
+ onShow
103
+ };
104
+ case "both": return {
105
+ command: true,
106
+ option: true,
107
+ onShow
108
+ };
109
+ }
91
110
  return {
92
- mode,
93
- shells,
94
- ...cGroup != null && { group: cGroup },
95
- name: "both",
96
- helpVisibility: completion.helpVisibility ?? "both",
111
+ ...completion,
97
112
  onShow
98
113
  };
99
114
  })();
100
- return runParser(parser, programName, args, {
115
+ const coreOptions = {
101
116
  stderr(line) {
102
117
  process.stderr.write(`${line}\n`);
103
118
  },
@@ -122,7 +137,73 @@ function runImpl(parserOrProgram, options = {}) {
122
137
  onError() {
123
138
  return process.exit(errorExitCode);
124
139
  }
125
- });
140
+ };
141
+ return {
142
+ programName,
143
+ args,
144
+ coreOptions
145
+ };
146
+ }
147
+ /**
148
+ * Set of known RunOptions field names. Used by `runImpl()` to separate
149
+ * RunOptions fields from context-required options via rest-spread.
150
+ */
151
+ const knownRunOptionsKeys = new Set([
152
+ "programName",
153
+ "args",
154
+ "colors",
155
+ "maxWidth",
156
+ "showDefault",
157
+ "showChoices",
158
+ "sectionOrder",
159
+ "help",
160
+ "version",
161
+ "completion",
162
+ "aboveError",
163
+ "errorExitCode",
164
+ "brief",
165
+ "description",
166
+ "examples",
167
+ "author",
168
+ "bugs",
169
+ "footer",
170
+ "contexts"
171
+ ]);
172
+ function runImpl(parserOrProgram, options = {}) {
173
+ const isProgram = "parser" in parserOrProgram && "metadata" in parserOrProgram;
174
+ let parser;
175
+ let programMetadata;
176
+ if (isProgram) {
177
+ const program = parserOrProgram;
178
+ parser = program.parser;
179
+ const programNameFromProgram = program.metadata.name;
180
+ programMetadata = {
181
+ brief: program.metadata.brief,
182
+ description: program.metadata.description,
183
+ examples: program.metadata.examples,
184
+ author: program.metadata.author,
185
+ bugs: program.metadata.bugs,
186
+ footer: program.metadata.footer
187
+ };
188
+ if (!options.programName) options = {
189
+ ...options,
190
+ programName: programNameFromProgram
191
+ };
192
+ } else parser = parserOrProgram;
193
+ const contexts = options.contexts;
194
+ if (contexts && contexts.length > 0) {
195
+ const { programName: programName$1, args: args$1, coreOptions: coreOptions$1 } = buildCoreOptions(options, programMetadata);
196
+ const contextOptions = {};
197
+ for (const key of Object.keys(options)) if (!knownRunOptionsKeys.has(key)) contextOptions[key] = options[key];
198
+ const runWithOptions = {
199
+ ...coreOptions$1,
200
+ ...contextOptions,
201
+ args: args$1
202
+ };
203
+ return runWith(parser, programName$1, contexts, runWithOptions);
204
+ }
205
+ const { programName, args, coreOptions } = buildCoreOptions(options, programMetadata);
206
+ return runParser(parser, programName, args, coreOptions);
126
207
  }
127
208
 
128
209
  //#endregion
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@optique/run",
3
- "version": "1.0.0-dev.429+66edc8ed",
3
+ "version": "1.0.0-dev.432+dddcca3d",
4
4
  "description": "Type-safe combinatorial command-line interface parser",
5
5
  "keywords": [
6
6
  "CLI",
@@ -70,7 +70,7 @@
70
70
  },
71
71
  "sideEffects": false,
72
72
  "dependencies": {
73
- "@optique/core": "1.0.0-dev.429+66edc8ed"
73
+ "@optique/core": "1.0.0-dev.432+dddcca3d"
74
74
  },
75
75
  "devDependencies": {
76
76
  "@types/node": "^20.19.9",