politty 0.11.3 → 0.11.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -16,6 +16,7 @@ From simple scripts to complex CLI tools with subcommands, validation, and auto-
16
16
  - **Interactive Prompts**: Prompt for missing arguments with pluggable adapters (clack, inquirer)
17
17
  - **Discriminated Union**: Support for mutually exclusive argument sets
18
18
  - **Skill Management**: Manage agent skills (SKILL.md) with file-based install/uninstall
19
+ - **Fast Startup**: Automatic Node.js compile cache (V8 code cache) integration, with a `generate-shim` command to cache the whole CLI graph
19
20
 
20
21
  ## Requirements
21
22
 
@@ -430,6 +431,23 @@ const command = defineCommand({
430
431
  });
431
432
  ```
432
433
 
434
+ ## Faster Startup (Compile Cache)
435
+
436
+ politty integrates Node.js's on-disk compile cache (V8 code cache, Node >= 22.8.0) so warm starts skip recompilation; older runtimes are a silent no-op. `runMain` enables it automatically, which covers dynamically imported modules such as `lazy()` subcommands. To cache the whole CLI graph — politty, zod, and your command definitions — generate a bin shim as part of your build:
437
+
438
+ ```jsonc
439
+ // package.json
440
+ {
441
+ "bin": { "my-cli": "./dist/bin.js" },
442
+ "scripts": {
443
+ "build": "tsdown", // builds src/cli.ts -> dist/cli.js
444
+ "postbuild": "politty generate-shim --entry ./cli.js",
445
+ },
446
+ }
447
+ ```
448
+
449
+ `generate-shim` writes an executable shim that enables the cache and loads `--entry` (a specifier relative to the shim) with a dynamic import. The rest is derived from `package.json`: the output path from the `bin` path and the program name from the `bin` name; packages with multiple bins pass `--entry` once per bin, and `--entry` itself can be omitted when the entry sits next to the shim under a conventional name (`./cli.js`, `./index.js`, ...). See [Faster Startup (Compile Cache)](./docs/recipes.md#faster-startup-compile-cache) for the flags, the opt-out (`compileCache: false`), and the hand-written shim variant.
450
+
433
451
  ## Skill Management
434
452
 
435
453
  politty manages SKILL.md-based agent skills distributed via npm packages.
@@ -450,9 +468,7 @@ const sourceDir = resolve(dirname(fileURLToPath(import.meta.url)), "../skills");
450
468
  const cli = withSkillCommand(
451
469
  defineCommand({
452
470
  name: "my-agent",
453
- subCommands: {
454
- /* ... */
455
- },
471
+ subCommands: {/* ... */},
456
472
  }),
457
473
  { sourceDir, package: "@my-agent/skills" },
458
474
  );
@@ -493,7 +509,7 @@ For detailed documentation, see the `docs/` directory:
493
509
  - [Essentials](./docs/essentials.md) - Core concepts explained
494
510
  - [Advanced Features](./docs/advanced-features.md) - Subcommands, Discriminated Union
495
511
  - [Interactive Prompts](./docs/interactive-prompts.md) - Prompt for missing arguments interactively
496
- - [Recipes](./docs/recipes.md) - Testing, configuration, error handling
512
+ - [Recipes](./docs/recipes.md) - Testing, configuration, error handling, faster startup (compile cache)
497
513
  - [Skill Management](./docs/skill-management.md) - Agent skill management (SKILL.md-based)
498
514
  - [API Reference](./docs/api-reference.md) - Detailed API reference
499
515
  - [Doc Generation](./docs/doc-generation.md) - Automatic documentation generation
@@ -1,5 +1,4 @@
1
1
  import { z } from "zod";
2
-
3
2
  //#region src/core/schema-extractor.d.ts
4
3
  /**
5
4
  * Resolved metadata for an argument field
@@ -389,6 +388,24 @@ interface MainOptions {
389
388
  * behavior. Not invoked for internal `__*` subcommands.
390
389
  */
391
390
  onUnknownSubcommand?: UnknownSubcommandHandler | undefined;
391
+ /**
392
+ * Node.js on-disk compile cache (V8 code cache) control. `runMain` enables
393
+ * it before executing the command so dynamically imported modules (e.g.
394
+ * `lazy()` subcommands) skip recompilation on warm starts (Node >= 22.8.0;
395
+ * no-op otherwise).
396
+ * - omitted / `true`: derive the directory from the command name
397
+ * (`${XDG_CACHE_HOME:-$HOME/.cache}/<sanitized name>/node-compile-cache`,
398
+ * shared with shell-completion workers; the name is reduced to a single
399
+ * safe path segment, e.g. `@scope/cli` → `scope-cli`)
400
+ * - `string`: use this cache directory
401
+ * - `false`: do not enable
402
+ *
403
+ * The `NODE_COMPILE_CACHE` environment variable always takes precedence.
404
+ * Note: the entry module's static import graph is compiled before `runMain`
405
+ * runs and cannot be cached here — see `politty/compile-cache` for the
406
+ * bin-shim pattern that covers it.
407
+ */
408
+ compileCache?: boolean | string;
392
409
  }
393
410
  /**
394
411
  * Handler for an unrecognized subcommand. See {@link MainOptions.onUnknownSubcommand}.
@@ -398,9 +415,19 @@ type UnknownSubcommandHandler = (context: {
398
415
  * Known subcommand names traversed before the unknown name (excludes the
399
416
  * root command name). Empty at the root level.
400
417
  */
401
- commandPath: readonly string[]; /** The unrecognized subcommand name (first unmatched positional). */
402
- name: string; /** Args following the name, forwarded verbatim to the plugin. */
418
+ commandPath: readonly string[];
419
+ /** The unrecognized subcommand name (first unmatched positional). */
420
+ name: string;
421
+ /** Args following the name, forwarded verbatim to the plugin. */
403
422
  args: readonly string[];
423
+ /**
424
+ * Option tokens the host consumed before the unknown name across every
425
+ * traversed level (e.g. global flags typed before the plugin command),
426
+ * excluding the traversed subcommand names themselves. Concatenate with
427
+ * `args` to reconstruct the user's full flag set when forwarding to a
428
+ * plugin: `[...precedingArgs, ...args]`.
429
+ */
430
+ precedingArgs: readonly string[];
404
431
  }) => number | undefined | Promise<number | undefined>;
405
432
  /**
406
433
  * Options for runCommand (programmatic/test usage)
@@ -654,13 +681,15 @@ interface CustomCompletion {
654
681
  * ```
655
682
  */
656
683
  type CompletionMeta = {
657
- /** Built-in completion type */type?: CompletionType; /** Custom completion (takes precedence over type if both specified) */
684
+ /** Built-in completion type */
685
+ type?: CompletionType;
686
+ /** Custom completion (takes precedence over type if both specified) */
658
687
  custom?: CustomCompletion;
659
688
  } & ({
660
- /** File extension filter (only applies when type is "file") */extensions?: string[];
689
+ /** File extension filter (only applies when type is "file") */ extensions?: string[];
661
690
  matcher?: never;
662
691
  } | {
663
- /** Glob patterns for file matching (only applies when type is "file") */matcher?: string[];
692
+ /** Glob patterns for file matching (only applies when type is "file") */ matcher?: string[];
664
693
  extensions?: never;
665
694
  });
666
695
  /**
@@ -714,7 +743,9 @@ interface PromptMeta {
714
743
  * When GlobalArgs is extended via declaration merging, `globalArgs` is typed accordingly.
715
744
  */
716
745
  type EffectContext = {
717
- /** Field name (camelCase) */name: string; /** Validated args for this schema (global args for global effects, command args for command effects) */
746
+ /** Field name (camelCase) */
747
+ name: string;
748
+ /** Validated args for this schema (global args for global effects, command args for command effects) */
718
749
  args: Readonly<Record<string, unknown>>;
719
750
  } & (IsEmpty<GlobalArgs> extends true ? {
720
751
  globalArgs?: Readonly<Record<string, unknown>>;
@@ -896,10 +927,10 @@ type ArgMeta<TValue = unknown> = RegularArgMeta<TValue> | BuiltinOverrideArgMeta
896
927
  * prevent distribution returning `never` for missing fields.
897
928
  */
898
929
  type ContainsReservedAlias<A> = [A] extends [never] ? false : A extends "h" | "H" ? true : A extends readonly (infer E)[] ? [Extract<E, "h" | "H">] extends [never] ? false : true : false;
899
- type ReservedAliasTypeError<M> = { [K in keyof M]: M[K] } & {
930
+ type ReservedAliasTypeError<M> = { [K in keyof M]: M[K]; } & {
900
931
  __typeError: "Alias 'h' or 'H' requires overrideBuiltinAlias: true";
901
932
  };
902
- type NegationTypeError<M> = { [K in keyof M]: M[K] } & {
933
+ type NegationTypeError<M> = { [K in keyof M]: M[K]; } & {
903
934
  __typeError: "negation/negationDescription can only be used on boolean fields";
904
935
  };
905
936
  type AliasFieldOf<M> = M extends {
@@ -947,4 +978,4 @@ declare function arg<T extends z.ZodType>(schema: T): T;
947
978
  declare function arg<T extends z.ZodType, M extends ArgMeta<z.output<T>>>(schema: T, meta: ValidateArgMeta<M, z.output<T>>): T;
948
979
  //#endregion
949
980
  export { toCamelCase as $, LogLevel as A, RunnableCommand as B, CommandBase as C, GlobalSetupContext as D, GlobalCleanupContext as E, PromptResolver as F, LazyCommand as G, SubCommandValue as H, RunCommandOptions as I, ExtractedFields as J, isLazyCommand as K, RunResult as L, Logger as M, MainOptions as N, IsEmpty as O, NonRunnableCommand as P, getUnknownKeysMode as Q, RunResultFailure as R, Command as S, GlobalArgs as T, SubCommandsRecord as U, SetupContext as V, UnknownSubcommandHandler as W, UnknownKeysMode as X, ResolvedFieldMeta as Y, extractFields as Z, AnyCommand as _, EffectContext as a, CleanupContext as b, arg as c, ResolvedExpandCandidate as d, toKebabCase as et, CompletionDirectiveMask as f, DynamicCompletionResult as g, DynamicCompletionResolver as h, CustomCompletion as i, LogStream as j, LogEntry as k, ExpandCandidate as l, DynamicCompletionContext as m, CompletionMeta as n, PromptMeta as o, DynamicCompletionCandidate as p, lazy as q, CompletionType as r, PromptType as s, ArgMeta as t, ExpandCompletion as u, ArgSource as v, Example as w, CollectedLogs as x, ArgsSchema as y, RunResultSuccess as z };
950
- //# sourceMappingURL=arg-registry-D558cYkD.d.ts.map
981
+ //# sourceMappingURL=arg-registry-SrNIsq-d.d.ts.map
package/dist/augment.d.ts CHANGED
@@ -1,5 +1,4 @@
1
- import { t as ArgMeta } from "./arg-registry-D558cYkD.js";
2
-
1
+ import { t as ArgMeta } from "./arg-registry-SrNIsq-d.js";
3
2
  //#region src/augment.d.ts
4
3
  declare module "zod" {
5
4
  interface ZodTypeDef {
@@ -0,0 +1 @@
1
+ export { };
@@ -0,0 +1,86 @@
1
+ import { n as generateCompileCacheShim, t as formatShimPath } from "./src-BiCtSNrn.js";
2
+ import { s as arg } from "./schema-extractor-wzJ1cGon.js";
3
+ import { n as defineCommand } from "./command-B4yA4LXX.js";
4
+ import { p as generateBundledCompletionWorker } from "./completion-D9SKGJad.js";
5
+ import { n as runMain } from "./runner-xN7248Ph.js";
6
+ import { z } from "zod";
7
+
8
+ //#region src/cli-main.ts
9
+ const generateWorkerCommand = defineCommand({
10
+ name: "generate-worker",
11
+ description: "Generate and verify a bundled shell completion worker",
12
+ args: z.object({
13
+ bin: arg(z.string(), {
14
+ description: "CLI binary or built JS entry file to invoke",
15
+ placeholder: "PATH"
16
+ }),
17
+ program: arg(z.string(), {
18
+ description: "Program name embedded in worker metadata",
19
+ placeholder: "NAME"
20
+ }),
21
+ shell: arg(z.enum([
22
+ "bash",
23
+ "zsh",
24
+ "fish"
25
+ ]), {
26
+ description: "Shell worker to generate",
27
+ placeholder: "SHELL"
28
+ }),
29
+ out: arg(z.string().optional(), {
30
+ description: "Output worker path (defaults to dist/completion/<shell>-worker.<ext>)",
31
+ placeholder: "PATH"
32
+ }),
33
+ verify: arg(z.boolean().default(false), { description: "Verify __completion-worker-path resolves to the generated worker" })
34
+ }),
35
+ async run(args) {
36
+ await generateBundledCompletionWorker({
37
+ bin: args.bin,
38
+ programName: args.program,
39
+ shell: args.shell,
40
+ ...args.out !== void 0 && { outputPath: args.out },
41
+ verify: args.verify
42
+ });
43
+ }
44
+ });
45
+ runMain(defineCommand({
46
+ name: "politty",
47
+ description: "politty development utilities",
48
+ subCommands: {
49
+ "generate-shim": defineCommand({
50
+ name: "generate-shim",
51
+ description: "Generate a compile-cache bin shim that loads the real CLI via dynamic import",
52
+ args: z.object({
53
+ entry: arg(z.array(z.string()).optional(), {
54
+ description: "Module specifier the shim imports, relative to the shim file; repeatable, one per bin/--out (defaults to ./cli.js, ./cli.mjs, ./index.js, or ./index.mjs next to each shim)",
55
+ placeholder: "SPECIFIER"
56
+ }),
57
+ out: arg(z.array(z.string()).optional(), {
58
+ description: "Output path for the generated shim; repeatable, one per --entry (defaults to the bin paths in package.json)",
59
+ placeholder: "PATH"
60
+ }),
61
+ program: arg(z.string().optional(), {
62
+ description: "Program name for the cache directory, applied to all shims (defaults per shim to its bin name)",
63
+ placeholder: "NAME"
64
+ })
65
+ }),
66
+ run(args) {
67
+ const cwd = process.cwd();
68
+ const results = generateCompileCacheShim({
69
+ ...args.entry !== void 0 && { entry: args.entry },
70
+ ...args.out !== void 0 && { out: args.out },
71
+ ...args.program !== void 0 && { program: args.program },
72
+ cwd
73
+ });
74
+ for (const result of results) console.log(`Generated compile-cache shim: ${formatShimPath(result.outputPath, cwd)} (program: ${result.program}, entry: ${result.entry})`);
75
+ }
76
+ }),
77
+ "generate-worker": generateWorkerCommand
78
+ }
79
+ })).catch((error) => {
80
+ console.error(error instanceof Error ? error.message : String(error));
81
+ process.exit(1);
82
+ });
83
+
84
+ //#endregion
85
+ export { };
86
+ //# sourceMappingURL=cli-main.js.map
package/dist/cli.js CHANGED
@@ -1,55 +1,16 @@
1
1
  #!/usr/bin/env node
2
- import { n as runMain } from "./runner-cEPqI3qs.js";
3
- import { s as arg } from "./schema-extractor-wzJ1cGon.js";
4
- import { n as defineCommand } from "./command-B4yA4LXX.js";
5
- import { p as generateBundledCompletionWorker } from "./completion-BEGiVJST.js";
6
- import "./index.js";
7
- import { z } from "zod";
2
+ import { n as enableCompileCache } from "./compile-cache-NnTkjJMV.js";
8
3
 
9
4
  //#region src/cli.ts
10
- runMain(defineCommand({
11
- name: "politty",
12
- description: "politty development utilities",
13
- subCommands: { "generate-worker": defineCommand({
14
- name: "generate-worker",
15
- description: "Generate and verify a bundled shell completion worker",
16
- args: z.object({
17
- bin: arg(z.string(), {
18
- description: "CLI binary or built JS entry file to invoke",
19
- placeholder: "PATH"
20
- }),
21
- program: arg(z.string(), {
22
- description: "Program name embedded in worker metadata",
23
- placeholder: "NAME"
24
- }),
25
- shell: arg(z.enum([
26
- "bash",
27
- "zsh",
28
- "fish"
29
- ]), {
30
- description: "Shell worker to generate",
31
- placeholder: "SHELL"
32
- }),
33
- out: arg(z.string().optional(), {
34
- description: "Output worker path (defaults to dist/completion/<shell>-worker.<ext>)",
35
- placeholder: "PATH"
36
- }),
37
- verify: arg(z.boolean().default(false), { description: "Verify __completion-worker-path resolves to the generated worker" })
38
- }),
39
- async run(args) {
40
- await generateBundledCompletionWorker({
41
- bin: args.bin,
42
- programName: args.program,
43
- shell: args.shell,
44
- ...args.out !== void 0 && { outputPath: args.out },
45
- verify: args.verify
46
- });
47
- }
48
- }) }
49
- })).catch((error) => {
50
- console.error(error instanceof Error ? error.message : String(error));
51
- process.exit(1);
52
- });
5
+ /**
6
+ * Bin shim: enable the on-disk V8 compile cache before the real CLI graph
7
+ * is compiled, so warm starts skip recompilation (Node >= 22.8.0; no-op
8
+ * otherwise). The actual CLI lives in `cli-main.ts` and is loaded via
9
+ * dynamic import — ESM static imports are compiled during the link phase,
10
+ * before any code runs, so they could never hit a cache enabled here.
11
+ */
12
+ enableCompileCache("politty");
13
+ await import("./cli-main.js");
53
14
 
54
15
  //#endregion
55
16
  export { };
@@ -0,0 +1,101 @@
1
+ import * as nodeModule from "node:module";
2
+ import { join } from "node:path";
3
+ import { homedir } from "node:os";
4
+
5
+ //#region src/compile-cache.ts
6
+ /**
7
+ * Node.js on-disk compile cache (V8 code cache) helpers.
8
+ *
9
+ * `node:module`'s `enableCompileCache` (Node.js >= 22.8.0) persists compiled
10
+ * bytecode to disk so warm starts skip recompilation. Because ESM static
11
+ * import graphs are compiled during the link phase — before any user code
12
+ * runs — enabling the cache inside `runMain` only covers modules imported
13
+ * *after* the call (e.g. `lazy()` subcommands). To cover the whole CLI,
14
+ * enable it from a minimal bin shim that dynamically imports the real entry:
15
+ *
16
+ * ```ts
17
+ * #!/usr/bin/env node
18
+ * import { enableCompileCache } from "politty/compile-cache";
19
+ *
20
+ * enableCompileCache("my-cli");
21
+ * await import("./cli.js");
22
+ * ```
23
+ *
24
+ * This module must stay dependency-free (node builtins only) so the shim's
25
+ * static graph — the part that can never be cached — stays tiny.
26
+ */
27
+ /**
28
+ * Reduce a program name to a single safe path segment. Path separators and
29
+ * a leading scope marker are collapsed (`@scope/cli` → `scope-cli`) so the
30
+ * name cannot escape the cache root; names that reduce to nothing (or to
31
+ * `.`/`..`) yield `undefined`. Realistic command names pass through
32
+ * unchanged.
33
+ */
34
+ function sanitizeProgramName(programName) {
35
+ const safe = programName.replace(/^@/, "").replace(/[/\\]+/g, "-").trim();
36
+ if (!safe || /^[.-]+$/.test(safe)) return void 0;
37
+ return safe;
38
+ }
39
+ /**
40
+ * Compute the cache directory for a program following the same XDG
41
+ * convention as the shell-completion dispatcher scripts
42
+ * (`src/completion/dispatcher.ts`), so direct CLI runs and completion
43
+ * workers share one warm cache:
44
+ * `${XDG_CACHE_HOME:-$HOME/.cache}/<sanitized programName>/node-compile-cache`.
45
+ * The program name is first reduced to a single safe path segment by
46
+ * {@link sanitizeProgramName} (e.g. `@scope/cli` → `scope-cli`). The
47
+ * dispatcher scripts use the raw name, but a completion program name is a
48
+ * single shell word resolved on PATH and can never contain separators, so
49
+ * for every name that can actually reach both sides the two paths coincide.
50
+ *
51
+ * Returns `undefined` when no home directory can be resolved or the program
52
+ * name does not reduce to a safe path segment; callers fall back to Node's
53
+ * default location (`NODE_COMPILE_CACHE` or the OS tmpdir).
54
+ */
55
+ function compileCacheDir(programName) {
56
+ const safeName = sanitizeProgramName(programName);
57
+ if (safeName === void 0) return void 0;
58
+ const xdg = process.env.XDG_CACHE_HOME;
59
+ if (xdg) return join(xdg, safeName, "node-compile-cache");
60
+ try {
61
+ const home = homedir();
62
+ if (!home) return void 0;
63
+ return join(home, ".cache", safeName, "node-compile-cache");
64
+ } catch {
65
+ return;
66
+ }
67
+ }
68
+ /**
69
+ * Enable the Node.js on-disk compile cache for this process.
70
+ *
71
+ * - No-ops (returns `{ enabled: false }`) on runtimes without
72
+ * `module.enableCompileCache` (Node.js < 22.8.0) and never throws.
73
+ * - When the `NODE_COMPILE_CACHE` environment variable is set it always
74
+ * wins, keeping runs spawned by completion scripts (which set the same
75
+ * variable) consistent with direct runs.
76
+ * - Repeat calls are harmless: Node keeps the directory from the first
77
+ * successful call.
78
+ *
79
+ * @param options - Program name (string shorthand) or {@link CompileCacheOptions}.
80
+ */
81
+ function enableCompileCache(options) {
82
+ const opts = typeof options === "string" ? { programName: options } : options ?? {};
83
+ try {
84
+ const enable = nodeModule.enableCompileCache;
85
+ if (typeof enable !== "function") return { enabled: false };
86
+ let dir;
87
+ if (!process.env.NODE_COMPILE_CACHE) dir = opts.cacheDir ?? (opts.programName !== void 0 ? compileCacheDir(opts.programName) : void 0);
88
+ const result = dir === void 0 ? enable() : enable(dir);
89
+ const status = nodeModule.constants?.compileCacheStatus;
90
+ return {
91
+ enabled: status !== void 0 ? result.status === status.ENABLED || result.status === status.ALREADY_ENABLED : result.status === 0 || result.status === 1,
92
+ ...result.directory !== void 0 && { directory: result.directory }
93
+ };
94
+ } catch {
95
+ return { enabled: false };
96
+ }
97
+ }
98
+
99
+ //#endregion
100
+ export { enableCompileCache as n, compileCacheDir as t };
101
+ //# sourceMappingURL=compile-cache-NnTkjJMV.js.map
@@ -0,0 +1,79 @@
1
+ //#region src/compile-cache.d.ts
2
+ /**
3
+ * Node.js on-disk compile cache (V8 code cache) helpers.
4
+ *
5
+ * `node:module`'s `enableCompileCache` (Node.js >= 22.8.0) persists compiled
6
+ * bytecode to disk so warm starts skip recompilation. Because ESM static
7
+ * import graphs are compiled during the link phase — before any user code
8
+ * runs — enabling the cache inside `runMain` only covers modules imported
9
+ * *after* the call (e.g. `lazy()` subcommands). To cover the whole CLI,
10
+ * enable it from a minimal bin shim that dynamically imports the real entry:
11
+ *
12
+ * ```ts
13
+ * #!/usr/bin/env node
14
+ * import { enableCompileCache } from "politty/compile-cache";
15
+ *
16
+ * enableCompileCache("my-cli");
17
+ * await import("./cli.js");
18
+ * ```
19
+ *
20
+ * This module must stay dependency-free (node builtins only) so the shim's
21
+ * static graph — the part that can never be cached — stays tiny.
22
+ */
23
+ /**
24
+ * Options for {@link enableCompileCache}.
25
+ */
26
+ interface CompileCacheOptions {
27
+ /**
28
+ * Program name used to derive the default cache directory
29
+ * (`${XDG_CACHE_HOME:-$HOME/.cache}/<sanitized programName>/node-compile-cache`
30
+ * — see {@link compileCacheDir} for how the name is sanitized).
31
+ * Ignored when `cacheDir` is set.
32
+ */
33
+ programName?: string;
34
+ /** Explicit cache directory (takes precedence over `programName`). */
35
+ cacheDir?: string;
36
+ }
37
+ /**
38
+ * Result of {@link enableCompileCache}.
39
+ */
40
+ interface CompileCacheResult {
41
+ /** Whether the compile cache is active for this process. */
42
+ enabled: boolean;
43
+ /** Directory the cache is (or was already) persisted to, when known. */
44
+ directory?: string;
45
+ }
46
+ /**
47
+ * Compute the cache directory for a program following the same XDG
48
+ * convention as the shell-completion dispatcher scripts
49
+ * (`src/completion/dispatcher.ts`), so direct CLI runs and completion
50
+ * workers share one warm cache:
51
+ * `${XDG_CACHE_HOME:-$HOME/.cache}/<sanitized programName>/node-compile-cache`.
52
+ * The program name is first reduced to a single safe path segment by
53
+ * {@link sanitizeProgramName} (e.g. `@scope/cli` → `scope-cli`). The
54
+ * dispatcher scripts use the raw name, but a completion program name is a
55
+ * single shell word resolved on PATH and can never contain separators, so
56
+ * for every name that can actually reach both sides the two paths coincide.
57
+ *
58
+ * Returns `undefined` when no home directory can be resolved or the program
59
+ * name does not reduce to a safe path segment; callers fall back to Node's
60
+ * default location (`NODE_COMPILE_CACHE` or the OS tmpdir).
61
+ */
62
+ declare function compileCacheDir(programName: string): string | undefined;
63
+ /**
64
+ * Enable the Node.js on-disk compile cache for this process.
65
+ *
66
+ * - No-ops (returns `{ enabled: false }`) on runtimes without
67
+ * `module.enableCompileCache` (Node.js < 22.8.0) and never throws.
68
+ * - When the `NODE_COMPILE_CACHE` environment variable is set it always
69
+ * wins, keeping runs spawned by completion scripts (which set the same
70
+ * variable) consistent with direct runs.
71
+ * - Repeat calls are harmless: Node keeps the directory from the first
72
+ * successful call.
73
+ *
74
+ * @param options - Program name (string shorthand) or {@link CompileCacheOptions}.
75
+ */
76
+ declare function enableCompileCache(options?: string | CompileCacheOptions): CompileCacheResult;
77
+ //#endregion
78
+ export { CompileCacheOptions, CompileCacheResult, compileCacheDir, enableCompileCache };
79
+ //# sourceMappingURL=compile-cache.d.ts.map
@@ -0,0 +1,3 @@
1
+ import { n as enableCompileCache, t as compileCacheDir } from "./compile-cache-NnTkjJMV.js";
2
+
3
+ export { compileCacheDir, enableCompileCache };
@@ -1,3 +1,3 @@
1
- import { f as CompletionDirectiveMask, g as DynamicCompletionResult, h as DynamicCompletionResolver, m as DynamicCompletionContext, p as DynamicCompletionCandidate } from "../arg-registry-D558cYkD.js";
2
- import { A as BundledWorkerOptions, C as CandidateResult, D as CompletionContext, E as generateCandidates, F as CompletionMode, I as CompletionOptions, L as CompletionResult, M as CompletableSubcommand, N as CompletionData, O as CompletionType, P as CompletionGenerator, R as ShellType, S as hasCompleteCommand, T as CompletionDirective, _ as extractCompletionData, a as detectShell, b as formatForShell, c as withCompletionCommand, d as GenerateBundledCompletionWorkerOptions, f as GenerateBundledCompletionWorkerResult, g as validateBundledWorkerFile, h as generateBundledCompletionWorker, i as createRefreshCompletionCommand, j as CompletableOption, k as parseCompletionContext, l as ValueCompletionField, m as defaultBundledWorkerOutputPath, n as createCompletionCommand, o as generateCompletion, p as bundledWorkerShellExtension, r as createCompletionWorkerPathCommand, s as getSupportedShells, t as WithCompletionOptions, u as resolveValueCompletion, v as extractPositionals, w as CompletionCandidate, x as createDynamicCompleteCommand, y as ShellFormatOptions } from "../index-CeZ1yI46.js";
1
+ import { f as CompletionDirectiveMask, g as DynamicCompletionResult, h as DynamicCompletionResolver, m as DynamicCompletionContext, p as DynamicCompletionCandidate } from "../arg-registry-SrNIsq-d.js";
2
+ import { A as BundledWorkerOptions, C as CandidateResult, D as CompletionContext, E as generateCandidates, F as CompletionMode, I as CompletionOptions, L as CompletionResult, M as CompletableSubcommand, N as CompletionData, O as CompletionType, P as CompletionGenerator, R as ShellType, S as hasCompleteCommand, T as CompletionDirective, _ as extractCompletionData, a as detectShell, b as formatForShell, c as withCompletionCommand, d as GenerateBundledCompletionWorkerOptions, f as GenerateBundledCompletionWorkerResult, g as validateBundledWorkerFile, h as generateBundledCompletionWorker, i as createRefreshCompletionCommand, j as CompletableOption, k as parseCompletionContext, l as ValueCompletionField, m as defaultBundledWorkerOutputPath, n as createCompletionCommand, o as generateCompletion, p as bundledWorkerShellExtension, r as createCompletionWorkerPathCommand, s as getSupportedShells, t as WithCompletionOptions, u as resolveValueCompletion, v as extractPositionals, w as CompletionCandidate, x as createDynamicCompleteCommand, y as ShellFormatOptions } from "../index-qqwo5WZT.js";
3
3
  export { type BundledWorkerOptions, type CandidateResult, type CompletableOption, type CompletableSubcommand, type CompletionCandidate, type CompletionContext, type CompletionData, CompletionDirective, type CompletionDirectiveMask, type CompletionGenerator, type CompletionMode, type CompletionOptions, type CompletionResult, type CompletionType, type DynamicCompletionCandidate, type DynamicCompletionContext, type DynamicCompletionResolver, type DynamicCompletionResult, type GenerateBundledCompletionWorkerOptions, type GenerateBundledCompletionWorkerResult, type ShellFormatOptions, type ShellType, type ValueCompletionField, WithCompletionOptions, bundledWorkerShellExtension, createCompletionCommand, createCompletionWorkerPathCommand, createDynamicCompleteCommand, createRefreshCompletionCommand, defaultBundledWorkerOutputPath, detectShell, extractCompletionData, extractPositionals, formatForShell, generateBundledCompletionWorker, generateCandidates, generateCompletion, getSupportedShells, hasCompleteCommand, parseCompletionContext, resolveValueCompletion, validateBundledWorkerFile, withCompletionCommand };
@@ -1,3 +1,3 @@
1
- import { _ as CompletionDirective, a as generateCompletion, b as resolveValueCompletion, c as createDynamicCompleteCommand, d as bundledWorkerShellExtension, f as defaultBundledWorkerOutputPath, g as extractPositionals, h as extractCompletionData, i as detectShell, l as hasCompleteCommand, m as validateBundledWorkerFile, n as createCompletionWorkerPathCommand, o as getSupportedShells, p as generateBundledCompletionWorker, r as createRefreshCompletionCommand, s as withCompletionCommand, t as createCompletionCommand, u as formatForShell, v as generateCandidates, y as parseCompletionContext } from "../completion-BEGiVJST.js";
1
+ import { _ as CompletionDirective, a as generateCompletion, b as resolveValueCompletion, c as createDynamicCompleteCommand, d as bundledWorkerShellExtension, f as defaultBundledWorkerOutputPath, g as extractPositionals, h as extractCompletionData, i as detectShell, l as hasCompleteCommand, m as validateBundledWorkerFile, n as createCompletionWorkerPathCommand, o as getSupportedShells, p as generateBundledCompletionWorker, r as createRefreshCompletionCommand, s as withCompletionCommand, t as createCompletionCommand, u as formatForShell, v as generateCandidates, y as parseCompletionContext } from "../completion-D9SKGJad.js";
2
2
 
3
3
  export { CompletionDirective, bundledWorkerShellExtension, createCompletionCommand, createCompletionWorkerPathCommand, createDynamicCompleteCommand, createRefreshCompletionCommand, defaultBundledWorkerOutputPath, detectShell, extractCompletionData, extractPositionals, formatForShell, generateBundledCompletionWorker, generateCandidates, generateCompletion, getSupportedShells, hasCompleteCommand, parseCompletionContext, resolveValueCompletion, validateBundledWorkerFile, withCompletionCommand };
@@ -1,10 +1,10 @@
1
1
  import { a as toCamelCase, n as getAllAliases, s as arg, t as extractFields } from "./schema-extractor-wzJ1cGon.js";
2
2
  import { n as defineCommand } from "./command-B4yA4LXX.js";
3
3
  import { c as resolveSubCommandMeta, i as resolveSubCommandAlias } from "./subcommand-router-CTzHPGzF.js";
4
- import { z } from "zod";
5
- import { execFile, execSync, spawn } from "node:child_process";
6
4
  import { existsSync, mkdirSync, readFileSync, realpathSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
7
5
  import { dirname, extname, isAbsolute, join, relative, resolve } from "node:path";
6
+ import { z } from "zod";
7
+ import { execFile, execSync, spawn } from "node:child_process";
8
8
  import { promisify } from "node:util";
9
9
 
10
10
  //#region src/completion/shell-shared.ts
@@ -5607,4 +5607,4 @@ function maybeSpawnRefresh(argv, ctx) {
5607
5607
 
5608
5608
  //#endregion
5609
5609
  export { CompletionDirective as _, generateCompletion as a, resolveValueCompletion as b, createDynamicCompleteCommand as c, bundledWorkerShellExtension as d, defaultBundledWorkerOutputPath as f, extractPositionals as g, extractCompletionData as h, detectShell as i, hasCompleteCommand as l, validateBundledWorkerFile as m, createCompletionWorkerPathCommand as n, getSupportedShells as o, generateBundledCompletionWorker as p, createRefreshCompletionCommand as r, withCompletionCommand as s, createCompletionCommand as t, formatForShell as u, generateCandidates as v, parseCompletionContext as y };
5610
- //# sourceMappingURL=completion-BEGiVJST.js.map
5610
+ //# sourceMappingURL=completion-D9SKGJad.js.map
@@ -1,7 +1,6 @@
1
- import { H as SubCommandValue, J as ExtractedFields, Y as ResolvedFieldMeta, _ as AnyCommand, w as Example, y as ArgsSchema } from "../arg-registry-D558cYkD.js";
2
- import { z } from "zod";
1
+ import { H as SubCommandValue, J as ExtractedFields, Y as ResolvedFieldMeta, _ as AnyCommand, w as Example, y as ArgsSchema } from "../arg-registry-SrNIsq-d.js";
3
2
  import * as fs from "node:fs";
4
-
3
+ import { z } from "zod";
5
4
  //#region src/executor/subcommand-router.d.ts
6
5
  /**
7
6
  * Resolve a lazy-loaded command (sync or async)
@@ -27,7 +26,8 @@ type ArgsShape = Record<string, z.ZodType>;
27
26
  * Options for rendering args table
28
27
  */
29
28
  type ArgsTableOptions = {
30
- /** Columns to include in the table (default: all columns) */columns?: ColumnId[];
29
+ /** Columns to include in the table (default: all columns) */
30
+ columns?: ColumnId[];
31
31
  };
32
32
  /**
33
33
  * Render args definition as a markdown options table
@@ -61,7 +61,9 @@ type HeadingLevel = 1 | 2 | 3 | 4 | 5 | 6;
61
61
  * Options for rendering command index
62
62
  */
63
63
  type CommandIndexOptions = {
64
- /** Base heading level (default: 3, which renders as ###) */headingLevel?: HeadingLevel; /** Only include leaf commands (commands without subcommands). Default: true */
64
+ /** Base heading level (default: 3, which renders as ###) */
65
+ headingLevel?: HeadingLevel;
66
+ /** Only include leaf commands (commands without subcommands). Default: true */
65
67
  leafOnly?: boolean;
66
68
  };
67
69
  /**
@@ -459,8 +461,11 @@ interface GenerateDocResult {
459
461
  success: boolean;
460
462
  /** File processing results */
461
463
  files: Array<{
462
- /** File path */path: string; /** Status of this file */
463
- status: "match" | "created" | "updated" | "diff"; /** Diff content (only when status is "diff") */
464
+ /** File path */
465
+ path: string;
466
+ /** Status of this file */
467
+ status: "match" | "created" | "updated" | "diff";
468
+ /** Diff content (only when status is "diff") */
464
469
  diff?: string | undefined;
465
470
  }>;
466
471
  /** Error message (when success is false) */
@@ -626,8 +631,11 @@ declare function createCommandRenderer(options?: DefaultRendererOptions): Render
626
631
  * Default renderers presets
627
632
  */
628
633
  declare const defaultRenderers: {
629
- /** Standard command documentation */command: (options?: DefaultRendererOptions) => RenderFunction; /** Table style options (default) */
630
- tableStyle: RenderFunction; /** List style options */
634
+ /** Standard command documentation */
635
+ command: (options?: DefaultRendererOptions) => RenderFunction;
636
+ /** Table style options (default) */
637
+ tableStyle: RenderFunction;
638
+ /** List style options */
631
639
  listStyle: RenderFunction;
632
640
  };
633
641
  //#endregion
@@ -710,10 +718,15 @@ declare function initDocFile(config: Pick<GenerateDocConfig, "files" | "template
710
718
  * Configuration for a command category
711
719
  */
712
720
  type CommandCategory = {
713
- /** Category title (e.g., "Application Commands") */title: string; /** Category description */
714
- description: string; /** Command paths to include (parent commands will auto-expand to leaf commands) */
715
- commands: string[]; /** Optional post-expansion allowlist, used when a caller has already applied ignores */
716
- allowedCommands?: string[]; /** Path to documentation file for links (e.g., "./cli/application.md") */
721
+ /** Category title (e.g., "Application Commands") */
722
+ title: string;
723
+ /** Category description */
724
+ description: string;
725
+ /** Command paths to include (parent commands will auto-expand to leaf commands) */
726
+ commands: string[];
727
+ /** Optional post-expansion allowlist, used when a caller has already applied ignores */
728
+ allowedCommands?: string[];
729
+ /** Path to documentation file for links (e.g., "./cli/application.md") */
717
730
  docPath: string;
718
731
  /**
719
732
  * When true, `commands` are used verbatim as index rows without expanding
@@ -1,10 +1,10 @@
1
1
  import { r as getExtractedFields, t as extractFields } from "../schema-extractor-wzJ1cGon.js";
2
2
  import { r as resolveLazyCommand } from "../subcommand-router-CTzHPGzF.js";
3
3
  import { t as createLogCollector } from "../log-collector-DK32-73m.js";
4
- import { z } from "zod";
5
4
  import * as fs from "node:fs";
6
5
  import * as path$1 from "node:path";
7
6
  import path from "node:path";
7
+ import { z } from "zod";
8
8
  import { isDeepStrictEqual } from "node:util";
9
9
 
10
10
  //#region src/docs/option-rows.ts
@@ -920,7 +920,7 @@ async function executeSingleExample(example, rootCommand, commandPath) {
920
920
  collector.start();
921
921
  let success = true;
922
922
  try {
923
- const { runCommand } = await import("../runner-cEPqI3qs.js").then((n) => n.r);
923
+ const { runCommand } = await import("../runner-BGs_QMJM.js");
924
924
  const result = await runCommand(rootCommand, argv);
925
925
  success = result.success;
926
926
  if (!result.success && result.error) console.error(result.error.message);