politty 0.11.5 → 0.11.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (51) hide show
  1. package/README.md +30 -1
  2. package/bin/cli.mjs +3 -0
  3. package/dist/augment.d.ts +1 -16
  4. package/dist/augment.js +2 -0
  5. package/dist/cli-run-DGe88d0G.js +14 -0
  6. package/dist/cli.d.ts +1 -1
  7. package/dist/cli.js +13 -9
  8. package/dist/compile-cache.d.ts +1 -79
  9. package/dist/compile-cache.js +2 -2
  10. package/dist/completion.d.ts +1 -0
  11. package/dist/completion.js +3 -0
  12. package/dist/docs.d.ts +1 -0
  13. package/dist/docs.js +3 -0
  14. package/dist/index.d.ts +10 -814
  15. package/dist/index.js +17 -8
  16. package/dist/prompt-clack.d.ts +1 -0
  17. package/dist/prompt-clack.js +3 -0
  18. package/dist/prompt-inquirer.d.ts +1 -0
  19. package/dist/prompt-inquirer.js +3 -0
  20. package/dist/prompt.d.ts +1 -0
  21. package/dist/prompt.js +3 -0
  22. package/dist/skill.d.ts +1 -0
  23. package/dist/skill.js +3 -0
  24. package/package.json +20 -46
  25. package/dist/arg-registry-SrNIsq-d.d.ts +0 -981
  26. package/dist/cli-main.d.ts +0 -1
  27. package/dist/cli-main.js +0 -86
  28. package/dist/command-B4yA4LXX.js +0 -43
  29. package/dist/compile-cache-NnTkjJMV.js +0 -101
  30. package/dist/completion/index.d.ts +0 -3
  31. package/dist/completion/index.js +0 -3
  32. package/dist/completion-D9SKGJad.js +0 -5610
  33. package/dist/docs/index.d.ts +0 -771
  34. package/dist/docs/index.js +0 -3024
  35. package/dist/index-qqwo5WZT.d.ts +0 -673
  36. package/dist/log-collector-DK32-73m.js +0 -115
  37. package/dist/logger-DbDkjdfO.js +0 -134
  38. package/dist/prompt/clack/index.d.ts +0 -17
  39. package/dist/prompt/clack/index.js +0 -32
  40. package/dist/prompt/index.d.ts +0 -107
  41. package/dist/prompt/index.js +0 -3
  42. package/dist/prompt/inquirer/index.d.ts +0 -17
  43. package/dist/prompt/inquirer/index.js +0 -47
  44. package/dist/prompt-Cc8Tfmdv.js +0 -172
  45. package/dist/runner-BGs_QMJM.js +0 -3
  46. package/dist/runner-xN7248Ph.js +0 -2966
  47. package/dist/schema-extractor-wzJ1cGon.js +0 -488
  48. package/dist/skill/index.d.ts +0 -584
  49. package/dist/skill/index.js +0 -1756
  50. package/dist/src-BiCtSNrn.js +0 -193
  51. package/dist/subcommand-router-CTzHPGzF.js +0 -135
package/dist/index.d.ts CHANGED
@@ -1,818 +1,14 @@
1
- import { $ as toCamelCase, A as LogLevel, B as RunnableCommand, C as CommandBase, D as GlobalSetupContext, E as GlobalCleanupContext, F as PromptResolver, G as LazyCommand, H as SubCommandValue, I as RunCommandOptions, J as ExtractedFields, K as isLazyCommand, L as RunResult, M as Logger, N as MainOptions, O as IsEmpty, P as NonRunnableCommand, Q as getUnknownKeysMode, R as RunResultFailure, S as Command, T as GlobalArgs, U as SubCommandsRecord, V as SetupContext, W as UnknownSubcommandHandler, X as UnknownKeysMode, Y as ResolvedFieldMeta, Z as extractFields, _ as AnyCommand, a as EffectContext, b as CleanupContext, c as arg, d as ResolvedExpandCandidate, et as toKebabCase, f as CompletionDirectiveMask, g as DynamicCompletionResult, h as DynamicCompletionResolver, i as CustomCompletion, j as LogStream, k as LogEntry, l as ExpandCandidate, m as DynamicCompletionContext, n as CompletionMeta, o as PromptMeta, p as DynamicCompletionCandidate, q as lazy, r as CompletionType, s as PromptType, t as ArgMeta, u as ExpandCompletion, v as ArgSource, w as Example, x as CollectedLogs, y as ArgsSchema, z as RunResultSuccess } from "./arg-registry-SrNIsq-d.js";
2
- import { I as CompletionOptions, L as CompletionResult, c as withCompletionCommand, d as GenerateBundledCompletionWorkerOptions, f as GenerateBundledCompletionWorkerResult, h as generateBundledCompletionWorker, o as generateCompletion, t as WithCompletionOptions } from "./index-qqwo5WZT.js";
3
- import { z } from "zod";
4
- //#region src/compile-cache-shim.d.ts
1
+ export * from "@politty/zod";
2
+ //#region src/index.d.ts
5
3
  /**
6
- * Generator for compile-cache bin shims.
4
+ * Generate compile-cache bin shims that import the cache helper from
5
+ * `politty/compile-cache`.
7
6
  *
8
- * Emits the minimal entry file described in docs/recipes.md ("Faster
9
- * Startup"): a shim that enables the Node.js on-disk compile cache via
10
- * `politty/compile-cache` and then loads the real CLI with a dynamic
11
- * import. Meant to be wired into a `postbuild` or `prepack` script via
12
- * `politty generate-shim` so the shim never has to live in source.
7
+ * Overrides `@politty/zod`'s binding of the same name — the one thing this
8
+ * alias cannot re-export as-is. A CLI depending on `politty` alone cannot
9
+ * resolve `@politty/zod` from its own package under a strict node_modules
10
+ * layout (pnpm), so a shim naming it would silently lose the compile cache.
13
11
  */
14
- /**
15
- * Options for {@link generateCompileCacheShim}.
16
- */
17
- interface GenerateCompileCacheShimOptions {
18
- /**
19
- * Module specifier(s) the shim imports to start the CLI, relative to the
20
- * generated shim file (e.g. `./cli.js`). Pass one per shim; when `out` is
21
- * omitted the count must match the package's `bin` entries (paired in
22
- * order). Defaults to the first of `./cli.js`, `./cli.mjs`, `./index.js`,
23
- * `./index.mjs` that exists next to each shim.
24
- */
25
- entry?: string | string[];
26
- /**
27
- * Output path(s) for the generated shim(s) (e.g. `dist/bin.js`). When
28
- * given, the count must match `entry` (paired in order). Defaults to all
29
- * `bin` paths in the nearest `package.json` — the places the executables
30
- * must live.
31
- */
32
- out?: string | string[];
33
- /**
34
- * Program name used to derive the cache directory, applied to every
35
- * generated shim. Defaults per shim to the `bin` name whose path is the
36
- * shim's output, falling back to the first `bin` name and then the
37
- * package name without its scope. The fallback never happens silently: a
38
- * warning is printed when an explicit `out` path cannot be matched to a
39
- * `bin` entry.
40
- */
41
- program?: string;
42
- /**
43
- * Base directory for resolving paths and locating the nearest
44
- * `package.json` (default: `process.cwd()`).
45
- */
46
- cwd?: string;
47
- }
48
- /**
49
- * One generated shim from {@link generateCompileCacheShim}.
50
- */
51
- interface GenerateCompileCacheShimResult {
52
- /** Absolute path of the generated shim. */
53
- outputPath: string;
54
- /** Program name baked into the shim. */
55
- program: string;
56
- /** Entry specifier baked into the shim. */
57
- entry: string;
58
- }
59
- /**
60
- * Generate executable compile-cache bin shims.
61
- *
62
- * With no explicit paths, one shim is generated per `bin` entry of the
63
- * nearest `package.json`, each importing a conventional built module next
64
- * to it — so a bare `politty generate-shim` in a `postbuild` script is
65
- * usually enough. Explicit `entry` values are paired in order with the
66
- * `bin` entries (or with explicit `out` values of the same count).
67
- *
68
- * The generated files are ESM (they use top-level `await import`), so `.js`
69
- * output requires `"type": "module"` in the package; use a `.mjs` extension
70
- * otherwise. Refuses to overwrite an existing file it did not generate, so
71
- * a `bin` path still pointing at the real CLI entry fails loudly instead of
72
- * clobbering the build output.
73
- */
74
- declare function generateCompileCacheShim(options?: GenerateCompileCacheShimOptions): GenerateCompileCacheShimResult[];
75
- //#endregion
76
- //#region src/core/case-types.d.ts
77
- /**
78
- * TypeScript utility types for case conversion between camelCase and kebab-case.
79
- *
80
- * These types enable dual-case access on CLI args objects,
81
- * so that both `args.myOption` and `args["my-option"]` are valid.
82
- */
83
- /**
84
- * Convert a kebab-case string to camelCase at the type level.
85
- *
86
- * @example
87
- * type R = CamelCase<"my-option">; // "myOption"
88
- * type R2 = CamelCase<"already">; // "already"
89
- */
90
- type CamelCase<S extends string> = S extends `${infer P}-${infer C}${infer R}` ? `${P}${Uppercase<C>}${CamelCase<R>}` : S;
91
- /**
92
- * Internal helper: insert hyphens before uppercase-to-lowercase transitions.
93
- * Matches the runtime `toKebabCase()` behavior:
94
- * - `([a-z])([A-Z])` → insert hyphen (e.g. "myOption" → "my-Option")
95
- * - `([A-Z]+)([A-Z][a-z])` → insert hyphen before last capital in a run
96
- * (e.g. "XMLParser" → "XML-Parser" → "xml-parser")
97
- *
98
- * Note: TypeScript template literal types have limited ability to match
99
- * multi-character uppercase runs precisely. This implementation handles
100
- * common CLI naming patterns (camelCase, PascalCase). For exotic acronym
101
- * patterns (e.g. "XMLParser"), the type-level result may differ slightly
102
- * from the runtime result. Dual-case proxy handles runtime resolution.
103
- */
104
- 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;
105
- /**
106
- * Strip a leading hyphen (produced when the first char is uppercase).
107
- */
108
- type StripLeadingHyphen<S extends string> = S extends `-${infer R}` ? R : S;
109
- /**
110
- * Convert a camelCase string to kebab-case at the type level.
111
- * Aligned with the runtime `toKebabCase()` function in schema-extractor.ts.
112
- *
113
- * @example
114
- * type R = KebabCase<"myOption">; // "my-option"
115
- * type R2 = KebabCase<"already">; // "already"
116
- */
117
- type KebabCase<S extends string> = StripLeadingHyphen<KebabCaseInner<S>>;
118
- /**
119
- * Add both camelCase and kebab-case variants for every key in T.
120
- *
121
- * Given `{ "my-option": string }`, produces
122
- * `{ "my-option": string } & { myOption: string }`.
123
- *
124
- * Given `{ myOption: string }`, produces
125
- * `{ myOption: string } & { "my-option": string }`.
126
- *
127
- * Keys that are identical in both cases (e.g. single-word keys) are not duplicated.
128
- * Uses a distributive conditional type so it works correctly with discriminated unions.
129
- */
130
- 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;
131
- //#endregion
132
- //#region src/core/case-proxy.d.ts
133
- /**
134
- * Wrap an args object with a Proxy that allows dual-case access.
135
- *
136
- * Given `{ "my-option": "value" }`, both `obj["my-option"]` and `obj.myOption`
137
- * will return `"value"`.
138
- *
139
- * - `Object.keys()`, `JSON.stringify()`, and spread return only the original keys.
140
- * - The `in` operator detects both case variants.
141
- */
142
- declare function createDualCaseProxy<T extends Record<string, unknown>>(obj: T): WithCaseVariants<T>;
143
- //#endregion
144
- //#region src/core/command.d.ts
145
- /**
146
- * Infer args type from schema, defaults to empty object if undefined.
147
- * Wraps with WithCaseVariants so both camelCase and kebab-case access is typed.
148
- */
149
- type InferArgs<TArgsSchema> = TArgsSchema extends z.ZodType ? WithCaseVariants<z.infer<TArgsSchema>> : Record<string, never>;
150
- /**
151
- * Merge local args with global args.
152
- * No-op when TGlobalArgs is empty (default GlobalArgs not extended).
153
- * Wraps TGlobalArgs with WithCaseVariants for dual-case access.
154
- */
155
- type MergedArgs<TLocalArgs, TGlobalArgs> = IsEmpty<TGlobalArgs> extends true ? TLocalArgs : TLocalArgs & WithCaseVariants<TGlobalArgs>;
156
- /**
157
- * Add the `$source` helper, which reports whether a given field's final
158
- * value came from an explicit CLI token, a `field.env` fallback, or
159
- * neither (schema default / `prompt` resolution).
160
- *
161
- * `name` is typed as a plain `string` (not `keyof T`) since the runtime
162
- * helper deliberately accepts either camelCase or kebab-case field names
163
- * (matching `createDualCaseProxy`'s dual-case access) and returns
164
- * `"default"` for anything it doesn't recognize. A `keyof T`-based type
165
- * would also be unsound for discriminated-union `args` schemas, where
166
- * narrowing `args` to one branch doesn't retroactively narrow `$source`'s
167
- * already-fixed parameter type.
168
- */
169
- type WithArgSource<T> = T & {
170
- $source?: (name: string) => ArgSource;
171
- };
172
- /**
173
- * Resolve merged args from schema and global args type
174
- */
175
- type ResolvedArgs<TArgsSchema, TGlobalArgs> = WithArgSource<MergedArgs<InferArgs<TArgsSchema>, TGlobalArgs>>;
176
- /**
177
- * Config for defining a command
178
- * @template TArgsSchema - The Zod schema type for arguments
179
- * @template TResult - The return type of run function (void if no run)
180
- * @template TGlobalArgs - Global args type (from declaration merging or factory)
181
- */
182
- interface DefineCommandConfig<TArgsSchema extends ArgsSchema | undefined, TResult, TGlobalArgs> {
183
- name: string;
184
- description?: string;
185
- aliases?: string[];
186
- args?: TArgsSchema;
187
- subCommands?: SubCommandsRecord;
188
- setup?: (context: {
189
- args: ResolvedArgs<TArgsSchema, TGlobalArgs>;
190
- }) => void | Promise<void>;
191
- run?: (args: ResolvedArgs<TArgsSchema, TGlobalArgs>) => TResult;
192
- cleanup?: (context: {
193
- args: ResolvedArgs<TArgsSchema, TGlobalArgs>;
194
- error?: Error | undefined;
195
- }) => void | Promise<void>;
196
- notes?: string;
197
- examples?: Example[];
198
- }
199
- /**
200
- * Config with run function (runnable command)
201
- */
202
- interface RunnableConfig<TArgsSchema extends ArgsSchema | undefined, TResult, TGlobalArgs> extends DefineCommandConfig<TArgsSchema, TResult, TGlobalArgs> {
203
- run: (args: ResolvedArgs<TArgsSchema, TGlobalArgs>) => TResult;
204
- }
205
- /**
206
- * Config without run function (non-runnable command)
207
- */
208
- interface NonRunnableConfig<TArgsSchema extends ArgsSchema | undefined, TGlobalArgs> extends Omit<DefineCommandConfig<TArgsSchema, void, TGlobalArgs>, "run"> {
209
- run?: undefined;
210
- }
211
- /**
212
- * Define a CLI command with type-safe arguments
213
- *
214
- * @param config - Command configuration
215
- * @returns A defined command with preserved type information
216
- *
217
- * @example
218
- * ```ts
219
- * import { z } from "zod";
220
- * import { arg, defineCommand } from "politty";
221
- *
222
- * const command = defineCommand({
223
- * name: "greet",
224
- * args: z.object({
225
- * name: arg(z.string(), { description: "Name to greet", positional: true }),
226
- * loud: arg(z.boolean().default(false), { alias: "l", description: "Use uppercase" }),
227
- * }),
228
- * run: (args) => {
229
- * const greeting = `Hello, ${args.name}!`;
230
- * console.log(args.loud ? greeting.toUpperCase() : greeting);
231
- * },
232
- * });
233
- *
234
- * // Type of command.argsSchema is preserved as z.ZodObject<...>
235
- * // Type of command.run is (args: { name: string; loud: boolean }) => void
236
- * ```
237
- *
238
- * @example
239
- * ```ts
240
- * // With discriminated union for subcommand-like behavior
241
- * const command = defineCommand({
242
- * name: "resource",
243
- * args: z.discriminatedUnion("action", [
244
- * z.object({
245
- * action: z.literal("create"),
246
- * name: arg(z.string(), { description: "Resource name" }),
247
- * }),
248
- * z.object({
249
- * action: z.literal("delete"),
250
- * id: arg(z.coerce.number(), { description: "Resource ID" }),
251
- * }),
252
- * ]),
253
- * run: (args) => {
254
- * if (args.action === "create") {
255
- * console.log(`Creating ${args.name}`);
256
- * } else {
257
- * console.log(`Deleting ${args.id}`);
258
- * }
259
- * },
260
- * });
261
- * ```
262
- */
263
- declare function defineCommand<TArgsSchema extends ArgsSchema | undefined = undefined, TResult = void, TGlobalArgs = GlobalArgs>(config: RunnableConfig<TArgsSchema, TResult, TGlobalArgs>): RunnableCommand<TArgsSchema, ResolvedArgs<TArgsSchema, TGlobalArgs>, TResult>;
264
- declare function defineCommand<TArgsSchema extends ArgsSchema | undefined = undefined, TGlobalArgs = GlobalArgs>(config: NonRunnableConfig<TArgsSchema, TGlobalArgs>): NonRunnableCommand<TArgsSchema, ResolvedArgs<TArgsSchema, TGlobalArgs>>;
265
- /**
266
- * Create a typed defineCommand factory with pre-bound global args type.
267
- * This is the recommended pattern for type-safe global options.
268
- *
269
- * @example
270
- * ```ts
271
- * // global-args.ts
272
- * type GlobalArgsType = { verbose: boolean; config?: string };
273
- * export const defineAppCommand = createDefineCommand<GlobalArgsType>();
274
- *
275
- * // commands/build.ts
276
- * export const buildCommand = defineAppCommand({
277
- * name: "build",
278
- * args: z.object({ output: arg(z.string().default("dist")) }),
279
- * run: (args) => {
280
- * args.verbose; // typed via GlobalArgsType
281
- * args.output; // typed via local args
282
- * },
283
- * });
284
- * ```
285
- */
286
- declare function createDefineCommand<TGlobalArgs>(): {
287
- <TArgsSchema extends ArgsSchema | undefined = undefined, TResult = void>(config: RunnableConfig<TArgsSchema, TResult, TGlobalArgs>): RunnableCommand<TArgsSchema, ResolvedArgs<TArgsSchema, TGlobalArgs>, TResult>;
288
- <TArgsSchema extends ArgsSchema | undefined = undefined>(config: NonRunnableConfig<TArgsSchema, TGlobalArgs>): NonRunnableCommand<TArgsSchema, ResolvedArgs<TArgsSchema, TGlobalArgs>>;
289
- };
290
- //#endregion
291
- //#region src/core/runner.d.ts
292
- /**
293
- * Run a command with the given arguments (programmatic/test usage)
294
- *
295
- * This function parses arguments, validates them, routes to subcommands,
296
- * and executes the command. It does NOT call process.exit.
297
- *
298
- * @param command - The command to run
299
- * @param argv - Command line arguments to parse
300
- * @param options - Run options
301
- * @returns The result of command execution
302
- *
303
- * @example
304
- * ```ts
305
- * import { defineCommand, runCommand } from "politty";
306
- *
307
- * const command = defineCommand({
308
- * name: "my-cli",
309
- * args: z.object({ name: z.string() }),
310
- * run: ({ name }) => console.log(`Hello, ${name}!`),
311
- * });
312
- *
313
- * // In tests
314
- * const result = await runCommand(command, ["--name", "World"]);
315
- * expect(result.exitCode).toBe(0);
316
- * ```
317
- */
318
- declare function runCommand<TResult = unknown>(command: AnyCommand, argv: string[], options?: RunCommandOptions): Promise<RunResult<TResult>>;
319
- /**
320
- * Run a CLI command as the main entry point
321
- *
322
- * This function:
323
- * - Uses process.argv for arguments
324
- * - Handles SIGINT/SIGTERM signals
325
- * - Calls process.exit with the appropriate exit code
326
- * - Invokes `command.runMainHook` once before parsing if set, so plug-ins
327
- * like `withCompletionCommand` can fire detached background work
328
- * - Bypasses user `setup`/`cleanup`/`prompt` and required `globalArgs`
329
- * for registered hidden subcommands whose name starts with `__`
330
- * (e.g. `__refresh-completion`)
331
- *
332
- * @param command - The command to run
333
- * @param options - Main options (version, debug)
334
- *
335
- * @example
336
- * ```ts
337
- * import { defineCommand, runMain } from "politty";
338
- *
339
- * const command = defineCommand({
340
- * name: "my-cli",
341
- * run: () => console.log("Hello!"),
342
- * });
343
- *
344
- * runMain(command, { version: "1.0.0" });
345
- * ```
346
- */
347
- declare function runMain(command: AnyCommand, options?: MainOptions): Promise<never>;
348
- //#endregion
349
- //#region src/output/help-generator.d.ts
350
- /**
351
- * Descriptions for built-in options
352
- */
353
- interface BuiltinOptionDescriptions {
354
- /** Description for --help option */
355
- help?: string;
356
- /** Description for --help-all option */
357
- helpAll?: string;
358
- /** Description for --version option */
359
- version?: string;
360
- }
361
- /**
362
- * Context for command hierarchy
363
- */
364
- interface CommandContext {
365
- /** Full command path (e.g., ["config", "get"]) */
366
- commandPath?: string[] | undefined;
367
- /** Root command name */
368
- rootName?: string | undefined;
369
- /** Root command version */
370
- rootVersion?: string | undefined;
371
- /** Extracted fields from global args schema */
372
- globalExtracted?: ExtractedFields | undefined;
373
- /** When the command was accessed via an alias, the canonical command name */
374
- aliasFor?: string | undefined;
375
- }
376
- /**
377
- * Options for help generation
378
- */
379
- interface HelpOptions {
380
- /** Show subcommand list */
381
- showSubcommands?: boolean | undefined;
382
- /** Show subcommand options */
383
- showSubcommandOptions?: boolean | undefined;
384
- /** Custom descriptions for built-in options */
385
- descriptions?: BuiltinOptionDescriptions | undefined;
386
- /** Command hierarchy context */
387
- context?: CommandContext | undefined;
388
- }
389
- /**
390
- * Generate help text for a command
391
- *
392
- * @param command - The command to generate help for
393
- * @param options - Help generation options
394
- * @returns Formatted help text
395
- */
396
- declare function generateHelp(command: AnyCommand, options: HelpOptions): string;
397
- //#endregion
398
- //#region src/output/logger.d.ts
399
- /**
400
- * Enable or disable color output programmatically
401
- */
402
- declare function setColorEnabled(enabled: boolean): void;
403
- /**
404
- * Check if color output is currently enabled
405
- */
406
- declare function isColorEnabled(): boolean;
407
- /**
408
- * Semantic style functions for inline text styling
409
- */
410
- declare const styles: {
411
- success: (text: string) => string;
412
- error: (text: string) => string;
413
- warning: (text: string) => string;
414
- info: (text: string) => string;
415
- bold: (text: string) => string;
416
- dim: (text: string) => string;
417
- italic: (text: string) => string;
418
- underline: (text: string) => string;
419
- red: (text: string) => string;
420
- green: (text: string) => string;
421
- yellow: (text: string) => string;
422
- blue: (text: string) => string;
423
- magenta: (text: string) => string;
424
- cyan: (text: string) => string;
425
- white: (text: string) => string;
426
- gray: (text: string) => string;
427
- command: (text: string) => string;
428
- commandName: (text: string) => string;
429
- option: (text: string) => string;
430
- optionName: (text: string) => string;
431
- placeholder: (text: string) => string;
432
- defaultValue: (text: string) => string;
433
- required: (text: string) => string;
434
- description: (text: string) => string;
435
- sectionHeader: (text: string) => string;
436
- version: (text: string) => string;
437
- };
438
- /**
439
- * Standardized symbols for CLI output
440
- */
441
- declare const symbols: {
442
- success: string;
443
- error: string;
444
- warning: string;
445
- info: string;
446
- bullet: string;
447
- arrow: string;
448
- };
449
- /**
450
- * Logger for CLI output
451
- */
452
- declare const logger: {
453
- /**
454
- * Log informational message
455
- */
456
- info(message: string): void;
457
- /**
458
- * Log success message
459
- */
460
- success(message: string): void;
461
- /**
462
- * Log warning message
463
- */
464
- warn(message: string): void;
465
- /**
466
- * Log error message
467
- */
468
- error(message: string): void;
469
- /**
470
- * Log raw message without prefix
471
- */
472
- log(message: string): void;
473
- /**
474
- * Log empty line
475
- */
476
- newline(): void;
477
- /**
478
- * Log debug message with dim color
479
- */
480
- debug(message: string): void;
481
- };
482
- //#endregion
483
- //#region src/output/markdown-renderer.d.ts
484
- /**
485
- * Lightweight Markdown-to-terminal renderer.
486
- *
487
- * Supports a subset of Markdown tailored for CLI help notes:
488
- * - Inline: bold, italic, inline code, links
489
- * - Block: paragraphs, unordered/ordered lists, blockquotes, headings,
490
- * horizontal rules, fenced code blocks
491
- */
492
- /**
493
- * Apply inline Markdown formatting to a string.
494
- *
495
- * Processing order matters to avoid conflicts:
496
- * 1. Inline code (backticks) — content inside is literal, no further processing
497
- * 2. Bold (**text**)
498
- * 3. Italic (*text* or _text_)
499
- * 4. Links [text](url)
500
- */
501
- declare function renderInline(text: string): string;
502
- /**
503
- * Render a Markdown string to styled terminal output.
504
- *
505
- * Block-level processing:
506
- * - Splits input into blocks separated by blank lines
507
- * - Detects headings, horizontal rules, blockquotes, lists, code blocks, and paragraphs
508
- * - Applies inline formatting within each block
509
- */
510
- declare function renderMarkdown(markdown: string): string;
511
- //#endregion
512
- //#region src/parser/argv-parser.d.ts
513
- /**
514
- * Parsed arguments result
515
- */
516
- interface ParsedArgv {
517
- /** Named options (--flag, -f) */
518
- options: Record<string, unknown>;
519
- /** Positional arguments */
520
- positionals: string[];
521
- /** Arguments after -- */
522
- rest: string[];
523
- }
524
- /**
525
- * Parser options
526
- */
527
- interface ParserOptions {
528
- /** Alias map (short -> long) */
529
- aliasMap?: Map<string, string>;
530
- /** Boolean flags (no value expected) */
531
- booleanFlags?: Set<string>;
532
- /** Array flags (can be repeated) */
533
- arrayFlags?: Set<string>;
534
- /**
535
- * All known canonical option names (as defined in the schema).
536
- * Used to disambiguate negation: when `--no-flag` or `--noFlag` matches
537
- * a name in this set, it is treated as a regular option rather than
538
- * boolean negation of `flag`.
539
- */
540
- definedNames?: Set<string>;
541
- /**
542
- * Map from a custom negation CLI name (and camelCase variant) to the
543
- * canonical field name. Used to recognize user-defined boolean negation
544
- * options (e.g. `--disable-cache` → `{ cache: false }`).
545
- */
546
- negationMap?: Map<string, string>;
547
- /**
548
- * Canonical field names whose default `--no-<name>` / `--no<Name>`
549
- * negation forms are suppressed. When omitted, every field in
550
- * `booleanFlags` has default negation suppressed.
551
- */
552
- defaultNegationDisabledFields?: Set<string>;
553
- }
554
- /**
555
- * Parse argv into a flat record
556
- *
557
- * Supports:
558
- * - Long options: --flag, --flag=value, --flag value
559
- * - Short options: -f, -f=value, -f value
560
- * - Combined short options: -abc (treated as -a -b -c if all are boolean)
561
- * - Positional arguments
562
- * - -- to stop parsing options
563
- * - Boolean negation: --no-flag, --noFlag (requires `booleanFlags` and `negation: true`)
564
- *
565
- * **Note:** When using negation detection (`--noFlag` / `--no-flag`),
566
- * supply `definedNames` so that options whose names happen to start with
567
- * "no" (e.g. `noDryRun`) are not mistaken for negation of another flag.
568
- * Without `definedNames`, all `--noX` forms matching a boolean flag will
569
- * be treated as negation.
570
- *
571
- * @param argv - Command line arguments
572
- * @param options - Parser options
573
- * @returns Parsed arguments
574
- */
575
- declare function parseArgv(argv: string[], options?: ParserOptions): ParsedArgv;
576
- //#endregion
577
- //#region src/validator/validation-errors.d.ts
578
- /**
579
- * Error thrown when positional argument configuration is invalid
580
- */
581
- declare class PositionalConfigError extends Error {
582
- constructor(message: string);
583
- }
584
- /**
585
- * Error thrown when a reserved alias is used
586
- */
587
- declare class ReservedAliasError extends Error {
588
- constructor(message: string);
589
- }
590
- /**
591
- * Error thrown when duplicate field names are detected
592
- */
593
- declare class DuplicateFieldError extends Error {
594
- constructor(message: string);
595
- }
596
- /**
597
- * Error thrown when duplicate aliases are detected
598
- */
599
- declare class DuplicateAliasError extends Error {
600
- constructor(message: string);
601
- }
602
- /**
603
- * Error thrown when fields are case variants of each other (e.g. "my-option" and "myOption")
604
- */
605
- declare class CaseVariantCollisionError extends Error {
606
- constructor(message: string);
607
- }
608
- /**
609
- * Error thrown when a custom boolean negation name collides with another
610
- * field's name, cliName, alias, or another field's negation (including
611
- * derived camelCase variants).
612
- */
613
- declare class DuplicateNegationError extends Error {
614
- constructor(message: string);
615
- }
616
- /**
617
- * Error thrown when a field name collides with a reserved, framework-injected
618
- * key on the final args object (e.g. `$source`).
619
- */
620
- declare class ReservedFieldNameError extends Error {
621
- constructor(message: string);
622
- }
623
- /**
624
- * Error thrown when a global field and a same-named local field have
625
- * different definitions (per `extractFields()`'s type bucket, whether the
626
- * field is positional, and enum values). Only exactly-matching definitions
627
- * are allowed to share a name across global/local schemas — anything else
628
- * is rejected at validation time rather than risking a value from one
629
- * schema silently flowing into the other.
630
- */
631
- declare class FieldTypeConflictError extends Error {
632
- constructor(message: string);
633
- }
634
- //#endregion
635
- //#region src/validator/command-validator.d.ts
636
- /**
637
- * Error detail for command validation
638
- */
639
- interface CommandValidationError {
640
- /** Path to the command (e.g., ["cli", "build", "watch"]) */
641
- commandPath: string[];
642
- /** Error type */
643
- type: "duplicate_field" | "duplicate_alias" | "invalid_alias" | "positional_config" | "reserved_alias" | "reserved_field_name" | "case_variant_collision" | "duplicate_negation" | "field_type_conflict";
644
- /** Error message */
645
- message: string;
646
- /** Related field name (if applicable) */
647
- field?: string;
648
- }
649
- /**
650
- * Result of command validation
651
- */
652
- type CommandValidationResult = {
653
- valid: true;
654
- } | {
655
- valid: false;
656
- errors: CommandValidationError[];
657
- };
658
- /**
659
- * Options for validateCommand
660
- */
661
- interface ValidateCommandOptions {
662
- /** Starting command path (for nested validation) */
663
- commandPath?: string[];
664
- /**
665
- * Global args schema to check the command tree against for cross-schema
666
- * field collisions (case-variant collisions and `FieldTypeConflictError`
667
- * conflicts) -- the same check `runCommand()` performs per-invocation at
668
- * parse time, but here applied eagerly to every command and subcommand
669
- * regardless of which subcommand path actually gets invoked at runtime.
670
- */
671
- globalArgs?: ArgsSchema;
672
- }
673
- /**
674
- * Validate that no duplicate field names exist
675
- *
676
- * @param extracted - Extracted fields from schema
677
- * @throws {DuplicateFieldError} If duplicate field names are found
678
- */
679
- declare function validateDuplicateFields(extracted: ExtractedFields): void;
680
- /**
681
- * Validate that no duplicate aliases exist
682
- *
683
- * Also checks for conflicts between aliases and field names
684
- *
685
- * @param extracted - Extracted fields from schema
686
- * @throws {DuplicateAliasError} If duplicate aliases are found or alias conflicts with field name
687
- */
688
- declare function validateDuplicateAliases(extracted: ExtractedFields): void;
689
- /**
690
- * Validate positional argument configuration
691
- *
692
- * Rules:
693
- * - Array positional arguments must be the last positional
694
- * - No positional arguments can follow an array positional
695
- * - Required positional arguments cannot follow optional positional arguments
696
- * - Array positional and optional positional cannot be used together (ambiguous parsing)
697
- *
698
- * @param extracted - Extracted fields from schema
699
- * @throws {PositionalConfigError} If configuration is invalid
700
- */
701
- declare function validatePositionalConfig(extracted: ExtractedFields): void;
702
- /**
703
- * Validate that no reserved aliases are used without explicit override
704
- *
705
- * Reserved aliases:
706
- * - 'h' is reserved for --help
707
- * - 'H' is reserved for --help-all
708
- *
709
- * Users can override these by setting overrideBuiltinAlias: true
710
- *
711
- * @param extracted - Extracted fields from schema
712
- * @param _hasSubCommands - Whether the command has subcommands (reserved for future use)
713
- * @throws {ReservedAliasError} If a reserved alias is used without override flag
714
- */
715
- declare function validateReservedAliases(extracted: ExtractedFields, _hasSubCommands: boolean): void;
716
- /**
717
- * Validate that no field name starts with `$`
718
- *
719
- * The `$` prefix is reserved for framework-injected helpers on the final
720
- * args object (e.g. `$source`), and is unusable as a real CLI flag anyway
721
- * since an unquoted `$name` gets shell-expanded before the program sees it.
722
- *
723
- * Checking `field.name` alone is sufficient: aliases can't start with `$`
724
- * (schema extraction already restricts alias characters to `[A-Za-z0-9-]`),
725
- * and `cliName` is derived from `name` via `toKebabCase`, which never strips
726
- * or moves a leading `$`. See {@link checkReservedFieldNames}.
727
- *
728
- * @param extracted - Extracted fields from schema
729
- * @throws {ReservedFieldNameError} If a field name starts with "$"
730
- */
731
- declare function validateReservedFieldNames(extracted: ExtractedFields): void;
732
- /**
733
- * Validate that custom boolean negation names do not collide with anything
734
- *
735
- * @param extracted - Extracted fields from schema
736
- * @throws {DuplicateNegationError} If a colliding negation is found
737
- */
738
- declare function validateDuplicateNegations(extracted: ExtractedFields): void;
739
- /**
740
- * Validate that no case-variant collisions exist
741
- *
742
- * @param extracted - Extracted fields from schema
743
- * @throws {CaseVariantCollisionError} If case-variant collisions are found
744
- */
745
- declare function validateCaseVariantCollisions(extracted: ExtractedFields): void;
746
- /**
747
- * Validate that no cross-schema collisions exist between two schemas
748
- * (e.g., global args and command args): neither a case-variant collision
749
- * (same canonical name, different spelling) nor a same-named field with a
750
- * different definition (same spelling, but the two schemas don't agree on
751
- * what values are valid).
752
- *
753
- * @param extractedA - Extracted fields from first schema (e.g., global args)
754
- * @param extractedB - Extracted fields from second schema (e.g., command args)
755
- * @throws {CaseVariantCollisionError} If cross-schema case-variant collisions are found
756
- * @throws {FieldTypeConflictError} If a same-named field has a different definition on each schema
757
- */
758
- declare function validateCrossSchemaCollisions(extractedA: ExtractedFields, extractedB: ExtractedFields): void;
759
- /**
760
- * Validate a command and all its subcommands recursively
761
- *
762
- * This function collects all validation errors without throwing,
763
- * making it suitable for test assertions.
764
- *
765
- * @param command - The command to validate
766
- * @param options - Validation options
767
- * @returns Validation result with all errors collected
768
- *
769
- * @example
770
- * ```ts
771
- * const result = await validateCommand(myCommand);
772
- * if (!result.valid) {
773
- * console.error(result.errors);
774
- * }
775
- * ```
776
- */
777
- declare function validateCommand(command: AnyCommand, options?: ValidateCommandOptions): Promise<CommandValidationResult>;
778
- /**
779
- * Format command validation errors for display
780
- *
781
- * @param errors - Array of validation errors
782
- * @returns Formatted error message
783
- */
784
- declare function formatCommandValidationErrors(errors: CommandValidationError[]): string;
785
- //#endregion
786
- //#region src/validator/zod-validator.d.ts
787
- /**
788
- * Validation error details
789
- */
790
- interface ValidationError {
791
- /** Path to the invalid field */
792
- path: string[];
793
- /** Error message */
794
- message: string;
795
- /** Zod error code */
796
- code: string;
797
- /** Value that was received */
798
- received?: unknown | undefined;
799
- /** Expected type or value */
800
- expected?: string | undefined;
801
- }
802
- /**
803
- * Validation result
804
- */
805
- type ValidationResult<T> = {
806
- success: true;
807
- data: T;
808
- } | {
809
- success: false;
810
- errors: ValidationError[];
811
- };
812
- /**
813
- * Format validation errors for display
814
- */
815
- declare function formatValidationErrors(errors: ValidationError[]): string;
12
+ declare const generateCompileCacheShim: (options?: import("@politty/zod").GenerateCompileCacheShimOptions) => import("@politty/zod").GenerateCompileCacheShimResult[];
816
13
  //#endregion
817
- export { type AnyCommand, type ArgMeta, type ArgSource, type ArgsSchema, type BuiltinOptionDescriptions, type CamelCase, CaseVariantCollisionError, 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 CustomCompletion, DuplicateAliasError, DuplicateFieldError, DuplicateNegationError, type DynamicCompletionCandidate, type DynamicCompletionContext, type DynamicCompletionResolver, type DynamicCompletionResult, type EffectContext, type Example, type ExpandCandidate, type ExpandCompletion, type ExtractedFields, FieldTypeConflictError, type GenerateBundledCompletionWorkerOptions, type GenerateBundledCompletionWorkerResult, type GenerateCompileCacheShimOptions, type GenerateCompileCacheShimResult, type GlobalArgs, type GlobalCleanupContext, type GlobalSetupContext, type HelpOptions, type KebabCase, type LazyCommand, type LogEntry, type LogLevel, type LogStream, type Logger, type MainOptions, type MergedArgs, type NonRunnableCommand, type ParsedArgv, type ParserOptions, PositionalConfigError, type PromptMeta, type PromptResolver, type PromptType, ReservedAliasError, ReservedFieldNameError, type ResolvedExpandCandidate, type ResolvedFieldMeta, type RunCommandOptions, type RunResult, type RunResultFailure, type RunResultSuccess, type RunnableCommand, type SetupContext, type SubCommandValue, type SubCommandsRecord, type UnknownKeysMode, type UnknownSubcommandHandler, type ValidationError, type ValidationResult, type WithCaseVariants, type WithCompletionOptions, arg, createDefineCommand, createDualCaseProxy, defineCommand, extractFields, formatCommandValidationErrors, formatValidationErrors, generateBundledCompletionWorker, generateCompileCacheShim, generateCompletion, generateHelp, getUnknownKeysMode, isColorEnabled, isLazyCommand, lazy, logger, parseArgv, renderInline, renderMarkdown, runCommand, runMain, setColorEnabled, styles, symbols, toCamelCase, toKebabCase, validateCaseVariantCollisions, validateCommand, validateCrossSchemaCollisions, validateDuplicateAliases, validateDuplicateFields, validateDuplicateNegations, validatePositionalConfig, validateReservedAliases, validateReservedFieldNames, withCompletionCommand };
818
- //# sourceMappingURL=index.d.ts.map
14
+ export { generateCompileCacheShim };