@wentools/zli 0.2.0-beta.2dc33a43

package/script/run.js

@@ -0,0 +1,189 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createRun = exports.run = void 0;
+/**
+ * Run a command or multi-command CLI
+ *
+ * This is the main entry point that:
+ * 1. Detects if help is requested
+ * 2. Parses arguments
+ * 3. Validates against schemas
+ * 4. Executes handler
+ */
+const dntShim = __importStar(require("./_dnt.shims.js"));
+const mod_js_1 = require("./parse_args/mod.js");
+const mod_js_2 = require("./validate_args/mod.js");
+const mod_js_3 = require("./detect_arg_conflicts/mod.js");
+const mod_js_4 = require("./generate_help_text/mod.js");
+const index_js_1 = require("./deps/jsr.io/@wentools/result/0.1.0/src/index.js");
+// Type guard - check if entry is a directory
+const isCommandDirectory = (input) => {
+    return 'commands' in input;
+};
+/**
+ * Create a run function with explicit argv (for testing)
+ */
+const createRun = (argv) => {
+    const runWithArgs = async (input) => {
+        if (isCommandDirectory(input)) {
+            await runCommandDirectory(input, argv, []);
+        }
+        else {
+            // Single command mode
+            const command = input;
+            // Check for help
+            if (argv[0] === '--help' || argv[0] === '-h') {
+                console.log((0, mod_js_4.generateHelpText)(command));
+                return;
+            }
+            await runSingleCommand(command, argv);
+        }
+    };
+    const runCommandDirectory = async (dir, args, commandPath) => {
+        // Build full path
+        const fullPath = [...commandPath, dir.name];
+        // Help handling
+        if (args.length === 0 || args[0] === '--help' || args[0] === '-h') {
+            showCommandDirectoryHelp(dir, fullPath);
+            return;
+        }
+        // Lookup subcommand
+        const subcommandName = args[0];
+        if (subcommandName === undefined) {
+            showCommandDirectoryHelp(dir, fullPath);
+            return;
+        }
+        const entry = dir.commands[subcommandName];
+        if (!entry) {
+            console.error(`❌ Unknown command: ${[...fullPath, subcommandName].join(' ')}`);
+            console.error(`\nAvailable commands: ${Object.keys(dir.commands).join(', ')}`);
+            dntShim.Deno.exit(1);
+        }
+        // Recurse or execute
+        if (isCommandDirectory(entry)) {
+            // Nested directory - recurse!
+            await runCommandDirectory(entry, args.slice(1), fullPath);
+        }
+        else {
+            // Leaf command - execute
+            const cmdPath = [...fullPath, subcommandName].join(' ');
+            // Check for command-specific help
+            if (args[1] === '--help' || args[1] === '-h') {
+                console.log((0, mod_js_4.generateHelpText)(entry, cmdPath));
+                return;
+            }
+            await runSingleCommand(entry, args.slice(1));
+        }
+    };
+    const showCommandDirectoryHelp = (dir, commandPath) => {
+        const pathStr = commandPath.join(' ');
+        console.log(`${dir.description || dir.name}\n`);
+        console.log('Commands:');
+        // Group and display commands
+        const entries = Object.entries(dir.commands);
+        const maxNameLength = Math.max(...entries.map(([name]) => name.length));
+        for (const [name, entry] of entries) {
+            const padding = ' '.repeat(maxNameLength - name.length + 2);
+            const indicator = isCommandDirectory(entry) ? '→ ' : '  ';
+            const desc = entry.description || '';
+            console.log(`  ${name}${padding}${indicator}${desc}`);
+        }
+        console.log(`\nUse '${pathStr} <command> --help' for command-specific help`);
+    };
+    const runSingleCommand = async (command, args) => {
+        // Check for conflicts
+        const conflicts = (0, mod_js_3.detectArgConflicts)(command.args);
+        if (conflicts.length > 0) {
+            console.error('❌ Argument configuration error:');
+            for (const conflict of conflicts) {
+                if (conflict.type === 'duplicate_name') {
+                    console.error(`   Duplicate argument name: ${conflict.name}`);
+                }
+                else {
+                    console.error(`   Duplicate short flag: -${conflict.name} used by ${conflict.conflictingArgs.join(', ')}`);
+                }
+            }
+            dntShim.Deno.exit(1);
+        }
+        // Parse arguments
+        const rawValues = (0, mod_js_1.parseArgs)(args, command.args);
+        // Validate arguments
+        const validatedResult = (0, mod_js_2.validateArgs)(rawValues, command.args);
+        if (validatedResult.isErr()) {
+            const { argName, zodError } = validatedResult.error;
+            console.error(`❌ Validation error for argument '${argName}':`);
+            zodError.issues.forEach((issue) => {
+                console.error(`   ${issue.path.join('.')}: ${issue.message}`);
+            });
+            dntShim.Deno.exit(1);
+        }
+        // Safe: isErr() checked above, Deno.exit() terminates
+        const validatedValues = validatedResult._unsafeUnwrap();
+        // Execute handler
+        try {
+            const result = await command.handler(validatedValues);
+            // Check if handler returned a Result type
+            if ((0, index_js_1.isResult)(result)) {
+                if (result.isErr()) {
+                    const error = result.error;
+                    console.error('❌ Command failed:');
+                    if (error && typeof error === 'object') {
+                        console.error(JSON.stringify(error, null, 2));
+                    }
+                    else {
+                        console.error(String(error));
+                    }
+                    dntShim.Deno.exit(1);
+                }
+                // ok() - just return, script ends normally
+            }
+        }
+        catch (error) {
+            console.error('❌ Command execution failed:', error);
+            dntShim.Deno.exit(1);
+        }
+    };
+    return runWithArgs;
+};
+exports.createRun = createRun;
+/**
+ * Run a CLI command using Deno.args
+ */
+const run = async (input) => {
+    const runWithArgs = createRun(dntShim.Deno.args);
+    await runWithArgs(input);
+};
+exports.run = run;

package/script/validate_args/mod.d.ts

@@ -0,0 +1,3 @@
+export { validateArgs } from './validate_args.js';
+export type { ValidationError, ValidatedValues } from './validate_args.js';
+//# sourceMappingURL=mod.d.ts.map

package/script/validate_args/mod.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mod.d.ts","sourceRoot":"","sources":["../../src/validate_args/mod.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AACjD,YAAY,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAA"}

package/script/validate_args/mod.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateArgs = void 0;
+var validate_args_js_1 = require("./validate_args.js");
+Object.defineProperty(exports, "validateArgs", { enumerable: true, get: function () { return validate_args_js_1.validateArgs; } });

package/script/validate_args/validate_args.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Validate parsed argument values against Zod schemas
+ *
+ * Takes raw parsed values and arg definitions, validates each value,
+ * returns validated & typed values or validation errors.
+ */
+import type { Arg } from '../arg.js';
+import type { RawValues } from '../parse_args/mod.js';
+import { type Result } from '../deps/jsr.io/@wentools/result/0.1.0/src/index.js';
+import type { ZodError } from 'zod';
+type ValidationError = {
+    type: 'validation_error';
+    argName: string;
+    zodError: ZodError;
+};
+type ValidatedValues = Record<string, unknown>;
+declare const validateArgs: (rawValues: RawValues, args: readonly Arg[]) => Result<ValidatedValues, ValidationError>;
+export { validateArgs };
+export type { ValidationError, ValidatedValues };
+//# sourceMappingURL=validate_args.d.ts.map

package/script/validate_args/validate_args.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate_args.d.ts","sourceRoot":"","sources":["../../src/validate_args/validate_args.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,WAAW,CAAA;AACpC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAA;AACrD,OAAO,EAAW,KAAK,MAAM,EAAE,MAAM,oDAAoD,CAAA;AACzF,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,KAAK,CAAA;AAEnC,KAAK,eAAe,GAAG;IACtB,IAAI,EAAE,kBAAkB,CAAA;IACxB,OAAO,EAAE,MAAM,CAAA;IACf,QAAQ,EAAE,QAAQ,CAAA;CAClB,CAAA;AAED,KAAK,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;AAE9C,QAAA,MAAM,YAAY,GACjB,WAAW,SAAS,EACpB,MAAM,SAAS,GAAG,EAAE,KAClB,MAAM,CAAC,eAAe,EAAE,eAAe,CAkBzC,CAAA;AAED,OAAO,EAAE,YAAY,EAAE,CAAA;AACvB,YAAY,EAAE,eAAe,EAAE,eAAe,EAAE,CAAA"}

package/script/validate_args/validate_args.js

@@ -0,0 +1,26 @@
+"use strict";
+/**
+ * Validate parsed argument values against Zod schemas
+ *
+ * Takes raw parsed values and arg definitions, validates each value,
+ * returns validated & typed values or validation errors.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateArgs = void 0;
+const index_js_1 = require("../deps/jsr.io/@wentools/result/0.1.0/src/index.js");
+const validateArgs = (rawValues, args) => {
+    const validated = {};
+    for (const arg of args) {
+        const rawValue = rawValues[arg.name];
+        const result = arg.schema.safeParse(rawValue);
+        if (!result.success) {
+            return (0, index_js_1.err)('validation_error', `Validation failed for argument: ${arg.name}`, {
+                argName: arg.name,
+                zodError: result.error,
+            });
+        }
+        validated[arg.name] = result.data;
+    }
+    return (0, index_js_1.ok)(validated);
+};
+exports.validateArgs = validateArgs;

package/script/zli.d.ts

@@ -0,0 +1,118 @@
+/**
+ * ZLI - Lightweight CLI builder with Zod validation
+ *
+ * A minimal, type-safe CLI argument parser built on Zod.
+ * Zero dependencies beyond Zod (already in project).
+ *
+ * ## Goals
+ *
+ * - Type-safe arguments inferred from Zod schemas
+ * - Flexible parsing: positional args by order OR by --name
+ * - Short flags: --verbose or -v
+ * - Copy-paste friendly: easy to expand from simple to multi-command scripts
+ * - Auto-generated help text
+ * - Pretty validation error messages
+ * - Conflict detection (duplicate names/shorts)
+ *
+ * ## API
+ *
+ * - `zli.p(name, schema, options?)` - Create positional argument
+ * - `zli.f(name, schema, options?)` - Create flag argument
+ * - `zli.c(args, handler, options?)` - Create command
+ * - `zli.d(name, options)` - Create command directory
+ * - `zli.run(command | multiCommand)` - Execute CLI
+ *
+ * ## Usage - Simple Single Command
+ *
+ * ```typescript
+ * import { zli } from '@wentools/zli'
+ * import { z } from 'zod'
+ *
+ * const command = zli.c(
+ *   [
+ *     zli.p('email', z.string().email(), {
+ *       description: 'User email address',
+ *       short: 'e'
+ *     }),
+ *     zli.f('verbose', z.boolean(), {
+ *       description: 'Verbose output',
+ *       short: 'v'
+ *     })
+ *   ],
+ *   (args) => {
+ *     console.log(args.email)    // typed as string
+ *     console.log(args.verbose)  // typed as boolean | undefined
+ *   },
+ *   { description: 'Check user permissions' }
+ * )
+ *
+ * zli.run(command)
+ * ```
+ *
+ * **Invocation:**
+ * ```bash
+ * # Positional
+ * pnpm exec tsx --env-file=.env script.ts user@example.com
+ *
+ * # Named
+ * pnpm exec tsx --env-file=.env script.ts --email user@example.com
+ *
+ * # Short flag
+ * pnpm exec tsx --env-file=.env script.ts -e user@example.com
+ *
+ * # With flags
+ * pnpm exec tsx --env-file=.env script.ts user@example.com --verbose
+ * pnpm exec tsx --env-file=.env script.ts user@example.com -v
+ *
+ * # Help
+ * pnpm exec tsx --env-file=.env script.ts --help
+ * ```
+ *
+ * ## Usage - Multi-Command Script
+ *
+ * ```typescript
+ * import { zli } from '@wentools/zli'
+ * import { z } from 'zod'
+ *
+ * const checkPermissions = zli.c(
+ *   [
+ *     zli.p('email', z.string().email(), { description: 'User email' }),
+ *     zli.f('verbose', z.boolean(), { description: 'Verbose output', short: 'v' })
+ *   ],
+ *   (args) => {
+ *     console.log(`Checking permissions for ${args.email}`)
+ *   },
+ *   { description: 'Check user permissions' }
+ * )
+ *
+ * const promote = zli.c(
+ *   [
+ *     zli.p('email', z.string().email(), { description: 'User email' })
+ *   ],
+ *   async (args) => {
+ *     console.log(`Promoting ${args.email} to admin`)
+ *   },
+ *   { description: 'Promote user to admin' }
+ * )
+ *
+ * zli.run({
+ *   name: 'user',
+ *   description: 'User management commands',
+ *   commands: {
+ *     'check-permissions': checkPermissions,
+ *     'promote': promote
+ *   }
+ * })
+ * ```
+ */
+declare const zli: {
+    p: <TSchema extends import("zod").ZodType>(name: string, schema: TSchema, options?: import("./create_positional_arg.js").PositionalArgOptions) => import("./create_positional_arg.js").PositionalArg<TSchema>;
+    f: <TSchema extends import("zod").ZodType>(name: string, schema: TSchema, options?: import("./create_flag_arg.js").FlagArgOptions) => import("./create_flag_arg.js").FlagArg<TSchema>;
+    c: <const TArgs extends readonly import("./arg.js").Arg[]>(args: TArgs, handler: import("./create_command.js").CommandHandler<import("./infer_args_type.js").InferArgsType<TArgs>>, options?: import("./create_command.js").CommandOptions) => import("./create_command.js").Command<TArgs>;
+    d: <const TCommands extends Record<string, import("./run.js").CommandEntry>>(name: string, options: import("./create_command_directory.js").CommandDirectoryOptions & {
+        commands: TCommands;
+    }) => import("./create_command_directory.js").CommandDirectory;
+    run: (input: import("./run.js").CliInput) => Promise<void>;
+};
+export { zli };
+//# sourceMappingURL=zli.d.ts.map

package/script/zli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"zli.d.ts","sourceRoot":"","sources":["../src/zli.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0GG;AAaH,QAAA,MAAM,GAAG;;;;;;;;CAMR,CAAA;AAED,OAAO,EAAE,GAAG,EAAE,CAAA"}

package/script/zli.js

@@ -0,0 +1,127 @@
+"use strict";
+/**
+ * ZLI - Lightweight CLI builder with Zod validation
+ *
+ * A minimal, type-safe CLI argument parser built on Zod.
+ * Zero dependencies beyond Zod (already in project).
+ *
+ * ## Goals
+ *
+ * - Type-safe arguments inferred from Zod schemas
+ * - Flexible parsing: positional args by order OR by --name
+ * - Short flags: --verbose or -v
+ * - Copy-paste friendly: easy to expand from simple to multi-command scripts
+ * - Auto-generated help text
+ * - Pretty validation error messages
+ * - Conflict detection (duplicate names/shorts)
+ *
+ * ## API
+ *
+ * - `zli.p(name, schema, options?)` - Create positional argument
+ * - `zli.f(name, schema, options?)` - Create flag argument
+ * - `zli.c(args, handler, options?)` - Create command
+ * - `zli.d(name, options)` - Create command directory
+ * - `zli.run(command | multiCommand)` - Execute CLI
+ *
+ * ## Usage - Simple Single Command
+ *
+ * ```typescript
+ * import { zli } from '@wentools/zli'
+ * import { z } from 'zod'
+ *
+ * const command = zli.c(
+ *   [
+ *     zli.p('email', z.string().email(), {
+ *       description: 'User email address',
+ *       short: 'e'
+ *     }),
+ *     zli.f('verbose', z.boolean(), {
+ *       description: 'Verbose output',
+ *       short: 'v'
+ *     })
+ *   ],
+ *   (args) => {
+ *     console.log(args.email)    // typed as string
+ *     console.log(args.verbose)  // typed as boolean | undefined
+ *   },
+ *   { description: 'Check user permissions' }
+ * )
+ *
+ * zli.run(command)
+ * ```
+ *
+ * **Invocation:**
+ * ```bash
+ * # Positional
+ * pnpm exec tsx --env-file=.env script.ts user@example.com
+ *
+ * # Named
+ * pnpm exec tsx --env-file=.env script.ts --email user@example.com
+ *
+ * # Short flag
+ * pnpm exec tsx --env-file=.env script.ts -e user@example.com
+ *
+ * # With flags
+ * pnpm exec tsx --env-file=.env script.ts user@example.com --verbose
+ * pnpm exec tsx --env-file=.env script.ts user@example.com -v
+ *
+ * # Help
+ * pnpm exec tsx --env-file=.env script.ts --help
+ * ```
+ *
+ * ## Usage - Multi-Command Script
+ *
+ * ```typescript
+ * import { zli } from '@wentools/zli'
+ * import { z } from 'zod'
+ *
+ * const checkPermissions = zli.c(
+ *   [
+ *     zli.p('email', z.string().email(), { description: 'User email' }),
+ *     zli.f('verbose', z.boolean(), { description: 'Verbose output', short: 'v' })
+ *   ],
+ *   (args) => {
+ *     console.log(`Checking permissions for ${args.email}`)
+ *   },
+ *   { description: 'Check user permissions' }
+ * )
+ *
+ * const promote = zli.c(
+ *   [
+ *     zli.p('email', z.string().email(), { description: 'User email' })
+ *   ],
+ *   async (args) => {
+ *     console.log(`Promoting ${args.email} to admin`)
+ *   },
+ *   { description: 'Promote user to admin' }
+ * )
+ *
+ * zli.run({
+ *   name: 'user',
+ *   description: 'User management commands',
+ *   commands: {
+ *     'check-permissions': checkPermissions,
+ *     'promote': promote
+ *   }
+ * })
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.zli = void 0;
+const create_positional_arg_js_1 = require("./create_positional_arg.js");
+const create_flag_arg_js_1 = require("./create_flag_arg.js");
+const create_command_js_1 = require("./create_command.js");
+const create_command_directory_js_1 = require("./create_command_directory.js");
+const run_js_1 = require("./run.js");
+const p = create_positional_arg_js_1.createPositionalArg;
+const f = create_flag_arg_js_1.createFlagArg;
+const c = create_command_js_1.createCommand;
+const d = create_command_directory_js_1.createCommandDirectory;
+const zli = {
+    p,
+    f,
+    c,
+    d,
+    run: run_js_1.run,
+};
+exports.zli = zli;