@politty/loculus 0.0.0-stage → 0.1.1

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 (50) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +65 -2
  3. package/bin/cli.mjs +3 -0
  4. package/dist/agent.d.ts +2 -0
  5. package/dist/agent.js +1 -0
  6. package/dist/argv-parser-BRSUT6IV.js +1 -0
  7. package/dist/cli-main-CoQp6CjD.js +1 -0
  8. package/dist/cli-main-D4rJTFFd.js +2 -0
  9. package/dist/cli-run-DABESHM4.js +1 -0
  10. package/dist/cli.d.ts +1 -0
  11. package/dist/cli.js +2 -0
  12. package/dist/command-BXsTrIgI.js +1 -0
  13. package/dist/compile-cache-6u9hgeWu.js +1 -0
  14. package/dist/compile-cache.d.ts +80 -0
  15. package/dist/compile-cache.js +1 -0
  16. package/dist/completion-BGidlN43.js +1 -0
  17. package/dist/completion-Cyw4RN-l.js +116 -0
  18. package/dist/completion.d.ts +333 -0
  19. package/dist/completion.js +1 -0
  20. package/dist/detect-agent-D7KSeWMh.js +3 -0
  21. package/dist/detect-agent-EHaSY1KW.d.ts +49 -0
  22. package/dist/docs.d.ts +770 -0
  23. package/dist/docs.js +94 -0
  24. package/dist/dynamic-BbeRdUqR.js +1 -0
  25. package/dist/dynamic-Hg5BDHzz.js +6 -0
  26. package/dist/import-meta-resolve-DgKm4LYW.js +3 -0
  27. package/dist/index.d.ts +1088 -0
  28. package/dist/index.js +1 -0
  29. package/dist/log-collector-uhRWYT-z.js +1 -0
  30. package/dist/logger-CoeDrmRr.js +1 -0
  31. package/dist/prompt-clack.d.ts +15 -0
  32. package/dist/prompt-clack.js +1 -0
  33. package/dist/prompt-fl79dWPz.js +1 -0
  34. package/dist/prompt-inquirer.d.ts +15 -0
  35. package/dist/prompt-inquirer.js +1 -0
  36. package/dist/prompt.d.ts +106 -0
  37. package/dist/prompt.js +1 -0
  38. package/dist/register-Ceh-HlVN.js +1 -0
  39. package/dist/registry-BEz5iex_.js +1 -0
  40. package/dist/runner-D-n1xa2K.js +33 -0
  41. package/dist/runner-nPWQnqQ3.js +1 -0
  42. package/dist/schema--6eHVfwR.js +1 -0
  43. package/dist/schema-extractor-DFawzmtj.js +1 -0
  44. package/dist/skill.d.ts +581 -0
  45. package/dist/skill.js +2 -0
  46. package/dist/subcommand-router-iqmWGZyU.js +2 -0
  47. package/dist/types-Dhar1ua6.d.ts +1125 -0
  48. package/dist/with-completion-command-CARvhYvv.d.ts +384 -0
  49. package/dist/with-completion-command-yg7HB6Zu.js +3 -0
  50. package/package.json +101 -3
@@ -0,0 +1,1088 @@
1
+ import { r as KnownAgentId, t as AgentInfo } from "./detect-agent-EHaSY1KW.js";
2
+ import { $ as DynamicCompletionCandidate, A as SubCommandsRecord, B as ArgFn, C as RunInvocation, D as RunnableCommand, E as RunResultSuccess, F as ExtractedFields, G as EffectContext, H as CompletionMeta, I as ResolvedFieldMeta, J as ValidateArgMeta, K as PromptMeta, L as UnknownKeysMode, M as LazyCommand, N as isLazyCommand, O as SetupContext, P as lazy, Q as CompletionDirectiveMask, R as toCamelCase, S as RunCommandOptions, T as RunResultFailure, U as CompletionType, V as ArgMeta, W as CustomCompletion, X as ExpandCompletion, Y as ExpandCandidate, Z as ResolvedExpandCandidate, _ as LogStream, a as ArgsSchema$1, at as InferSchemaOutput, b as NonRunnableCommand, c as Command, d as GlobalArgs, et as DynamicCompletionContext, f as GlobalCleanupContext, g as LogLevel, h as LogEntry, i as ArgSource, it as loadPackage, j as UnknownSubcommandHandler, k as SubCommandValue, l as CommandBase, m as IsEmpty, n as AgentHelpContext, nt as DynamicCompletionResult, o as CleanupContext, ot as SchemaLike, p as GlobalSetupContext, q as PromptType, r as AnyCommand, rt as PackageRequirement, s as CollectedLogs, t as AgentHelp, tt as DynamicCompletionResolver, u as Example, v as Logger, w as RunResult, x as PromptResolver, y as MainOptions, z as toKebabCase } from "./types-Dhar1ua6.js";
3
+ import { _ as CompletionResult, g as CompletionOptions, i as GenerateBundledCompletionWorkerResult, n as withCompletionCommand, r as GenerateBundledCompletionWorkerOptions, t as WithCompletionOptions, x as InternalArgsSchema } from "./with-completion-command-CARvhYvv.js";
4
+ import { Field, Schema } from "loculus";
5
+ //#region ../core/src/core/schema-extractor.d.ts
6
+ /**
7
+ * Detect the unknown-keys handling mode of an args schema. Works for any
8
+ * schema politty itself attaches to a command (including internal
9
+ * descriptor-based commands), not just user-provided library schemas.
10
+ */
11
+ export declare function getUnknownKeysMode(schema: ArgsSchema$1): UnknownKeysMode;
12
+ /**
13
+ * Extract all fields from a schema
14
+ *
15
+ * @param schema - The args schema (ZodObject, ZodDiscriminatedUnion, etc.)
16
+ * @returns Extracted field information
17
+ */
18
+ export declare function extractFields(schema: ArgsSchema$1): ExtractedFields;
19
+ //#endregion
20
+ //#region ../core/src/adapter/types.d.ts
21
+ /**
22
+ * Validation error details
23
+ */
24
+ interface ValidationError {
25
+ /** Path to the invalid field */
26
+ path: string[];
27
+ /** Error message */
28
+ message: string;
29
+ /** Error code (adapter-specific, e.g. zod issue code) */
30
+ code: string;
31
+ /** Value that was received */
32
+ received?: unknown | undefined;
33
+ /** Expected type or value */
34
+ expected?: string | undefined;
35
+ }
36
+ /**
37
+ * Validation result
38
+ */
39
+ type ValidationResult<T> = {
40
+ success: true;
41
+ data: T;
42
+ } | {
43
+ success: false;
44
+ errors: ValidationError[];
45
+ };
46
+ //#endregion
47
+ //#region ../core/src/cli-main.d.ts
48
+ /**
49
+ * Run politty's own development CLI (`generate-shim`, `generate-worker`).
50
+ *
51
+ * `ownerPackage` is the npm name of the politty package providing the `politty`
52
+ * bin that invoked this — `@politty/zod`, `@politty/valibot`, or `politty`. It
53
+ * is threaded through to {@link createCompileCacheShimGenerator} so a generated
54
+ * shim imports the cache helper from the package the user actually installed,
55
+ * which is the one guaranteed to resolve from their own package.
56
+ *
57
+ * Never returns: it exits the process, like `runMain`.
58
+ */
59
+ export declare function runPolittyCli(ownerPackage: string): Promise<never>;
60
+ //#endregion
61
+ //#region ../core/src/compile-cache-shim.d.ts
62
+ /**
63
+ * Generator for compile-cache bin shims.
64
+ *
65
+ * Emits the minimal entry file described in docs/recipes.md ("Faster
66
+ * Startup"): a shim that enables the Node.js on-disk compile cache and then
67
+ * loads the real CLI with a dynamic import. Meant to be wired into a
68
+ * `postbuild` or `prepack` script via `politty generate-shim` so the shim
69
+ * never has to live in source.
70
+ *
71
+ * Each politty package binds its own generator with
72
+ * {@link createCompileCacheShimGenerator}, so the shim imports the cache
73
+ * helper from the package that generated it.
74
+ */
75
+ /**
76
+ * Options for the generator returned by
77
+ * {@link createCompileCacheShimGenerator} — exported as
78
+ * `generateCompileCacheShim` from each politty package.
79
+ */
80
+ interface GenerateCompileCacheShimOptions {
81
+ /**
82
+ * Module specifier(s) the shim imports to start the CLI, relative to the
83
+ * generated shim file (e.g. `./cli.js`). Pass one per shim; when `out` is
84
+ * omitted the count must match the package's `bin` entries (paired in
85
+ * order). Defaults to the first of `./cli.js`, `./cli.mjs`, `./index.js`,
86
+ * `./index.mjs` that exists next to each shim.
87
+ */
88
+ entry?: string | string[];
89
+ /**
90
+ * Output path(s) for the generated shim(s) (e.g. `dist/bin.js`). When
91
+ * given, the count must match `entry` (paired in order). Defaults to all
92
+ * `bin` paths in the nearest `package.json` — the places the executables
93
+ * must live.
94
+ */
95
+ out?: string | string[];
96
+ /**
97
+ * Program name used to derive the cache directory, applied to every
98
+ * generated shim. Defaults per shim to the `bin` name whose path is the
99
+ * shim's output, falling back to the first `bin` name and then the
100
+ * package name without its scope. The fallback never happens silently: a
101
+ * warning is printed when an explicit `out` path cannot be matched to a
102
+ * `bin` entry.
103
+ */
104
+ program?: string;
105
+ /**
106
+ * Base directory for resolving paths and locating the nearest
107
+ * `package.json` (default: `process.cwd()`).
108
+ */
109
+ cwd?: string;
110
+ /**
111
+ * Module specifier the shim imports `enableCompileCache` from. Defaults to
112
+ * the `compile-cache` subpath of the politty package this generator belongs
113
+ * to (see {@link createCompileCacheShimGenerator}). Set this when politty is
114
+ * reached some other way — a re-export from your own package, an import
115
+ * map, and so on.
116
+ */
117
+ compileCacheSpecifier?: string;
118
+ }
119
+ /**
120
+ * One generated shim from the generator returned by
121
+ * {@link createCompileCacheShimGenerator}.
122
+ */
123
+ interface GenerateCompileCacheShimResult {
124
+ /** Absolute path of the generated shim. */
125
+ outputPath: string;
126
+ /** Program name baked into the shim. */
127
+ program: string;
128
+ /** Entry specifier baked into the shim. */
129
+ entry: string;
130
+ /** Specifier the shim imports `enableCompileCache` from. */
131
+ compileCacheSpecifier: string;
132
+ }
133
+ /**
134
+ * Build the shim generator for one politty package.
135
+ *
136
+ * `ownerPackage` is the npm name of the package the generator is exported
137
+ * from (`@politty/zod`, `@politty/valibot`, `politty`), and the shim imports
138
+ * `enableCompileCache` from its `compile-cache` subpath. Taking the name from
139
+ * the owner rather than guessing it is what makes the specifier reliable:
140
+ * reaching this generator at all — through that package's bin or through an
141
+ * import of it — means the package is installed in the host, so the specifier
142
+ * resolves from the shim that lands there. The alternative, reading the host's
143
+ * `package.json`, could only guess which of the three politty packages was
144
+ * meant.
145
+ *
146
+ * The returned function generates executable shims. With no explicit paths,
147
+ * one is generated per `bin` entry of the nearest `package.json`, each
148
+ * importing a conventional built module next to it — so a bare
149
+ * `politty generate-shim` in a `postbuild` script is usually enough. Explicit
150
+ * `entry` values are paired in order with the `bin` entries (or with explicit
151
+ * `out` values of the same count).
152
+ *
153
+ * The generated files are ESM (they use top-level `await import`), so `.js`
154
+ * output requires `"type": "module"` in the package; use a `.mjs` extension
155
+ * otherwise. Refuses to overwrite an existing file it did not generate, so
156
+ * a `bin` path still pointing at the real CLI entry fails loudly instead of
157
+ * clobbering the build output.
158
+ */
159
+ export declare function createCompileCacheShimGenerator(ownerPackage: string): (options?: GenerateCompileCacheShimOptions) => GenerateCompileCacheShimResult[];
160
+ //#endregion
161
+ //#region ../core/src/core/case-types.d.ts
162
+ /**
163
+ * TypeScript utility types for case conversion between camelCase and kebab-case.
164
+ *
165
+ * These types enable dual-case access on CLI args objects,
166
+ * so that both `args.myOption` and `args["my-option"]` are valid.
167
+ */
168
+ /**
169
+ * Convert a kebab-case string to camelCase at the type level.
170
+ *
171
+ * @example
172
+ * type R = CamelCase<"my-option">; // "myOption"
173
+ * type R2 = CamelCase<"already">; // "already"
174
+ */
175
+ type CamelCase<S extends string> = S extends `${infer P}-${infer C}${infer R}` ? `${P}${Uppercase<C>}${CamelCase<R>}` : S;
176
+ /**
177
+ * Internal helper: insert hyphens before uppercase-to-lowercase transitions.
178
+ * Matches the runtime `toKebabCase()` behavior:
179
+ * - `([a-z])([A-Z])` → insert hyphen (e.g. "myOption" → "my-Option")
180
+ * - `([A-Z]+)([A-Z][a-z])` → insert hyphen before last capital in a run
181
+ * (e.g. "XMLParser" → "XML-Parser" → "xml-parser")
182
+ *
183
+ * Note: TypeScript template literal types have limited ability to match
184
+ * multi-character uppercase runs precisely. This implementation handles
185
+ * common CLI naming patterns (camelCase, PascalCase). For exotic acronym
186
+ * patterns (e.g. "XMLParser"), the type-level result may differ slightly
187
+ * from the runtime result. Dual-case proxy handles runtime resolution.
188
+ */
189
+ type KebabCaseInner<S extends string> = S extends `${infer First}${infer Rest}` ? Rest extends "" ? First extends Lowercase<First> ? First : `-${Lowercase<First>}` : First extends Lowercase<First> ? `${First}${KebabCaseInner<Rest>}` : Rest extends `${infer Next}${infer Tail}` ? Next extends Lowercase<Next> ? `-${Lowercase<First>}${Next}${KebabCaseInner<Tail>}` : `${Lowercase<First>}${KebabCaseInner<Rest>}` : `-${Lowercase<First>}` : S;
190
+ /**
191
+ * Strip a leading hyphen (produced when the first char is uppercase).
192
+ */
193
+ type StripLeadingHyphen<S extends string> = S extends `-${infer R}` ? R : S;
194
+ /**
195
+ * Convert a camelCase string to kebab-case at the type level.
196
+ * Aligned with the runtime `toKebabCase()` function in schema-extractor.ts.
197
+ *
198
+ * @example
199
+ * type R = KebabCase<"myOption">; // "my-option"
200
+ * type R2 = KebabCase<"already">; // "already"
201
+ */
202
+ type KebabCase<S extends string> = StripLeadingHyphen<KebabCaseInner<S>>;
203
+ /**
204
+ * Add both camelCase and kebab-case variants for every key in T.
205
+ *
206
+ * Given `{ "my-option": string }`, produces
207
+ * `{ "my-option": string } & { myOption: string }`.
208
+ *
209
+ * Given `{ myOption: string }`, produces
210
+ * `{ myOption: string } & { "my-option": string }`.
211
+ *
212
+ * Keys that are identical in both cases (e.g. single-word keys) are not duplicated.
213
+ * Uses a distributive conditional type so it works correctly with discriminated unions.
214
+ */
215
+ type WithCaseVariants<T> = T extends unknown ? T & { [K in keyof T as CamelCase<K & string>]: T[K]; } & { [K in keyof T as KebabCase<K & string>]: T[K]; } : never;
216
+ //#endregion
217
+ //#region ../core/src/core/case-proxy.d.ts
218
+ /**
219
+ * Wrap an args object with a Proxy that allows dual-case access.
220
+ *
221
+ * Given `{ "my-option": "value" }`, both `obj["my-option"]` and `obj.myOption`
222
+ * will return `"value"`.
223
+ *
224
+ * - `Object.keys()`, `JSON.stringify()`, and spread return only the original keys.
225
+ * - The `in` operator detects both case variants.
226
+ */
227
+ export declare function createDualCaseProxy<T extends Record<string, unknown>>(obj: T): WithCaseVariants<T>;
228
+ //#endregion
229
+ //#region ../core/src/core/command.d.ts
230
+ /**
231
+ * Infer args type from schema, defaults to empty object if undefined.
232
+ * Wraps with WithCaseVariants so both camelCase and kebab-case access is typed.
233
+ *
234
+ * politty's internal validator-free descriptors are checked before the
235
+ * schema-library branch: they present themselves as `ArgsSchema` at the
236
+ * type level (see `InternalArgsSchema`), so without the brand check they
237
+ * would fall into `z.infer` and lose their field types.
238
+ */
239
+ type InferArgs<TArgsSchema> = TArgsSchema extends InternalArgsSchema<infer TInternalOut> ? WithCaseVariants<TInternalOut> : TArgsSchema extends SchemaLike ? WithCaseVariants<InferSchemaOutput<TArgsSchema>> : Record<string, never>;
240
+ /**
241
+ * Merge local args with global args.
242
+ * No-op when TGlobalArgs is empty (default GlobalArgs not extended).
243
+ * Wraps TGlobalArgs with WithCaseVariants for dual-case access.
244
+ */
245
+ type MergedArgs<TLocalArgs, TGlobalArgs> = IsEmpty<TGlobalArgs> extends true ? TLocalArgs : TLocalArgs & WithCaseVariants<TGlobalArgs>;
246
+ /**
247
+ * Add the `$source`, `$invocation` and `$agent` run-time metadata helpers.
248
+ *
249
+ * `$source` reports whether a given field's final value came from an
250
+ * explicit CLI token, a `field.env` fallback, or neither (schema default /
251
+ * `prompt` resolution). Its `name` parameter is typed as a plain `string`
252
+ * (not `keyof T`) since the runtime helper deliberately accepts either
253
+ * camelCase or kebab-case field names (matching `createDualCaseProxy`'s
254
+ * dual-case access) and returns `"default"` for anything it doesn't
255
+ * recognize. A `keyof T`-based type would also be unsound for
256
+ * discriminated-union `args` schemas, where narrowing `args` to one branch
257
+ * doesn't retroactively narrow `$source`'s already-fixed parameter type.
258
+ *
259
+ * `$invocation` reports the CLI name (canonical or alias) this command was
260
+ * invoked with.
261
+ *
262
+ * `$agent` reports the AI coding agent running the CLI (see `detectAgent`),
263
+ * or `undefined` when none is detected.
264
+ */
265
+ type WithRunMeta<T> = T & {
266
+ $source?: (name: string) => ArgSource;
267
+ $invocation?: RunInvocation;
268
+ $agent?: AgentInfo | undefined;
269
+ };
270
+ /**
271
+ * Resolve merged args from schema and global args type
272
+ */
273
+ type ResolvedArgs<TArgsSchema, TGlobalArgs> = WithRunMeta<MergedArgs<InferArgs<TArgsSchema>, TGlobalArgs>>;
274
+ /**
275
+ * Resolve the set of subcommand keys usable by `defaultSubCommand`, given the
276
+ * `subCommands` type inferred from a `defineCommand` call's config literal.
277
+ * `never` when no `subCommands` were provided, so `defaultSubCommand` cannot
278
+ * be set on a command without any subcommands.
279
+ */
280
+ type DefaultSubCommandKey<TSubCommands> = TSubCommands extends SubCommandsRecord ? keyof TSubCommands & string : never;
281
+ /**
282
+ * Config for defining a command
283
+ * @template TArgsSchema - The args schema type (from the CLI's schema library)
284
+ * @template TResult - The return type of run function (void if no run)
285
+ * @template TGlobalArgs - Global args type (from declaration merging or factory)
286
+ * @template TSubCommands - The `subCommands` record type (inferred from the config literal)
287
+ */
288
+ interface DefineCommandConfig<TArgsSchema extends ArgsSchema$1 | undefined, TResult, TGlobalArgs, TSubCommands extends SubCommandsRecord | undefined = undefined> {
289
+ name: string;
290
+ description?: string;
291
+ requiredPackages?: readonly PackageRequirement<ResolvedArgs<TArgsSchema, TGlobalArgs>>[];
292
+ aliases?: string[];
293
+ args?: TArgsSchema;
294
+ subCommands?: TSubCommands;
295
+ setup?: (context: {
296
+ args: ResolvedArgs<TArgsSchema, TGlobalArgs>;
297
+ }) => void | Promise<void>;
298
+ run?: (args: ResolvedArgs<TArgsSchema, TGlobalArgs>) => TResult;
299
+ cleanup?: (context: {
300
+ args: ResolvedArgs<TArgsSchema, TGlobalArgs>;
301
+ error?: Error | undefined;
302
+ }) => void | Promise<void>;
303
+ notes?: string;
304
+ examples?: Example[];
305
+ }
306
+ /**
307
+ * The overloaded `defineCommand` signature, parameterized by the args-schema
308
+ * constraint. Core's `defineCommand` uses the Standard-Schema-based
309
+ * {@link ArgsSchema}; adapter packages re-pin the same runtime function to
310
+ * their library's schema type (e.g. `DefineCommandFn<z.ZodType<...>>` in
311
+ * `@politty/zod`) so a schema from the wrong library is rejected at the type
312
+ * level instead of failing at runtime in the registered adapter.
313
+ */
314
+ interface DefineCommandFn<TArgsBase extends ArgsSchema$1 = ArgsSchema$1> {
315
+ <TArgsSchema extends TArgsBase | undefined = undefined, TResult = void, TGlobalArgs = GlobalArgs, TSubCommands extends SubCommandsRecord | undefined = undefined>(config: RunnableConfig<TArgsSchema, TResult, TGlobalArgs, TSubCommands>): RunnableCommand<TArgsSchema, ResolvedArgs<TArgsSchema, TGlobalArgs>, TResult>;
316
+ <TArgsSchema extends TArgsBase | undefined = undefined, TGlobalArgs = GlobalArgs, TSubCommands extends SubCommandsRecord | undefined = undefined>(config: NonRunnableConfig<TArgsSchema, TGlobalArgs, TSubCommands>): NonRunnableCommand<TArgsSchema, ResolvedArgs<TArgsSchema, TGlobalArgs>>;
317
+ }
318
+ /**
319
+ * `defineCommand` with a pre-bound global args type — the shape returned by
320
+ * {@link createDefineCommand}. Parameterized by the args-schema constraint
321
+ * for the same adapter re-pinning as {@link DefineCommandFn}.
322
+ */
323
+ interface BoundDefineCommandFn<TGlobalArgs, TArgsBase extends ArgsSchema$1 = ArgsSchema$1> {
324
+ <TArgsSchema extends TArgsBase | undefined = undefined, TResult = void, TSubCommands extends SubCommandsRecord | undefined = undefined>(config: RunnableConfig<TArgsSchema, TResult, TGlobalArgs, TSubCommands>): RunnableCommand<TArgsSchema, ResolvedArgs<TArgsSchema, TGlobalArgs>, TResult>;
325
+ <TArgsSchema extends TArgsBase | undefined = undefined, TSubCommands extends SubCommandsRecord | undefined = undefined>(config: NonRunnableConfig<TArgsSchema, TGlobalArgs, TSubCommands>): NonRunnableCommand<TArgsSchema, ResolvedArgs<TArgsSchema, TGlobalArgs>>;
326
+ }
327
+ /**
328
+ * The `createDefineCommand` signature, parameterized by the args-schema
329
+ * constraint for adapter re-pinning (see {@link DefineCommandFn}).
330
+ */
331
+ interface CreateDefineCommandFn<TArgsBase extends ArgsSchema$1 = ArgsSchema$1> {
332
+ <TGlobalArgs>(): BoundDefineCommandFn<TGlobalArgs, TArgsBase>;
333
+ }
334
+ /**
335
+ * Config with run function (runnable command)
336
+ */
337
+ interface RunnableConfig<TArgsSchema extends ArgsSchema$1 | undefined, TResult, TGlobalArgs, TSubCommands extends SubCommandsRecord | undefined = undefined> extends DefineCommandConfig<TArgsSchema, TResult, TGlobalArgs, TSubCommands> {
338
+ run: (args: ResolvedArgs<TArgsSchema, TGlobalArgs>) => TResult;
339
+ /** Not settable alongside `run` (see `NonRunnableConfig.defaultSubCommand`) */
340
+ defaultSubCommand?: undefined;
341
+ }
342
+ /**
343
+ * Config without run function (non-runnable command)
344
+ */
345
+ interface NonRunnableConfig<TArgsSchema extends ArgsSchema$1 | undefined, TGlobalArgs, TSubCommands extends SubCommandsRecord | undefined = undefined> extends Omit<DefineCommandConfig<TArgsSchema, void, TGlobalArgs, TSubCommands>, "run"> {
346
+ run?: undefined;
347
+ /**
348
+ * Name of a `subCommands` entry to run when this command is invoked with
349
+ * no subcommand specified, instead of showing help. Must be a key of
350
+ * `subCommands` (checked at compile time). See
351
+ * `NonRunnableCommand.defaultSubCommand`.
352
+ */
353
+ defaultSubCommand?: DefaultSubCommandKey<TSubCommands> | undefined;
354
+ }
355
+ //#endregion
356
+ //#region ../core/src/core/runner.d.ts
357
+ /**
358
+ * Run a command with the given arguments (programmatic/test usage)
359
+ *
360
+ * This function parses arguments, validates them, routes to subcommands,
361
+ * and executes the command. It does NOT call process.exit.
362
+ *
363
+ * @param command - The command to run
364
+ * @param argv - Command line arguments to parse
365
+ * @param options - Run options
366
+ * @returns The result of command execution
367
+ *
368
+ * @example
369
+ * ```ts
370
+ * import { defineCommand, runCommand } from "politty";
371
+ *
372
+ * const command = defineCommand({
373
+ * name: "my-cli",
374
+ * args: z.object({ name: z.string() }),
375
+ * run: ({ name }) => console.log(`Hello, ${name}!`),
376
+ * });
377
+ *
378
+ * // In tests
379
+ * const result = await runCommand(command, ["--name", "World"]);
380
+ * expect(result.exitCode).toBe(0);
381
+ * ```
382
+ */
383
+ export declare function runCommand<TResult = unknown>(command: AnyCommand, argv: string[], options?: RunCommandOptions): Promise<RunResult<TResult>>;
384
+ /**
385
+ * Run a CLI command as the main entry point
386
+ *
387
+ * This function:
388
+ * - Uses process.argv for arguments
389
+ * - Handles SIGINT/SIGTERM signals
390
+ * - Calls process.exit with the appropriate exit code
391
+ * - Invokes `command.runMainHook` once before parsing if set, so plug-ins
392
+ * like `withCompletionCommand` can fire detached background work
393
+ * - Bypasses user `setup`/`cleanup`/`prompt` and required `globalArgs`
394
+ * for registered hidden subcommands whose name starts with `__`
395
+ * (e.g. `__refresh-completion`)
396
+ *
397
+ * @param command - The command to run
398
+ * @param options - Main options (version, debug)
399
+ *
400
+ * @example
401
+ * ```ts
402
+ * import { defineCommand, runMain } from "politty";
403
+ *
404
+ * const command = defineCommand({
405
+ * name: "my-cli",
406
+ * run: () => console.log("Hello!"),
407
+ * });
408
+ *
409
+ * runMain(command, { version: "1.0.0" });
410
+ * ```
411
+ */
412
+ export declare function runMain(command: AnyCommand, options?: MainOptions): Promise<never>;
413
+ //#endregion
414
+ //#region ../core/src/output/help-generator.d.ts
415
+ /**
416
+ * Descriptions for built-in options
417
+ */
418
+ interface BuiltinOptionDescriptions {
419
+ /** Description for --help option */
420
+ help?: string;
421
+ /** Description for --help-all option */
422
+ helpAll?: string;
423
+ /** Description for --help-json option */
424
+ helpJson?: string;
425
+ /** Description for --version option */
426
+ version?: string;
427
+ }
428
+ /**
429
+ * Context for command hierarchy
430
+ */
431
+ interface CommandContext {
432
+ /** Full command path (e.g., ["config", "get"]) */
433
+ commandPath?: string[] | undefined;
434
+ /** Root command name */
435
+ rootName?: string | undefined;
436
+ /** Root command version */
437
+ rootVersion?: string | undefined;
438
+ /** Extracted fields from global args schema */
439
+ globalExtracted?: ExtractedFields | undefined;
440
+ /** When the command was accessed via an alias, the canonical command name */
441
+ aliasFor?: string | undefined;
442
+ }
443
+ /**
444
+ * Options for help generation
445
+ */
446
+ interface HelpOptions {
447
+ /** Show subcommand list */
448
+ showSubcommands?: boolean | undefined;
449
+ /** Show subcommand options */
450
+ showSubcommandOptions?: boolean | undefined;
451
+ /** Custom descriptions for built-in options */
452
+ descriptions?: BuiltinOptionDescriptions | undefined;
453
+ /** Command hierarchy context */
454
+ context?: CommandContext | undefined;
455
+ /** Agent-only guidance (Markdown) shown above everything else */
456
+ agentHelp?: string | undefined;
457
+ }
458
+ /**
459
+ * Serializable representation of a single argument (positional or option),
460
+ * whitelisted from {@link ResolvedFieldMeta} down to JSON-safe fields.
461
+ * `schema`, `completion`, `prompt`, and `effect` are intentionally omitted:
462
+ * they carry library-specific schema objects and callbacks that cannot
463
+ * round-trip through JSON, and text help never surfaces them either.
464
+ */
465
+ interface HelpFieldData {
466
+ requiredPackages?: {
467
+ name: string;
468
+ install: string;
469
+ }[] | undefined;
470
+ /** Field name (camelCase, as defined in the schema) */
471
+ name: string;
472
+ /** CLI option name (kebab-case) */
473
+ cliName: string;
474
+ /** Whether this is a positional argument */
475
+ positional: boolean;
476
+ /** Whether this is accepted as a long option (`--cli-name`), including a named positional */
477
+ named: boolean;
478
+ /** Whether this argument is required */
479
+ required: boolean;
480
+ /** Detected type from schema */
481
+ type: "string" | "number" | "boolean" | "array" | "unknown";
482
+ /** Aliases for this option (short: 1 char, long: multi-char) */
483
+ alias?: string[] | undefined;
484
+ /** Argument description */
485
+ description?: string | undefined;
486
+ /** Placeholder shown in help */
487
+ placeholder?: string | undefined;
488
+ /** Environment variable name(s) to read value from */
489
+ env?: string | string[] | undefined;
490
+ /** Default value, if any */
491
+ defaultValue?: unknown;
492
+ /** Enum values, if detected from schema */
493
+ enumValues?: string[] | undefined;
494
+ /** Negation configuration (see {@link ResolvedFieldMeta.negation}) */
495
+ negation?: string | boolean | undefined;
496
+ /** Derived negation flag name (no `--` prefix), or undefined when hidden */
497
+ negationDisplay?: string | undefined;
498
+ /** Description shown for the negation option */
499
+ negationDescription?: string | undefined;
500
+ }
501
+ /**
502
+ * A named group of fields sharing a discriminated-union variant or a plain
503
+ * union option (see {@link ExtractedFields.variants} / `.unionOptions`).
504
+ */
505
+ interface HelpVariantData {
506
+ requiredPackages?: HelpFieldData["requiredPackages"];
507
+ /** Discriminator value this variant matches (discriminated unions only) */
508
+ discriminatorValue?: string | undefined;
509
+ /** Variant/option description */
510
+ description?: string | undefined;
511
+ /**
512
+ * Fields unique to this variant/option (common fields are not repeated
513
+ * here). Positional fields unique to this variant/option are included too,
514
+ * duplicated from the flat top-level {@link HelpData.positionals}, so JSON
515
+ * consumers can attribute a positional to the variant/option it belongs to.
516
+ */
517
+ fields: HelpFieldData[];
518
+ }
519
+ /**
520
+ * Structured usage information, equivalent in content to {@link renderUsageLine}
521
+ * but free of ANSI styling and rendering order decisions, so JSON consumers
522
+ * can format it however they like.
523
+ */
524
+ interface HelpUsageData {
525
+ /** Command name as shown in usage (includes root name for subcommands) */
526
+ commandName: string;
527
+ /** Whether global options are defined */
528
+ hasGlobalOptions: boolean;
529
+ /** Whether this command defines any (non-positional) options */
530
+ hasOptions: boolean;
531
+ /**
532
+ * Whether a subcommand token is expected: "required" when the command has
533
+ * no `run` of its own, "optional" when it does. Undefined when the
534
+ * command has no (visible) subcommands.
535
+ */
536
+ subcommand?: "required" | "optional" | undefined;
537
+ /** Positional arguments in order */
538
+ positionals: Array<{
539
+ name: string;
540
+ required: boolean;
541
+ }>;
542
+ }
543
+ /**
544
+ * A subcommand entry in {@link HelpData.subcommands}.
545
+ */
546
+ interface HelpSubcommandData {
547
+ /** Subcommand name (key under `subCommands`) */
548
+ name: string;
549
+ /** Subcommand aliases */
550
+ aliases?: string[] | undefined;
551
+ /**
552
+ * Set when this subcommand is a legacy async factory (`() => Promise<Command>`)
553
+ * registered without {@link lazy}, so no synchronous metadata is available
554
+ * and `data` cannot be produced. `lazy()` subcommands are always resolved
555
+ * (their `meta` is synchronous) and never hit this case.
556
+ */
557
+ unresolved?: true | undefined;
558
+ /** Full structured help for this subcommand, recursively. Absent when `unresolved` is true. */
559
+ data?: HelpData | undefined;
560
+ }
561
+ /**
562
+ * Structured, JSON-serializable representation of a command's help.
563
+ * Produced by {@link generateHelpData}; the machine-readable counterpart of
564
+ * {@link generateHelp}'s formatted text.
565
+ */
566
+ interface HelpData {
567
+ requiredPackages?: {
568
+ name: string;
569
+ install: string;
570
+ description?: string | undefined;
571
+ }[] | undefined;
572
+ /** Command name (command.name) */
573
+ name: string;
574
+ /**
575
+ * Full path from the root command. Empty at the true root; also empty
576
+ * when generateHelpData is called directly on a non-root command without
577
+ * a context.commandPath (there is no root to compute the path from).
578
+ */
579
+ commandPath: string[];
580
+ /**
581
+ * Root command name. Always set when produced through `runMain`/`runCommand`
582
+ * (equal to `name` itself at the root); `undefined` whenever
583
+ * `context.rootName` is not supplied to `generateHelpData` -- whether
584
+ * because no `context` was given at all, or because the given `context`
585
+ * simply omits `rootName`.
586
+ */
587
+ rootName?: string | undefined;
588
+ /** Root command version, when provided to runMain/runCommand */
589
+ version?: string | undefined;
590
+ /** Canonical subcommand name, set only when this command was reached via an alias */
591
+ aliasFor?: string | undefined;
592
+ /** Command description */
593
+ description?: string | undefined;
594
+ /** Command aliases (as a subcommand) */
595
+ aliases?: string[] | undefined;
596
+ /** Structured usage line */
597
+ usage: HelpUsageData;
598
+ /** Descriptions of the built-in --help/--help-all/--help-json/--version options */
599
+ builtinOptions: {
600
+ help: string;
601
+ helpAll: string;
602
+ helpJson: string;
603
+ version?: string | undefined;
604
+ };
605
+ /** Args schema shape: a plain object, or a union/discriminated-union of variants */
606
+ schemaType?: "object" | "discriminatedUnion" | "union" | "xor" | "intersection" | undefined;
607
+ /** Positional arguments */
608
+ positionals: HelpFieldData[];
609
+ /**
610
+ * Non-positional options. For `discriminatedUnion`/`union`/`xor` schemas,
611
+ * this holds only the fields common to every variant/option; the rest are
612
+ * under `variants`/`unionOptions`.
613
+ */
614
+ options: HelpFieldData[];
615
+ /** Discriminator field name (discriminatedUnion schemas only) */
616
+ discriminator?: string | undefined;
617
+ /** Per-variant fields (discriminatedUnion schemas only) */
618
+ variants?: HelpVariantData[] | undefined;
619
+ /** Per-option fields (union/xor schemas only) */
620
+ unionOptions?: HelpVariantData[] | undefined;
621
+ /** Global options shared across all commands, when a global args schema is defined */
622
+ globalOptions?: HelpFieldData[] | undefined;
623
+ /** Subcommands, recursively resolved */
624
+ subcommands?: HelpSubcommandData[] | undefined;
625
+ /** Example usages */
626
+ examples?: Example[] | undefined;
627
+ /** Additional notes (raw Markdown, unrendered) */
628
+ notes?: string | undefined;
629
+ /** Agent-only guidance (raw Markdown), set only when an AI coding agent is detected */
630
+ agentHelp?: string | undefined;
631
+ }
632
+ /**
633
+ * Generate help text for a command
634
+ *
635
+ * @param command - The command to generate help for
636
+ * @param options - Help generation options
637
+ * @returns Formatted help text
638
+ */
639
+ export declare function generateHelp(command: AnyCommand, options: HelpOptions): string;
640
+ /**
641
+ * Options for {@link generateHelpData}
642
+ */
643
+ interface HelpDataOptions {
644
+ /** Custom descriptions for the --help/--help-all/--help-json/--version built-in options */
645
+ descriptions?: BuiltinOptionDescriptions | undefined;
646
+ /** Command hierarchy context */
647
+ context?: CommandContext | undefined;
648
+ /** Agent-only guidance (raw Markdown) to include as {@link HelpData.agentHelp} */
649
+ agentHelp?: string | undefined;
650
+ }
651
+ /**
652
+ * Generate a structured, JSON-serializable representation of a command's help.
653
+ *
654
+ * The machine-readable counterpart of {@link generateHelp}: same underlying
655
+ * field metadata, but as plain data (no ANSI styling, no fixed layout) and
656
+ * always including the full recursive subcommand tree (there is no
657
+ * `--help`/`--help-all` depth distinction here).
658
+ *
659
+ * @param command - The command to generate help data for
660
+ * @param options - Help data generation options
661
+ * @returns Structured help data
662
+ */
663
+ export declare function generateHelpData(command: AnyCommand, options?: HelpDataOptions): HelpData;
664
+ //#endregion
665
+ //#region ../core/src/output/logger.d.ts
666
+ /**
667
+ * Enable or disable color output programmatically
668
+ */
669
+ export declare function setColorEnabled(enabled: boolean): void;
670
+ /**
671
+ * Check if color output is currently enabled
672
+ */
673
+ export declare function isColorEnabled(): boolean;
674
+ /**
675
+ * Semantic style functions for inline text styling
676
+ */
677
+ export declare const styles: {
678
+ success: (text: string) => string;
679
+ error: (text: string) => string;
680
+ warning: (text: string) => string;
681
+ info: (text: string) => string;
682
+ bold: (text: string) => string;
683
+ dim: (text: string) => string;
684
+ italic: (text: string) => string;
685
+ underline: (text: string) => string;
686
+ red: (text: string) => string;
687
+ green: (text: string) => string;
688
+ yellow: (text: string) => string;
689
+ blue: (text: string) => string;
690
+ magenta: (text: string) => string;
691
+ cyan: (text: string) => string;
692
+ white: (text: string) => string;
693
+ gray: (text: string) => string;
694
+ command: (text: string) => string;
695
+ commandName: (text: string) => string;
696
+ option: (text: string) => string;
697
+ optionName: (text: string) => string;
698
+ placeholder: (text: string) => string;
699
+ defaultValue: (text: string) => string;
700
+ required: (text: string) => string;
701
+ description: (text: string) => string;
702
+ sectionHeader: (text: string) => string;
703
+ version: (text: string) => string;
704
+ };
705
+ /**
706
+ * Standardized symbols for CLI output
707
+ */
708
+ export declare const symbols: {
709
+ success: string;
710
+ error: string;
711
+ warning: string;
712
+ info: string;
713
+ bullet: string;
714
+ arrow: string;
715
+ };
716
+ /**
717
+ * Logger for CLI output
718
+ */
719
+ export declare const logger: {
720
+ /**
721
+ * Log informational message
722
+ */
723
+ info(message: string): void;
724
+ /**
725
+ * Log success message
726
+ */
727
+ success(message: string): void;
728
+ /**
729
+ * Log warning message
730
+ */
731
+ warn(message: string): void;
732
+ /**
733
+ * Log error message
734
+ */
735
+ error(message: string): void;
736
+ /**
737
+ * Log raw message without prefix
738
+ */
739
+ log(message: string): void;
740
+ /**
741
+ * Log empty line
742
+ */
743
+ newline(): void;
744
+ /**
745
+ * Log debug message with dim color
746
+ */
747
+ debug(message: string): void;
748
+ };
749
+ //#endregion
750
+ //#region ../core/src/output/markdown-renderer.d.ts
751
+ /**
752
+ * Lightweight Markdown-to-terminal renderer.
753
+ *
754
+ * Supports a subset of Markdown tailored for CLI help notes:
755
+ * - Inline: bold, italic, inline code, links
756
+ * - Block: paragraphs, unordered/ordered lists, blockquotes, headings,
757
+ * horizontal rules, fenced code blocks
758
+ */
759
+ /**
760
+ * Apply inline Markdown formatting to a string.
761
+ *
762
+ * Processing order matters to avoid conflicts:
763
+ * 1. Inline code (backticks) — content inside is literal, no further processing
764
+ * 2. Bold (**text**)
765
+ * 3. Italic (*text* or _text_)
766
+ * 4. Links [text](url)
767
+ */
768
+ export declare function renderInline(text: string): string;
769
+ /**
770
+ * Render a Markdown string to styled terminal output.
771
+ *
772
+ * Block-level processing:
773
+ * - Splits input into blocks separated by blank lines
774
+ * - Detects headings, horizontal rules, blockquotes, lists, code blocks, and paragraphs
775
+ * - Applies inline formatting within each block
776
+ */
777
+ export declare function renderMarkdown(markdown: string): string;
778
+ //#endregion
779
+ //#region ../core/src/parser/argv-parser.d.ts
780
+ /**
781
+ * Parsed arguments result
782
+ */
783
+ interface ParsedArgv {
784
+ /** Named options (--flag, -f) */
785
+ options: Record<string, unknown>;
786
+ /** Positional arguments */
787
+ positionals: string[];
788
+ /** Arguments after -- */
789
+ rest: string[];
790
+ }
791
+ /**
792
+ * Parser options
793
+ */
794
+ interface ParserOptions {
795
+ /** Alias map (short -> long) */
796
+ aliasMap?: Map<string, string>;
797
+ /** Boolean flags (no value expected) */
798
+ booleanFlags?: Set<string>;
799
+ /** Array flags (can be repeated) */
800
+ arrayFlags?: Set<string>;
801
+ /**
802
+ * All known canonical option names (as defined in the schema).
803
+ * Used to disambiguate negation: when `--no-flag` or `--noFlag` matches
804
+ * a name in this set, it is treated as a regular option rather than
805
+ * boolean negation of `flag`.
806
+ */
807
+ definedNames?: Set<string>;
808
+ /**
809
+ * Map from a custom negation CLI name (and camelCase variant) to the
810
+ * canonical field name. Used to recognize user-defined boolean negation
811
+ * options (e.g. `--disable-cache` → `{ cache: false }`).
812
+ */
813
+ negationMap?: Map<string, string>;
814
+ /**
815
+ * Canonical field names whose default `--no-<name>` / `--no<Name>`
816
+ * negation forms are suppressed. When omitted, every field in
817
+ * `booleanFlags` has default negation suppressed.
818
+ */
819
+ defaultNegationDisabledFields?: Set<string>;
820
+ }
821
+ /**
822
+ * Parse argv into a flat record
823
+ *
824
+ * Supports:
825
+ * - Long options: --flag, --flag=value, --flag value
826
+ * - Short options: -f, -f=value, -f value
827
+ * - Combined short options: -abc (treated as -a -b -c if all are boolean)
828
+ * - Positional arguments
829
+ * - -- to stop parsing options
830
+ * - Boolean negation: --no-flag, --noFlag (requires `booleanFlags` and `negation: true`)
831
+ *
832
+ * **Note:** When using negation detection (`--noFlag` / `--no-flag`),
833
+ * supply `definedNames` so that options whose names happen to start with
834
+ * "no" (e.g. `noDryRun`) are not mistaken for negation of another flag.
835
+ * Without `definedNames`, all `--noX` forms matching a boolean flag will
836
+ * be treated as negation.
837
+ *
838
+ * @param argv - Command line arguments
839
+ * @param options - Parser options
840
+ * @returns Parsed arguments
841
+ */
842
+ export declare function parseArgv(argv: string[], options?: ParserOptions): ParsedArgv;
843
+ //#endregion
844
+ //#region ../core/src/validator/args-validator.d.ts
845
+ /**
846
+ * Format validation errors for display
847
+ */
848
+ export declare function formatValidationErrors(errors: ValidationError[]): string;
849
+ //#endregion
850
+ //#region ../core/src/validator/validation-errors.d.ts
851
+ /**
852
+ * Error thrown when positional argument configuration is invalid
853
+ */
854
+ export declare class PositionalConfigError extends Error {
855
+ constructor(message: string);
856
+ }
857
+ /**
858
+ * Error thrown when a reserved alias is used
859
+ */
860
+ export declare class ReservedAliasError extends Error {
861
+ constructor(message: string);
862
+ }
863
+ /**
864
+ * Error thrown when duplicate field names are detected
865
+ */
866
+ export declare class DuplicateFieldError extends Error {
867
+ constructor(message: string);
868
+ }
869
+ /**
870
+ * Error thrown when duplicate aliases are detected
871
+ */
872
+ export declare class DuplicateAliasError extends Error {
873
+ constructor(message: string);
874
+ }
875
+ /**
876
+ * Error thrown when fields are case variants of each other (e.g. "my-option" and "myOption")
877
+ */
878
+ export declare class CaseVariantCollisionError extends Error {
879
+ constructor(message: string);
880
+ }
881
+ /**
882
+ * Error thrown when a custom boolean negation name collides with another
883
+ * field's name, cliName, alias, or another field's negation (including
884
+ * derived camelCase variants).
885
+ */
886
+ export declare class DuplicateNegationError extends Error {
887
+ constructor(message: string);
888
+ }
889
+ /**
890
+ * Error thrown when a field name collides with a reserved, framework-injected
891
+ * key on the final args object (e.g. `$source`).
892
+ */
893
+ export declare class ReservedFieldNameError extends Error {
894
+ constructor(message: string);
895
+ }
896
+ /**
897
+ * Error thrown when a command's `defaultSubCommand` is misconfigured: set
898
+ * together with `run`, or pointing at a name that isn't a registered
899
+ * `subCommands` key.
900
+ */
901
+ export declare class DefaultSubCommandError extends Error {
902
+ constructor(message: string);
903
+ }
904
+ /**
905
+ * Error thrown when a global field and a same-named local field have
906
+ * different definitions (per `extractFields()`'s type bucket, whether the
907
+ * field is positional, and enum values). Only exactly-matching definitions
908
+ * are allowed to share a name across global/local schemas — anything else
909
+ * is rejected at validation time rather than risking a value from one
910
+ * schema silently flowing into the other.
911
+ */
912
+ export declare class FieldTypeConflictError extends Error {
913
+ constructor(message: string);
914
+ }
915
+ //#endregion
916
+ //#region ../core/src/validator/command-validator.d.ts
917
+ /**
918
+ * Error detail for command validation
919
+ */
920
+ interface CommandValidationError {
921
+ /** Path to the command (e.g., ["cli", "build", "watch"]) */
922
+ commandPath: string[];
923
+ /** Error type */
924
+ type: "duplicate_field" | "duplicate_alias" | "invalid_alias" | "positional_config" | "reserved_alias" | "reserved_field_name" | "case_variant_collision" | "duplicate_negation" | "field_type_conflict" | "subcommand_key_name_mismatch" | "default_subcommand_conflict" | "default_subcommand_not_found";
925
+ /** Error message */
926
+ message: string;
927
+ /** Related field name (if applicable) */
928
+ field?: string;
929
+ }
930
+ /**
931
+ * Result of command validation
932
+ */
933
+ type CommandValidationResult = {
934
+ valid: true;
935
+ } | {
936
+ valid: false;
937
+ errors: CommandValidationError[];
938
+ };
939
+ /**
940
+ * Options for validateCommand
941
+ */
942
+ interface ValidateCommandOptions {
943
+ /** Starting command path (for nested validation) */
944
+ commandPath?: string[];
945
+ /**
946
+ * Global args schema to check the command tree against for cross-schema
947
+ * field collisions (case-variant collisions and `FieldTypeConflictError`
948
+ * conflicts) -- the same check `runCommand()` performs per-invocation at
949
+ * parse time, but here applied eagerly to every command and subcommand
950
+ * regardless of which subcommand path actually gets invoked at runtime.
951
+ */
952
+ globalArgs?: ArgsSchema$1;
953
+ }
954
+ /**
955
+ * Validate that no duplicate field names exist
956
+ *
957
+ * @param extracted - Extracted fields from schema
958
+ * @throws {DuplicateFieldError} If duplicate field names are found
959
+ */
960
+ export declare function validateDuplicateFields(extracted: ExtractedFields): void;
961
+ /**
962
+ * Validate that no duplicate aliases exist
963
+ *
964
+ * Also checks for conflicts between aliases and field names
965
+ *
966
+ * @param extracted - Extracted fields from schema
967
+ * @throws {DuplicateAliasError} If duplicate aliases are found or alias conflicts with field name
968
+ */
969
+ export declare function validateDuplicateAliases(extracted: ExtractedFields): void;
970
+ /**
971
+ * Validate positional argument configuration
972
+ *
973
+ * Rules:
974
+ * - Array positional arguments must be the last positional
975
+ * - No positional arguments can follow an array positional
976
+ * - Required positional arguments cannot follow optional positional arguments
977
+ * - Array positional and optional positional cannot be used together (ambiguous parsing)
978
+ *
979
+ * @param extracted - Extracted fields from schema
980
+ * @throws {PositionalConfigError} If configuration is invalid
981
+ */
982
+ export declare function validatePositionalConfig(extracted: ExtractedFields): void;
983
+ /**
984
+ * Validate that no reserved names are used without explicit override
985
+ *
986
+ * Reserved names:
987
+ * - 'h' is reserved for --help, 'H' for --help-all (short aliases). Users
988
+ * can override this by setting overrideBuiltinAlias: true on the field.
989
+ * - a field's `cliName` or any long alias matching `help`, `help-all`,
990
+ * `help-json`, or `version` collides with the matching built-in long
991
+ * flag. This has no override: `overrideBuiltinAlias: true` does not
992
+ * suppress it (see {@link checkReservedAliases}).
993
+ *
994
+ * @param extracted - Extracted fields from schema
995
+ * @param _hasSubCommands - Whether the command has subcommands (reserved for future use)
996
+ * @throws {ReservedAliasError} If `h`/`H` is used without `overrideBuiltinAlias: true`,
997
+ * or if a field's `cliName`/long alias collides with `help`/`help-all`/`help-json`/`version`
998
+ * (this second case is never suppressed by `overrideBuiltinAlias`)
999
+ */
1000
+ export declare function validateReservedAliases(extracted: ExtractedFields, _hasSubCommands: boolean): void;
1001
+ /**
1002
+ * Validate that no field name starts with `$`
1003
+ *
1004
+ * The `$` prefix is reserved for framework-injected helpers on the final
1005
+ * args object (e.g. `$source`), and is unusable as a real CLI flag anyway
1006
+ * since an unquoted `$name` gets shell-expanded before the program sees it.
1007
+ *
1008
+ * Checking `field.name` alone is sufficient: aliases can't start with `$`
1009
+ * (schema extraction already restricts alias characters to `[A-Za-z0-9-]`),
1010
+ * and `cliName` is derived from `name` via `toKebabCase`, which never strips
1011
+ * or moves a leading `$`. See {@link checkReservedFieldNames}.
1012
+ *
1013
+ * @param extracted - Extracted fields from schema
1014
+ * @throws {ReservedFieldNameError} If a field name starts with "$"
1015
+ */
1016
+ export declare function validateReservedFieldNames(extracted: ExtractedFields): void;
1017
+ /**
1018
+ * Validate that custom boolean negation names do not collide with anything
1019
+ *
1020
+ * @param extracted - Extracted fields from schema
1021
+ * @throws {DuplicateNegationError} If a colliding negation is found
1022
+ */
1023
+ export declare function validateDuplicateNegations(extracted: ExtractedFields): void;
1024
+ /**
1025
+ * Validate that no case-variant collisions exist
1026
+ *
1027
+ * @param extracted - Extracted fields from schema
1028
+ * @throws {CaseVariantCollisionError} If case-variant collisions are found
1029
+ */
1030
+ export declare function validateCaseVariantCollisions(extracted: ExtractedFields): void;
1031
+ /**
1032
+ * Validate that no cross-schema collisions exist between two schemas
1033
+ * (e.g., global args and command args): neither a case-variant collision
1034
+ * (same canonical name, different spelling) nor a same-named field with a
1035
+ * different definition (same spelling, but the two schemas don't agree on
1036
+ * what values are valid).
1037
+ *
1038
+ * @param extractedA - Extracted fields from first schema (e.g., global args)
1039
+ * @param extractedB - Extracted fields from second schema (e.g., command args)
1040
+ * @throws {CaseVariantCollisionError} If cross-schema case-variant collisions are found
1041
+ * @throws {FieldTypeConflictError} If a same-named field has a different definition on each schema
1042
+ */
1043
+ export declare function validateCrossSchemaCollisions(extractedA: ExtractedFields, extractedB: ExtractedFields): void;
1044
+ /**
1045
+ * Validate that a command's `defaultSubCommand` (if set) is not combined
1046
+ * with `run` and points at a registered `subCommands` key.
1047
+ *
1048
+ * @param command - The command to validate
1049
+ * @throws {DefaultSubCommandError} If the configuration is invalid
1050
+ */
1051
+ export declare function validateDefaultSubCommand(command: AnyCommand): void;
1052
+ /**
1053
+ * Validate a command and all its subcommands recursively
1054
+ *
1055
+ * This function collects all validation errors without throwing,
1056
+ * making it suitable for test assertions.
1057
+ *
1058
+ * @param command - The command to validate
1059
+ * @param options - Validation options
1060
+ * @returns Validation result with all errors collected
1061
+ *
1062
+ * @example
1063
+ * ```ts
1064
+ * const result = await validateCommand(myCommand);
1065
+ * if (!result.valid) {
1066
+ * console.error(result.errors);
1067
+ * }
1068
+ * ```
1069
+ */
1070
+ export declare function validateCommand(command: AnyCommand, options?: ValidateCommandOptions): Promise<CommandValidationResult>;
1071
+ /**
1072
+ * Format command validation errors for display
1073
+ *
1074
+ * @param errors - Array of validation errors
1075
+ * @returns Formatted error message
1076
+ */
1077
+ export declare function formatCommandValidationErrors(errors: CommandValidationError[]): string;
1078
+ //#endregion
1079
+ //#region src/index.d.ts
1080
+ export declare const generateCompileCacheShim: (options?: GenerateCompileCacheShimOptions) => GenerateCompileCacheShimResult[];
1081
+ export type ArgsSchema = Schema<Record<string, unknown>, Record<string, any>>;
1082
+ export declare const defineCommand: DefineCommandFn<ArgsSchema>;
1083
+ export declare const createDefineCommand: CreateDefineCommandFn<ArgsSchema>;
1084
+ export declare const arg: ArgFn<Field<any, any, boolean> & {
1085
+ readonly shape?: never;
1086
+ }>;
1087
+ //#endregion
1088
+ export { type AgentHelp, type AgentHelpContext, type AgentInfo, type AnyCommand, type ArgFn, type ArgMeta, type ArgSource, type BoundDefineCommandFn, type BuiltinOptionDescriptions, type CamelCase, type CleanupContext, type CollectedLogs, type Command, type CommandBase, type CommandContext, type CommandValidationError, type CommandValidationResult, type CompletionDirectiveMask, type CompletionMeta, type CompletionOptions, type CompletionResult, type CompletionType, type CreateDefineCommandFn, type CustomCompletion, type DefineCommandFn, type DynamicCompletionCandidate, type DynamicCompletionContext, type DynamicCompletionResolver, type DynamicCompletionResult, type EffectContext, type Example, type ExpandCandidate, type ExpandCompletion, type ExtractedFields, type GenerateBundledCompletionWorkerOptions, type GenerateBundledCompletionWorkerResult, type GenerateCompileCacheShimOptions, type GenerateCompileCacheShimResult, type GlobalArgs, type GlobalCleanupContext, type GlobalSetupContext, type HelpData, type HelpDataOptions, type HelpFieldData, type HelpOptions, type HelpSubcommandData, type HelpUsageData, type HelpVariantData, type InferSchemaOutput, type KebabCase, type KnownAgentId, type LazyCommand, type LogEntry, type LogLevel, type LogStream, type Logger, type MainOptions, type MergedArgs, type NonRunnableCommand, type PackageRequirement, type ParsedArgv, type ParserOptions, type PromptMeta, type PromptResolver, type PromptType, type ResolvedExpandCandidate, type ResolvedFieldMeta, type RunCommandOptions, type RunInvocation, type RunResult, type RunResultFailure, type RunResultSuccess, type RunnableCommand, type SchemaLike, type SetupContext, type SubCommandValue, type SubCommandsRecord, type UnknownKeysMode, type UnknownSubcommandHandler, type ValidateArgMeta, type ValidationError, type ValidationResult, type WithCaseVariants, type WithCompletionOptions, isLazyCommand, lazy, loadPackage, toCamelCase, toKebabCase, withCompletionCommand };