politty 0.11.2 → 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 +20 -4
- package/dist/{arg-registry-D558cYkD.d.ts → arg-registry-SrNIsq-d.d.ts} +41 -10
- package/dist/augment.d.ts +1 -2
- package/dist/cli-main.d.ts +1 -0
- package/dist/cli-main.js +86 -0
- package/dist/cli.js +10 -49
- package/dist/compile-cache-NnTkjJMV.js +101 -0
- package/dist/compile-cache.d.ts +79 -0
- package/dist/compile-cache.js +3 -0
- package/dist/completion/index.d.ts +2 -2
- package/dist/completion/index.js +1 -1
- package/dist/{completion-B1K87cU5.js → completion-D9SKGJad.js} +5 -4
- package/dist/docs/index.d.ts +26 -13
- package/dist/docs/index.js +2 -2
- package/dist/{index-CeZ1yI46.d.ts → index-qqwo5WZT.d.ts} +29 -18
- package/dist/index.d.ts +76 -5
- package/dist/index.js +4 -3
- package/dist/prompt/clack/index.d.ts +1 -2
- package/dist/prompt/index.d.ts +1 -2
- package/dist/prompt/inquirer/index.d.ts +1 -2
- package/dist/runner-BGs_QMJM.js +3 -0
- package/dist/{runner-CEDtiI7D.js → runner-xN7248Ph.js} +26 -31
- package/dist/skill/index.d.ts +37 -3
- package/dist/skill/index.js +35 -10
- package/dist/src-BiCtSNrn.js +193 -0
- package/package.json +16 -12
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[];
|
|
402
|
-
|
|
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 */
|
|
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) */
|
|
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-
|
|
981
|
+
//# sourceMappingURL=arg-registry-SrNIsq-d.d.ts.map
|
package/dist/augment.d.ts
CHANGED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export { };
|
package/dist/cli-main.js
ADDED
|
@@ -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
|
|
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-B1K87cU5.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
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
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
|
|
@@ -1,3 +1,3 @@
|
|
|
1
|
-
import { f as CompletionDirectiveMask, g as DynamicCompletionResult, h as DynamicCompletionResolver, m as DynamicCompletionContext, p as DynamicCompletionCandidate } from "../arg-registry-
|
|
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-
|
|
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 };
|
package/dist/completion/index.js
CHANGED
|
@@ -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-
|
|
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
|
|
@@ -1802,7 +1802,8 @@ function collectTrackedFields(root, specs, globalOptions = []) {
|
|
|
1802
1802
|
return groups;
|
|
1803
1803
|
};
|
|
1804
1804
|
const addGlobalDepTracker = (dep, opt, spec) => {
|
|
1805
|
-
const
|
|
1805
|
+
const allTokens = collectOptionTokens(opt.cliName, opt.alias);
|
|
1806
|
+
const groups = groupGlobalFramesByTokenSet(allTokens, spec.pathStrs, spec.intermediatePathStrs);
|
|
1806
1807
|
for (const [tokenKey, group] of groups) addPath(`g::${dep}::${tokenKey}`, {
|
|
1807
1808
|
fieldName: dep,
|
|
1808
1809
|
isGlobal: true,
|
|
@@ -5606,4 +5607,4 @@ function maybeSpawnRefresh(argv, ctx) {
|
|
|
5606
5607
|
|
|
5607
5608
|
//#endregion
|
|
5608
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 };
|
|
5609
|
-
//# sourceMappingURL=completion-
|
|
5610
|
+
//# sourceMappingURL=completion-D9SKGJad.js.map
|
package/dist/docs/index.d.ts
CHANGED
|
@@ -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-
|
|
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) */
|
|
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 ###) */
|
|
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 */
|
|
463
|
-
|
|
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 */
|
|
630
|
-
|
|
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") */
|
|
714
|
-
|
|
715
|
-
|
|
716
|
-
|
|
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
|
package/dist/docs/index.js
CHANGED
|
@@ -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-
|
|
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);
|