politty 0.0.1 → 0.1.0

package/README.md

@@ -1,45 +1,314 @@
 # politty
 
-## ⚠️ IMPORTANT NOTICE ⚠️
+**politty** is a lightweight, type-safe CLI framework for Node.js built on **Zod v4**.
 
-**This package is created solely for the purpose of setting up OIDC (OpenID Connect) trusted publishing with npm.**
+From simple scripts to complex CLI tools with subcommands, validation, and auto-generated help, you can build them all with a developer-friendly API.
 
-This is **NOT** a functional package and contains **NO** code or functionality beyond the OIDC setup configuration.
+## Features
 
-## Purpose
+- **Zod Native**: Use Zod schemas directly for argument definition and validation
+- **Type Safety**: Full TypeScript support with automatic type inference for parsed arguments
+- **Flexible Argument Definition**: Support for positional arguments, flags, aliases, arrays, and environment variable fallbacks
+- **Subcommands**: Build Git-style nested subcommands (with lazy loading support)
+- **Lifecycle Management**: Guaranteed `setup` → `run` → `cleanup` execution order
+- **Signal Handling**: Proper SIGINT/SIGTERM handling with guaranteed cleanup execution
+- **Auto Help Generation**: Automatically generate help text from definitions
+- **Discriminated Union**: Support for mutually exclusive argument sets
 
-This package exists to:
-1. Configure OIDC trusted publishing for the package name `politty`
-2. Enable secure, token-less publishing from CI/CD workflows
-3. Establish provenance for packages published under this name
+## Requirements
 
-## What is OIDC Trusted Publishing?
+- Node.js >= 18
+- Zod >= 4.2.1
 
-OIDC trusted publishing allows package maintainers to publish packages directly from their CI/CD workflows without needing to manage npm access tokens. Instead, it uses OpenID Connect to establish trust between the CI/CD provider (like GitHub Actions) and npm.
+## Installation
 
-## Setup Instructions
+```bash
+npm install politty zod
+# or
+pnpm add politty zod
+# or
+yarn add politty zod
+```
 
-To properly configure OIDC trusted publishing for this package:
+## Quick Start
 
-1. Go to [npmjs.com](https://www.npmjs.com/) and navigate to your package settings
-2. Configure the trusted publisher (e.g., GitHub Actions)
-3. Specify the repository and workflow that should be allowed to publish
-4. Use the configured workflow to publish your actual package
+```typescript
+import { z } from "zod";
+import { defineCommand, runMain, arg } from "politty";
 
-## DO NOT USE THIS PACKAGE
+const command = defineCommand({
+  name: "greet",
+  description: "A CLI tool that displays greetings",
+  args: z.object({
+    name: arg(z.string(), {
+      positional: true,
+      description: "Name of the person to greet",
+    }),
+    greeting: arg(z.string().default("Hello"), {
+      alias: "g",
+      description: "Greeting phrase",
+    }),
+    loud: arg(z.boolean().default(false), {
+      alias: "l",
+      description: "Output in uppercase",
+    }),
+  }),
+  run: (args) => {
+    let message = `${args.greeting}, ${args.name}!`;
+    if (args.loud) {
+      message = message.toUpperCase();
+    }
+    console.log(message);
+  },
+});
 
-This package is a placeholder for OIDC configuration only. It:
-- Contains no executable code
-- Provides no functionality
-- Should not be installed as a dependency
-- Exists only for administrative purposes
+runMain(command);
+```
 
-## More Information
+Example usage:
 
-For more details about npm's trusted publishing feature, see:
-- [npm Trusted Publishing Documentation](https://docs.npmjs.com/generating-provenance-statements)
-- [GitHub Actions OIDC Documentation](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect)
+```bash
+$ my-cli World
+Hello, World!
 
----
+$ my-cli World -g "Hi" -l
+HI, WORLD!
 
-**Maintained for OIDC setup purposes only**
+$ my-cli --help
+Usage: greet <name> [options]
+
+A CLI tool that displays greetings
+
+Arguments:
+  name    Name of the person to greet
+
+Options:
+  -g, --greeting <value>  Greeting phrase (default: "Hello")
+  -l, --loud              Output in uppercase
+  -h, --help              Show help
+```
+
+## Basic Usage
+
+### Defining Arguments
+
+Use the `arg()` function to define argument metadata:
+
+```typescript
+import { z } from "zod";
+import { arg, defineCommand } from "politty";
+
+const command = defineCommand({
+  name: "example",
+  args: z.object({
+    // Positional argument (required)
+    input: arg(z.string(), {
+      positional: true,
+      description: "Input file",
+    }),
+
+    // Optional positional argument
+    output: arg(z.string().optional(), {
+      positional: true,
+      description: "Output file",
+    }),
+
+    // Flag (with alias)
+    verbose: arg(z.boolean().default(false), {
+      alias: "v",
+      description: "Verbose output",
+    }),
+
+    // Environment variable fallback
+    apiKey: arg(z.string().optional(), {
+      env: "API_KEY",
+      description: "API key",
+    }),
+
+    // Array argument (--file a.txt --file b.txt)
+    files: arg(z.array(z.string()).default([]), {
+      alias: "f",
+      description: "Files to process",
+    }),
+  }),
+  run: (args) => {
+    console.log(args);
+  },
+});
+```
+
+### Subcommands
+
+Define Git-style subcommands:
+
+```typescript
+import { z } from "zod";
+import { arg, defineCommand, runMain } from "politty";
+
+const initCommand = defineCommand({
+  name: "init",
+  description: "Initialize a project",
+  args: z.object({
+    template: arg(z.string().default("default"), {
+      alias: "t",
+      description: "Template name",
+    }),
+  }),
+  run: (args) => {
+    console.log(`Initializing with template: ${args.template}`);
+  },
+});
+
+const buildCommand = defineCommand({
+  name: "build",
+  description: "Build the project",
+  args: z.object({
+    output: arg(z.string().default("dist"), {
+      alias: "o",
+      description: "Output directory",
+    }),
+    minify: arg(z.boolean().default(false), {
+      alias: "m",
+      description: "Minify output",
+    }),
+  }),
+  run: (args) => {
+    console.log(`Building to: ${args.output}`);
+  },
+});
+
+const cli = defineCommand({
+  name: "my-cli",
+  description: "Example CLI with subcommands",
+  subCommands: {
+    init: initCommand,
+    build: buildCommand,
+  },
+});
+
+runMain(cli, { version: "1.0.0" });
+```
+
+Example usage:
+
+```bash
+$ my-cli init -t react
+$ my-cli build -o out -m
+$ my-cli --help
+```
+
+### Lifecycle Hooks
+
+Execute hooks in `setup` → `run` → `cleanup` order. The `cleanup` hook is always executed, even if an error occurs:
+
+```typescript
+const command = defineCommand({
+  name: "db-query",
+  description: "Execute database queries",
+  args: z.object({
+    database: arg(z.string(), {
+      alias: "d",
+      description: "Database connection string",
+    }),
+    query: arg(z.string(), {
+      alias: "q",
+      description: "SQL query",
+    }),
+  }),
+  setup: async ({ args }) => {
+    console.log("[setup] Connecting to database...");
+    // Establish DB connection
+  },
+  run: async (args) => {
+    console.log("[run] Executing query...");
+    // Execute query
+    return { rowCount: 42 };
+  },
+  cleanup: async ({ args, error }) => {
+    console.log("[cleanup] Closing connection...");
+    if (error) {
+      console.error(`Error occurred: ${error.message}`);
+    }
+    // Close connection
+  },
+});
+```
+
+## API
+
+### `defineCommand(options)`
+
+Define a command.
+
+| Option        | Type                          | Description         |
+| ------------- | ----------------------------- | ------------------- |
+| `name`        | `string`                      | Command name        |
+| `description` | `string?`                     | Command description |
+| `args`        | `ZodSchema`                   | Argument schema     |
+| `subCommands` | `Record<string, Command>?`    | Subcommands         |
+| `setup`       | `(context) => Promise<void>?` | Setup hook          |
+| `run`         | `(args) => T?`                | Run function        |
+| `cleanup`     | `(context) => Promise<void>?` | Cleanup hook        |
+
+### `runMain(command, options?)`
+
+CLI entry point. Handles signals and calls `process.exit()`.
+
+```typescript
+runMain(command, {
+  version: "1.0.0",    // Displayed with --version flag
+  argv: process.argv,  // Custom argv
+});
+```
+
+### `runCommand(command, argv, options?)`
+
+Programmatic/testing entry point. Does not call `process.exit()` and returns a result object.
+
+```typescript
+const result = await runCommand(command, ["arg1", "--flag"]);
+if (result.success) {
+  console.log(result.result);
+} else {
+  console.error(result.error);
+}
+```
+
+### `arg(schema, meta)`
+
+Attach metadata to an argument.
+
+| Metadata      | Type       | Description                          |
+| ------------- | ---------- | ------------------------------------ |
+| `positional`  | `boolean?` | Treat as positional argument         |
+| `alias`       | `string?`  | Short alias (e.g., `-v`)             |
+| `description` | `string?`  | Argument description                 |
+| `placeholder` | `string?`  | Placeholder shown in help            |
+| `env`         | `string?`  | Environment variable name (fallback) |
+
+## Documentation
+
+For detailed documentation, see the `docs/` directory:
+
+- [Getting Started](./docs/getting-started.md) - Installation and creating your first command
+- [Essentials](./docs/essentials.md) - Core concepts explained
+- [Advanced Features](./docs/advanced-features.md) - Subcommands, Discriminated Union
+- [Recipes](./docs/recipes.md) - Testing, configuration, error handling
+- [API Reference](./docs/api-reference.md) - Detailed API reference
+- [Doc Generation](./docs/doc-generation.md) - Automatic documentation generation
+
+## Examples
+
+The `playground/` directory contains many examples:
+
+- `01-hello-world` - Minimal command configuration
+- `02-greet` - Positional arguments and flags
+- `03-array-args` - Array arguments
+- `05-lifecycle-hooks` - Lifecycle hooks
+- `10-subcommands` - Subcommands
+- `12-discriminated-union` - Discriminated Union
+- `21-lazy-subcommands` - Lazy loading
+
+## License
+
+MIT

package/dist/arg-registry-ClI2WGgH.d.cts

@@ -0,0 +1,89 @@
+import { z } from "zod";
+
+//#region src/core/arg-registry.d.ts
+
+/**
+ * Base metadata shared by all argument types
+ */
+interface BaseArgMeta {
+  /** Argument description */
+  description?: string;
+  /** Treat as positional argument */
+  positional?: boolean;
+  /** Placeholder for help display */
+  placeholder?: string;
+  /**
+   * Environment variable name(s) to read value from.
+   * If an array is provided, earlier entries take priority.
+   * CLI arguments always take precedence over environment variables.
+   *
+   * @example
+   * ```ts
+   * // Single env var
+   * port: arg(z.coerce.number(), { env: "PORT" })
+   *
+   * // Multiple env vars (PORT takes priority over SERVER_PORT)
+   * port: arg(z.coerce.number(), { env: ["PORT", "SERVER_PORT"] })
+   * ```
+   */
+  env?: string | string[];
+}
+/**
+ * Metadata for regular arguments (non-builtin aliases)
+ */
+interface RegularArgMeta extends BaseArgMeta {
+  /** Short alias (e.g., 'v' for --verbose) */
+  alias?: string;
+}
+/**
+ * Metadata for overriding built-in aliases (-h, -H)
+ */
+interface BuiltinOverrideArgMeta extends BaseArgMeta {
+  /** Built-in alias to override ('h' or 'H') */
+  alias: "h" | "H";
+  /** Must be true to override built-in aliases */
+  overrideBuiltinAlias: true;
+}
+/**
+ * Metadata options for argument definition
+ */
+type ArgMeta = RegularArgMeta | BuiltinOverrideArgMeta;
+/**
+ * Register metadata for a Zod schema
+ *
+ * @param schema - The Zod schema
+ * @param meta - Argument metadata
+ * @returns The same schema (for chaining)
+ *
+ * @example
+ * ```ts
+ * import { z } from "zod";
+ * import { arg, defineCommand } from "politty";
+ *
+ * const cmd = defineCommand({
+ *   args: z.object({
+ *     name: arg(z.string(), { description: "User name", positional: true }),
+ *     verbose: arg(z.boolean().default(false), { alias: "v" }),
+ *   }),
+ *   run: (args) => {
+ *     console.log(args.name, args.verbose);
+ *   },
+ * });
+ * ```
+ */
+/**
+ * Type helper to validate ArgMeta
+ * Forces a type error if alias is "h" or "H" without overrideBuiltinAlias: true
+ */
+type ValidateArgMeta<M> = M extends {
+  alias: "h" | "H";
+} ? M extends {
+  overrideBuiltinAlias: true;
+} ? M : { [K in keyof M]: M[K] } & {
+  __typeError: "Alias 'h' or 'H' requires overrideBuiltinAlias: true";
+} : M;
+declare function arg<T extends z.ZodType>(schema: T): T;
+declare function arg<T extends z.ZodType, M extends ArgMeta>(schema: T, meta: ValidateArgMeta<M>): T;
+//#endregion
+export { arg as n, ArgMeta as t };
+//# sourceMappingURL=arg-registry-ClI2WGgH.d.cts.map

package/dist/arg-registry-ClI2WGgH.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"arg-registry-ClI2WGgH.d.cts","names":[],"sources":["../src/core/arg-registry.ts"],"sourcesContent":[],"mappings":";;;;;;AAKA;AA2BiB,UA3BA,WAAA,CA2Be;EAQf;EAUL,WAAO,CAAA,EAAA,MAAA;EAmCd;EAAqB,UAAA,CAAA,EAAA,OAAA;EACtB;EACE,WAAA,CAAA,EAAA,MAAA;EAEc;;;;;AAMpB;;;;;AACA;;;;EAA6F,GAAA,CAAA,EAAA,MAAA,GAAA,MAAA,EAAA;;;;;UAhE5E,cAAA,SAAuB;;;;;;;UAQvB,sBAAA,SAA+B;;;;;;;;;KAUpC,OAAA,GAAU,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;KAmClC,qBAAqB;;IACtB;;IACE,kBAEc,IAAI,EAAE;;IAItB;iBAEY,cAAc,CAAA,CAAE,iBAAiB,IAAI;iBACrC,cAAc,CAAA,CAAE,mBAAmB,iBAAiB,SAAS,gBAAgB,KAAK"}

package/dist/arg-registry-D4NsqcNZ.d.ts

@@ -0,0 +1,89 @@
+import { z } from "zod";
+
+//#region src/core/arg-registry.d.ts
+
+/**
+ * Base metadata shared by all argument types
+ */
+interface BaseArgMeta {
+  /** Argument description */
+  description?: string;
+  /** Treat as positional argument */
+  positional?: boolean;
+  /** Placeholder for help display */
+  placeholder?: string;
+  /**
+   * Environment variable name(s) to read value from.
+   * If an array is provided, earlier entries take priority.
+   * CLI arguments always take precedence over environment variables.
+   *
+   * @example
+   * ```ts
+   * // Single env var
+   * port: arg(z.coerce.number(), { env: "PORT" })
+   *
+   * // Multiple env vars (PORT takes priority over SERVER_PORT)
+   * port: arg(z.coerce.number(), { env: ["PORT", "SERVER_PORT"] })
+   * ```
+   */
+  env?: string | string[];
+}
+/**
+ * Metadata for regular arguments (non-builtin aliases)
+ */
+interface RegularArgMeta extends BaseArgMeta {
+  /** Short alias (e.g., 'v' for --verbose) */
+  alias?: string;
+}
+/**
+ * Metadata for overriding built-in aliases (-h, -H)
+ */
+interface BuiltinOverrideArgMeta extends BaseArgMeta {
+  /** Built-in alias to override ('h' or 'H') */
+  alias: "h" | "H";
+  /** Must be true to override built-in aliases */
+  overrideBuiltinAlias: true;
+}
+/**
+ * Metadata options for argument definition
+ */
+type ArgMeta = RegularArgMeta | BuiltinOverrideArgMeta;
+/**
+ * Register metadata for a Zod schema
+ *
+ * @param schema - The Zod schema
+ * @param meta - Argument metadata
+ * @returns The same schema (for chaining)
+ *
+ * @example
+ * ```ts
+ * import { z } from "zod";
+ * import { arg, defineCommand } from "politty";
+ *
+ * const cmd = defineCommand({
+ *   args: z.object({
+ *     name: arg(z.string(), { description: "User name", positional: true }),
+ *     verbose: arg(z.boolean().default(false), { alias: "v" }),
+ *   }),
+ *   run: (args) => {
+ *     console.log(args.name, args.verbose);
+ *   },
+ * });
+ * ```
+ */
+/**
+ * Type helper to validate ArgMeta
+ * Forces a type error if alias is "h" or "H" without overrideBuiltinAlias: true
+ */
+type ValidateArgMeta<M> = M extends {
+  alias: "h" | "H";
+} ? M extends {
+  overrideBuiltinAlias: true;
+} ? M : { [K in keyof M]: M[K] } & {
+  __typeError: "Alias 'h' or 'H' requires overrideBuiltinAlias: true";
+} : M;
+declare function arg<T extends z.ZodType>(schema: T): T;
+declare function arg<T extends z.ZodType, M extends ArgMeta>(schema: T, meta: ValidateArgMeta<M>): T;
+//#endregion
+export { arg as n, ArgMeta as t };
+//# sourceMappingURL=arg-registry-D4NsqcNZ.d.ts.map

package/dist/arg-registry-D4NsqcNZ.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"arg-registry-D4NsqcNZ.d.ts","names":[],"sources":["../src/core/arg-registry.ts"],"sourcesContent":[],"mappings":";;;;;;AAKA;AA2BiB,UA3BA,WAAA,CA2Be;EAQf;EAUL,WAAO,CAAA,EAAA,MAAA;EAmCd;EAAqB,UAAA,CAAA,EAAA,OAAA;EACtB;EACE,WAAA,CAAA,EAAA,MAAA;EAEc;;;;;AAMpB;;;;;AACA;;;;EAA6F,GAAA,CAAA,EAAA,MAAA,GAAA,MAAA,EAAA;;;;;UAhE5E,cAAA,SAAuB;;;;;;;UAQvB,sBAAA,SAA+B;;;;;;;;;KAUpC,OAAA,GAAU,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;KAmClC,qBAAqB;;IACtB;;IACE,kBAEc,IAAI,EAAE;;IAItB;iBAEY,cAAc,CAAA,CAAE,iBAAiB,IAAI;iBACrC,cAAc,CAAA,CAAE,mBAAmB,iBAAiB,SAAS,gBAAgB,KAAK"}

package/dist/augment.d.cts

@@ -0,0 +1,17 @@
+import { t as ArgMeta } from "./arg-registry-ClI2WGgH.cjs";
+
+//#region src/augment.d.ts
+
+declare module "zod" {
+  interface ZodTypeDef {
+    argMeta?: ArgMeta;
+  }
+  interface GlobalMeta {
+    description?: string;
+    positional?: boolean;
+    placeholder?: string;
+    alias?: string;
+    overrideBuiltinAlias?: boolean;
+  }
+}
+//# sourceMappingURL=augment.d.cts.map

package/dist/augment.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"augment.d.cts","names":[],"sources":["../src/augment.ts"],"sourcesContent":[],"mappings":";;;;;;cAkBc"}

package/dist/augment.d.ts

@@ -0,0 +1,17 @@
+import { t as ArgMeta } from "./arg-registry-D4NsqcNZ.js";
+
+//#region src/augment.d.ts
+
+declare module "zod" {
+  interface ZodTypeDef {
+    argMeta?: ArgMeta;
+  }
+  interface GlobalMeta {
+    description?: string;
+    positional?: boolean;
+    placeholder?: string;
+    alias?: string;
+    overrideBuiltinAlias?: boolean;
+  }
+}
+//# sourceMappingURL=augment.d.ts.map

package/dist/augment.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"augment.d.ts","names":[],"sources":["../src/augment.ts"],"sourcesContent":[],"mappings":";;;;;;cAkBc"}

package/dist/augment.js

@@ -0,0 +1 @@
+export {  };

package/dist/command-Bgd-yIwv.cjs

@@ -0,0 +1,25 @@
+let zod = require("zod");
+
+//#region src/core/command.ts
+function defineCommand(config) {
+	return {
+		name: config.name,
+		description: config.description,
+		args: config.args,
+		subCommands: config.subCommands,
+		setup: config.setup,
+		run: config.run,
+		cleanup: config.cleanup,
+		notes: config.notes,
+		examples: config.examples
+	};
+}
+
+//#endregion
+Object.defineProperty(exports, 'defineCommand', {
+  enumerable: true,
+  get: function () {
+    return defineCommand;
+  }
+});
+//# sourceMappingURL=command-Bgd-yIwv.cjs.map

package/dist/command-Bgd-yIwv.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-Bgd-yIwv.cjs","names":[],"sources":["../src/core/command.ts"],"sourcesContent":["import { z } from \"zod\";\nimport type {\n  ArgsSchema,\n  Command,\n  Example,\n  NonRunnableCommand,\n  RunnableCommand,\n  SubCommandsRecord,\n} from \"../types.js\";\n\n/**\n * Infer args type from schema, defaults to empty object if undefined\n */\ntype InferArgs<TArgsSchema> = TArgsSchema extends z.ZodType\n  ? z.infer<TArgsSchema>\n  : Record<string, never>;\n\n/**\n * Config for defining a command\n * @template TArgsSchema - The Zod schema type for arguments\n * @template TResult - The return type of run function (void if no run)\n */\ninterface DefineCommandConfig<TArgsSchema extends ArgsSchema | undefined, TResult> {\n  name: string;\n  description?: string;\n  args?: TArgsSchema;\n  subCommands?: SubCommandsRecord;\n  setup?: (context: { args: InferArgs<TArgsSchema> }) => void | Promise<void>;\n  run?: (args: InferArgs<TArgsSchema>) => TResult;\n  cleanup?: (context: {\n    args: InferArgs<TArgsSchema>;\n    error?: Error | undefined;\n  }) => void | Promise<void>;\n  notes?: string;\n  examples?: Example[];\n}\n\n/**\n * Config with run function (runnable command)\n */\ninterface RunnableConfig<\n  TArgsSchema extends ArgsSchema | undefined,\n  TResult,\n> extends DefineCommandConfig<TArgsSchema, TResult> {\n  run: (args: InferArgs<TArgsSchema>) => TResult;\n}\n\n/**\n * Config without run function (non-runnable command)\n */\ninterface NonRunnableConfig<TArgsSchema extends ArgsSchema | undefined> extends Omit<\n  DefineCommandConfig<TArgsSchema, void>,\n  \"run\"\n> {\n  run?: undefined;\n}\n\n/**\n * Define a CLI command with type-safe arguments\n *\n * @param config - Command configuration\n * @returns A defined command with preserved type information\n *\n * @example\n * ```ts\n * import { z } from \"zod\";\n * import { arg, defineCommand } from \"politty\";\n *\n * const command = defineCommand({\n *   name: \"greet\",\n *   args: z.object({\n *     name: arg(z.string(), { description: \"Name to greet\", positional: true }),\n *     loud: arg(z.boolean().default(false), { alias: \"l\", description: \"Use uppercase\" }),\n *   }),\n *   run: (args) => {\n *     const greeting = `Hello, ${args.name}!`;\n *     console.log(args.loud ? greeting.toUpperCase() : greeting);\n *   },\n * });\n *\n * // Type of command.argsSchema is preserved as z.ZodObject<...>\n * // Type of command.run is (args: { name: string; loud: boolean }) => void\n * ```\n *\n * @example\n * ```ts\n * // With discriminated union for subcommand-like behavior\n * const command = defineCommand({\n *   name: \"resource\",\n *   args: z.discriminatedUnion(\"action\", [\n *     z.object({\n *       action: z.literal(\"create\"),\n *       name: arg(z.string(), { description: \"Resource name\" }),\n *     }),\n *     z.object({\n *       action: z.literal(\"delete\"),\n *       id: arg(z.coerce.number(), { description: \"Resource ID\" }),\n *     }),\n *   ]),\n *   run: (args) => {\n *     if (args.action === \"create\") {\n *       console.log(`Creating ${args.name}`);\n *     } else {\n *       console.log(`Deleting ${args.id}`);\n *     }\n *   },\n * });\n * ```\n */\n// Overload 1: with run function - returns RunnableCommand with preserved schema type\nexport function defineCommand<\n  TArgsSchema extends ArgsSchema | undefined = undefined,\n  TResult = void,\n>(\n  config: RunnableConfig<TArgsSchema, TResult>,\n): RunnableCommand<TArgsSchema, InferArgs<TArgsSchema>, TResult>;\n\n// Overload 2: without run function - returns NonRunnableCommand with preserved schema type\nexport function defineCommand<TArgsSchema extends ArgsSchema | undefined = undefined>(\n  config: NonRunnableConfig<TArgsSchema>,\n): NonRunnableCommand<TArgsSchema, InferArgs<TArgsSchema>>;\n\n// Implementation\nexport function defineCommand<\n  TArgsSchema extends ArgsSchema | undefined = undefined,\n  TResult = void,\n>(\n  config: RunnableConfig<TArgsSchema, TResult> | NonRunnableConfig<TArgsSchema>,\n): Command<TArgsSchema, InferArgs<TArgsSchema>, TResult> {\n  return {\n    name: config.name,\n    description: config.description,\n    args: config.args as TArgsSchema,\n    subCommands: config.subCommands,\n    setup: config.setup,\n    run: config.run,\n    cleanup: config.cleanup,\n    notes: config.notes,\n    examples: config.examples,\n  } as Command<TArgsSchema, InferArgs<TArgsSchema>, TResult>;\n}\n"],"mappings":";;;AA2HA,SAAgB,cAId,QACuD;AACvD,QAAO;EACL,MAAM,OAAO;EACb,aAAa,OAAO;EACpB,MAAM,OAAO;EACb,aAAa,OAAO;EACpB,OAAO,OAAO;EACd,KAAK,OAAO;EACZ,SAAS,OAAO;EAChB,OAAO,OAAO;EACd,UAAU,OAAO;EAClB"}

package/dist/command-CvKyk4ag.js

@@ -0,0 +1,20 @@
+import { z } from "zod";
+
+//#region src/core/command.ts
+function defineCommand(config) {
+	return {
+		name: config.name,
+		description: config.description,
+		args: config.args,
+		subCommands: config.subCommands,
+		setup: config.setup,
+		run: config.run,
+		cleanup: config.cleanup,
+		notes: config.notes,
+		examples: config.examples
+	};
+}
+
+//#endregion
+export { defineCommand as t };
+//# sourceMappingURL=command-CvKyk4ag.js.map

package/dist/command-CvKyk4ag.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-CvKyk4ag.js","names":[],"sources":["../src/core/command.ts"],"sourcesContent":["import { z } from \"zod\";\nimport type {\n  ArgsSchema,\n  Command,\n  Example,\n  NonRunnableCommand,\n  RunnableCommand,\n  SubCommandsRecord,\n} from \"../types.js\";\n\n/**\n * Infer args type from schema, defaults to empty object if undefined\n */\ntype InferArgs<TArgsSchema> = TArgsSchema extends z.ZodType\n  ? z.infer<TArgsSchema>\n  : Record<string, never>;\n\n/**\n * Config for defining a command\n * @template TArgsSchema - The Zod schema type for arguments\n * @template TResult - The return type of run function (void if no run)\n */\ninterface DefineCommandConfig<TArgsSchema extends ArgsSchema | undefined, TResult> {\n  name: string;\n  description?: string;\n  args?: TArgsSchema;\n  subCommands?: SubCommandsRecord;\n  setup?: (context: { args: InferArgs<TArgsSchema> }) => void | Promise<void>;\n  run?: (args: InferArgs<TArgsSchema>) => TResult;\n  cleanup?: (context: {\n    args: InferArgs<TArgsSchema>;\n    error?: Error | undefined;\n  }) => void | Promise<void>;\n  notes?: string;\n  examples?: Example[];\n}\n\n/**\n * Config with run function (runnable command)\n */\ninterface RunnableConfig<\n  TArgsSchema extends ArgsSchema | undefined,\n  TResult,\n> extends DefineCommandConfig<TArgsSchema, TResult> {\n  run: (args: InferArgs<TArgsSchema>) => TResult;\n}\n\n/**\n * Config without run function (non-runnable command)\n */\ninterface NonRunnableConfig<TArgsSchema extends ArgsSchema | undefined> extends Omit<\n  DefineCommandConfig<TArgsSchema, void>,\n  \"run\"\n> {\n  run?: undefined;\n}\n\n/**\n * Define a CLI command with type-safe arguments\n *\n * @param config - Command configuration\n * @returns A defined command with preserved type information\n *\n * @example\n * ```ts\n * import { z } from \"zod\";\n * import { arg, defineCommand } from \"politty\";\n *\n * const command = defineCommand({\n *   name: \"greet\",\n *   args: z.object({\n *     name: arg(z.string(), { description: \"Name to greet\", positional: true }),\n *     loud: arg(z.boolean().default(false), { alias: \"l\", description: \"Use uppercase\" }),\n *   }),\n *   run: (args) => {\n *     const greeting = `Hello, ${args.name}!`;\n *     console.log(args.loud ? greeting.toUpperCase() : greeting);\n *   },\n * });\n *\n * // Type of command.argsSchema is preserved as z.ZodObject<...>\n * // Type of command.run is (args: { name: string; loud: boolean }) => void\n * ```\n *\n * @example\n * ```ts\n * // With discriminated union for subcommand-like behavior\n * const command = defineCommand({\n *   name: \"resource\",\n *   args: z.discriminatedUnion(\"action\", [\n *     z.object({\n *       action: z.literal(\"create\"),\n *       name: arg(z.string(), { description: \"Resource name\" }),\n *     }),\n *     z.object({\n *       action: z.literal(\"delete\"),\n *       id: arg(z.coerce.number(), { description: \"Resource ID\" }),\n *     }),\n *   ]),\n *   run: (args) => {\n *     if (args.action === \"create\") {\n *       console.log(`Creating ${args.name}`);\n *     } else {\n *       console.log(`Deleting ${args.id}`);\n *     }\n *   },\n * });\n * ```\n */\n// Overload 1: with run function - returns RunnableCommand with preserved schema type\nexport function defineCommand<\n  TArgsSchema extends ArgsSchema | undefined = undefined,\n  TResult = void,\n>(\n  config: RunnableConfig<TArgsSchema, TResult>,\n): RunnableCommand<TArgsSchema, InferArgs<TArgsSchema>, TResult>;\n\n// Overload 2: without run function - returns NonRunnableCommand with preserved schema type\nexport function defineCommand<TArgsSchema extends ArgsSchema | undefined = undefined>(\n  config: NonRunnableConfig<TArgsSchema>,\n): NonRunnableCommand<TArgsSchema, InferArgs<TArgsSchema>>;\n\n// Implementation\nexport function defineCommand<\n  TArgsSchema extends ArgsSchema | undefined = undefined,\n  TResult = void,\n>(\n  config: RunnableConfig<TArgsSchema, TResult> | NonRunnableConfig<TArgsSchema>,\n): Command<TArgsSchema, InferArgs<TArgsSchema>, TResult> {\n  return {\n    name: config.name,\n    description: config.description,\n    args: config.args as TArgsSchema,\n    subCommands: config.subCommands,\n    setup: config.setup,\n    run: config.run,\n    cleanup: config.cleanup,\n    notes: config.notes,\n    examples: config.examples,\n  } as Command<TArgsSchema, InferArgs<TArgsSchema>, TResult>;\n}\n"],"mappings":";;;AA2HA,SAAgB,cAId,QACuD;AACvD,QAAO;EACL,MAAM,OAAO;EACb,aAAa,OAAO;EACpB,MAAM,OAAO;EACb,aAAa,OAAO;EACpB,OAAO,OAAO;EACd,KAAK,OAAO;EACZ,SAAS,OAAO;EAChB,OAAO,OAAO;EACd,UAAU,OAAO;EAClB"}