@silvery/commander 0.8.1 → 0.8.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bjørn Stabell
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -49,7 +49,7 @@ const { env, force, verbose } = program.opts()
 //      └──────────────── "dev" | "staging" | "prod"
 ```
 
-With plain Commander, `opts()` returns `Record<string, any>` — every value is untyped. With `@silvery/commander`, each option's type is inferred from its schema: `z.port` produces `number`, `z.enum(...)` produces a union, `z.csv` produces `string[]`. Invalid values are rejected at parse time with clear error messages — not silently passed through as strings.
+With plain Commander, `opts()` returns `Record<string, any>` — every value is untyped. With `@silvery/commander`, each `.option()` call narrows the return type of `.opts()` — no manual interfaces needed. Types are inferred from flag syntax (`--verbose` → `boolean`, `--port <n>` → `string`), parser functions (`port` → `number`, `csv` → `string[]`), schemas (`z.enum(...)` → union), and choices arrays. Accessing a nonexistent option is a compile error. Invalid values are rejected at parse time with clear error messages.
 
 [Zod](https://github.com/colinhacks/zod) is entirely optional — `z` is tree-shaken from your bundle if you don't import it. Without Zod, use the built-in types (`port`, `int`, `csv`) or plain Commander.
 
@@ -75,6 +75,80 @@ Options with [Zod](https://github.com/colinhacks/zod) schemas or built-in types
 
 Full reference, type table, and API details at **[silvery.dev/reference/commander](https://silvery.dev/reference/commander)**.
 
+## Typed `.action()` and `.actionMerged()`
+
+`.action()` is Commander-native: positional arguments, then the options object, then the command instance. Every positional is fully typed from the `.argument()` chain, and `opts` is fully typed from the `.option()` chain:
+
+```ts
+new Command("deploy")
+  .argument("<service>", "Service to deploy")
+  .argument("[env]", "Environment", ["dev", "staging", "prod"] as const)
+  .option("--verbose", "Verbose output")
+  .action((service, env, opts) => {
+    service // string
+    env // "dev" | "staging" | "prod" | undefined
+    opts.verbose // boolean | undefined
+  })
+```
+
+For commands with several positional arguments, `.actionMerged()` provides a flat named-object form:
+
+```ts
+new Command("deploy")
+  .argument("<service>", "Service to deploy")
+  .argument("[env]", "Environment", ["dev", "staging", "prod"] as const)
+  .option("-p, --port <n>", "Port", port)
+  .option("--verbose", "Verbose output")
+  .actionMerged(({ service, env, port, verbose }, cmd) => {
+    // Everything in one destructured object.
+    // `cmd` is the Command instance.
+  })
+```
+
+`.actionMerged()` merges all arguments (by camelCased name) and options into a single `params` object. It's a convenience over `.action()` — use whichever reads better for your command.
+
+**Picking between them:**
+
+- `.action()` — better for commands with zero or one positional argument, or when you want access to the command instance as a trailing argument. Matches Commander.js muscle memory.
+- `.actionMerged()` — better for commands with 2+ positional arguments, where a flat object is nicer than nested destructure.
+
+Both forms are fully typed end-to-end. The only runtime difference is whether arguments are merged into the params object or passed positionally.
+
+### Two ways to declare positional arguments
+
+Both forms are fully typed end-to-end and produce equivalent `Command<{}, Args, ArgsRecord>`:
+
+```ts
+// Inline form — Commander.js native shorthand
+.command("deploy <service> [env]")
+  .action((service, env, opts) => { /* service: string, env: string | undefined */ })
+
+// Explicit form — chained .argument() calls
+.command("deploy")
+  .argument("<service>", "Service to deploy")
+  .argument("[env]", "Environment", ["dev", "staging", "prod"] as const)
+  .action((service, env, opts) => { /* service: string, env: union | undefined */ })
+```
+
+Use the inline form for plain string args (terse, matches Commander.js docs and tutorials).
+Use `.argument()` when you need:
+
+- A description for `--help` output
+- A parser, schema, or `choices` array (the inline string syntax can't express these)
+- A default value
+
+The two forms compose: inline args declared in the command string come first in the
+positional tuple, and any `.argument()` calls append. The merged form `.actionMerged()`
+sees all of them on a single named-object parameter regardless of which form declared them.
+
+## Replaces `@commander-js/extra-typings`
+
+[`@commander-js/extra-typings`](https://github.com/commander-js/extra-typings) pioneered chain-inferred option types for Commander.js — each `.option()` call narrows the type of `.opts()`. We use the same idea but with a much simpler implementation (~100 lines vs. 1536 lines) because we own the `Command` class rather than wrapping someone else's.
+
+`extra-typings` re-declares Commander's entire API from the outside — every method, every overload, every generic parameter — because it's a type-only wrapper around a class it doesn't control. We use interface merging on our own class and only type the methods that matter (`.option()`, `.opts()`, `.action()`). Modern TS features (const type parameters, template literal types) keep the flag-parsing utilities clean.
+
+If you're using `@silvery/commander`, you don't need `@commander-js/extra-typings`.
+
 ## Credits
 
 - **[Commander.js](https://github.com/tj/commander.js)** by TJ Holowaychuk and contributors