politty 0.12.4 → 0.13.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/README.md +22 -1
- package/dist/index.d.ts +2 -3
- package/package.json +3 -3
package/README.md
CHANGED
|
@@ -12,7 +12,7 @@ From simple scripts to complex CLI tools with subcommands, validation, and auto-
|
|
|
12
12
|
- **Subcommands**: Build Git-style nested subcommands (with lazy loading and alias support)
|
|
13
13
|
- **Lifecycle Management**: Guaranteed `setup` → `run` → `cleanup` execution order
|
|
14
14
|
- **Signal Handling**: Proper SIGINT/SIGTERM handling with guaranteed cleanup execution
|
|
15
|
-
- **Auto Help Generation**: Automatically generate help text from definitions
|
|
15
|
+
- **Auto Help Generation**: Automatically generate help text from definitions, plus a `--help-json` flag for structured (JSON) help
|
|
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
|
|
@@ -149,8 +149,19 @@ Options:
|
|
|
149
149
|
-g, --greeting <value> Greeting phrase (default: "Hello")
|
|
150
150
|
-l, --loud Output in uppercase
|
|
151
151
|
-h, --help Show help
|
|
152
|
+
-H, --help-all Show help with all subcommand options
|
|
153
|
+
--help-json Show help as JSON
|
|
152
154
|
```
|
|
153
155
|
|
|
156
|
+
Every command also accepts `--help-json`, which prints the same information as a single JSON object instead of formatted text — useful for tools that consume a CLI's help programmatically (e.g. generating docs or another UI) rather than parsing `--help`'s output:
|
|
157
|
+
|
|
158
|
+
```bash
|
|
159
|
+
$ my-cli --help-json
|
|
160
|
+
{"name":"greet","commandPath":[],"rootName":"greet","description":"A CLI tool that displays greetings","usage":{"commandName":"greet","hasGlobalOptions":false,"hasOptions":true,"positionals":[{"name":"name","required":true}]},"builtinOptions":{"help":"Show help","helpAll":"Show help with all subcommand options","helpJson":"Show help as JSON"},"schemaType":"object","positionals":[{"name":"name","cliName":"name","positional":true,"required":true,"type":"string","description":"Name of the person to greet"}],"options":[{"name":"greeting","cliName":"greeting","positional":false,"required":false,"type":"string","alias":["g"],"description":"Greeting phrase","defaultValue":"Hello"},{"name":"loud","cliName":"loud","positional":false,"required":false,"type":"boolean","alias":["l"],"description":"Output in uppercase","defaultValue":false}]}
|
|
161
|
+
```
|
|
162
|
+
|
|
163
|
+
Unlike `--help-all` (which only expands subcommand options when asked), `--help-json` always includes the full recursive subcommand tree — except for legacy subcommands registered without `lazy()`, which have no synchronous metadata available and appear only as `{ name, unresolved: true }`. Call `generateHelpData(command, options?)` directly to get the same `HelpData` object without going through argv parsing — see [API Reference](./docs/api-reference.md#generatehelpdata).
|
|
164
|
+
|
|
154
165
|
## Basic Usage
|
|
155
166
|
|
|
156
167
|
### Defining Arguments
|
|
@@ -208,6 +219,16 @@ run: (args) => {
|
|
|
208
219
|
},
|
|
209
220
|
```
|
|
210
221
|
|
|
222
|
+
It is also available on an `effect`'s context args, which is how a flag whose parsed value cannot reveal its own origin — a boolean, say — tells an explicitly typed `--flag=false` apart from the schema default:
|
|
223
|
+
|
|
224
|
+
```typescript
|
|
225
|
+
json: arg(z.boolean().default(false), {
|
|
226
|
+
effect: (value, { args }) => {
|
|
227
|
+
if (args.$source?.("json") !== "cli") applyDefaultFromEnvironment();
|
|
228
|
+
},
|
|
229
|
+
}),
|
|
230
|
+
```
|
|
231
|
+
|
|
211
232
|
### Subcommands
|
|
212
233
|
|
|
213
234
|
Define Git-style subcommands:
|
package/dist/index.d.ts
CHANGED
|
@@ -9,6 +9,5 @@ export * from "@politty/zod";
|
|
|
9
9
|
* resolve `@politty/zod` from its own package under a strict node_modules
|
|
10
10
|
* layout (pnpm), so a shim naming it would silently lose the compile cache.
|
|
11
11
|
*/
|
|
12
|
-
declare const generateCompileCacheShim: (options?: import("@politty/zod").GenerateCompileCacheShimOptions) => import("@politty/zod").GenerateCompileCacheShimResult[];
|
|
13
|
-
//#endregion
|
|
14
|
-
export { generateCompileCacheShim };
|
|
12
|
+
export declare const generateCompileCacheShim: (options?: import("@politty/zod").GenerateCompileCacheShimOptions) => import("@politty/zod").GenerateCompileCacheShimResult[];
|
|
13
|
+
//#endregion
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "politty",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.13.0",
|
|
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",
|
|
@@ -67,12 +67,12 @@
|
|
|
67
67
|
}
|
|
68
68
|
},
|
|
69
69
|
"dependencies": {
|
|
70
|
-
"@politty/zod": "^0.
|
|
70
|
+
"@politty/zod": "^0.3.0"
|
|
71
71
|
},
|
|
72
72
|
"devDependencies": {
|
|
73
73
|
"@types/node": "25.9.5",
|
|
74
74
|
"@typescript/native-preview": "7.0.0-dev.20260707.2",
|
|
75
|
-
"tsdown": "0.
|
|
75
|
+
"tsdown": "0.23.0",
|
|
76
76
|
"typescript": "7.0.2",
|
|
77
77
|
"zod": "4.5.4"
|
|
78
78
|
},
|