@dbx-tools/cli-args 0.9.58 → 0.9.60

package/README.md

@@ -1,37 +1,43 @@
 # @dbx-tools/cli-args
 
-Bind Zod object fields to Commander flags, environment bindings, layered local
-config, help defaults, and service arguments.
+Generate Commander flags from a Zod object schema so any CLI can share one
+argument, help, and layered-config path without installing the full `dbx`
+package.
 
-## Bind A Schema
+## Bind And Parse Arguments
 
 ```ts
-import { addArgs, parseArgs } from "@dbx-tools/cli-args/args";
+import { addArgs, parseArgs } from "@dbx-tools/cli-args";
 import { Command } from "commander";
 import { z } from "zod";
 
-const ConfigSchema = z.object({
+const OptionsSchema = z.object({
   port: z.coerce.number().default(3000).describe("Server listening port"),
-  debug: z.boolean().default(false).describe("Enable verbose debug logging"),
+  databaseUrl: z.string().url().describe("PostgreSQL connection string"),
 });
 
-const command = addArgs(new Command("demo"), ConfigSchema, { scope: [] });
-command.action(() => {
-  const config = parseArgs(command, ConfigSchema);
-  process.stdout.write(`${JSON.stringify(config)}\n`);
-});
+const program = addArgs(new Command("demo"), OptionsSchema);
+await program.parseAsync(process.argv);
+const options = parseArgs(program, OptionsSchema);
 ```
 
-Field names derive `--kebab-case` flags and `UPPER_SNAKE_CASE` environment
-names. Add `.meta({ env: "EXACT_NAME" })` for an established environment name.
-Add `.meta({ env: "EXACT_NAME", flag: false })` for config that should remain
-environment-only.
+Help defaults come from Zod and from layered `@dbx-tools/core` configuration
+(environment, `.env`, bundle, and app YAML). Use `.meta({ env, flag, helpDefault })`
+when a field needs an exact environment name, should stay off the flag list, or
+should hide its default.
+
+## Serialize Options Back To Argv
 
-`configUtils` resolves process environment, `.env`, bundle App env, and
-`app.yaml` values before Zod performs the final parse.
+```ts
+import { serializeArgs } from "@dbx-tools/cli-args";
+
+const argv = serializeArgs(OptionsSchema);
+const fromValues = serializeArgs({ port: 8080, debug: false });
+```
 
-## Serialize Service Arguments
+Schemas serialize their parsed defaults. Concrete objects serialize current
+values. Boolean false becomes `--no-*`, arrays become repeated flags, and
+listener addresses use the shared listen-address format.
 
-`serializeArgs` converts schema defaults or a concrete option object into an
-argument array. Boolean values become positive or negated flags, arrays become
-repeated flags, and listener addresses become `host:port`.
+Consuming commands own their schemas. This package only binds Commander, help,
+and argv serialization.

package/exports.ts

@@ -0,0 +1 @@
+export { addArgs, parseArgs, serializeArgs } from "./src/args.ts";

package/index.ts

@@ -3,6 +3,7 @@
 // Hand edits are overwritten on the next watch; this file is read-only.
 
 export const PACKAGE_IDENTIFIER = "@dbx-tools/cli-args";
-export const PACKAGE_VERSION = "0.9.58";
+export const PACKAGE_VERSION = "0.9.60";
 export * as args from "./src/args.ts";
 export type { CliArgsOptions, CliArgMeta, ArgumentSource } from "./src/args.ts";
+export * from "./exports.ts";

package/lib/exports.d.ts

@@ -0,0 +1 @@
+export { addArgs, parseArgs, serializeArgs } from "./src/args.ts";

package/lib/exports.js

@@ -0,0 +1,2 @@
+export { addArgs, parseArgs, serializeArgs } from "./src/args.js";
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZXhwb3J0cy5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uL2V4cG9ydHMudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsT0FBTyxFQUFFLE9BQU8sRUFBRSxTQUFTLEVBQUUsYUFBYSxFQUFFLE1BQU0sZUFBZSxDQUFDIiwic291cmNlc0NvbnRlbnQiOlsiZXhwb3J0IHsgYWRkQXJncywgcGFyc2VBcmdzLCBzZXJpYWxpemVBcmdzIH0gZnJvbSBcIi4vc3JjL2FyZ3MudHNcIjtcbiJdfQ==

package/lib/index.d.ts

@@ -1,4 +1,5 @@
 export declare const PACKAGE_IDENTIFIER = "@dbx-tools/cli-args";
-export declare const PACKAGE_VERSION = "0.9.58";
+export declare const PACKAGE_VERSION = "0.9.60";
 export * as args from "./src/args.ts";
 export type { CliArgsOptions, CliArgMeta, ArgumentSource } from "./src/args.ts";
+export * from "./exports.ts";

package/lib/index.js

@@ -2,6 +2,7 @@
 // Regenerated from the exporting modules in ./src.
 // Hand edits are overwritten on the next watch; this file is read-only.
 export const PACKAGE_IDENTIFIER = "@dbx-tools/cli-args";
-export const PACKAGE_VERSION = "0.9.58";
+export const PACKAGE_VERSION = "0.9.60";
 export * as args from "./src/args.js";
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi9pbmRleC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSwyQ0FBMkM7QUFDM0MsbURBQW1EO0FBQ25ELHdFQUF3RTtBQUV4RSxNQUFNLENBQUMsTUFBTSxrQkFBa0IsR0FBRyxxQkFBcUIsQ0FBQztBQUN4RCxNQUFNLENBQUMsTUFBTSxlQUFlLEdBQUcsUUFBUSxDQUFDO0FBQ3hDLE9BQU8sS0FBSyxJQUFJLE1BQU0sZUFBZSxDQUFDIiwic291cmNlc0NvbnRlbnQiOlsiLy8gR0VORVJBVEVEIGJ5IHByb2plbiB3YXRjaCAtIERPIE5PVCBFRElULlxuLy8gUmVnZW5lcmF0ZWQgZnJvbSB0aGUgZXhwb3J0aW5nIG1vZHVsZXMgaW4gLi9zcmMuXG4vLyBIYW5kIGVkaXRzIGFyZSBvdmVyd3JpdHRlbiBvbiB0aGUgbmV4dCB3YXRjaDsgdGhpcyBmaWxlIGlzIHJlYWQtb25seS5cblxuZXhwb3J0IGNvbnN0IFBBQ0tBR0VfSURFTlRJRklFUiA9IFwiQGRieC10b29scy9jbGktYXJnc1wiO1xuZXhwb3J0IGNvbnN0IFBBQ0tBR0VfVkVSU0lPTiA9IFwiMC45LjU4XCI7XG5leHBvcnQgKiBhcyBhcmdzIGZyb20gXCIuL3NyYy9hcmdzLnRzXCI7XG5leHBvcnQgdHlwZSB7IENsaUFyZ3NPcHRpb25zLCBDbGlBcmdNZXRhLCBBcmd1bWVudFNvdXJjZSB9IGZyb20gXCIuL3NyYy9hcmdzLnRzXCI7XG4iXX0=
+export * from "./exports.js";
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi9pbmRleC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSwyQ0FBMkM7QUFDM0MsbURBQW1EO0FBQ25ELHdFQUF3RTtBQUV4RSxNQUFNLENBQUMsTUFBTSxrQkFBa0IsR0FBRyxxQkFBcUIsQ0FBQztBQUN4RCxNQUFNLENBQUMsTUFBTSxlQUFlLEdBQUcsUUFBUSxDQUFDO0FBQ3hDLE9BQU8sS0FBSyxJQUFJLE1BQU0sZUFBZSxDQUFDO0FBRXRDLGNBQWMsY0FBYyxDQUFDIiwic291cmNlc0NvbnRlbnQiOlsiLy8gR0VORVJBVEVEIGJ5IHByb2plbiB3YXRjaCAtIERPIE5PVCBFRElULlxuLy8gUmVnZW5lcmF0ZWQgZnJvbSB0aGUgZXhwb3J0aW5nIG1vZHVsZXMgaW4gLi9zcmMuXG4vLyBIYW5kIGVkaXRzIGFyZSBvdmVyd3JpdHRlbiBvbiB0aGUgbmV4dCB3YXRjaDsgdGhpcyBmaWxlIGlzIHJlYWQtb25seS5cblxuZXhwb3J0IGNvbnN0IFBBQ0tBR0VfSURFTlRJRklFUiA9IFwiQGRieC10b29scy9jbGktYXJnc1wiO1xuZXhwb3J0IGNvbnN0IFBBQ0tBR0VfVkVSU0lPTiA9IFwiMC45LjYwXCI7XG5leHBvcnQgKiBhcyBhcmdzIGZyb20gXCIuL3NyYy9hcmdzLnRzXCI7XG5leHBvcnQgdHlwZSB7IENsaUFyZ3NPcHRpb25zLCBDbGlBcmdNZXRhLCBBcmd1bWVudFNvdXJjZSB9IGZyb20gXCIuL3NyYy9hcmdzLnRzXCI7XG5leHBvcnQgKiBmcm9tIFwiLi9leHBvcnRzLnRzXCI7XG4iXX0=

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dbx-tools/cli-args",
-  "description": "Bind Zod schemas to Commander arguments with layered configUtils defaults",
+  "description": "Commander argument generation from Zod object schemas for dbx-tools CLIs",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/reggie-db/dbx-tools.git",
@@ -23,8 +23,8 @@
     "typescript": "^5.9.3"
   },
   "dependencies": {
-    "@dbx-tools/core": "^0.9.58",
-    "@dbx-tools/shared-core": "^0.9.58",
+    "@dbx-tools/core": "^0.9.60",
+    "@dbx-tools/shared-core": "^0.9.60",
     "commander": "^15.0.0",
     "zod": "4.3.6"
   },
@@ -46,7 +46,7 @@
       "./package.json": "./package.json"
     }
   },
-  "version": "0.9.58",
+  "version": "0.9.60",
   "types": "./lib/index.d.ts",
   "dbxToolsConfig": {
     "tags": [
@@ -68,6 +68,7 @@
   "files": [
     "index.ts",
     "src",
+    "exports.ts",
     "bin",
     "lib"
   ],