politty 0.12.5 → 0.13.1

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.
Files changed (2) hide show
  1. package/README.md +19 -6
  2. package/package.json +4 -4
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
@@ -138,19 +138,32 @@ $ my-cli World -g "Hi" -l
138
138
  HI, WORLD!
139
139
 
140
140
  $ my-cli --help
141
- Usage: greet <name> [options]
141
+ greet
142
142
 
143
143
  A CLI tool that displays greetings
144
144
 
145
+ Usage: greet [options] <name>
146
+
145
147
  Arguments:
146
- name Name of the person to greet
148
+ <name> Name of the person to greet
147
149
 
148
150
  Options:
149
- -g, --greeting <value> Greeting phrase (default: "Hello")
150
- -l, --loud Output in uppercase
151
- -h, --help Show help
151
+ -h, --help Show help
152
+ -H, --help-all Show help with all subcommand options
153
+ --help-json Show help as JSON
154
+ -g, --greeting <GREETING> Greeting phrase (default: "Hello")
155
+ -l, --loud Output in uppercase (default: false)
156
+ ```
157
+
158
+ 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:
159
+
160
+ ```bash
161
+ $ my-cli --help-json
162
+ {"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}]}
152
163
  ```
153
164
 
165
+ 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).
166
+
154
167
  ## Basic Usage
155
168
 
156
169
  ### Defining Arguments
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "politty",
3
- "version": "0.12.5",
3
+ "version": "0.13.1",
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,14 +67,14 @@
67
67
  }
68
68
  },
69
69
  "dependencies": {
70
- "@politty/zod": "^0.2.4"
70
+ "@politty/zod": "^0.3.1"
71
71
  },
72
72
  "devDependencies": {
73
- "@types/node": "25.9.5",
73
+ "@types/node": "25.9.7",
74
74
  "@typescript/native-preview": "7.0.0-dev.20260707.2",
75
75
  "tsdown": "0.23.0",
76
76
  "typescript": "7.0.2",
77
- "zod": "4.5.4"
77
+ "zod": "4.6.5"
78
78
  },
79
79
  "peerDependencies": {
80
80
  "@clack/prompts": "^0.10.0 || ^0.11.0 || ^1.0.0",