@politty/zod 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 toiroakr
+
+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

@@ -0,0 +1,561 @@
+# politty
+
+**politty** is a lightweight, type-safe CLI framework for Node.js built on **Zod v4**.
+
+From simple scripts to complex CLI tools with subcommands, validation, and auto-generated help, you can build them all with a developer-friendly API.
+
+## Features
+
+- **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 and alias 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
+- **Interactive Prompts**: Prompt for missing arguments with pluggable adapters (clack, inquirer)
+- **Discriminated Union**: Support for mutually exclusive argument sets
+- **Skill Management**: Manage agent skills (SKILL.md) with file-based install/uninstall
+- **Fast Startup**: Automatic Node.js compile cache (V8 code cache) integration, with a `generate-shim` command to cache the whole CLI graph
+
+## Requirements
+
+- Node.js >= 20.12.0 (excluding 21.0.0 - 21.6.x)
+- Zod >= 4.2.1
+
+## Installation
+
+```bash
+npm install politty zod
+# or
+pnpm add politty zod
+# or
+yarn add politty zod
+```
+
+### Using valibot instead of zod
+
+politty is also available as [`@politty/valibot`](https://www.npmjs.com/package/@politty/valibot), built on [valibot](https://valibot.dev/) schemas — same API (`defineCommand`, `arg`, `runMain`, and all subpath modules), and its published build never loads zod:
+
+```bash
+npm install @politty/valibot valibot
+```
+
+```typescript
+import * as v from "valibot";
+import { defineCommand, runMain, arg } from "@politty/valibot";
+
+const command = defineCommand({
+  name: "greet",
+  args: v.object({
+    name: arg(v.string(), { description: "Name to greet", positional: true }),
+    loud: arg(v.optional(v.boolean(), false), { alias: "l" }),
+  }),
+  run: (args) => {
+    const greeting = `Hello, ${args.name}!`;
+    console.log(args.loud ? greeting.toUpperCase() : greeting);
+  },
+});
+
+runMain(command);
+```
+
+Field descriptions can also come from valibot's own metadata actions. They are actions, not schemas, so they belong inside `v.pipe(...)`: `v.pipe(v.string(), v.description("..."))` or `v.pipe(v.string(), v.metadata({ description: "..." }))`. The one zod-only feature without a valibot counterpart is the `politty/augment` module (zod `GlobalMeta` interface augmentation) — use `arg()` or `v.metadata()` instead. The `politty` package itself remains the zod flavor (an alias of `@politty/zod`).
+
+## Quick Start
+
+```typescript
+import { z } from "zod";
+import { defineCommand, runMain, arg } from "politty";
+
+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);
+  },
+});
+
+runMain(command);
+```
+
+Example usage:
+
+```bash
+$ my-cli World
+Hello, World!
+
+$ my-cli World -g "Hi" -l
+HI, WORLD!
+
+$ 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);
+  },
+});
+```
+
+Use `args.$source(name)` to check whether a value came from an explicit CLI token, an `env` fallback, or neither (e.g. a schema default). It's typed as optional since directly-constructed args objects (e.g. in unit tests) won't have it:
+
+```typescript
+run: (args) => {
+  args.$source?.("apiKey"); // "cli" | "env" | "default"
+},
+```
+
+### 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",
+  aliases: ["i"],
+  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",
+  aliases: ["b"],
+  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 i -t react        # alias for init
+$ my-cli build -o out -m
+$ my-cli b -o out -m        # alias for build
+$ 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     |
+| `aliases`     | `string[]?`                   | Command aliases     |
+| `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
+});
+```
+
+### `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)                                     |
+| `completion`  | `object?`     | Shell completion configuration                                           |
+| `prompt`      | `PromptMeta?` | Interactive prompt configuration ([docs](./docs/interactive-prompts.md)) |
+
+## Shell Completion
+
+politty provides automatic shell completion generation for bash, zsh, and fish.
+The default generated script is a small runtime dispatcher: when the user
+presses TAB, it resolves the executable currently visible on `PATH` and uses a
+bundled static worker from that executable's package when one is available. If
+no package-relative bundled worker is found, it falls back to a per-binary
+static worker cache and regenerates that cache from the hidden
+`__refresh-completion` command when needed. Sourced workers are memoized for the
+shell session, so warm completions call the worker function directly.
+Completion fields that require runtime JavaScript still delegate to the
+binary's hidden `__complete` command.
+When `NODE_COMPILE_CACHE` is unset, the dispatcher sets it to a
+program-specific cache directory before invoking `__complete`, letting Node.js
+22+ reuse V8 module compile cache across repeated completion requests.
+
+### Quick Setup
+
+Use `withCompletionCommand` to add completion support to your CLI:
+
+```typescript
+import { defineCommand, runMain, withCompletionCommand } from "politty";
+
+const mainCommand = withCompletionCommand(
+  defineCommand({
+    name: "mycli",
+    subCommands: {
+      build: buildCommand,
+      test: testCommand,
+    },
+  }),
+);
+
+runMain(mainCommand);
+```
+
+Then users can enable completions:
+
+```bash
+# Bash
+eval "$(mycli completion bash)"
+
+# Zsh
+eval "$(mycli completion zsh)"
+
+# Fish
+mycli completion fish | source
+```
+
+For project-local CLIs, put the local binary directory in `PATH` with your
+environment manager, for example:
+
+```sh
+# .envrc
+PATH_add node_modules/.bin
+```
+
+Completion then follows the same executable the shell would run.
+
+Published CLIs can ship a fast worker artifact:
+
+```bash
+politty generate-worker --bin dist/cli/index.mjs --program mycli --shell zsh --verify
+```
+
+or call `generateBundledCompletionWorker()` from `politty/completion` in your
+own build script. The default output path is
+`dist/completion/<shell>-worker.<ext>`.
+
+The dispatcher looks for common package-relative worker paths such as
+`dist/completion/zsh-worker.zsh` from the visible binary. Use
+`withCompletionCommand({ bundledWorker: { relativePaths: { zsh: [...] } } })`
+to customize the package-relative lookup. For package layouts that cannot be
+expressed with relative paths, `bundledWorker.queryCommand: true` lets the
+dispatcher ask the binary's hidden `__completion-worker-path` command on the
+miss path.
+
+To generate the older static script with command metadata baked in, use:
+
+```bash
+eval "$(mycli completion bash --static)"
+eval "$(mycli completion zsh --static)"
+```
+
+### Value Completion
+
+Define completion hints for arguments:
+
+```typescript
+const command = defineCommand({
+  name: "build",
+  args: z.object({
+    // Auto-detected from z.enum()
+    format: arg(z.enum(["json", "yaml", "xml"]), {
+      alias: "f",
+      description: "Output format",
+    }),
+
+    // File completion
+    config: arg(z.string(), {
+      completion: { type: "file", extensions: ["json", "yaml"] },
+    }),
+
+    // Directory completion
+    outputDir: arg(z.string(), {
+      completion: { type: "directory" },
+    }),
+
+    // Custom shell command
+    branch: arg(z.string().optional(), {
+      completion: {
+        custom: { shellCommand: "git branch --format='%(refname:short)'" },
+      },
+    }),
+
+    // Static choices
+    environment: arg(z.string(), {
+      completion: {
+        custom: { choices: ["development", "staging", "production"] },
+      },
+    }),
+  }),
+  run: (args) => {
+    /* ... */
+  },
+});
+```
+
+## Faster Startup (Compile Cache)
+
+politty integrates Node.js's on-disk compile cache (V8 code cache, Node >= 22.8.0) so warm starts skip recompilation; older runtimes are a silent no-op. `runMain` enables it automatically, which covers dynamically imported modules such as `lazy()` subcommands. To cache the whole CLI graph — politty, zod, and your command definitions — generate a bin shim as part of your build:
+
+```jsonc
+// package.json
+{
+  "bin": { "my-cli": "./dist/bin.js" },
+  "scripts": {
+    "build": "tsdown", // builds src/cli.ts -> dist/cli.js
+    "postbuild": "politty generate-shim --entry ./cli.js",
+  },
+}
+```
+
+`generate-shim` writes an executable shim that enables the cache and loads `--entry` (a specifier relative to the shim) with a dynamic import. The rest is derived from `package.json`: the output path from the `bin` path and the program name from the `bin` name; packages with multiple bins pass `--entry` once per bin, and `--entry` itself can be omitted when the entry sits next to the shim under a conventional name (`./cli.js`, `./index.js`, ...). See [Faster Startup (Compile Cache)](./docs/recipes.md#faster-startup-compile-cache) for the flags, the opt-out (`compileCache: false`), and the hand-written shim variant.
+
+## Skill Management
+
+politty manages SKILL.md-based agent skills distributed via npm packages.
+
+### Quick Setup
+
+Use `withSkillCommand` to add skill management to your CLI:
+
+```typescript
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { defineCommand, runMain } from "politty";
+import { withSkillCommand } from "politty/skill";
+
+// Resolves to ../skills from both src/ and dist/
+const sourceDir = resolve(dirname(fileURLToPath(import.meta.url)), "../skills");
+
+const cli = withSkillCommand(
+  defineCommand({
+    name: "my-agent",
+    subCommands: {/* ... */},
+  }),
+  { sourceDir, package: "@my-agent/skills" },
+);
+
+runMain(cli);
+```
+
+`package` identifies who owns these skills. It is combined with the command name as `"{package}:{cliName}"` and must match the `metadata["politty-cli"]` stamp pre-declared in each source SKILL.md — `skills add`/`sync` refuse mismatches, and `remove`/`sync` refuse to delete skills belonging to another tool. The default install mode is `"symlink"` (`.agents/skills/<name>` -> source, `.claude/skills/<name>` -> canonical), so source updates propagate live; on filesystems without symlink support (e.g. Windows without Developer Mode) install throws with guidance to retry with `mode: "copy"`, which recursively copies instead (source updates then require re-running `sync`). See [Skill Management](./docs/skill-management.md) for details.
+
+Skills are SKILL.md files with YAML frontmatter (spec-compliant: https://agentskills.io/specification). The `metadata["politty-cli"]` stamp is authored by the skill package:
+
+```markdown
+---
+name: commit
+description: Git commit message generation
+license: MIT
+metadata:
+  politty-cli: "@my-agent/skills:my-agent"
+---
+
+# Instructions for the agent...
+```
+
+Then users can manage skills:
+
+```bash
+my-agent skills sync              # Remove and reinstall all skills
+my-agent skills add commit        # Install a specific skill
+my-agent skills remove commit     # Remove a specific skill
+my-agent skills list              # List available skills
+```
+
+## 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
+- [Interactive Prompts](./docs/interactive-prompts.md) - Prompt for missing arguments interactively
+- [Recipes](./docs/recipes.md) - Testing, configuration, error handling, faster startup (compile cache)
+- [Skill Management](./docs/skill-management.md) - Agent skill management (SKILL.md-based)
+- [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
+- `26-command-alias` - Command aliases
+
+## License
+
+MIT

package/bin/cli.mjs

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+// Committed launcher: pnpm only links a bin whose target exists at install time.
+import "../dist/cli.js";