argsbarg 3.6.1 → 3.6.2

package/CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [3.6.2] - 2026-06-23
+
+### Added
+
+- **`cli-program.md`** — “Read flags once, resolve once” pattern for multi-surface leaves (`read*Flags` + `resolve*Input`).
+
 ## [3.6.1] - 2026-06-23
 
 ### Fixed
@@ -393,7 +399,8 @@ const cli = { ... } satisfies CliProgram;  // or : CliProgram
 - Migrate schemas: rename every `children` property to **`commands`**; move positional definitions to **`CliPositional`** objects on `positionals` and strip `positional` / `argMin` / `argMax` from flag definitions under `options` (flags only carry `name`, `description`, `kind`, and optional `shortName`).
 - Imports: use `CliPositional` where needed; replace `CliOptionDef` with `CliOption` or `CliPositional` as appropriate.
 
-[Unreleased]: https://github.com/bdombro/bun-argsbarg/compare/v3.6.1...HEAD
+[Unreleased]: https://github.com/bdombro/bun-argsbarg/compare/v3.6.2...HEAD
+[3.6.2]: https://github.com/bdombro/bun-argsbarg/releases/tag/v3.6.2
 [3.6.1]: https://github.com/bdombro/bun-argsbarg/releases/tag/v3.6.1
 [3.6.0]: https://github.com/bdombro/bun-argsbarg/releases/tag/v3.6.0
 [3.5.0]: https://github.com/bdombro/bun-argsbarg/releases/tag/v3.5.0

package/docs/cli-program.md

@@ -195,6 +195,59 @@ const { limit, "skip-readiness": skipReadiness, timeout } = ctx.readLeafInputs()
 
 Cross-field rules (e.g. `--match-remote` requires `--branch`) stay in consumer `resolve*` layers — argsbarg does not validate those.
 
+## Read flags once, resolve once
+
+For apps with **Ink + headless + MCP** (multiple surfaces per leaf), avoid scattering `ctx.hasFlag` / `ctx.stringOpt` through the handler. Use two layers:
+
+| Layer | Responsibility |
+| --- | --- |
+| **`read*Flags(ctx)`** | Read coerced values from `ctx` (`readLeafInputs()`, `durationOpt`, `commaListOpt`, shared mutator flags) into one typed struct |
+| **`resolve*Input(flags)`** | Cross-field validation and defaults; returns `{ ok, input }` or `{ ok: false, error }` |
+
+The handler calls **`read*Flags` once**, passes the struct to **`resolve*Input`**, then branches to Ink, headless, or MCP with the same resolved input.
+
+**Shared reads** — when many leaves share options (`yes`, `dry-run`, `json`), one app-level helper (e.g. `readMutatingFlags(ctx)`) plus per-command extensions:
+
+```typescript
+// cli/flags.ts
+export function readMutatingFlags(ctx: CliContext) {
+  const dryRun = ctx.hasFlag("dry-run");
+  return {
+    dryRun,
+    yes: ctx.hasFlag("yes"),
+    explicitJson: wantsExplicitJson(ctx, ctx.hasFlag("json")),
+  };
+}
+
+// commands/reset/resolve.ts
+export function readResetFlags(ctx: CliContext) {
+  return {
+    ...readMutatingFlags(ctx),
+    env: ctx.args[0],
+    force: ctx.hasFlag("force"),
+    services: ctx.commaListOpt("services"),
+  };
+}
+
+export function resolveResetInput(flags: ReturnType<typeof readResetFlags>) {
+  if (!flags.env) return { ok: false, error: "…" };
+  return { ok: true, input: { env: flags.env, force: flags.force, services: flags.services } };
+}
+
+// command handler
+handler: async (ctx) => {
+  const flags = readResetFlags(ctx);
+  await dispatchMutatingCommand({
+    dryRun: flags.dryRun,
+    headless: shouldRunHeadlessWithYes(ctx, { yes: flags.yes, hasRequiredArgs: !!flags.env, dryRun: flags.dryRun }),
+    resolve: () => resolveResetInput(flags),
+    /* … */
+  });
+};
+```
+
+**JSON-only CLIs** — a single `readCommandOptions(ctx)` wrapping `readLeafInputs()` per shared option set is usually enough; full `resolve*` layering is optional.
+
 ## Headless-capable handlers
 
 Simple leaves (read args, print stdout) are already headless — no extra work. **Any handler that might mount Ink, prompt, or open a browser should also implement a scriptable fast path** for:

package/docs/templates/cursor/rules/cli-program.mdc

@@ -19,5 +19,6 @@ When adding or changing argsbarg schema, leaf handlers, or MCP exposure:
 - Interactive leaves: one headless path for MCP, non-TTY CLI, and `--yes` / `--dry-run` / `--json` (`shouldRunHeadless*`, `requireYesInNonTty`); not raw `isTTY`.
 - String options: `format` / `default` / `pattern` per `cli-program.md`; `readLeafInputs()` for multi-flag leaves.
 - Varargs (`argMax: 0`): CLI space-separated; MCP JSON array only — no comma-splitting positionals.
+- Multi-surface leaves (Ink + headless + MCP): one **`read*Flags(ctx)`** per command (or shared family helper + extensions); one **`resolve*Input(flags)`** for cross-field rules — handler reads ctx once, all paths share the struct.
 
 **App-specific conventions:** add below or in a separate `.cursor/rules/` file (shared flags path, Ink vs JSON-only, etc.).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "argsbarg",
-  "version": "3.6.1",
+  "version": "3.6.2",
   "type": "module",
   "engines": {
     "bun": ">=1.3"