politty 0.11.1 → 0.11.2

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.
@@ -0,0 +1,135 @@
1
+ //#region src/lazy.ts
2
+ /**
3
+ * Marker property for LazyCommand identification
4
+ */
5
+ const LAZY_BRAND = "__politty_lazy__";
6
+ /**
7
+ * Type guard: check if a value is a LazyCommand
8
+ */
9
+ function isLazyCommand(value) {
10
+ return typeof value === "object" && value !== null && LAZY_BRAND in value && value[LAZY_BRAND] === true;
11
+ }
12
+ /**
13
+ * Create a lazily-loaded subcommand with synchronous metadata.
14
+ *
15
+ * The `meta` command provides names, descriptions, and args schema
16
+ * for static analysis (completion scripts, help text) without loading
17
+ * the full command module.
18
+ *
19
+ * The `load` function is called only at execution time.
20
+ *
21
+ * @example
22
+ * ```ts
23
+ * import { lazy, defineCommand } from "politty";
24
+ *
25
+ * const cli = defineCommand({
26
+ * name: "mycli",
27
+ * subCommands: {
28
+ * deploy: lazy(
29
+ * defineCommand({
30
+ * name: "deploy",
31
+ * description: "Deploy the application",
32
+ * args: z.object({ env: arg(z.string()) }),
33
+ * }),
34
+ * () => import("./deploy.js").then((m) => m.deployCommand),
35
+ * ),
36
+ * },
37
+ * });
38
+ * ```
39
+ */
40
+ function lazy(meta, load) {
41
+ return {
42
+ [LAZY_BRAND]: true,
43
+ meta,
44
+ load
45
+ };
46
+ }
47
+ /**
48
+ * Resolve synchronous metadata from a SubCommandValue.
49
+ * Returns null for legacy async subcommands whose metadata is unavailable.
50
+ */
51
+ function resolveSubCommandMeta(subCmd) {
52
+ if (isLazyCommand(subCmd)) return subCmd.meta;
53
+ if (typeof subCmd === "function") return null;
54
+ return subCmd;
55
+ }
56
+
57
+ //#endregion
58
+ //#region src/executor/subcommand-router.ts
59
+ /**
60
+ * Resolve a lazy-loaded command (sync or async)
61
+ *
62
+ * @param cmd - The command or lazy loader function
63
+ * @returns The resolved command
64
+ */
65
+ async function resolveLazyCommand(cmd) {
66
+ if (isLazyCommand(cmd)) return await cmd.load();
67
+ if (typeof cmd === "function") return await cmd();
68
+ return cmd;
69
+ }
70
+ /**
71
+ * Resolve a subcommand by name (including alias lookup) and return both the
72
+ * resolved command and the canonical name if accessed via alias.
73
+ *
74
+ * This avoids a redundant alias scan when the caller needs both pieces of info.
75
+ */
76
+ async function resolveSubcommandWithAlias(command, name) {
77
+ if (!command.subCommands) return;
78
+ const subCmd = Object.hasOwn(command.subCommands, name) ? command.subCommands[name] : void 0;
79
+ if (subCmd) return {
80
+ command: await resolveLazyCommand(subCmd),
81
+ aliasFor: void 0
82
+ };
83
+ const canonicalName = resolveSubCommandAlias(command, name);
84
+ if (canonicalName) return {
85
+ command: await resolveLazyCommand(command.subCommands[canonicalName]),
86
+ aliasFor: canonicalName
87
+ };
88
+ }
89
+ /**
90
+ * Resolve an alias to the canonical subcommand name.
91
+ * Returns the canonical name if the given name is an alias, or undefined.
92
+ *
93
+ * Note: Aliases are only recognized for eagerly-defined commands and
94
+ * `lazy()` commands (which carry synchronous metadata). Pure async
95
+ * subcommand functions do not expose metadata synchronously, so their
96
+ * aliases cannot be resolved without loading the module.
97
+ *
98
+ * @param command - The parent command
99
+ * @param alias - The alias to look up
100
+ * @returns The canonical subcommand name, or undefined
101
+ */
102
+ function resolveSubCommandAlias(command, alias) {
103
+ if (!command.subCommands) return void 0;
104
+ for (const [name, subCmd] of Object.entries(command.subCommands)) if (resolveSubCommandMeta(subCmd)?.aliases?.includes(alias)) return name;
105
+ }
106
+ /**
107
+ * Build a set of all recognized subcommand names including aliases.
108
+ *
109
+ * @param command - The parent command
110
+ * @returns Set of all names (canonical + aliases)
111
+ */
112
+ function listSubCommandNamesWithAliases(command) {
113
+ const names = /* @__PURE__ */ new Set();
114
+ if (!command.subCommands) return names;
115
+ for (const [name, subCmd] of Object.entries(command.subCommands)) {
116
+ names.add(name);
117
+ const meta = resolveSubCommandMeta(subCmd);
118
+ if (meta?.aliases) for (const alias of meta.aliases) names.add(alias);
119
+ }
120
+ return names;
121
+ }
122
+ /**
123
+ * List all subcommand names for a command
124
+ *
125
+ * @param command - The parent command
126
+ * @returns Array of subcommand names
127
+ */
128
+ function listSubCommands(command) {
129
+ if (!command.subCommands) return [];
130
+ return Object.keys(command.subCommands);
131
+ }
132
+
133
+ //#endregion
134
+ export { resolveSubcommandWithAlias as a, resolveSubCommandMeta as c, resolveSubCommandAlias as i, listSubCommands as n, isLazyCommand as o, resolveLazyCommand as r, lazy as s, listSubCommandNamesWithAliases as t };
135
+ //# sourceMappingURL=subcommand-router-CTzHPGzF.js.map
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "politty",
3
- "version": "0.11.1",
3
+ "version": "0.11.2",
4
4
  "description": "A lightweight CLI framework inspired by citty with zod v4 registry integration for type-safe metadata management",
5
5
  "keywords": [
6
6
  "argument-parser",
@@ -69,9 +69,9 @@
69
69
  "@inquirer/prompts": "8.5.2",
70
70
  "@quansync/fs": "1.0.0",
71
71
  "@types/node": "25.9.4",
72
- "@typescript/native-preview": "7.0.0-dev.20260701.1",
72
+ "@typescript/native-preview": "7.0.0-dev.20260702.3",
73
73
  "@vitest/coverage-v8": "4.1.9",
74
- "knip": "6.23.0",
74
+ "knip": "6.24.0",
75
75
  "lefthook": "2.1.9",
76
76
  "organize-imports-cli": "1.0.2",
77
77
  "oxfmt": "0.57.0",
@@ -1,25 +0,0 @@
1
- import { z } from "zod";
2
-
3
- //#region src/core/arg-registry.ts
4
- /**
5
- * Custom registry for politty argument metadata
6
- * This avoids polluting Zod's GlobalMeta
7
- */
8
- const argRegistry = z.registry();
9
- function arg(schema, meta) {
10
- if (meta) argRegistry.add(schema, meta);
11
- return schema;
12
- }
13
- /**
14
- * Get metadata for a schema from the registry
15
- *
16
- * @param schema - The Zod schema
17
- * @returns The metadata if registered, undefined otherwise
18
- */
19
- function getArgMeta(schema) {
20
- return argRegistry.get(schema);
21
- }
22
-
23
- //#endregion
24
- export { getArgMeta as n, arg as t };
25
- //# sourceMappingURL=arg-registry-BeLLAW5-.js.map