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