citty 0.1.2 → 0.1.4

package/README.md

@@ -65,7 +65,7 @@ const main = defineCommand({
     },
   },
   run({ args }) {
-    consol.log(`${args.friendly ? "Hi" : "Greetings"} ${args.name}!`);
+    console.log(`${args.friendly ? "Hi" : "Greetings"} ${args.name}!`);
   },
 });
 
@@ -82,6 +82,10 @@ runMain(main);
 
 Runs a command with usage support and graceful error handling.
 
+### `createMain`
+
+Create a wrapper around command that calls `runMain` when called.
+
 ### `runCommand`
 
 Parses input args and runs command and sub-commands (unsupervised).

package/dist/index.cjs

@@ -293,30 +293,37 @@ async function runCommand(cmd, opts) {
   if (typeof cmd.setup === "function") {
     await cmd.setup(context);
   }
-  const subCommands = await resolveValue(cmd.subCommands);
-  if (subCommands && Object.keys(subCommands).length > 0) {
-    const subCommandArgIndex = opts.rawArgs.findIndex(
-      (arg) => !arg.startsWith("-")
-    );
-    const subCommandName = opts.rawArgs[subCommandArgIndex];
-    if (!subCommandName && !cmd.run) {
-      throw new CLIError(`No command specified.`, "E_NO_COMMAND");
-    }
-    if (!subCommands[subCommandName]) {
-      throw new CLIError(
-        `Unknown command \`${subCommandName}\``,
-        "E_UNKNOWN_COMMAND"
+  try {
+    const subCommands = await resolveValue(cmd.subCommands);
+    if (subCommands && Object.keys(subCommands).length > 0) {
+      const subCommandArgIndex = opts.rawArgs.findIndex(
+        (arg) => !arg.startsWith("-")
       );
+      const subCommandName = opts.rawArgs[subCommandArgIndex];
+      if (subCommandName) {
+        if (!subCommands[subCommandName]) {
+          throw new CLIError(
+            `Unknown command \`${subCommandName}\``,
+            "E_UNKNOWN_COMMAND"
+          );
+        }
+        const subCommand = await resolveValue(subCommands[subCommandName]);
+        if (subCommand) {
+          await runCommand(subCommand, {
+            rawArgs: opts.rawArgs.slice(subCommandArgIndex + 1)
+          });
+        }
+      } else if (!cmd.run) {
+        throw new CLIError(`No command specified.`, "E_NO_COMMAND");
+      }
     }
-    const subCommand = await resolveValue(subCommands[subCommandName]);
-    if (subCommand) {
-      await runCommand(subCommand, {
-        rawArgs: opts.rawArgs.slice(subCommandArgIndex + 1)
-      });
+    if (typeof cmd.run === "function") {
+      await cmd.run(context);
+    }
+  } finally {
+    if (typeof cmd.cleanup === "function") {
+      await cmd.cleanup(context);
     }
-  }
-  if (typeof cmd.run === "function") {
-    await cmd.run(context);
   }
 }
 async function resolveSubCommand(cmd, rawArgs, parent) {
@@ -427,6 +434,12 @@ async function runMain(cmd, opts = {}) {
     if (rawArgs.includes("--help") || rawArgs.includes("-h")) {
       await showUsage(...await resolveSubCommand(cmd, rawArgs));
       process.exit(0);
+    } else if (rawArgs.length === 1 && rawArgs[0] === "--version") {
+      const meta = typeof cmd.meta === "function" ? await cmd.meta() : await cmd.meta;
+      if (!meta?.version) {
+        throw new CLIError("No version specified", "E_NO_VERSION");
+      }
+      consola__default.log(meta.version);
     } else {
       await runCommand(cmd, { rawArgs });
     }
@@ -442,7 +455,11 @@ async function runMain(cmd, opts = {}) {
     process.exit(1);
   }
 }
+function createMain(cmd) {
+  return (opts = {}) => runMain(cmd, opts);
+}
 
+exports.createMain = createMain;
 exports.defineCommand = defineCommand;
 exports.parseArgs = parseArgs;
 exports.renderUsage = renderUsage;

package/dist/index.d.cts

@@ -0,0 +1,77 @@
+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;
+};
+type BooleanArgDef = _ArgDef<"boolean", boolean>;
+type StringArgDef = _ArgDef<"string", string>;
+type PositionalArgDef = Omit<_ArgDef<"positional", string>, "alias">;
+type ArgDef = BooleanArgDef | StringArgDef | PositionalArgDef;
+type ArgsDef = Record<string, ArgDef>;
+type Arg = ArgDef & {
+    name: string;
+    alias: 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[]>;
+interface CommandMeta {
+    name?: string;
+    version?: string;
+    description?: 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>;
+};
+type CommandContext<T extends ArgsDef = ArgsDef> = {
+    rawArgs: string[];
+    args: ParsedArgs<T>;
+    cmd: CommandDef<T>;
+    subCommand?: CommandDef<T>;
+    data?: any;
+};
+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>;
+interface RunCommandOptions {
+    rawArgs: string[];
+    data?: any;
+    showUsage?: boolean;
+}
+declare function runCommand<T extends ArgsDef = ArgsDef>(cmd: CommandDef<T>, opts: RunCommandOptions): Promise<void>;
+
+interface RunMainOptions {
+    rawArgs?: string[];
+}
+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>;
+
+declare function parseArgs<T extends ArgsDef = ArgsDef>(rawArgs: string[], argsDef: ArgsDef): ParsedArgs<T>;
+
+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>;
+
+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 };

package/dist/index.d.mts

@@ -0,0 +1,77 @@
+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;
+};
+type BooleanArgDef = _ArgDef<"boolean", boolean>;
+type StringArgDef = _ArgDef<"string", string>;
+type PositionalArgDef = Omit<_ArgDef<"positional", string>, "alias">;
+type ArgDef = BooleanArgDef | StringArgDef | PositionalArgDef;
+type ArgsDef = Record<string, ArgDef>;
+type Arg = ArgDef & {
+    name: string;
+    alias: 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[]>;
+interface CommandMeta {
+    name?: string;
+    version?: string;
+    description?: 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>;
+};
+type CommandContext<T extends ArgsDef = ArgsDef> = {
+    rawArgs: string[];
+    args: ParsedArgs<T>;
+    cmd: CommandDef<T>;
+    subCommand?: CommandDef<T>;
+    data?: any;
+};
+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>;
+interface RunCommandOptions {
+    rawArgs: string[];
+    data?: any;
+    showUsage?: boolean;
+}
+declare function runCommand<T extends ArgsDef = ArgsDef>(cmd: CommandDef<T>, opts: RunCommandOptions): Promise<void>;
+
+interface RunMainOptions {
+    rawArgs?: string[];
+}
+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>;
+
+declare function parseArgs<T extends ArgsDef = ArgsDef>(rawArgs: string[], argsDef: ArgsDef): ParsedArgs<T>;
+
+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>;
+
+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 };

package/dist/index.d.ts

@@ -30,7 +30,7 @@ type ParsedArgs<T extends ArgsDef = ArgsDef> = {
     [K in keyof T]: T[K] extends {
         type: "boolean";
     } ? K : never;
-}[keyof T], boolean> & Record<string, string | boolean>;
+}[keyof T], boolean> & Record<string, string | boolean | string[]>;
 interface CommandMeta {
     name?: string;
     version?: string;
@@ -67,10 +67,11 @@ interface RunMainOptions {
     rawArgs?: string[];
 }
 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>;
 
 declare function parseArgs<T extends ArgsDef = ArgsDef>(rawArgs: string[], argsDef: ArgsDef): ParsedArgs<T>;
 
 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>;
 
-export { Arg, ArgDef, ArgType, ArgsDef, Awaitable, BooleanArgDef, CommandContext, CommandDef, CommandMeta, ParsedArgs, PositionalArgDef, Resolvable, RunCommandOptions, RunMainOptions, StringArgDef, SubCommandsDef, _ArgDef, defineCommand, parseArgs, renderUsage, runCommand, runMain, showUsage };
+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 };

package/dist/index.mjs

@@ -287,30 +287,37 @@ async function runCommand(cmd, opts) {
   if (typeof cmd.setup === "function") {
     await cmd.setup(context);
   }
-  const subCommands = await resolveValue(cmd.subCommands);
-  if (subCommands && Object.keys(subCommands).length > 0) {
-    const subCommandArgIndex = opts.rawArgs.findIndex(
-      (arg) => !arg.startsWith("-")
-    );
-    const subCommandName = opts.rawArgs[subCommandArgIndex];
-    if (!subCommandName && !cmd.run) {
-      throw new CLIError(`No command specified.`, "E_NO_COMMAND");
-    }
-    if (!subCommands[subCommandName]) {
-      throw new CLIError(
-        `Unknown command \`${subCommandName}\``,
-        "E_UNKNOWN_COMMAND"
+  try {
+    const subCommands = await resolveValue(cmd.subCommands);
+    if (subCommands && Object.keys(subCommands).length > 0) {
+      const subCommandArgIndex = opts.rawArgs.findIndex(
+        (arg) => !arg.startsWith("-")
       );
+      const subCommandName = opts.rawArgs[subCommandArgIndex];
+      if (subCommandName) {
+        if (!subCommands[subCommandName]) {
+          throw new CLIError(
+            `Unknown command \`${subCommandName}\``,
+            "E_UNKNOWN_COMMAND"
+          );
+        }
+        const subCommand = await resolveValue(subCommands[subCommandName]);
+        if (subCommand) {
+          await runCommand(subCommand, {
+            rawArgs: opts.rawArgs.slice(subCommandArgIndex + 1)
+          });
+        }
+      } else if (!cmd.run) {
+        throw new CLIError(`No command specified.`, "E_NO_COMMAND");
+      }
     }
-    const subCommand = await resolveValue(subCommands[subCommandName]);
-    if (subCommand) {
-      await runCommand(subCommand, {
-        rawArgs: opts.rawArgs.slice(subCommandArgIndex + 1)
-      });
+    if (typeof cmd.run === "function") {
+      await cmd.run(context);
+    }
+  } finally {
+    if (typeof cmd.cleanup === "function") {
+      await cmd.cleanup(context);
     }
-  }
-  if (typeof cmd.run === "function") {
-    await cmd.run(context);
   }
 }
 async function resolveSubCommand(cmd, rawArgs, parent) {
@@ -421,6 +428,12 @@ async function runMain(cmd, opts = {}) {
     if (rawArgs.includes("--help") || rawArgs.includes("-h")) {
       await showUsage(...await resolveSubCommand(cmd, rawArgs));
       process.exit(0);
+    } else if (rawArgs.length === 1 && rawArgs[0] === "--version") {
+      const meta = typeof cmd.meta === "function" ? await cmd.meta() : await cmd.meta;
+      if (!meta?.version) {
+        throw new CLIError("No version specified", "E_NO_VERSION");
+      }
+      consola.log(meta.version);
     } else {
       await runCommand(cmd, { rawArgs });
     }
@@ -436,5 +449,8 @@ async function runMain(cmd, opts = {}) {
     process.exit(1);
   }
 }
+function createMain(cmd) {
+  return (opts = {}) => runMain(cmd, opts);
+}
 
-export { defineCommand, parseArgs, renderUsage, runCommand, runMain, showUsage };
+export { createMain, defineCommand, parseArgs, renderUsage, runCommand, runMain, showUsage };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "citty",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Elegant CLI Builder",
   "repository": "unjs/citty",
   "license": "MIT",
@@ -33,17 +33,17 @@
     "consola": "^3.2.3"
   },
   "devDependencies": {
-    "@types/node": "^20.4.0",
-    "@vitest/coverage-v8": "^0.32.4",
-    "changelogen": "^0.5.4",
-    "eslint": "^8.44.0",
+    "@types/node": "^20.6.0",
+    "@vitest/coverage-v8": "^0.34.4",
+    "changelogen": "^0.5.5",
+    "eslint": "^8.49.0",
     "eslint-config-unjs": "^0.2.1",
-    "jiti": "^1.19.1",
-    "prettier": "^3.0.0",
+    "jiti": "^1.20.0",
+    "prettier": "^3.0.3",
     "scule": "^1.0.0",
-    "typescript": "^5.1.6",
-    "unbuild": "^1.2.1",
-    "vitest": "^0.32.4"
+    "typescript": "^5.2.2",
+    "unbuild": "^2.0.0",
+    "vitest": "^0.34.4"
   },
-  "packageManager": "pnpm@8.6.6"
+  "packageManager": "pnpm@8.7.4"
 }