citty 0.0.0 → 0.0.2

package/LICENSE

@@ -0,0 +1,47 @@
+MIT License
+
+Copyright (c) Pooya Parsa <pooya@pi0.io>
+
+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.
+
+---
+
+Parser is based on https://github.com/lukeed/mri
+
+The MIT License (MIT)
+
+Copyright (c) Luke Edwards luke.edwards05@gmail.com (lukeed.com)
+
+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.
+
+---
+
+Colorette dependency is bundled (https://github.com/jorgebucaran/colorette)
+
+Copyright © Jorge Bucaran <https://jorgebucaran.com>
+
+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,130 @@
+# 🌆 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]
+
+> Elegant CLI Builder
+
+- 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
+
+🚧 This project is under heavy development. More features are coming soon!
+
+## Usage
+
+Install package:
+
+```sh
+# npm
+npm install citty
+
+# yarn
+yarn add citty
+
+# pnpm
+pnpm install 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({
+  meta: {
+    name: "hello",
+    version: "1.0.0",
+    description: "My Awesome CLI App",
+  },
+  args: {
+    name: {
+      type: "positional",
+      description: "Your name",
+      required: true,
+    },
+    friendly: {
+      type: "boolean",
+      description: "Use friendly greeting",
+    },
+  },
+  run({ args }) {
+    console.log(`${args.friendly ? "Hi" : "Greetings"} ${args.name}!`);
+  },
+});
+
+runMain(main);
+```
+
+## Utils
+
+### `defineCommand`
+
+`defineCommand` is a type helper for defining commands.
+
+### `runMain`
+
+Runs a command with usage support and graceful error handling.
+
+### `runCommand`
+
+Parses input args and runs command and sub-commands (unsupervised).
+
+### `parseArgs`
+
+Parses input arguments and applies defaults.
+
+### `renderUsage`
+
+Renders command usage to a string value.
+
+### `showUsage`
+
+Renders usage and prints to the console
+
+## Development
+
+- Clone this repository
+- Install latest LTS version of [Node.js](https://nodejs.org/en/)
+- Enable [Corepack](https://github.com/nodejs/corepack) using `corepack enable`
+- Install dependencies using `pnpm install`
+- Run interactive tests using `pnpm dev`
+
+## 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/dist/index.cjs

@@ -0,0 +1,544 @@
+'use strict';
+
+const scule = require('scule');
+const tty = require('tty');
+
+function _interopNamespaceDefault(e) {
+  const n = Object.create(null);
+  if (e) {
+    for (const k in e) {
+      n[k] = e[k];
+    }
+  }
+  n.default = e;
+  return n;
+}
+
+const tty__namespace = /*#__PURE__*/_interopNamespaceDefault(tty);
+
+function toArray(val) {
+  if (Array.isArray(val)) {
+    return val;
+  }
+  return val !== void 0 ? [val] : [];
+}
+function formatLineColumns(lines, linePrefix = "") {
+  const maxLengh = [];
+  for (const line of lines) {
+    for (const [i, element] of line.entries()) {
+      maxLengh[i] = Math.max(maxLengh[i] || 0, element.length);
+    }
+  }
+  return lines.map(
+    (l) => l.map(
+      (c, i) => linePrefix + c[i === 0 ? "padStart" : "padEnd"](maxLengh[i])
+    ).join("  ")
+  ).join("\n");
+}
+function resolveValue(input) {
+  return typeof input === "function" ? input() : input;
+}
+class CLIError extends Error {
+  constructor(message, code) {
+    super(message);
+    this.code = code;
+    this.name = "CLIError";
+  }
+}
+
+function toArr(any) {
+  return any == void 0 ? [] : Array.isArray(any) ? any : [any];
+}
+function toVal(out, key, val, opts) {
+  let x;
+  const old = out[key];
+  const nxt = ~opts.string.indexOf(key) ? val == void 0 || val === true ? "" : String(val) : typeof val === "boolean" ? val : ~opts.boolean.indexOf(key) ? val === "false" ? false : val === "true" || (out._.push((x = +val, x * 0 === 0) ? x : val), !!val) : (x = +val, x * 0 === 0) ? x : val;
+  out[key] = old == void 0 ? nxt : Array.isArray(old) ? old.concat(nxt) : [old, nxt];
+}
+function parseRawArgs(args = [], opts = {}) {
+  let k;
+  let arr;
+  let arg;
+  let name;
+  let val;
+  const out = { _: [] };
+  let i = 0;
+  let j = 0;
+  let idx = 0;
+  const len = args.length;
+  const alibi = opts.alias !== void 0;
+  const strict = opts.unknown !== void 0;
+  const defaults = opts.default !== void 0;
+  opts.alias = opts.alias || {};
+  opts.string = toArr(opts.string);
+  opts.boolean = toArr(opts.boolean);
+  if (alibi) {
+    for (k in opts.alias) {
+      arr = opts.alias[k] = toArr(opts.alias[k]);
+      for (i = 0; i < arr.length; i++) {
+        (opts.alias[arr[i]] = arr.concat(k)).splice(i, 1);
+      }
+    }
+  }
+  for (i = opts.boolean.length; i-- > 0; ) {
+    arr = opts.alias[opts.boolean[i]] || [];
+    for (j = arr.length; j-- > 0; ) {
+      opts.boolean.push(arr[j]);
+    }
+  }
+  for (i = opts.string.length; i-- > 0; ) {
+    arr = opts.alias[opts.string[i]] || [];
+    for (j = arr.length; j-- > 0; ) {
+      opts.string.push(arr[j]);
+    }
+  }
+  if (defaults) {
+    for (k in opts.default) {
+      name = typeof opts.default[k];
+      arr = opts.alias[k] = opts.alias[k] || [];
+      if (opts[name] !== void 0) {
+        opts[name].push(k);
+        for (i = 0; i < arr.length; i++) {
+          opts[name].push(arr[i]);
+        }
+      }
+    }
+  }
+  const keys = strict ? Object.keys(opts.alias) : [];
+  for (i = 0; i < len; i++) {
+    arg = args[i];
+    if (arg === "--") {
+      out._ = out._.concat(args.slice(++i));
+      break;
+    }
+    for (j = 0; j < arg.length; j++) {
+      if (arg.charCodeAt(j) !== 45) {
+        break;
+      }
+    }
+    if (j === 0) {
+      out._.push(arg);
+    } else if (arg.substring(j, j + 3) === "no-") {
+      name = arg.slice(Math.max(0, j + 3));
+      if (strict && !~keys.indexOf(name)) {
+        return opts.unknown(arg);
+      }
+      out[name] = false;
+    } else {
+      for (idx = j + 1; idx < arg.length; idx++) {
+        if (arg.charCodeAt(idx) === 61) {
+          break;
+        }
+      }
+      name = arg.substring(j, idx);
+      val = arg.slice(Math.max(0, ++idx)) || i + 1 === len || ("" + args[i + 1]).charCodeAt(0) === 45 || args[++i];
+      arr = j === 2 ? [name] : name;
+      for (idx = 0; idx < arr.length; idx++) {
+        name = arr[idx];
+        if (strict && !~keys.indexOf(name)) {
+          return opts.unknown("-".repeat(j) + name);
+        }
+        toVal(out, name, idx + 1 < arr.length || val, opts);
+      }
+    }
+  }
+  if (defaults) {
+    for (k in opts.default) {
+      if (out[k] === void 0) {
+        out[k] = opts.default[k];
+      }
+    }
+  }
+  if (alibi) {
+    for (k in out) {
+      arr = opts.alias[k] || [];
+      while (arr.length > 0) {
+        out[arr.shift()] = out[k];
+      }
+    }
+  }
+  return out;
+}
+
+function parseArgs(rawArgs, argsDef) {
+  const parseOptions = {
+    boolean: [],
+    string: [],
+    alias: {},
+    default: {}
+  };
+  const args = resolveArgs(argsDef);
+  for (const arg of args) {
+    if (arg.type === "positional") {
+      continue;
+    }
+    parseOptions[arg.type || "boolean"].push(arg.name);
+    if (arg.default !== void 0) {
+      parseOptions.default[arg.name] = arg.default;
+    }
+    if (arg.alias) {
+      parseOptions.alias[arg.name] = arg.alias;
+    }
+  }
+  const parsed = parseRawArgs(rawArgs, parseOptions);
+  const [, ...positionalArguments] = parsed._;
+  const parsedArgsProxy = new Proxy(parsed, {
+    get(target, prop) {
+      return target[prop] ?? target[scule.camelCase(prop)] ?? target[scule.kebabCase(prop)];
+    }
+  });
+  for (const [, arg] of args.entries()) {
+    if (arg.type === "positional") {
+      const nextPositionalArgument = positionalArguments.shift();
+      if (nextPositionalArgument !== void 0) {
+        parsedArgsProxy[arg.name] = nextPositionalArgument;
+      } else if (arg.default !== void 0) {
+        parsedArgsProxy[arg.name] = arg.default;
+      } else {
+        throw new CLIError(
+          `Missing required positional argument: ${arg.name.toUpperCase()}`,
+          "EARG"
+        );
+      }
+    } else if (arg.required && parsedArgsProxy[arg.name] === void 0) {
+      throw new CLIError(`Missing required argument: --${arg.name}`, "EARG");
+    }
+  }
+  return parsedArgsProxy;
+}
+function resolveArgs(argsDef) {
+  const args = [];
+  for (const [name, argDef] of Object.entries(argsDef || {})) {
+    args.push({
+      ...argDef,
+      name,
+      alias: toArray(argDef.alias)
+    });
+  }
+  return args;
+}
+
+function defineCommand(def) {
+  return def;
+}
+async function runCommand(cmd, opts) {
+  const cmdArgs = await resolveValue(cmd.args || {});
+  const parsedArgs = parseArgs(opts.rawArgs, cmdArgs);
+  const context = {
+    rawArgs: opts.rawArgs,
+    args: parsedArgs,
+    cmd
+  };
+  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(
+        `Missing sub command. Use --help to see available sub commands.`,
+        "ESUBCOMMAND"
+      );
+    }
+    if (!subCommands[subCommandName]) {
+      throw new CLIError(
+        `Unknown sub command: ${subCommandName}`,
+        "ESUBCOMMAND"
+      );
+    }
+    const subCommand = await resolveValue(subCommands[subCommandName]);
+    if (subCommand) {
+      await runCommand(subCommand, {
+        rawArgs: opts.rawArgs.slice(subCommandArgIndex)
+      });
+    }
+  }
+  if (typeof cmd.run === "function") {
+    await cmd.run(context);
+  }
+}
+async function resolveSubCommand(cmd, rawArgs, parent) {
+  const subCommands = await resolveValue(cmd.subCommands);
+  if (subCommands && Object.keys(subCommands).length > 0) {
+    const subCommandArgIndex = rawArgs.findIndex((arg) => !arg.startsWith("-"));
+    const subCommandName = rawArgs[subCommandArgIndex];
+    const subCommand = await resolveValue(subCommands[subCommandName]);
+    if (subCommand) {
+      return resolveSubCommand(
+        subCommand,
+        rawArgs.slice(subCommandArgIndex),
+        cmd
+      );
+    }
+  }
+  return [cmd, parent];
+}
+
+async function showUsage(cmd, parent) {
+  try {
+    console.log(await renderUsage(cmd, parent) + "\n");
+  } catch (error) {
+    console.error(error);
+  }
+}
+async function renderUsage(cmd, parent) {
+  const cmdMeta = await resolveValue(cmd.meta || {});
+  const cmdArgs = resolveArgs(await resolveValue(cmd.args || {}));
+  const parentMeta = await resolveValue(parent?.meta || {});
+  const commandName = `${parentMeta.name ? `${parentMeta.name} ` : ""}` + (cmdMeta.name || process.argv[1]);
+  const argLines = [];
+  const posLines = [];
+  const commandsLines = [];
+  const usageLine = [];
+  for (const arg of cmdArgs) {
+    if (arg.type === "positional") {
+      const name = arg.name.toUpperCase();
+      const isRequired = arg.required !== false && arg.default === void 0;
+      const usageHint = arg.default ? `="${arg.default}"` : "";
+      posLines.push([name + usageHint, arg.description || ""]);
+      usageLine.push(isRequired ? `<${name}>` : `[${name}]`);
+    } else {
+      const isRequired = arg.required === true && arg.default === void 0;
+      const argStr = (arg.type === "boolean" && arg.default === true ? [
+        ...(arg.alias || []).map((a) => `--no-${a}`),
+        `--no-${arg.name}`
+      ].join(", ") : [...(arg.alias || []).map((a) => `-${a}`), `--${arg.name}`].join(
+        ", "
+      )) + (arg.type === "string" && (arg.valueHint || arg.default) ? `=${arg.valueHint ? `<${arg.valueHint}>` : `"${arg.default || ""}"`}` : "");
+      argLines.push([
+        argStr + (isRequired ? " (required)" : ""),
+        arg.description || ""
+      ]);
+      if (isRequired) {
+        usageLine.push(argStr);
+      }
+    }
+  }
+  if (cmd.subCommands) {
+    const commandNames = [];
+    for (const [name, sub] of Object.entries(cmd.subCommands)) {
+      commandsLines.push([name, sub.meta?.description || ""]);
+      commandNames.push(name);
+    }
+    usageLine.push(commandNames.join("|"));
+  }
+  const usageLines = [];
+  const version = cmdMeta.version || parentMeta.version;
+  usageLines.push(
+    commandName + (version ? ` v${version}` : ""),
+    cmdMeta.description,
+    ""
+  );
+  const hasOptions = argLines.length > 0 || posLines.length > 0;
+  usageLines.push(
+    `USAGE: ${commandName}${hasOptions ? " [OPTIONS]" : ""} ${usageLine.join(
+      " "
+    )}`,
+    ""
+  );
+  if (posLines.length > 0) {
+    usageLines.push("ARGUMENTS:", "");
+    usageLines.push(formatLineColumns(posLines, "  "));
+    usageLines.push("");
+  }
+  if (argLines.length > 0) {
+    usageLines.push("OPTIONS:", "");
+    usageLines.push(formatLineColumns(argLines, "  "));
+    usageLines.push("");
+  }
+  if (commandsLines.length > 0) {
+    usageLines.push("COMMANDS:", "");
+    usageLines.push(formatLineColumns(commandsLines, "  "));
+    usageLines.push(
+      "",
+      `Use \`${commandName} <command> --help\` for more information about a command.`
+    );
+  }
+  return usageLines.filter((l) => typeof l === "string").join("\n");
+}
+
+const {
+  env = {},
+  argv = [],
+  platform = "",
+} = typeof process === "undefined" ? {} : process;
+
+const isDisabled = "NO_COLOR" in env || argv.includes("--no-color");
+const isForced = "FORCE_COLOR" in env || argv.includes("--color");
+const isWindows = platform === "win32";
+const isDumbTerminal = env.TERM === "dumb";
+
+const isCompatibleTerminal =
+  tty__namespace && tty__namespace.isatty && tty__namespace.isatty(1) && env.TERM && !isDumbTerminal;
+
+const isCI =
+  "CI" in env &&
+  ("GITHUB_ACTIONS" in env || "GITLAB_CI" in env || "CIRCLECI" in env);
+
+const isColorSupported =
+  !isDisabled &&
+  (isForced || (isWindows && !isDumbTerminal) || isCompatibleTerminal || isCI);
+
+const replaceClose = (
+  index,
+  string,
+  close,
+  replace,
+  head = string.substring(0, index) + replace,
+  tail = string.substring(index + close.length),
+  next = tail.indexOf(close)
+) => head + (next < 0 ? tail : replaceClose(next, tail, close, replace));
+
+const clearBleed = (index, string, open, close, replace) =>
+  index < 0
+    ? open + string + close
+    : open + replaceClose(index, string, close, replace) + close;
+
+const filterEmpty =
+  (open, close, replace = open, at = open.length + 1) =>
+  (string) =>
+    string || !(string === "" || string === undefined)
+      ? clearBleed(
+          ("" + string).indexOf(close, at),
+          string,
+          open,
+          close,
+          replace
+        )
+      : "";
+
+const init = (open, close, replace) =>
+  filterEmpty(`\x1b[${open}m`, `\x1b[${close}m`, replace);
+
+const colors = {
+  reset: init(0, 0),
+  bold: init(1, 22, "\x1b[22m\x1b[1m"),
+  dim: init(2, 22, "\x1b[22m\x1b[2m"),
+  italic: init(3, 23),
+  underline: init(4, 24),
+  inverse: init(7, 27),
+  hidden: init(8, 28),
+  strikethrough: init(9, 29),
+  black: init(30, 39),
+  red: init(31, 39),
+  green: init(32, 39),
+  yellow: init(33, 39),
+  blue: init(34, 39),
+  magenta: init(35, 39),
+  cyan: init(36, 39),
+  white: init(37, 39),
+  gray: init(90, 39),
+  bgBlack: init(40, 49),
+  bgRed: init(41, 49),
+  bgGreen: init(42, 49),
+  bgYellow: init(43, 49),
+  bgBlue: init(44, 49),
+  bgMagenta: init(45, 49),
+  bgCyan: init(46, 49),
+  bgWhite: init(47, 49),
+  blackBright: init(90, 39),
+  redBright: init(91, 39),
+  greenBright: init(92, 39),
+  yellowBright: init(93, 39),
+  blueBright: init(94, 39),
+  magentaBright: init(95, 39),
+  cyanBright: init(96, 39),
+  whiteBright: init(97, 39),
+  bgBlackBright: init(100, 49),
+  bgRedBright: init(101, 49),
+  bgGreenBright: init(102, 49),
+  bgYellowBright: init(103, 49),
+  bgBlueBright: init(104, 49),
+  bgMagentaBright: init(105, 49),
+  bgCyanBright: init(106, 49),
+  bgWhiteBright: init(107, 49),
+};
+
+const createColors = ({ useColor = isColorSupported } = {}) =>
+  useColor
+    ? colors
+    : Object.keys(colors).reduce(
+        (colors, key) => ({ ...colors, [key]: String }),
+        {}
+      );
+
+const {
+  reset,
+  bold,
+  dim,
+  italic,
+  underline,
+  inverse,
+  hidden,
+  strikethrough,
+  black,
+  red,
+  green,
+  yellow,
+  blue,
+  magenta,
+  cyan,
+  white,
+  gray,
+  bgBlack,
+  bgRed,
+  bgGreen,
+  bgYellow,
+  bgBlue,
+  bgMagenta,
+  bgCyan,
+  bgWhite,
+  blackBright,
+  redBright,
+  greenBright,
+  yellowBright,
+  blueBright,
+  magentaBright,
+  cyanBright,
+  whiteBright,
+  bgBlackBright,
+  bgRedBright,
+  bgGreenBright,
+  bgYellowBright,
+  bgBlueBright,
+  bgMagentaBright,
+  bgCyanBright,
+  bgWhiteBright,
+} = createColors();
+
+async function runMain(cmd, opts = {}) {
+  const rawArgs = opts.rawArgs || process.argv.slice(2);
+  try {
+    if (rawArgs.includes("--help") || rawArgs.includes("-h")) {
+      await showUsage(...await resolveSubCommand(cmd, rawArgs));
+      process.exit(0);
+    } else {
+      await runCommand(cmd, { rawArgs });
+    }
+  } catch (error) {
+    const isCLIError = error instanceof CLIError;
+    if (!isCLIError) {
+      console.error(error, "\n");
+    }
+    console.error(
+      `
+${bgRed(` ${error.code || error.name} `)} ${error.message}
+`
+    );
+    if (isCLIError) {
+      await showUsage(...await resolveSubCommand(cmd, rawArgs));
+    }
+    process.exit(1);
+  }
+}
+
+exports.defineCommand = defineCommand;
+exports.parseArgs = parseArgs;
+exports.renderUsage = renderUsage;
+exports.runCommand = runCommand;
+exports.runMain = runMain;
+exports.showUsage = showUsage;

package/dist/index.d.ts

@@ -0,0 +1,74 @@
+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 | boolean> & 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>;
+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;
+    subCommand?: CommandDef<T>;
+};
+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[];
+    showUsage?: boolean;
+}
+declare function runCommand(cmd: CommandDef, opts: RunCommandOptions): Promise<void>;
+
+interface RunMainOptions {
+    rawArgs?: string[];
+}
+declare function runMain(cmd: CommandDef, opts?: RunMainOptions): Promise<void>;
+
+declare function parseArgs(rawArgs: string[], argsDef: ArgsDef): ParsedArgs;
+
+declare function showUsage(cmd: CommandDef, parent?: CommandDef): Promise<void>;
+declare function renderUsage(cmd: CommandDef, parent?: CommandDef): 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 };

package/dist/index.mjs

@@ -0,0 +1,524 @@
+import { camelCase, kebabCase } from 'scule';
+import * as tty from 'tty';
+
+function toArray(val) {
+  if (Array.isArray(val)) {
+    return val;
+  }
+  return val !== void 0 ? [val] : [];
+}
+function formatLineColumns(lines, linePrefix = "") {
+  const maxLengh = [];
+  for (const line of lines) {
+    for (const [i, element] of line.entries()) {
+      maxLengh[i] = Math.max(maxLengh[i] || 0, element.length);
+    }
+  }
+  return lines.map(
+    (l) => l.map(
+      (c, i) => linePrefix + c[i === 0 ? "padStart" : "padEnd"](maxLengh[i])
+    ).join("  ")
+  ).join("\n");
+}
+function resolveValue(input) {
+  return typeof input === "function" ? input() : input;
+}
+class CLIError extends Error {
+  constructor(message, code) {
+    super(message);
+    this.code = code;
+    this.name = "CLIError";
+  }
+}
+
+function toArr(any) {
+  return any == void 0 ? [] : Array.isArray(any) ? any : [any];
+}
+function toVal(out, key, val, opts) {
+  let x;
+  const old = out[key];
+  const nxt = ~opts.string.indexOf(key) ? val == void 0 || val === true ? "" : String(val) : typeof val === "boolean" ? val : ~opts.boolean.indexOf(key) ? val === "false" ? false : val === "true" || (out._.push((x = +val, x * 0 === 0) ? x : val), !!val) : (x = +val, x * 0 === 0) ? x : val;
+  out[key] = old == void 0 ? nxt : Array.isArray(old) ? old.concat(nxt) : [old, nxt];
+}
+function parseRawArgs(args = [], opts = {}) {
+  let k;
+  let arr;
+  let arg;
+  let name;
+  let val;
+  const out = { _: [] };
+  let i = 0;
+  let j = 0;
+  let idx = 0;
+  const len = args.length;
+  const alibi = opts.alias !== void 0;
+  const strict = opts.unknown !== void 0;
+  const defaults = opts.default !== void 0;
+  opts.alias = opts.alias || {};
+  opts.string = toArr(opts.string);
+  opts.boolean = toArr(opts.boolean);
+  if (alibi) {
+    for (k in opts.alias) {
+      arr = opts.alias[k] = toArr(opts.alias[k]);
+      for (i = 0; i < arr.length; i++) {
+        (opts.alias[arr[i]] = arr.concat(k)).splice(i, 1);
+      }
+    }
+  }
+  for (i = opts.boolean.length; i-- > 0; ) {
+    arr = opts.alias[opts.boolean[i]] || [];
+    for (j = arr.length; j-- > 0; ) {
+      opts.boolean.push(arr[j]);
+    }
+  }
+  for (i = opts.string.length; i-- > 0; ) {
+    arr = opts.alias[opts.string[i]] || [];
+    for (j = arr.length; j-- > 0; ) {
+      opts.string.push(arr[j]);
+    }
+  }
+  if (defaults) {
+    for (k in opts.default) {
+      name = typeof opts.default[k];
+      arr = opts.alias[k] = opts.alias[k] || [];
+      if (opts[name] !== void 0) {
+        opts[name].push(k);
+        for (i = 0; i < arr.length; i++) {
+          opts[name].push(arr[i]);
+        }
+      }
+    }
+  }
+  const keys = strict ? Object.keys(opts.alias) : [];
+  for (i = 0; i < len; i++) {
+    arg = args[i];
+    if (arg === "--") {
+      out._ = out._.concat(args.slice(++i));
+      break;
+    }
+    for (j = 0; j < arg.length; j++) {
+      if (arg.charCodeAt(j) !== 45) {
+        break;
+      }
+    }
+    if (j === 0) {
+      out._.push(arg);
+    } else if (arg.substring(j, j + 3) === "no-") {
+      name = arg.slice(Math.max(0, j + 3));
+      if (strict && !~keys.indexOf(name)) {
+        return opts.unknown(arg);
+      }
+      out[name] = false;
+    } else {
+      for (idx = j + 1; idx < arg.length; idx++) {
+        if (arg.charCodeAt(idx) === 61) {
+          break;
+        }
+      }
+      name = arg.substring(j, idx);
+      val = arg.slice(Math.max(0, ++idx)) || i + 1 === len || ("" + args[i + 1]).charCodeAt(0) === 45 || args[++i];
+      arr = j === 2 ? [name] : name;
+      for (idx = 0; idx < arr.length; idx++) {
+        name = arr[idx];
+        if (strict && !~keys.indexOf(name)) {
+          return opts.unknown("-".repeat(j) + name);
+        }
+        toVal(out, name, idx + 1 < arr.length || val, opts);
+      }
+    }
+  }
+  if (defaults) {
+    for (k in opts.default) {
+      if (out[k] === void 0) {
+        out[k] = opts.default[k];
+      }
+    }
+  }
+  if (alibi) {
+    for (k in out) {
+      arr = opts.alias[k] || [];
+      while (arr.length > 0) {
+        out[arr.shift()] = out[k];
+      }
+    }
+  }
+  return out;
+}
+
+function parseArgs(rawArgs, argsDef) {
+  const parseOptions = {
+    boolean: [],
+    string: [],
+    alias: {},
+    default: {}
+  };
+  const args = resolveArgs(argsDef);
+  for (const arg of args) {
+    if (arg.type === "positional") {
+      continue;
+    }
+    parseOptions[arg.type || "boolean"].push(arg.name);
+    if (arg.default !== void 0) {
+      parseOptions.default[arg.name] = arg.default;
+    }
+    if (arg.alias) {
+      parseOptions.alias[arg.name] = arg.alias;
+    }
+  }
+  const parsed = parseRawArgs(rawArgs, parseOptions);
+  const [, ...positionalArguments] = parsed._;
+  const parsedArgsProxy = new Proxy(parsed, {
+    get(target, prop) {
+      return target[prop] ?? target[camelCase(prop)] ?? target[kebabCase(prop)];
+    }
+  });
+  for (const [, arg] of args.entries()) {
+    if (arg.type === "positional") {
+      const nextPositionalArgument = positionalArguments.shift();
+      if (nextPositionalArgument !== void 0) {
+        parsedArgsProxy[arg.name] = nextPositionalArgument;
+      } else if (arg.default !== void 0) {
+        parsedArgsProxy[arg.name] = arg.default;
+      } else {
+        throw new CLIError(
+          `Missing required positional argument: ${arg.name.toUpperCase()}`,
+          "EARG"
+        );
+      }
+    } else if (arg.required && parsedArgsProxy[arg.name] === void 0) {
+      throw new CLIError(`Missing required argument: --${arg.name}`, "EARG");
+    }
+  }
+  return parsedArgsProxy;
+}
+function resolveArgs(argsDef) {
+  const args = [];
+  for (const [name, argDef] of Object.entries(argsDef || {})) {
+    args.push({
+      ...argDef,
+      name,
+      alias: toArray(argDef.alias)
+    });
+  }
+  return args;
+}
+
+function defineCommand(def) {
+  return def;
+}
+async function runCommand(cmd, opts) {
+  const cmdArgs = await resolveValue(cmd.args || {});
+  const parsedArgs = parseArgs(opts.rawArgs, cmdArgs);
+  const context = {
+    rawArgs: opts.rawArgs,
+    args: parsedArgs,
+    cmd
+  };
+  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(
+        `Missing sub command. Use --help to see available sub commands.`,
+        "ESUBCOMMAND"
+      );
+    }
+    if (!subCommands[subCommandName]) {
+      throw new CLIError(
+        `Unknown sub command: ${subCommandName}`,
+        "ESUBCOMMAND"
+      );
+    }
+    const subCommand = await resolveValue(subCommands[subCommandName]);
+    if (subCommand) {
+      await runCommand(subCommand, {
+        rawArgs: opts.rawArgs.slice(subCommandArgIndex)
+      });
+    }
+  }
+  if (typeof cmd.run === "function") {
+    await cmd.run(context);
+  }
+}
+async function resolveSubCommand(cmd, rawArgs, parent) {
+  const subCommands = await resolveValue(cmd.subCommands);
+  if (subCommands && Object.keys(subCommands).length > 0) {
+    const subCommandArgIndex = rawArgs.findIndex((arg) => !arg.startsWith("-"));
+    const subCommandName = rawArgs[subCommandArgIndex];
+    const subCommand = await resolveValue(subCommands[subCommandName]);
+    if (subCommand) {
+      return resolveSubCommand(
+        subCommand,
+        rawArgs.slice(subCommandArgIndex),
+        cmd
+      );
+    }
+  }
+  return [cmd, parent];
+}
+
+async function showUsage(cmd, parent) {
+  try {
+    console.log(await renderUsage(cmd, parent) + "\n");
+  } catch (error) {
+    console.error(error);
+  }
+}
+async function renderUsage(cmd, parent) {
+  const cmdMeta = await resolveValue(cmd.meta || {});
+  const cmdArgs = resolveArgs(await resolveValue(cmd.args || {}));
+  const parentMeta = await resolveValue(parent?.meta || {});
+  const commandName = `${parentMeta.name ? `${parentMeta.name} ` : ""}` + (cmdMeta.name || process.argv[1]);
+  const argLines = [];
+  const posLines = [];
+  const commandsLines = [];
+  const usageLine = [];
+  for (const arg of cmdArgs) {
+    if (arg.type === "positional") {
+      const name = arg.name.toUpperCase();
+      const isRequired = arg.required !== false && arg.default === void 0;
+      const usageHint = arg.default ? `="${arg.default}"` : "";
+      posLines.push([name + usageHint, arg.description || ""]);
+      usageLine.push(isRequired ? `<${name}>` : `[${name}]`);
+    } else {
+      const isRequired = arg.required === true && arg.default === void 0;
+      const argStr = (arg.type === "boolean" && arg.default === true ? [
+        ...(arg.alias || []).map((a) => `--no-${a}`),
+        `--no-${arg.name}`
+      ].join(", ") : [...(arg.alias || []).map((a) => `-${a}`), `--${arg.name}`].join(
+        ", "
+      )) + (arg.type === "string" && (arg.valueHint || arg.default) ? `=${arg.valueHint ? `<${arg.valueHint}>` : `"${arg.default || ""}"`}` : "");
+      argLines.push([
+        argStr + (isRequired ? " (required)" : ""),
+        arg.description || ""
+      ]);
+      if (isRequired) {
+        usageLine.push(argStr);
+      }
+    }
+  }
+  if (cmd.subCommands) {
+    const commandNames = [];
+    for (const [name, sub] of Object.entries(cmd.subCommands)) {
+      commandsLines.push([name, sub.meta?.description || ""]);
+      commandNames.push(name);
+    }
+    usageLine.push(commandNames.join("|"));
+  }
+  const usageLines = [];
+  const version = cmdMeta.version || parentMeta.version;
+  usageLines.push(
+    commandName + (version ? ` v${version}` : ""),
+    cmdMeta.description,
+    ""
+  );
+  const hasOptions = argLines.length > 0 || posLines.length > 0;
+  usageLines.push(
+    `USAGE: ${commandName}${hasOptions ? " [OPTIONS]" : ""} ${usageLine.join(
+      " "
+    )}`,
+    ""
+  );
+  if (posLines.length > 0) {
+    usageLines.push("ARGUMENTS:", "");
+    usageLines.push(formatLineColumns(posLines, "  "));
+    usageLines.push("");
+  }
+  if (argLines.length > 0) {
+    usageLines.push("OPTIONS:", "");
+    usageLines.push(formatLineColumns(argLines, "  "));
+    usageLines.push("");
+  }
+  if (commandsLines.length > 0) {
+    usageLines.push("COMMANDS:", "");
+    usageLines.push(formatLineColumns(commandsLines, "  "));
+    usageLines.push(
+      "",
+      `Use \`${commandName} <command> --help\` for more information about a command.`
+    );
+  }
+  return usageLines.filter((l) => typeof l === "string").join("\n");
+}
+
+const {
+  env = {},
+  argv = [],
+  platform = "",
+} = typeof process === "undefined" ? {} : process;
+
+const isDisabled = "NO_COLOR" in env || argv.includes("--no-color");
+const isForced = "FORCE_COLOR" in env || argv.includes("--color");
+const isWindows = platform === "win32";
+const isDumbTerminal = env.TERM === "dumb";
+
+const isCompatibleTerminal =
+  tty && tty.isatty && tty.isatty(1) && env.TERM && !isDumbTerminal;
+
+const isCI =
+  "CI" in env &&
+  ("GITHUB_ACTIONS" in env || "GITLAB_CI" in env || "CIRCLECI" in env);
+
+const isColorSupported =
+  !isDisabled &&
+  (isForced || (isWindows && !isDumbTerminal) || isCompatibleTerminal || isCI);
+
+const replaceClose = (
+  index,
+  string,
+  close,
+  replace,
+  head = string.substring(0, index) + replace,
+  tail = string.substring(index + close.length),
+  next = tail.indexOf(close)
+) => head + (next < 0 ? tail : replaceClose(next, tail, close, replace));
+
+const clearBleed = (index, string, open, close, replace) =>
+  index < 0
+    ? open + string + close
+    : open + replaceClose(index, string, close, replace) + close;
+
+const filterEmpty =
+  (open, close, replace = open, at = open.length + 1) =>
+  (string) =>
+    string || !(string === "" || string === undefined)
+      ? clearBleed(
+          ("" + string).indexOf(close, at),
+          string,
+          open,
+          close,
+          replace
+        )
+      : "";
+
+const init = (open, close, replace) =>
+  filterEmpty(`\x1b[${open}m`, `\x1b[${close}m`, replace);
+
+const colors = {
+  reset: init(0, 0),
+  bold: init(1, 22, "\x1b[22m\x1b[1m"),
+  dim: init(2, 22, "\x1b[22m\x1b[2m"),
+  italic: init(3, 23),
+  underline: init(4, 24),
+  inverse: init(7, 27),
+  hidden: init(8, 28),
+  strikethrough: init(9, 29),
+  black: init(30, 39),
+  red: init(31, 39),
+  green: init(32, 39),
+  yellow: init(33, 39),
+  blue: init(34, 39),
+  magenta: init(35, 39),
+  cyan: init(36, 39),
+  white: init(37, 39),
+  gray: init(90, 39),
+  bgBlack: init(40, 49),
+  bgRed: init(41, 49),
+  bgGreen: init(42, 49),
+  bgYellow: init(43, 49),
+  bgBlue: init(44, 49),
+  bgMagenta: init(45, 49),
+  bgCyan: init(46, 49),
+  bgWhite: init(47, 49),
+  blackBright: init(90, 39),
+  redBright: init(91, 39),
+  greenBright: init(92, 39),
+  yellowBright: init(93, 39),
+  blueBright: init(94, 39),
+  magentaBright: init(95, 39),
+  cyanBright: init(96, 39),
+  whiteBright: init(97, 39),
+  bgBlackBright: init(100, 49),
+  bgRedBright: init(101, 49),
+  bgGreenBright: init(102, 49),
+  bgYellowBright: init(103, 49),
+  bgBlueBright: init(104, 49),
+  bgMagentaBright: init(105, 49),
+  bgCyanBright: init(106, 49),
+  bgWhiteBright: init(107, 49),
+};
+
+const createColors = ({ useColor = isColorSupported } = {}) =>
+  useColor
+    ? colors
+    : Object.keys(colors).reduce(
+        (colors, key) => ({ ...colors, [key]: String }),
+        {}
+      );
+
+const {
+  reset,
+  bold,
+  dim,
+  italic,
+  underline,
+  inverse,
+  hidden,
+  strikethrough,
+  black,
+  red,
+  green,
+  yellow,
+  blue,
+  magenta,
+  cyan,
+  white,
+  gray,
+  bgBlack,
+  bgRed,
+  bgGreen,
+  bgYellow,
+  bgBlue,
+  bgMagenta,
+  bgCyan,
+  bgWhite,
+  blackBright,
+  redBright,
+  greenBright,
+  yellowBright,
+  blueBright,
+  magentaBright,
+  cyanBright,
+  whiteBright,
+  bgBlackBright,
+  bgRedBright,
+  bgGreenBright,
+  bgYellowBright,
+  bgBlueBright,
+  bgMagentaBright,
+  bgCyanBright,
+  bgWhiteBright,
+} = createColors();
+
+async function runMain(cmd, opts = {}) {
+  const rawArgs = opts.rawArgs || process.argv.slice(2);
+  try {
+    if (rawArgs.includes("--help") || rawArgs.includes("-h")) {
+      await showUsage(...await resolveSubCommand(cmd, rawArgs));
+      process.exit(0);
+    } else {
+      await runCommand(cmd, { rawArgs });
+    }
+  } catch (error) {
+    const isCLIError = error instanceof CLIError;
+    if (!isCLIError) {
+      console.error(error, "\n");
+    }
+    console.error(
+      `
+${bgRed(` ${error.code || error.name} `)} ${error.message}
+`
+    );
+    if (isCLIError) {
+      await showUsage(...await resolveSubCommand(cmd, rawArgs));
+    }
+    process.exit(1);
+  }
+}
+
+export { defineCommand, parseArgs, renderUsage, runCommand, runMain, showUsage };

package/package.json

@@ -1,5 +1,49 @@
 {
- "name": "citty",
- "version": "0.0.0",
- "license": "MIT"
+  "name": "citty",
+  "version": "0.0.2",
+  "description": "Elegant CLI Builder",
+  "repository": "unjs/citty",
+  "license": "MIT",
+  "sideEffects": false,
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "unbuild",
+    "dev": "vitest dev",
+    "lint": "eslint --cache --ext .ts,.js,.mjs,.cjs . && prettier -c src test",
+    "lint:fix": "eslint --cache --ext .ts,.js,.mjs,.cjs . --fix && prettier -c src test -w",
+    "prepack": "pnpm run build",
+    "play": "jiti ./playground/cli.ts",
+    "release": "pnpm test && changelogen --release --push && npm publish",
+    "test": "pnpm lint && vitest run --coverage"
+  },
+  "dependencies": {
+    "scule": "^1.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^18.15.10",
+    "@vitest/coverage-c8": "^0.29.8",
+    "changelogen": "^0.5.2",
+    "colorette": "^2.0.19",
+    "eslint": "^8.36.0",
+    "eslint-config-unjs": "^0.1.0",
+    "jiti": "^1.18.2",
+    "prettier": "^2.8.7",
+    "typescript": "^5.0.2",
+    "unbuild": "^1.1.2",
+    "vitest": "^0.29.8"
+  },
+  "packageManager": "pnpm@8.0.0"
 }