@politty/zod 0.0.0

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 (41) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +561 -0
  3. package/bin/cli.mjs +3 -0
  4. package/dist/arg-registry-YaWTVu_x.d.ts +1025 -0
  5. package/dist/augment.d.ts +15 -0
  6. package/dist/augment.js +1 -0
  7. package/dist/cli-main-Dn88vIyn.js +84 -0
  8. package/dist/cli-run-eibUcgys.js +7 -0
  9. package/dist/cli.d.ts +1 -0
  10. package/dist/cli.js +16 -0
  11. package/dist/command-k-4yAz4J.js +42 -0
  12. package/dist/compile-cache-Ct41pWGL.js +100 -0
  13. package/dist/compile-cache.d.ts +78 -0
  14. package/dist/compile-cache.js +3 -0
  15. package/dist/completion-gtWX3mwP.js +5608 -0
  16. package/dist/completion.d.ts +242 -0
  17. package/dist/completion.js +4 -0
  18. package/dist/docs.d.ts +770 -0
  19. package/dist/docs.js +3044 -0
  20. package/dist/field-meta-DMy5BcRr.js +146 -0
  21. package/dist/index-CvhsecfS.d.ts +455 -0
  22. package/dist/index.d.ts +799 -0
  23. package/dist/index.js +17 -0
  24. package/dist/log-collector-CoUkLVJB.js +114 -0
  25. package/dist/logger-i_bb-Jhc.js +133 -0
  26. package/dist/prompt-CEIZ-7H1.js +171 -0
  27. package/dist/prompt-clack.d.ts +16 -0
  28. package/dist/prompt-clack.js +32 -0
  29. package/dist/prompt-inquirer.d.ts +16 -0
  30. package/dist/prompt-inquirer.js +47 -0
  31. package/dist/prompt.d.ts +106 -0
  32. package/dist/prompt.js +4 -0
  33. package/dist/register-Bk0K83W2.js +439 -0
  34. package/dist/runner-D72I7wvK.js +2956 -0
  35. package/dist/runner-FvUwOHyE.js +3 -0
  36. package/dist/schema-extractor-DMSozq40.js +250 -0
  37. package/dist/skill.d.ts +608 -0
  38. package/dist/skill.js +1832 -0
  39. package/dist/src-KzC0g5CS.js +191 -0
  40. package/dist/subcommand-router-Cskpofdk.js +134 -0
  41. package/package.json +103 -0
@@ -0,0 +1,146 @@
1
+ //#region ../core/src/adapter/registry.ts
2
+ let registered;
3
+ /**
4
+ * Register the validator adapter core should use for user schemas.
5
+ * Registration unconditionally replaces the current adapter, so every
6
+ * adapter entry module may call this safely — repeated registration of
7
+ * the same adapter has no observable effect.
8
+ *
9
+ * Single-adapter assumption: the registry holds one adapter per process
10
+ * (last registration wins) — a CLI is built against exactly one schema
11
+ * library. If mixing adapters in one process ever becomes a supported
12
+ * scenario, this needs per-schema vendor dispatch instead.
13
+ */
14
+ function registerValidatorAdapter(adapter) {
15
+ registered = adapter;
16
+ }
17
+ /**
18
+ * Resolve the registered validator adapter.
19
+ *
20
+ * @throws if no adapter has been registered — i.e. core was imported
21
+ * directly instead of through an adapter package entry.
22
+ */
23
+ function getValidatorAdapter() {
24
+ if (!registered) throw new Error("No validator adapter registered. Import politty through an adapter package (e.g. `import { defineCommand } from \"@politty/zod\"` or `from \"politty\"`) so the schema library integration is set up.");
25
+ return registered;
26
+ }
27
+
28
+ //#endregion
29
+ //#region ../core/src/adapter/field-meta.ts
30
+ /**
31
+ * Long flag names reserved for built-in handling (parseArgs / scanForSubcommand
32
+ * intercept these before option parsing), so custom negation names must avoid them.
33
+ */
34
+ const RESERVED_NEGATION_NAMES = /* @__PURE__ */ new Set([
35
+ "help",
36
+ "help-all",
37
+ "version"
38
+ ]);
39
+ /**
40
+ * Convert camelCase to kebab-case
41
+ * @example toKebabCase("dryRun") => "dry-run"
42
+ * @example toKebabCase("outputDir") => "output-dir"
43
+ * @example toKebabCase("XMLParser") => "xml-parser"
44
+ */
45
+ function toKebabCase(str) {
46
+ return str.replace(/([a-z])([A-Z])/g, "$1-$2").replace(/([A-Z]+)([A-Z][a-z])/g, "$1-$2").toLowerCase();
47
+ }
48
+ /**
49
+ * Convert hyphen-separated sequences to camelCase.
50
+ *
51
+ * Replaces `-x` (hyphen followed by a lowercase letter) with the uppercase
52
+ * variant. Non-hyphenated input (e.g., already camelCase) is returned as-is.
53
+ *
54
+ * @param str - A string that may contain hyphens
55
+ * @example toCamelCase("dry-run") => "dryRun"
56
+ * @example toCamelCase("output-dir") => "outputDir"
57
+ * @example toCamelCase("dryRun") => "dryRun"
58
+ */
59
+ function toCamelCase(str) {
60
+ return str.replace(/-([a-z])/g, (_, char) => char.toUpperCase());
61
+ }
62
+ /**
63
+ * Get the combined list of visible + hidden aliases for a field.
64
+ * Used by the parser and validators which treat both equally,
65
+ * while help/docs/completion rely on `field.alias` only.
66
+ */
67
+ function getAllAliases(field) {
68
+ if (!field.alias && !field.hiddenAlias) return [];
69
+ return [...field.alias ?? [], ...field.hiddenAlias ?? []];
70
+ }
71
+ /**
72
+ * Assemble a {@link ResolvedFieldMeta} from adapter-provided introspection.
73
+ * Single source of truth for alias/negation normalization and validation.
74
+ */
75
+ function resolveFieldMeta(name, intro) {
76
+ const argMeta = intro.argMeta;
77
+ const description = argMeta?.description ?? intro.description;
78
+ const cliName = toKebabCase(name);
79
+ const aliasPattern = /^[A-Za-z0-9][A-Za-z0-9-]*$/;
80
+ const normalizeAliasList = (input, metaKey) => {
81
+ if (input == null) return void 0;
82
+ const normalized = (Array.isArray(input) ? input : [input]).map((a) => {
83
+ if (typeof a !== "string") throw new Error(`Invalid ${metaKey} for field "${name}": expected string or string[], received ${typeof a}.`);
84
+ const candidate = a.trim().replace(/^-+/, "");
85
+ if (candidate.length === 0 || !aliasPattern.test(candidate)) throw new Error(`Invalid ${metaKey} "${a}" for field "${name}": aliases must match ${aliasPattern}.`);
86
+ return candidate;
87
+ });
88
+ const result = Array.from(new Set(normalized));
89
+ return result.length > 0 ? result : void 0;
90
+ };
91
+ const alias = normalizeAliasList(argMeta?.alias, "alias");
92
+ const visibleSet = new Set(alias ?? []);
93
+ const hiddenAlias = normalizeAliasList(argMeta?.hiddenAlias, "hiddenAlias")?.filter((a) => !visibleSet.has(a));
94
+ const hiddenAliasFinal = hiddenAlias && hiddenAlias.length > 0 ? hiddenAlias : void 0;
95
+ const fieldType = intro.type;
96
+ const rawNegation = argMeta?.negation;
97
+ let negation;
98
+ if (rawNegation !== void 0 && rawNegation !== null) if (typeof rawNegation === "boolean") {
99
+ if (fieldType !== "boolean") throw new Error(`Invalid negation for field "${name}": negation can only be used on boolean fields.`);
100
+ negation = rawNegation;
101
+ } else {
102
+ if (typeof rawNegation !== "string") throw new Error(`Invalid negation for field "${name}": expected string or boolean, received ${typeof rawNegation}.`);
103
+ const candidate = rawNegation.trim().replace(/^-+/, "");
104
+ if (candidate.length === 0 || !aliasPattern.test(candidate)) throw new Error(`Invalid negation "${rawNegation}" for field "${name}": negation names must match ${aliasPattern}.`);
105
+ if (RESERVED_NEGATION_NAMES.has(candidate)) throw new Error(`Invalid negation "${rawNegation}" for field "${name}": negation cannot use reserved built-in flag names (${[...RESERVED_NEGATION_NAMES].map((n) => `--${n}`).join(", ")}).`);
106
+ if (fieldType !== "boolean") throw new Error(`Invalid negation for field "${name}": negation can only be used on boolean fields.`);
107
+ negation = candidate;
108
+ }
109
+ const rawNegationDescription = argMeta?.negationDescription;
110
+ let negationDescription;
111
+ if (rawNegationDescription !== void 0 && rawNegationDescription !== null) {
112
+ if (typeof rawNegationDescription !== "string") throw new Error(`Invalid negationDescription for field "${name}": expected string, received ${typeof rawNegationDescription}.`);
113
+ if (negation === false) throw new Error(`Invalid negationDescription for field "${name}": negationDescription cannot be used when negation is false.`);
114
+ if (negation === void 0) throw new Error(`Invalid negationDescription for field "${name}": negationDescription requires \`negation\` to be set (string or true).`);
115
+ const trimmed = rawNegationDescription.trim();
116
+ if (trimmed.length === 0) throw new Error(`Invalid negationDescription for field "${name}": negationDescription must be a non-empty string.`);
117
+ negationDescription = trimmed;
118
+ }
119
+ const negationDisplay = typeof negation === "string" ? negation : negation === true ? `no-${cliName}` : void 0;
120
+ const meta = {
121
+ name,
122
+ cliName,
123
+ alias,
124
+ hiddenAlias: hiddenAliasFinal,
125
+ description,
126
+ positional: argMeta?.positional ?? false,
127
+ placeholder: argMeta?.placeholder,
128
+ env: argMeta?.env,
129
+ required: intro.required,
130
+ defaultValue: intro.defaultValue,
131
+ type: fieldType,
132
+ schema: intro.schema,
133
+ enumValues: intro.enumValues,
134
+ completion: argMeta?.completion,
135
+ prompt: argMeta?.prompt,
136
+ negation,
137
+ negationDisplay,
138
+ negationDescription,
139
+ effect: argMeta?.effect
140
+ };
141
+ if (argMeta && "overrideBuiltinAlias" in argMeta && argMeta.overrideBuiltinAlias === true) meta.overrideBuiltinAlias = true;
142
+ return meta;
143
+ }
144
+
145
+ //#endregion
146
+ export { getValidatorAdapter as a, toKebabCase as i, resolveFieldMeta as n, registerValidatorAdapter as o, toCamelCase as r, getAllAliases as t };
@@ -0,0 +1,455 @@
1
+ import { C as Command, Z as UnknownKeysMode, b as ArgsSchema, f as ResolvedExpandCandidate, g as DynamicCompletionResolver, n as ArgMeta, v as AnyCommand } from "./arg-registry-YaWTVu_x.js";
2
+ //#region ../core/src/adapter/internal-args.d.ts
3
+ /** Runtime brand distinguishing internal descriptors from library schemas. */
4
+ declare const INTERNAL_ARGS_BRAND = "__polittyInternalArgs";
5
+ type InternalFieldKind = "string" | "boolean" | "enum" | "string-array";
6
+ interface InternalFieldSpec {
7
+ kind: InternalFieldKind;
8
+ /** Allowed values (enum kind only) */
9
+ enumValues?: readonly string[] | undefined;
10
+ /** Whether omitting the value is allowed without a default */
11
+ optional: boolean;
12
+ /** Default applied when the value is missing */
13
+ defaultValue?: unknown;
14
+ /**
15
+ * arg()-style metadata (description, positional, alias, ...).
16
+ * Stored as `ArgMeta<any>`: `ArgMeta`'s `effect` callback makes the type
17
+ * contravariant in its value parameter, so the precisely-typed metas the
18
+ * builders accept only unify under `any`.
19
+ */
20
+ meta?: ArgMeta<any> | undefined;
21
+ }
22
+ /**
23
+ * An internal args schema. The `& ArgsSchema` half is a deliberate
24
+ * type-level fiction: the runtime object has none of a schema library's
25
+ * methods, but presenting it as an {@link ArgsSchema} lets internal
26
+ * commands flow through `defineCommand` and `Command<...>` without widening
27
+ * politty's public types. Nothing ever calls schema methods on it — the
28
+ * extract/validate facades check {@link isInternalArgsSchema} first.
29
+ */
30
+ type InternalArgsSchema<TOut extends Record<string, unknown> = Record<string, unknown>> = {
31
+ readonly [INTERNAL_ARGS_BRAND]: true;
32
+ readonly fields: Record<string, InternalFieldSpec>;
33
+ readonly unknownKeys: UnknownKeysMode;
34
+ readonly __out?: TOut;
35
+ } & ArgsSchema;
36
+ /** Infer the validated output type of an {@link internalArgs} descriptor. */
37
+ type InferInternalArgs<S> = S extends {
38
+ readonly __out?: infer TOut;
39
+ } ? NonNullable<TOut> : never;
40
+ //#endregion
41
+ //#region ../core/src/completion/types.d.ts
42
+ /**
43
+ * A single resolved entry in an "expand" lookup table.
44
+ *
45
+ * `key` is the tuple of `dependsOn` values that triggers this entry, in the
46
+ * same order as the originating `dependsOn` array. `candidates` is the
47
+ * (already deduplicated) list returned by the user's `enumerate` callback
48
+ * for that combination.
49
+ */
50
+ interface ExpandTableEntry {
51
+ readonly key: readonly string[];
52
+ readonly candidates: readonly ResolvedExpandCandidate[];
53
+ }
54
+ /**
55
+ * Supported shell types for completion
56
+ */
57
+ type ShellType = "bash" | "zsh" | "fish";
58
+ /**
59
+ * Completion script generation mode.
60
+ *
61
+ * - `dispatcher`: small runtime script that resolves the executable visible on
62
+ * PATH at TAB time and delegates to its `__complete` command.
63
+ * - `static`: self-contained script with command metadata baked in at
64
+ * generation time.
65
+ */
66
+ type CompletionMode = "dispatcher" | "static";
67
+ /**
68
+ * Optional published worker artifact lookup.
69
+ *
70
+ * Paths are resolved relative to the visible executable's real directory.
71
+ * Templates may include `{shell}`, `{ext}`, and `{program}`.
72
+ */
73
+ interface BundledWorkerOptions {
74
+ /** Disable bundled-worker lookup while keeping cache/dynamic fallbacks. */
75
+ disabled?: boolean | undefined;
76
+ /** Shell-specific worker paths relative to the executable directory. */
77
+ relativePaths?: Partial<Record<ShellType, readonly string[]>> | undefined;
78
+ /**
79
+ * Let dispatcher scripts ask the CLI for `__completion-worker-path <shell>`
80
+ * when package-relative lookup misses. Disabled by default because it starts
81
+ * the CLI process on that miss path.
82
+ */
83
+ queryCommand?: boolean | undefined;
84
+ }
85
+ /**
86
+ * Options for completion generation
87
+ */
88
+ interface CompletionOptions {
89
+ /** The shell type to generate completion for */
90
+ shell: ShellType;
91
+ /** The command name as it will be invoked */
92
+ programName: string;
93
+ /** Include subcommand completions (default: true) */
94
+ includeSubcommands?: boolean;
95
+ /** Include description in completions where supported (default: true) */
96
+ includeDescriptions?: boolean;
97
+ /**
98
+ * Completion script mode.
99
+ *
100
+ * `generateCompletion` defaults to `static` when this is omitted. The
101
+ * `completion <shell>` subcommand passes `dispatcher` explicitly by default.
102
+ */
103
+ mode?: CompletionMode;
104
+ /** Global args schema for deriving global options in completion */
105
+ globalArgsSchema?: ArgsSchema;
106
+ /**
107
+ * Path to the binary whose mtime is the freshness signature.
108
+ * Defaults to `process.argv[1]`.
109
+ */
110
+ binPath?: string;
111
+ /** Program version to embed in the script header. */
112
+ programVersion?: string;
113
+ /**
114
+ * Cache directory for the loader to write the regenerated script into.
115
+ * Defaults to `${XDG_CACHE_HOME:-$HOME/.cache}/<programName>` at runtime.
116
+ * Setting this hardcodes the location into the generated loader.
117
+ */
118
+ cacheDir?: string;
119
+ /**
120
+ * Internal static-worker generation hook used by dispatcher caches.
121
+ * Worker scripts define suffixed functions and skip shell registration.
122
+ */
123
+ staticWorker?: {
124
+ functionSuffix: string;
125
+ };
126
+ /** Published static-worker artifact lookup used by dispatcher mode. */
127
+ bundledWorker?: BundledWorkerOptions | undefined;
128
+ }
129
+ /**
130
+ * Value completion specification for shell scripts.
131
+ *
132
+ * Discriminated by `type`. The `dynamic` variant carries a JS resolver that
133
+ * the static shell scripts delegate to via `<program> __complete`. All
134
+ * variants share the same optional metadata fields (left undefined where
135
+ * inapplicable) so consumers can read `vc.choices`/`vc.extensions`/etc.
136
+ * without narrowing first.
137
+ */
138
+ type ValueCompletion = ({
139
+ /** Completion type */
140
+ type: "choices" | "file" | "directory" | "command" | "none";
141
+ /** List of valid choices (for "choices" type) */
142
+ choices?: string[];
143
+ /** Shell command for dynamic completion (for "command" type) */
144
+ shellCommand?: string;
145
+ resolve?: never;
146
+ dependsOn?: never;
147
+ table?: never;
148
+ } & ({
149
+ extensions?: string[];
150
+ matcher?: never;
151
+ } | {
152
+ /** Glob patterns for file matching (for "file" type) */ matcher?: string[];
153
+ extensions?: never;
154
+ })) | {
155
+ /** In-process dynamic completion via JS callback. */
156
+ type: "dynamic";
157
+ resolve: DynamicCompletionResolver;
158
+ choices?: never;
159
+ shellCommand?: never;
160
+ extensions?: never;
161
+ matcher?: never;
162
+ dependsOn?: never;
163
+ table?: never;
164
+ } | {
165
+ /**
166
+ * Pre-enumerated completion baked into the generated shell script.
167
+ * The `table` is the cartesian product of the `dependsOn` arg values
168
+ * (each having a static `choices` or enum schema). At completion time
169
+ * the shell dispatches on the runtime values of those args — no Node
170
+ * is spawned.
171
+ */
172
+ type: "expand";
173
+ dependsOn: readonly string[];
174
+ table: readonly ExpandTableEntry[];
175
+ choices?: never;
176
+ shellCommand?: never;
177
+ resolve?: never;
178
+ extensions?: never;
179
+ matcher?: never;
180
+ } | {
181
+ /**
182
+ * Runtime form of `completion.custom.expand` used by `__complete`.
183
+ * The dispatcher invokes `__complete` at TAB time, so it can call the
184
+ * user's `enumerate` function against the already typed dependency
185
+ * values instead of baking a table into the shell script.
186
+ */
187
+ type: "runtime-expand";
188
+ dependsOn: readonly string[];
189
+ enumerate: (deps: Readonly<Record<string, string>>) => ReadonlyArray<string | {
190
+ value: string;
191
+ description?: string;
192
+ }>;
193
+ choices?: never;
194
+ shellCommand?: never;
195
+ resolve?: never;
196
+ extensions?: never;
197
+ matcher?: never;
198
+ table?: never;
199
+ };
200
+ /**
201
+ * Information about a completable option
202
+ */
203
+ interface CompletableOption {
204
+ /** Long option name (e.g., "verbose") */
205
+ name: string;
206
+ /** CLI name (kebab-case, e.g., "dry-run") */
207
+ cliName: string;
208
+ /**
209
+ * Aliases for this option (both short and long).
210
+ * 1-char entries are short (`-v`); multi-char entries are long (`--to-be`).
211
+ */
212
+ alias?: string[] | undefined;
213
+ /**
214
+ * Negation name to advertise in shell completions (no `--` prefix),
215
+ * or `undefined` to hide the negation. Mirrors `ResolvedFieldMeta.negationDisplay`.
216
+ */
217
+ negation?: string | undefined;
218
+ /** Description for the negation option (when distinct from the main description) */
219
+ negationDescription?: string | undefined;
220
+ /**
221
+ * Whether the runtime parser accepts the default `--no-<cliName>` (and
222
+ * camelCase) form for this boolean option. True only when the user set
223
+ * `negation: true`; false when unset, `negation: false`, or
224
+ * `negation: <custom name>`. Used by the completion context parser so
225
+ * dynamic resolvers see the same `parsedArgs` state the runtime would compute.
226
+ */
227
+ defaultNegationAccepted?: boolean;
228
+ /** Description for completion */
229
+ description?: string | undefined;
230
+ /**
231
+ * True when this option originates from a `globalArgsSchema` and was
232
+ * propagated into every subcommand frame. The runtime parser keeps
233
+ * global values visible across subcommand descent, so shell generators
234
+ * must keep their tracker buckets separate from per-frame state.
235
+ */
236
+ isGlobal?: boolean;
237
+ /** Whether this option takes a value */
238
+ takesValue: boolean;
239
+ /** Type of value expected */
240
+ valueType: "string" | "number" | "boolean" | "array" | "unknown";
241
+ /** Whether the option is required */
242
+ required: boolean;
243
+ /** Value completion specification */
244
+ valueCompletion?: ValueCompletion | undefined;
245
+ }
246
+ /**
247
+ * Information about a positional argument for completion
248
+ */
249
+ interface CompletablePositional {
250
+ /** Field name */
251
+ name: string;
252
+ /** CLI name (kebab-case) */
253
+ cliName: string;
254
+ /** Position index (0-based) */
255
+ position: number;
256
+ /** Description */
257
+ description?: string | undefined;
258
+ /** Whether required */
259
+ required: boolean;
260
+ /** Whether this positional accepts multiple values (array type) */
261
+ variadic?: boolean | undefined;
262
+ /** Value completion specification */
263
+ valueCompletion?: ValueCompletion | undefined;
264
+ }
265
+ /**
266
+ * Information about a subcommand for completion
267
+ */
268
+ interface CompletableSubcommand {
269
+ /** Subcommand name */
270
+ name: string;
271
+ /** Subcommand description */
272
+ description?: string | undefined;
273
+ /** Alternative names (aliases) for this subcommand */
274
+ aliases?: string[] | undefined;
275
+ /** Nested subcommands */
276
+ subcommands: CompletableSubcommand[];
277
+ /** Options for this subcommand */
278
+ options: CompletableOption[];
279
+ /** Positional arguments */
280
+ positionals: CompletablePositional[];
281
+ }
282
+ /**
283
+ * Extracted completion data from a command
284
+ */
285
+ interface CompletionData {
286
+ /** The root command */
287
+ command: CompletableSubcommand;
288
+ /** Program name */
289
+ programName: string;
290
+ /** Global options (available to all subcommands) */
291
+ globalOptions: CompletableOption[];
292
+ }
293
+ /**
294
+ * Result of completion generation
295
+ */
296
+ interface CompletionResult {
297
+ /** The generated completion script */
298
+ script: string;
299
+ /** The shell type this script is for */
300
+ shell: ShellType;
301
+ /** Instructions for installing the completion */
302
+ installInstructions: string;
303
+ }
304
+ /**
305
+ * Generator function type for shell completions
306
+ */
307
+ type CompletionGenerator = (command: AnyCommand, options: CompletionOptions) => CompletionResult;
308
+ //#endregion
309
+ //#region ../core/src/completion/bundled-worker.d.ts
310
+ interface GenerateBundledCompletionWorkerOptions {
311
+ /** CLI binary or built JS entry file to invoke. */
312
+ bin: string;
313
+ /** Program name embedded in completion metadata. */
314
+ programName: string;
315
+ /** Shell worker to generate. */
316
+ shell: ShellType;
317
+ /** Output path. Defaults to `dist/completion/<shell>-worker.<ext>`. */
318
+ outputPath?: string | undefined;
319
+ /** Verify that `__completion-worker-path <shell>` resolves to the generated file. */
320
+ verify?: boolean | undefined;
321
+ /** Working directory used for relative paths. Defaults to `process.cwd()`. */
322
+ cwd?: string | undefined;
323
+ /** Extra environment passed to the target binary. */
324
+ env?: Readonly<Record<string, string | undefined>> | undefined;
325
+ /** Suppress the success message. */
326
+ quiet?: boolean | undefined;
327
+ }
328
+ interface GenerateBundledCompletionWorkerResult {
329
+ /** Absolute generated worker path. */
330
+ outputPath: string;
331
+ /** Generated file size in bytes. */
332
+ size: number;
333
+ /** Absolute path reported by `__completion-worker-path`, when verified. */
334
+ reportedPath?: string | undefined;
335
+ }
336
+ declare function bundledWorkerShellExtension(shell: ShellType): string;
337
+ declare function defaultBundledWorkerOutputPath(shell: ShellType): string;
338
+ declare function validateBundledWorkerFile(path: string, programName: string, shell: ShellType): void;
339
+ declare function generateBundledCompletionWorker(options: GenerateBundledCompletionWorkerOptions): Promise<GenerateBundledCompletionWorkerResult>;
340
+ //#endregion
341
+ //#region ../core/src/completion/index.d.ts
342
+ /**
343
+ * Generate completion script for the specified shell
344
+ */
345
+ declare function generateCompletion(command: AnyCommand, options: CompletionOptions): CompletionResult;
346
+ /**
347
+ * Get the list of supported shells
348
+ */
349
+ declare function getSupportedShells(): ShellType[];
350
+ /**
351
+ * Detect the current shell from environment
352
+ */
353
+ declare function detectShell(): ShellType | null;
354
+ /**
355
+ * Schema for the completion command arguments
356
+ */
357
+ declare const completionArgsSchema: InternalArgsSchema<{
358
+ shell: "bash" | "fish" | "zsh" | undefined;
359
+ instructions: boolean;
360
+ loader: boolean;
361
+ install: boolean;
362
+ static: boolean;
363
+ dispatcher: boolean;
364
+ worker: boolean;
365
+ }>;
366
+ type CompletionArgs = InferInternalArgs<typeof completionArgsSchema>;
367
+ declare const refreshArgsSchema: InternalArgsSchema<{
368
+ shell: "bash" | "fish" | "zsh";
369
+ target: string | undefined;
370
+ static: boolean;
371
+ worker: boolean;
372
+ }>;
373
+ type RefreshArgs = InferInternalArgs<typeof refreshArgsSchema>;
374
+ declare const workerPathArgsSchema: InternalArgsSchema<{
375
+ shell: "bash" | "fish" | "zsh";
376
+ }>;
377
+ type WorkerPathArgs = InferInternalArgs<typeof workerPathArgsSchema>;
378
+ /**
379
+ * Create a completion subcommand for your CLI
380
+ *
381
+ * This creates a ready-to-use subcommand that generates completion scripts.
382
+ *
383
+ * @example
384
+ * ```typescript
385
+ * const mainCommand = defineCommand({
386
+ * name: "mycli",
387
+ * subCommands: {
388
+ * completion: createCompletionCommand(mainCommand)
389
+ * }
390
+ * });
391
+ * ```
392
+ */
393
+ declare function createCompletionCommand(rootCommand: AnyCommand, programName?: string, globalArgsSchema?: ArgsSchema, extra?: {
394
+ cacheDir?: string;
395
+ programVersion?: string;
396
+ bundledWorker?: BundledWorkerOptions;
397
+ }): Command<typeof completionArgsSchema, CompletionArgs, any>;
398
+ /**
399
+ * Hidden subcommand that the runMain background hook spawns. It does
400
+ * the same stat-compare + atomic rewrite as the rc loader, but in a
401
+ * detached child process so it's invisible to the user.
402
+ */
403
+ declare function createRefreshCompletionCommand(rootCommand: AnyCommand, programName: string, extra?: {
404
+ cacheDir?: string;
405
+ programVersion?: string;
406
+ globalArgsSchema?: ArgsSchema;
407
+ bundledWorker?: BundledWorkerOptions;
408
+ }): Command<typeof refreshArgsSchema, RefreshArgs, any>;
409
+ declare function createCompletionWorkerPathCommand(programName: string, extra?: {
410
+ binPath?: string;
411
+ bundledWorker?: BundledWorkerOptions;
412
+ }): Command<typeof workerPathArgsSchema, WorkerPathArgs, any>;
413
+ /**
414
+ * Options for withCompletionCommand
415
+ */
416
+ interface WithCompletionOptions {
417
+ /** Override the program name (defaults to command.name) */
418
+ programName?: string;
419
+ /** Global args schema for deriving global options in completion */
420
+ globalArgsSchema?: ArgsSchema;
421
+ /**
422
+ * Hardcode the cache directory used by the rc loader and the
423
+ * background refresh. When omitted, the loader derives
424
+ * `${XDG_CACHE_HOME:-$HOME/.cache}/<programName>` at runtime, which
425
+ * is the right answer for almost every CLI.
426
+ */
427
+ cacheDir?: string;
428
+ /** Program version embedded in the script header. */
429
+ programVersion?: string;
430
+ /** Published worker artifact lookup used by dispatcher mode. */
431
+ bundledWorker?: BundledWorkerOptions;
432
+ }
433
+ /**
434
+ * Wrap a command with a completion subcommand
435
+ *
436
+ * This avoids circular references that occur when a command references itself
437
+ * in its subCommands (e.g., for completion generation).
438
+ *
439
+ * @param command - The command to wrap
440
+ * @param options - Options including programName
441
+ * @returns A new command with the completion subcommand added
442
+ *
443
+ * @example
444
+ * ```typescript
445
+ * const mainCommand = withCompletionCommand(
446
+ * defineCommand({
447
+ * name: "mycli",
448
+ * subCommands: { ... },
449
+ * }),
450
+ * );
451
+ * ```
452
+ */
453
+ declare function withCompletionCommand<T extends AnyCommand>(command: T, options?: string | WithCompletionOptions): T;
454
+ //#endregion
455
+ export { CompletionResult as C, InternalArgsSchema as D, InferInternalArgs as E, CompletionOptions as S, ValueCompletion as T, CompletablePositional as _, detectShell as a, CompletionGenerator as b, withCompletionCommand as c, bundledWorkerShellExtension as d, defaultBundledWorkerOutputPath as f, CompletableOption as g, BundledWorkerOptions as h, createRefreshCompletionCommand as i, GenerateBundledCompletionWorkerOptions as l, validateBundledWorkerFile as m, createCompletionCommand as n, generateCompletion as o, generateBundledCompletionWorker as p, createCompletionWorkerPathCommand as r, getSupportedShells as s, WithCompletionOptions as t, GenerateBundledCompletionWorkerResult as u, CompletableSubcommand as v, ShellType as w, CompletionMode as x, CompletionData as y };