@maizzle/framework 6.0.0-rc.1 → 6.0.0-rc.2

package/node_modules/citty/README.md

@@ -1,50 +1,27 @@
 # 🌆 citty
 
-[![npm version][npm-version-src]][npm-version-href]
-[![npm downloads][npm-downloads-src]][npm-downloads-href]
-[![bundle][bundle-src]][bundle-href]
-[![Codecov][codecov-src]][codecov-href]
-[![License][license-src]][license-href]
+<!-- automd:badges color=yellow bundlephobia -->
 
-> Elegant CLI Builder
+[![npm version](https://img.shields.io/npm/v/citty?color=yellow)](https://npmjs.com/package/citty)
+[![npm downloads](https://img.shields.io/npm/dm/citty?color=yellow)](https://npmjs.com/package/citty)
+[![bundle size](https://img.shields.io/bundlephobia/minzip/citty?color=yellow)](https://bundlephobia.com/package/citty)
 
-- Fast and lightweight argument parser based on [mri](https://github.com/lukeed/mri)
-- Smart value parsing with typecast, boolean shortcuts and unknown flag handling
-- Nested sub-commands
-- Lazy and Async commands
-- Plugable and composable API
-- Auto generated usage and help
+<!-- /automd -->
 
-🚧 This project is under heavy development. More features are coming soon!
+Elegant CLI Builder
 
-## Usage
+- Zero dependency, fast and lightweight (based on native [`util.parseArgs`](https://nodejs.org/api/util.html#utilparseargsconfig))
+- Smart value parsing with typecast and boolean shortcuts
+- Nested sub-commands with lazy and async loading
+- Pluggable and composable API with auto generated usage
 
-Install package:
+## Usage
 
 ```sh
-# npm
-npm install citty
-
-# yarn
-yarn add citty
-
-# pnpm
-pnpm install citty
+npx nypm add -D citty
 ```
 
-Import:
-
 ```js
-// ESM
-import { defineCommand, runMain } from "citty";
-
-// CommonJS
-const { defineCommand, runMain } = require("citty");
-```
-
-Define main command to run:
-
-```ts
 import { defineCommand, runMain } from "citty";
 
 const main = defineCommand({
@@ -64,6 +41,12 @@ const main = defineCommand({
       description: "Use friendly greeting",
     },
   },
+  setup({ args }) {
+    console.log(`now setup ${args.command}`);
+  },
+  cleanup({ args }) {
+    console.log(`now cleanup ${args.command}`);
+  },
   run({ args }) {
     console.log(`${args.friendly ? "Hi" : "Greetings"} ${args.name}!`);
   },
@@ -72,35 +55,168 @@ const main = defineCommand({
 runMain(main);
 ```
 
-## Utils
+```sh
+node index.mjs john
+# Greetings john!
+```
 
-### `defineCommand`
+### Sub Commands
 
-`defineCommand` is a type helper for defining commands.
+Sub commands can be nested recursively. Use lazy imports for large CLIs to avoid loading all commands at once.
 
-### `runMain`
+```js
+import { defineCommand, runMain } from "citty";
 
-Runs a command with usage support and graceful error handling.
+const sub = defineCommand({
+  meta: { name: "sub", description: "Sub command" },
+  args: {
+    name: { type: "positional", description: "Your name", required: true },
+  },
+  run({ args }) {
+    console.log(`Hello ${args.name}!`);
+  },
+});
 
-### `createMain`
+const main = defineCommand({
+  meta: { name: "hello", version: "1.0.0", description: "My Awesome CLI App" },
+  subCommands: { sub },
+});
+
+runMain(main);
+```
 
-Create a wrapper around command that calls `runMain` when called.
+Subcommands support `meta.alias` (e.g., `["i", "add"]`) and `meta.hidden: true` to hide from help output.
 
-### `runCommand`
+### Lazy Commands
+
+For large CLIs, lazy load sub commands so only the executed command is imported:
+
+```js
+const main = defineCommand({
+  meta: { name: "hello", version: "1.0.0", description: "My Awesome CLI App" },
+  subCommands: {
+    sub: () => import("./sub.mjs").then((m) => m.default),
+  },
+});
+```
 
-Parses input args and runs command and sub-commands (unsupervised). You can access `result` key from returnd/awaited value to access command's result.
+`meta`, `args`, and `subCommands` all accept `Resolvable<T>` values — a value, Promise, function, or async function — enabling lazy and dynamic resolution.
 
-### `parseArgs`
+### Hooks
 
-Parses input arguments and applies defaults.
+Commands support `setup` and `cleanup` functions called before and after `run()`. Only the executed command's hooks run. `cleanup` always runs, even if `run()` throws.
 
-### `renderUsage`
+```js
+const main = defineCommand({
+  meta: { name: "hello", version: "1.0.0", description: "My Awesome CLI App" },
+  setup() {
+    console.log("Setting up...");
+  },
+  cleanup() {
+    console.log("Cleaning up...");
+  },
+  run() {
+    console.log("Hello World!");
+  },
+});
+```
 
-Renders command usage to a string value.
+### Plugins
 
-### `showUsage`
+Plugins extend commands with reusable `setup` and `cleanup` hooks:
 
-Renders usage and prints to the console
+```js
+import { defineCommand, defineCittyPlugin, runMain } from "citty";
+
+const logger = defineCittyPlugin({
+  name: "logger",
+  setup({ args }) {
+    console.log("Logger setup, args:", args);
+  },
+  cleanup() {
+    console.log("Logger cleanup");
+  },
+});
+
+const main = defineCommand({
+  meta: { name: "hello", description: "My CLI App" },
+  plugins: [logger],
+  run() {
+    console.log("Hello!");
+  },
+});
+
+runMain(main);
+```
+
+Plugin `setup` hooks run before the command's `setup` (in order), `cleanup` hooks run after (in reverse). Plugins can be async or factory functions.
+
+## Arguments
+
+### Argument Types
+
+| Type         | Description                              | Example                     |
+| ------------ | ---------------------------------------- | --------------------------- |
+| `positional` | Unnamed positional args                  | `cli <name>`                |
+| `string`     | Named string options                     | `--name value`              |
+| `boolean`    | Boolean flags, supports `--no-` negation | `--verbose`                 |
+| `enum`       | Constrained to `options` array           | `--level=info\|warn\|error` |
+
+### Common Options
+
+| Option        | Description                                                   |
+| ------------- | ------------------------------------------------------------- |
+| `description` | Help text shown in usage output                               |
+| `required`    | Whether the argument is required                              |
+| `default`     | Default value when not provided                               |
+| `alias`       | Short aliases (e.g., `["f"]`). Not for `positional`           |
+| `valueHint`   | Display hint in help (e.g., `"host"` renders `--name=<host>`) |
+
+### Example
+
+```js
+const main = defineCommand({
+  args: {
+    name: { type: "positional", description: "Your name", required: true },
+    friendly: { type: "boolean", description: "Use friendly greeting", alias: ["f"] },
+    greeting: { type: "string", description: "Custom greeting", default: "Hello" },
+    level: {
+      type: "enum",
+      description: "Log level",
+      options: ["debug", "info", "warn", "error"],
+      default: "info",
+    },
+  },
+  run({ args }) {
+    console.log(`${args.greeting} ${args.name}! (level: ${args.level})`);
+  },
+});
+```
+
+### Boolean Negation
+
+Boolean args support `--no-` prefix. The negative variant appears in help when `default: true` or `negativeDescription` is set.
+
+### Case-Agnostic Access
+
+Kebab-case args can be accessed as camelCase: `args["output-dir"]` and `args.outputDir` both work.
+
+## Built-in Flags
+
+`--help` / `-h` and `--version` / `-v` are handled automatically. Disabled if your command defines args with the same names or aliases.
+
+## API
+
+| Function                      | Description                                                                |
+| ----------------------------- | -------------------------------------------------------------------------- |
+| `defineCommand(def)`          | Type helper for defining commands                                          |
+| `runMain(cmd, opts?)`         | Run a command with usage support and graceful error handling               |
+| `createMain(cmd)`             | Create a wrapper that calls `runMain` when invoked                         |
+| `runCommand(cmd, opts)`       | Parse args and run command/sub-commands; access `result` from return value |
+| `parseArgs(rawArgs, argsDef)` | Parse input arguments and apply defaults                                   |
+| `renderUsage(cmd, parent?)`   | Render command usage to a string                                           |
+| `showUsage(cmd, parent?)`     | Render usage and print to console                                          |
+| `defineCittyPlugin(def)`      | Type helper for defining plugins                                           |
 
 ## Development
 
@@ -113,22 +229,3 @@ Renders usage and prints to the console
 ## License
 
 Made with 💛 Published under [MIT License](./LICENSE).
-
-Argument parser is based on [lukeed/mri](https://github.com/lukeed/mri) by Luke Edwards ([@lukeed](https://github.com/lukeed)).
-
-<!-- Badges -->
-
-<!-- Badges -->
-
-[npm-version-src]: https://img.shields.io/npm/v/citty?style=flat&colorA=18181B&colorB=F0DB4F
-[npm-version-href]: https://npmjs.com/package/citty
-[npm-downloads-src]: https://img.shields.io/npm/dm/citty?style=flat&colorA=18181B&colorB=F0DB4F
-[npm-downloads-href]: https://npmjs.com/package/citty
-[codecov-src]: https://img.shields.io/codecov/c/gh/unjs/citty/main?style=flat&colorA=18181B&colorB=F0DB4F
-[codecov-href]: https://codecov.io/gh/unjs/citty
-[bundle-src]: https://img.shields.io/bundlephobia/minzip/citty?style=flat&colorA=18181B&colorB=F0DB4F
-[bundle-href]: https://bundlephobia.com/result?p=citty
-[license-src]: https://img.shields.io/github/license/unjs/citty.svg?style=flat&colorA=18181B&colorB=F0DB4F
-[license-href]: https://github.com/unjs/citty/blob/main/LICENSE
-[jsdocs-src]: https://img.shields.io/badge/jsDocs.io-reference-18181B?style=flat&colorA=18181B&colorB=F0DB4F
-[jsdocs-href]: https://www.jsdocs.io/package/citty

package/node_modules/citty/dist/index.d.mts

@@ -1,80 +1,112 @@
-type ArgType = "boolean" | "string" | "positional" | undefined;
-type _ArgDef<T extends ArgType, VT extends boolean | string> = {
-    type?: T;
-    description?: string;
-    valueHint?: string;
-    alias?: string | string[];
-    default?: VT;
-    required?: boolean;
+//#region src/types.d.ts
+type ArgType = "boolean" | "string" | "enum" | "positional" | undefined;
+type _ArgDef<T extends ArgType, VT extends boolean | number | string> = {
+  type?: T;
+  description?: string;
+  valueHint?: string;
+  alias?: string | string[];
+  default?: VT;
+  required?: boolean;
+  options?: string[];
 };
-type BooleanArgDef = _ArgDef<"boolean", boolean>;
-type StringArgDef = _ArgDef<"string", string>;
-type PositionalArgDef = Omit<_ArgDef<"positional", string>, "alias">;
-type ArgDef = BooleanArgDef | StringArgDef | PositionalArgDef;
+type BooleanArgDef = Omit<_ArgDef<"boolean", boolean>, "options"> & {
+  negativeDescription?: string;
+};
+type StringArgDef = Omit<_ArgDef<"string", string>, "options">;
+type EnumArgDef = _ArgDef<"enum", string>;
+type PositionalArgDef = Omit<_ArgDef<"positional", string>, "alias" | "options">;
+type ArgDef = BooleanArgDef | StringArgDef | PositionalArgDef | EnumArgDef;
 type ArgsDef = Record<string, ArgDef>;
 type Arg = ArgDef & {
-    name: string;
-    alias: string[];
+  name: string;
+  alias: string[];
+};
+type ResolveParsedArgType<T extends ArgDef, VT> = T extends {
+  default?: any;
+  required?: boolean;
+} ? T["default"] extends NonNullable<VT> ? VT : T["required"] extends true ? VT : VT | undefined : VT | undefined;
+type ParsedPositionalArg<T extends ArgDef> = T extends {
+  type: "positional";
+} ? ResolveParsedArgType<T, string> : never;
+type ParsedStringArg<T extends ArgDef> = T extends {
+  type: "string";
+} ? ResolveParsedArgType<T, string> : never;
+type ParsedBooleanArg<T extends ArgDef> = T extends {
+  type: "boolean";
+} ? ResolveParsedArgType<T, boolean> : never;
+type ParsedEnumArg<T extends ArgDef> = T extends {
+  type: "enum";
+  options: infer U;
+} ? U extends Array<any> ? ResolveParsedArgType<T, U[number]> : never : never;
+type RawArgs = {
+  _: string[];
 };
-type ParsedArgs<T extends ArgsDef = ArgsDef> = {
-    _: string[];
-} & Record<{
-    [K in keyof T]: T[K] extends {
-        type: "positional";
-    } ? K : never;
-}[keyof T], string> & Record<{
-    [K in keyof T]: T[K] extends {
-        type: "string";
-    } ? K : never;
-}[keyof T], string> & Record<{
-    [K in keyof T]: T[K] extends {
-        type: "boolean";
-    } ? K : never;
-}[keyof T], boolean> & Record<string, string | boolean | string[]>;
+type ParsedArg<T extends ArgDef> = T["type"] extends "positional" ? ParsedPositionalArg<T> : T["type"] extends "boolean" ? ParsedBooleanArg<T> : T["type"] extends "string" ? ParsedStringArg<T> : T["type"] extends "enum" ? ParsedEnumArg<T> : never;
+type ParsedArgs<T extends ArgsDef = ArgsDef> = RawArgs & { [K in keyof T]: ParsedArg<T[K]> } & { [K in keyof T as T[K] extends {
+  alias: string;
+} ? T[K]["alias"] : never]: ParsedArg<T[K]> } & { [K in keyof T as T[K] extends {
+  alias: string[];
+} ? T[K]["alias"][number] : never]: ParsedArg<T[K]> } & Record<string, string | number | boolean | string[]>;
 interface CommandMeta {
-    name?: string;
-    version?: string;
-    description?: string;
+  name?: string;
+  version?: string;
+  description?: string;
+  hidden?: boolean;
+  alias?: string | string[];
 }
 type SubCommandsDef = Record<string, Resolvable<CommandDef<any>>>;
 type CommandDef<T extends ArgsDef = ArgsDef> = {
-    meta?: Resolvable<CommandMeta>;
-    args?: Resolvable<T>;
-    subCommands?: Resolvable<SubCommandsDef>;
-    setup?: (context: CommandContext<T>) => any | Promise<any>;
-    cleanup?: (context: CommandContext<T>) => any | Promise<any>;
-    run?: (context: CommandContext<T>) => any | Promise<any>;
+  meta?: Resolvable<CommandMeta>;
+  args?: Resolvable<T>;
+  default?: Resolvable<string>;
+  subCommands?: Resolvable<SubCommandsDef>;
+  plugins?: Resolvable<CittyPlugin>[];
+  setup?: (context: CommandContext<T>) => any | Promise<any>;
+  cleanup?: (context: CommandContext<T>) => any | Promise<any>;
+  run?: (context: CommandContext<T>) => any | Promise<any>;
 };
 type CommandContext<T extends ArgsDef = ArgsDef> = {
-    rawArgs: string[];
-    args: ParsedArgs<T>;
-    cmd: CommandDef<T>;
-    subCommand?: CommandDef<T>;
-    data?: any;
+  rawArgs: string[];
+  args: ParsedArgs<T>;
+  cmd: CommandDef<T>;
+  subCommand?: CommandDef<T>;
+  data?: any;
+};
+type CittyPlugin = {
+  name: string;
+  setup?(context: CommandContext<any>): void | Promise<void>;
+  cleanup?(context: CommandContext<any>): void | Promise<void>;
 };
 type Awaitable<T> = () => T | Promise<T>;
 type Resolvable<T> = T | Promise<T> | (() => T) | (() => Promise<T>);
-
-declare function defineCommand<T extends ArgsDef = ArgsDef>(def: CommandDef<T>): CommandDef<T>;
+//#endregion
+//#region src/command.d.ts
+declare function defineCommand<const T extends ArgsDef = ArgsDef>(def: CommandDef<T>): CommandDef<T>;
 interface RunCommandOptions {
-    rawArgs: string[];
-    data?: any;
-    showUsage?: boolean;
+  rawArgs: string[];
+  data?: any;
+  showUsage?: boolean;
 }
 declare function runCommand<T extends ArgsDef = ArgsDef>(cmd: CommandDef<T>, opts: RunCommandOptions): Promise<{
-    result: unknown;
+  result: unknown;
 }>;
-
+//#endregion
+//#region src/usage.d.ts
 declare function showUsage<T extends ArgsDef = ArgsDef>(cmd: CommandDef<T>, parent?: CommandDef<T>): Promise<void>;
 declare function renderUsage<T extends ArgsDef = ArgsDef>(cmd: CommandDef<T>, parent?: CommandDef<T>): Promise<string>;
-
+//#endregion
+//#region src/main.d.ts
 interface RunMainOptions {
-    rawArgs?: string[];
-    showUsage?: typeof showUsage;
+  rawArgs?: string[];
+  showUsage?: typeof showUsage;
 }
 declare function runMain<T extends ArgsDef = ArgsDef>(cmd: CommandDef<T>, opts?: RunMainOptions): Promise<void>;
 declare function createMain<T extends ArgsDef = ArgsDef>(cmd: CommandDef<T>): (opts?: RunMainOptions) => Promise<void>;
-
+//#endregion
+//#region src/args.d.ts
 declare function parseArgs<T extends ArgsDef = ArgsDef>(rawArgs: string[], argsDef: ArgsDef): ParsedArgs<T>;
-
-export { type Arg, type ArgDef, type ArgType, type ArgsDef, type Awaitable, type BooleanArgDef, type CommandContext, type CommandDef, type CommandMeta, type ParsedArgs, type PositionalArgDef, type Resolvable, type RunCommandOptions, type RunMainOptions, type StringArgDef, type SubCommandsDef, type _ArgDef, createMain, defineCommand, parseArgs, renderUsage, runCommand, runMain, showUsage };
+//#endregion
+//#region src/plugin.d.ts
+declare function defineCittyPlugin(plugin: Resolvable<CittyPlugin>): Resolvable<CittyPlugin>;
+//#endregion
+export { Arg, ArgDef, ArgType, ArgsDef, Awaitable, BooleanArgDef, CittyPlugin, CommandContext, CommandDef, CommandMeta, EnumArgDef, ParsedArgs, PositionalArgDef, Resolvable, type RunCommandOptions, type RunMainOptions, StringArgDef, SubCommandsDef, _ArgDef, createMain, defineCittyPlugin, defineCommand, parseArgs, renderUsage, runCommand, runMain, showUsage };