@jpillora/take 0.8.1 → 0.8.5

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@jpillora/take",
-  "version": "0.8.1",
+  "version": "0.8.5",
   "description": "A minimal CLI library for building TypeScript-based command-line tools",
   "type": "module",
-  "main": "./take.ts",
-  "exports": "./take.ts",
-  "files": ["take.ts"],
+  "main": "./take.mjs",
+  "exports": "./take.mjs",
+  "files": ["take.mjs"],
   "license": "MIT",
   "repository": {
     "type": "git",

package/take.mjs

@@ -0,0 +1,408 @@
+"use strict";
+// Take is a mini-CLI library for building typescript-based command-line tools
+// Works with Deno, Node.js (with type stripping), and Bun
+// deno-lint-ignore-file no-explicit-any
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.timer = void 0;
+exports.newFlags = newFlags;
+exports.help = help;
+exports.spawn = spawn;
+exports.Register = Register;
+exports.Command = Command;
+const promises_1 = require("node:fs/promises");
+const node_path_1 = require("node:path");
+const node_child_process_1 = require("node:child_process");
+const node_process_1 = __importDefault(require("node:process"));
+function newFlags(flags) {
+    return flags;
+}
+function help(str) {
+    throw str;
+}
+const exit = (...args) => {
+    console.log(...args);
+    node_process_1.default.exit(1);
+};
+function namedFlags(record) {
+    return Object.entries(record).map((kv) => ({
+        name: kv[0],
+        ...kv[1],
+    })).toSorted((na, nb) => na.name < nb.name ? -1 : 1);
+}
+function convert(val, type) {
+    switch (type) {
+        case "string":
+            return `${val}`;
+        case "number": {
+            const f = parseFloat(val);
+            if (isNaN(f)) {
+                throw `expected a number, got: ${val}`;
+            }
+            return f;
+        }
+        case "boolean":
+            return Boolean(val);
+        default:
+            throw `unknown type: ${type}`;
+    }
+}
+async function spawn(options) {
+    return await new Promise((resolve, reject) => {
+        const child = (0, node_child_process_1.spawn)(options.program, options.args ?? [], options);
+        child.on("close", (code) => {
+            if (code === 0) {
+                resolve(0);
+            }
+            else {
+                reject(code);
+            }
+        });
+    });
+}
+// helper for measuring time
+exports.timer = (() => {
+    const scale = [
+        [1000, "ms"],
+        [60, "sec"],
+        [60, "min"],
+        [24, "hr"],
+    ];
+    const fmt = (v) => {
+        for (const s of scale) {
+            const n = s[0], u = s[1];
+            if (v < n) {
+                return `${v.toFixed(2)}${u}${v == 1 || u.endsWith("s") ? "" : "s"}`;
+            }
+            v /= n;
+        }
+        throw `??`;
+    };
+    return () => {
+        const t0 = performance.now();
+        const stop = () => {
+            const t1 = performance.now();
+            return fmt(t1 - t0);
+        };
+        stop.toString = stop; // 🧙‍♂️you may omit the brackets
+        return stop;
+    };
+})();
+// Load .env file if it exists
+async function loadEnvFile(path) {
+    try {
+        const content = await (0, promises_1.readFile)(path, "utf-8");
+        for (const line of content.split("\n")) {
+            const trimmed = line.trim();
+            if (!trimmed || trimmed.startsWith("#"))
+                continue;
+            const match = trimmed.match(/^([^=]+)=(.*)$/);
+            if (match) {
+                const key = match[1].trim();
+                let value = match[2].trim();
+                // Remove quotes if present
+                if ((value.startsWith('"') && value.endsWith('"')) ||
+                    (value.startsWith("'") && value.endsWith("'"))) {
+                    value = value.slice(1, -1);
+                }
+                node_process_1.default.env[key] = value;
+            }
+        }
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function Register(...commands) {
+    // Load .env by default
+    await loadEnvFile(".env");
+    // Get script name from argv[1]
+    const scriptName = (0, node_path_1.basename)(node_process_1.default.argv[1] || "cli");
+    // validate commands
+    if (!Array.isArray(commands)) {
+        exit(`CLI(commands) must be an array`);
+    }
+    if (commands.length === 0) {
+        exit(`CLI(commands) must have at least 1 command`);
+    }
+    const names = new Set();
+    for (const c of commands) {
+        // validate name
+        if (typeof c.name !== "string") {
+            exit(`all CLI(commands) must have a "name"`);
+        }
+        // transform name
+        // list out "sub-command" names
+        c.names = c.name.trim().split(/\s+/g);
+        c.name = c.names.join(" "); // tidy name
+        // duplicate check
+        if (names.has(c.name)) {
+            exit(`duplicate command name: ${c.name}`);
+        }
+        names.add(c.name);
+        // validate function
+        if (typeof c.run !== "function") {
+            exit(`command "${c.name}" must have a "run" function`);
+        }
+        // validate flags
+        if (!c.flags) {
+            exit(`command "${c.name}" must have "flags", you can use {}`);
+        }
+        if (Array.isArray(c.flags)) {
+            exit(`command "${c.name}" flags must be an object, not an array`);
+        }
+        for (const [name, flag] of Object.entries(c.flags)) {
+            if (!flag.description) {
+                exit(`command "${c.name}" flag "${name}" must have a "description"`);
+            }
+        }
+    }
+    commands.sort((a, b) => (a.name < b.name ? -1 : 1));
+    const joinColumns = (table) => {
+        const max = table.reduce((m, { left }) => Math.max(m, left.length), 0);
+        return table
+            .map((item) => {
+            if (!item.right)
+                return item.left;
+            const pad = " ".repeat(max - item.left.length);
+            return `${item.left}${pad} ${item.right}`;
+        })
+            .join("\n");
+    };
+    // recursive help text builder for the command tree
+    function help(msg) {
+        // build command list
+        const content = joinColumns(commands.filter((cmd) => {
+            return cmd.name !== "debug" || node_process_1.default.env.DEBUG === "1";
+        }).map((cmd) => ({
+            left: ` • ${cmd.name}`,
+            right: cmd.description ? `- ${cmd.description}` : "",
+        })));
+        // print result
+        console.log(`\n${scriptName} <command> --help\n\n` + "commands:\n" + content + "\n");
+        if (msg) {
+            console.log("ERROR:", msg);
+            console.log("");
+        }
+        node_process_1.default.exit(msg ? 1 : 0);
+    }
+    // help text builder for a given command
+    function helpFor(cmd, flagSpecs, msg) {
+        // build flag help
+        const shorts = new Set();
+        const short = (name) => {
+            const l = name[0];
+            if (shorts.has(l))
+                return "";
+            shorts.add(l);
+            return `, -${l}`;
+        };
+        const extras = (flag) => {
+            const { env, initial } = flag;
+            const out = [];
+            if (env)
+                out.push(`env=${env}`);
+            if (initial)
+                out.push(`default=${initial}`);
+            return out.length ? ` (${out.join(" ")})` : "";
+        };
+        const content = joinColumns(flagSpecs.map((flag) => ({
+            left: ` --${flag.name}${short(flag.name)}${typeof flag.initial === "boolean" ? "" : ` <${typeof flag.initial}>`}`,
+            right: ` ${flag.description || ""}${extras(flag)}`,
+        })));
+        // print result
+        console.log(`\n${scriptName} ` +
+            cmd.name +
+            " <flags>\n\n" +
+            "description:\n" +
+            cmd.description +
+            (cmd.help ? ("\n\nhelp:\n" + cmd.help) : "") +
+            "\n\n" +
+            "flags:\n" +
+            content +
+            "\n");
+        if (msg) {
+            console.log("ERROR:", msg);
+            console.log("");
+        }
+        node_process_1.default.exit(0);
+    }
+    // run 1 command from the command tree.
+    // this function can be called from other commands
+    async function cmd(...args) {
+        if (args.length === 0) {
+            help();
+        }
+        // stage 1, find command, split args into names/rest
+        let match = null;
+        let rest = [];
+        let names = null;
+        for (let i = args.length - 1; i >= 0; i--) {
+            names = args.slice(0, i + 1);
+            rest = args.slice(i + 1);
+            const name = names.join(" ");
+            match = commands.find((c) => c.name === name);
+            if (match) {
+                break;
+            }
+        }
+        if (!match) {
+            return help(`no matched command: ${args.join(" ")}`);
+        }
+        // convert command flags into a list
+        const flagSpecs = namedFlags(match.flags);
+        // always add --help
+        flagSpecs.push({
+            name: "help",
+            initial: false,
+            description: "show help",
+        });
+        // stage 2, init flags, parse rest of args
+        const cmdHelp = helpFor.bind(null, match, flagSpecs);
+        let nextFlag = null;
+        // traverse rest arguments, sorting into either flags or cmd-args
+        const flagVals = {};
+        const cmdArgs = [];
+        for (const arg of rest) {
+            // arg is flag-value
+            if (nextFlag) {
+                flagVals[nextFlag.name] = convert(arg, typeof nextFlag.initial);
+                nextFlag = null;
+                continue;
+            }
+            // arg is command-flag
+            const m = /^-(-?)(\S+)$/.exec(arg);
+            if (m) {
+                const long = Boolean(m[1]);
+                const name = m[2];
+                const fs = flagSpecs.find((f) => {
+                    if (!long) {
+                        const letters = name.split("");
+                        return letters.includes(f.name[0]);
+                    }
+                    return f.name === name;
+                });
+                if (!fs) {
+                    return cmdHelp(`unknown flag "${name}"`);
+                }
+                if (typeof fs.initial === "boolean") {
+                    flagVals[fs.name] = true;
+                }
+                else {
+                    nextFlag = fs; // collect String/Number flags
+                }
+                continue;
+            }
+            // arg is command-arg
+            cmdArgs.push(arg);
+            continue;
+        }
+        // missing flag value
+        if (nextFlag) {
+            cmdHelp(`missing value for flag: ${nextFlag.name}`);
+        }
+        // help requested
+        if (flagVals.help) {
+            cmdHelp();
+        }
+        // set default values
+        for (const flag of flagSpecs) {
+            const { name, env, initial } = flag;
+            if (name in flagVals) {
+                continue;
+            }
+            if (env && node_process_1.default.env[env]) {
+                flagVals[name] = convert(node_process_1.default.env[env], typeof initial);
+                continue;
+            }
+            if (initial !== undefined) {
+                flagVals[name] = initial;
+            }
+        }
+        // exec targets 'run' function
+        const t = (0, exports.timer)();
+        try {
+            await match.run({
+                flags: flagVals,
+                args: cmdArgs,
+                cmd,
+                cmdName: match.name,
+                help: cmdHelp,
+            });
+        }
+        catch (err) {
+            if (typeof err === "string") {
+                cmdHelp(err);
+            }
+            throw err;
+        }
+        console.log(`${scriptName} "${match.name}" ran in ${t}`);
+    }
+    // "root" command
+    // process.argv: [node, script, ...args]
+    const args = node_process_1.default.argv.slice(2);
+    // help intercept
+    if (args.length === 0 || args[0] === "-h" || args[0] === "--help") {
+        help();
+    }
+    // normal command execution
+    try {
+        await cmd(...args);
+    }
+    catch (err) {
+        if (typeof err === "string") {
+            help(err);
+        }
+        // parse and display error
+        const eo = err;
+        if (eo && typeof eo === "object") {
+            // handle command output
+            if (typeof eo.code === "number") {
+                node_process_1.default.exit(eo.code);
+            }
+            // handle js error
+            const msg = err ? eo.stack || eo.message : `${err}`;
+            if (/exit with (\d+)/.test(msg)) {
+                node_process_1.default.exit(parseInt(RegExp.$1, 10));
+            }
+            console.log("ERROR: " + msg + "\n");
+        }
+        // caught error -> exit 1
+        node_process_1.default.exit(1);
+    }
+}
+function Command(command) {
+    return { ...command, flagValues: null, input: null };
+}
+// deno-lint-ignore no-constant-condition
+if (42 < 7) {
+    // TYPE CHECK
+    Register(Command({
+        name: "foo",
+        description: "...",
+        flags: {
+            zip: {
+                initial: 42,
+                description: "this is a test",
+            },
+        },
+        run(input) {
+            input.flags.zip; // (property) zip: number
+        },
+    }), Command({
+        name: "bar",
+        description: "test command",
+        flags: {
+            zop: {
+                initial: "hello",
+                description: "string flag",
+            },
+        },
+        run(input) {
+            console.log("zop:", input.flags.zop); // (property) zop: string
+        },
+    }));
+}

package/README.md

@@ -1,318 +0,0 @@
-# take
-
-A minimal CLI library for building TypeScript-based command-line tools. Works with Deno, Node.js (with type stripping), and Bun.
-
-## Installation
-
-```bash
-deno add jsr:@jpillora/take
-```
-
-## Quick Start
-
-1. Write file `dev.ts`
-
-    ```typescript
-    #!/usr/bin/env -S deno run --allow-env
-    // or execute with bun, or with node
-
-    import { Command, Register } from "@jpillora/take";
-
-    Register(
-      Command({
-        name: "greet",
-        description: "Say hello",
-        flags: {},
-        run() {
-          console.log("Hello, world!");
-        },
-      })
-    );
-    ```
-
-2. Make it executable  `chmod +x dev.ts`
-
-3. Run it:
-
-    ```
-    ./dev.ts --help
-
-    dev.ts <command> --help
-
-    commands:
-     • greet - Say hello
-
-    ./dev.ts greet
-    Hello, world!
-    ```
-
-## Examples
-
-### String Flag
-
-```typescript
-Command({
-  name: "greet",
-  description: "Greet someone by name",
-  flags: {
-    name: {
-      initial: "world",
-      description: "Name to greet",
-    },
-  },
-  run({ flags }) {
-    // typescript infers flag types from initial:
-    //   (property) name: string
-    console.log(`Hello, ${flags.name}!`);
-  },
-});
-```
-
-```bash
-$ ./dev.ts greet --name Alice
-Hello, Alice!
-```
-
-### Number Flag
-
-```typescript
-Command({
-  name: "repeat",
-  description: "Repeat a message N times",
-  flags: {
-    count: {
-      initial: 3,
-      description: "Number of repetitions",
-    },
-  },
-  run({ flags }) {
-    for (let i = 0; i < flags.count; i++) {
-      console.log("Hello!");
-    }
-  },
-});
-```
-
-```bash
-$ ./dev.ts repeat --count 5
-```
-
-### Boolean Flag
-
-```typescript
-Command({
-  name: "build",
-  description: "Build the project",
-  flags: {
-    minify: {
-      initial: false,
-      description: "Minify the output",
-    },
-  },
-  run({ flags }) {
-    if (flags.minify) {
-      console.log("Building with minification...");
-    } else {
-      console.log("Building...");
-    }
-  },
-});
-```
-
-```bash
-$ ./dev.ts build --minify
-```
-
-### Environment Variable Fallback
-
-Flags can read from environment variables when not provided on the command line.
-
-```typescript
-Command({
-  name: "deploy",
-  description: "Deploy the application",
-  flags: {
-    token: {
-      initial: "",
-      description: "API token",
-      env: "DEPLOY_TOKEN",
-    },
-  },
-  run({ flags }) {
-    if (!flags.token) {
-      throw "token is required";
-    }
-    console.log("Deploying with token...");
-  },
-});
-```
-
-```bash
-$ DEPLOY_TOKEN=secret ./dev.ts deploy
-# or
-$ ./dev.ts deploy --token secret
-```
-
-### Additional Help Text
-
-```typescript
-Command({
-  name: "migrate",
-  description: "Run database migrations",
-  help: `
-This command runs pending database migrations.
-Make sure your DATABASE_URL is set correctly.
-
-Examples:
-  ./dev.ts migrate --dry-run
-  ./dev.ts migrate --target 5`,
-  flags: {
-    dryRun: {
-      initial: false,
-      description: "Preview changes without applying",
-    },
-    target: {
-      initial: 0,
-      description: "Target migration version (0 = latest)",
-    },
-  },
-  run({ flags }) {
-    // migration logic
-  },
-});
-```
-
-### Positional Arguments
-
-Non-flag arguments are available in `args`.
-
-```typescript
-Command({
-  name: "copy",
-  description: "Copy files to destination",
-  flags: {},
-  run({ args }) {
-    const [source, dest] = args;
-    if (!source || !dest) {
-      throw "usage: copy <source> <dest>";
-    }
-    console.log(`Copying ${source} to ${dest}`);
-  },
-});
-```
-
-```bash
-$ ./dev.ts copy file.txt backup/
-```
-
-### Subcommands
-
-Use spaces in the name to create nested commands.
-
-```typescript
-await Register(
-  Command({
-    name: "db migrate",
-    description: "Run database migrations",
-    flags: {},
-    run() {
-      console.log("Running migrations...");
-    },
-  }),
-  Command({
-    name: "db seed",
-    description: "Seed the database",
-    flags: {},
-    run() {
-      console.log("Seeding database...");
-    },
-  })
-);
-```
-
-```bash
-$ ./dev.ts db migrate
-$ ./dev.ts db seed
-```
-
-### Calling Other Commands
-
-Use `cmd` to invoke other registered commands programmatically.
-
-```typescript
-Command({
-  name: "all",
-  description: "Run build, test, and deploy",
-  flags: {},
-  async run({ cmd }) {
-    await cmd("build", "--minify");
-    await cmd("test");
-    await cmd("deploy");
-  },
-});
-```
-
-### Show Help Programmatically
-
-```typescript
-Command({
-  name: "process",
-  description: "Process input files",
-  flags: {},
-  run({ args, help }) {
-    if (args.length === 0) {
-      help("no input files provided");
-    }
-    // process files...
-  },
-});
-```
-
-### Timer Utility
-
-Measure execution time with the built-in timer.
-
-```typescript
-import { Command, Register, timer } from "@jpillora/take";
-
-Command({
-  name: "slow",
-  description: "A slow operation",
-  flags: {},
-  run() {
-    const t = timer();
-    // ... do work ...
-    console.log(`Completed in ${t}`); // "Completed in 1.23sec"
-  },
-});
-```
-
-### Spawn Utility
-
-Run external commands with a Promise-based wrapper.
-
-```typescript
-import { Command, Register, spawn } from "@jpillora/take";
-
-Command({
-  name: "lint",
-  description: "Run the linter",
-  flags: {
-    fix: {
-      initial: false,
-      description: "Auto-fix issues",
-    },
-  },
-  async run({ flags }) {
-    await spawn({
-      program: "deno",
-      args: flags.fix ? ["lint", "--fix"] : ["lint"],
-      stdio: "inherit",
-    });
-  },
-});
-```
-
-## License
-
-MIT

package/take.ts

@@ -1,472 +0,0 @@
-// Take is a mini-CLI library for building typescript-based command-line tools
-// Works with Deno, Node.js (with type stripping), and Bun
-// deno-lint-ignore-file no-explicit-any
-
-import { readFile } from "node:fs/promises";
-import { basename } from "node:path";
-import {
-  spawn as nodeSpawn,
-  SpawnOptions as nodeSpawnOptions,
-} from "node:child_process";
-import process from "node:process";
-
-export type Flag = {
-  initial: number | string | boolean | Date;
-  description: string;
-  env?: string;
-};
-
-type Flags = Record<string, Flag>;
-
-export type FlagValues<T extends Flags> = {
-  [P in keyof T]: T[P]["initial"] extends number ? number
-    : T[P]["initial"] extends string ? string
-    : T[P]["initial"] extends boolean ? boolean
-    : T[P]["initial"] extends Date ? Date
-    : never;
-};
-
-export type TakeCommand<F extends Flags = Flags> = {
-  name: string;
-  names?: string[];
-  description: string;
-  help?: string;
-  flags: F;
-  run: (input: CommandInput<F>) => void | Promise<void>;
-};
-
-export function newFlags<F extends Flags>(flags: F): F {
-  return flags;
-}
-
-export type NewCommand<F extends Flags = Flags> = TakeCommand<F> & {
-  // always null, but can be type-referenced
-  flagValues: FlagValues<F>;
-  input: CommandInput<F>;
-};
-
-export type CommandInput<F extends Flags> = {
-  flags: FlagValues<F>;
-  args: string[];
-  cmd: (...args: string[]) => Promise<void>;
-  cmdName: string;
-  help: (msg?: string) => void;
-};
-
-export function help(str: string) {
-  throw str;
-}
-
-const exit = (...args: any[]) => {
-  console.log(...args);
-  process.exit(1);
-};
-
-type namedFlag = { name: string } & Flag;
-
-type namedFlags = namedFlag[];
-
-function namedFlags(record: Flags): namedFlags {
-  return Object.entries(record).map((kv) => ({
-    name: kv[0],
-    ...kv[1],
-  })).toSorted(
-    (na, nb) => na.name < nb.name ? -1 : 1,
-  );
-}
-
-function convert(val: any, type: string) {
-  switch (type) {
-    case "string":
-      return `${val}`;
-    case "number": {
-      const f = parseFloat(val);
-      if (isNaN(f)) {
-        throw `expected a number, got: ${val}`;
-      }
-      return f;
-    }
-    case "boolean":
-      return Boolean(val);
-    default:
-      throw `unknown type: ${type}`;
-  }
-}
-
-// helper async node spawn
-export type SpawnOptions =
-  & { program: string; args?: string[] }
-  & nodeSpawnOptions;
-
-export async function spawn(options: SpawnOptions): Promise<number> {
-  return await new Promise<number>((resolve, reject) => {
-    const child = nodeSpawn(options.program, options.args ?? [], options);
-    child.on("close", (code) => {
-      if (code === 0) {
-        resolve(0);
-      } else {
-        reject(code);
-      }
-    });
-  });
-}
-
-// helper for measuring time
-export const timer: () => () => string = (() => {
-  const scale: [n: number, s: string][] = [
-    [1000, "ms"],
-    [60, "sec"],
-    [60, "min"],
-    [24, "hr"],
-  ];
-  const fmt = (v: number) => {
-    for (const s of scale) {
-      const n = s[0], u = s[1];
-      if (v < n) {
-        return `${v.toFixed(2)}${u}${v == 1 || u.endsWith("s") ? "" : "s"}`;
-      }
-      v /= n;
-    }
-    throw `??`;
-  };
-  return () => {
-    const t0 = performance.now();
-    const stop = () => {
-      const t1 = performance.now();
-      return fmt(t1 - t0);
-    };
-    stop.toString = stop; // 🧙‍♂️you may omit the brackets
-    return stop;
-  };
-})();
-
-// Load .env file if it exists
-async function loadEnvFile(path: string): Promise<boolean> {
-  try {
-    const content = await readFile(path, "utf-8");
-    for (const line of content.split("\n")) {
-      const trimmed = line.trim();
-      if (!trimmed || trimmed.startsWith("#")) continue;
-      const match = trimmed.match(/^([^=]+)=(.*)$/);
-      if (match) {
-        const key = match[1].trim();
-        let value = match[2].trim();
-        // Remove quotes if present
-        if (
-          (value.startsWith('"') && value.endsWith('"')) ||
-          (value.startsWith("'") && value.endsWith("'"))
-        ) {
-          value = value.slice(1, -1);
-        }
-        process.env[key] = value;
-      }
-    }
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-export async function Register(...commands: NewCommand<any>[]) {
-  // Load .env by default
-  await loadEnvFile(".env");
-  // Get script name from argv[1]
-  const scriptName = basename(process.argv[1] || "cli");
-  // validate commands
-  if (!Array.isArray(commands)) {
-    exit(`CLI(commands) must be an array`);
-  }
-  if (commands.length === 0) {
-    exit(`CLI(commands) must have at least 1 command`);
-  }
-  const names = new Set();
-  for (const c of commands) {
-    // validate name
-    if (typeof c.name !== "string") {
-      exit(`all CLI(commands) must have a "name"`);
-    }
-    // transform name
-    // list out "sub-command" names
-    c.names = c.name.trim().split(/\s+/g);
-    c.name = c.names.join(" "); // tidy name
-    // duplicate check
-    if (names.has(c.name)) {
-      exit(`duplicate command name: ${c.name}`);
-    }
-    names.add(c.name);
-    // validate function
-    if (typeof c.run !== "function") {
-      exit(`command "${c.name}" must have a "run" function`);
-    }
-    // validate flags
-    if (!c.flags) {
-      exit(`command "${c.name}" must have "flags", you can use {}`);
-    }
-    if (Array.isArray(c.flags)) {
-      exit(`command "${c.name}" flags must be an object, not an array`);
-    }
-    for (const [name, flag] of Object.entries(c.flags) as [string, Flag][]) {
-      if (!flag.description) {
-        exit(`command "${c.name}" flag "${name}" must have a "description"`);
-      }
-    }
-  }
-  commands.sort((a, b) => (a.name < b.name ? -1 : 1));
-  // helper for joining 2 columns of text
-  type Table = { left: string; right: string }[];
-  const joinColumns = (table: Table) => {
-    const max = table.reduce((m, { left }) => Math.max(m, left.length), 0);
-    return table
-      .map((item) => {
-        if (!item.right) return item.left;
-        const pad = " ".repeat(max - item.left.length);
-        return `${item.left}${pad} ${item.right}`;
-      })
-      .join("\n");
-  };
-  // recursive help text builder for the command tree
-  function help(msg?: string) {
-    // build command list
-    const content = joinColumns(
-      commands.filter((cmd) => {
-        return cmd.name !== "debug" || process.env.DEBUG === "1";
-      }).map((cmd) => ({
-        left: ` • ${cmd.name}`,
-        right: cmd.description ? `- ${cmd.description}` : "",
-      })),
-    );
-    // print result
-    console.log(
-      `\n${scriptName} <command> --help\n\n` + "commands:\n" + content + "\n",
-    );
-    if (msg) {
-      console.log("ERROR:", msg);
-      console.log("");
-    }
-    process.exit(msg ? 1 : 0);
-  }
-  // help text builder for a given command
-  function helpFor(cmd: TakeCommand, flagSpecs: namedFlags, msg?: string) {
-    // build flag help
-    const shorts = new Set();
-    const short = (name: string) => {
-      const l = name[0];
-      if (shorts.has(l)) return "";
-      shorts.add(l);
-      return `, -${l}`;
-    };
-    const extras = (flag: Flag) => {
-      const { env, initial } = flag;
-      const out = [];
-      if (env) out.push(`env=${env}`);
-      if (initial) out.push(`default=${initial}`);
-      return out.length ? ` (${out.join(" ")})` : "";
-    };
-    const content = joinColumns(
-      flagSpecs.map((flag) => ({
-        left: ` --${flag.name}${short(flag.name)}${
-          typeof flag.initial === "boolean" ? "" : ` <${typeof flag.initial}>`
-        }`,
-        right: ` ${flag.description || ""}${extras(flag)}`,
-      })),
-    );
-    // print result
-    console.log(
-      `\n${scriptName} ` +
-        cmd.name +
-        " <flags>\n\n" +
-        "description:\n" +
-        cmd.description +
-        (cmd.help ? ("\n\nhelp:\n" + cmd.help) : "") +
-        "\n\n" +
-        "flags:\n" +
-        content +
-        "\n",
-    );
-    if (msg) {
-      console.log("ERROR:", msg);
-      console.log("");
-    }
-    process.exit(0);
-  }
-  // run 1 command from the command tree.
-  // this function can be called from other commands
-  async function cmd(...args: string[]) {
-    if (args.length === 0) {
-      help();
-    }
-    // stage 1, find command, split args into names/rest
-    let match = null;
-    let rest: string[] = [];
-    let names = null;
-    for (let i = args.length - 1; i >= 0; i--) {
-      names = args.slice(0, i + 1);
-      rest = args.slice(i + 1);
-      const name = names.join(" ");
-      match = commands.find((c) => c.name === name);
-      if (match) {
-        break;
-      }
-    }
-    if (!match) {
-      return help(`no matched command: ${args.join(" ")}`);
-    }
-    // convert command flags into a list
-    const flagSpecs = namedFlags(match.flags);
-    // always add --help
-    flagSpecs.push({
-      name: "help",
-      initial: false,
-      description: "show help",
-    });
-    // stage 2, init flags, parse rest of args
-    const cmdHelp = helpFor.bind(null, match, flagSpecs);
-    let nextFlag: namedFlag | null = null;
-    // traverse rest arguments, sorting into either flags or cmd-args
-    const flagVals: Record<string, any> = {};
-    const cmdArgs = [];
-    for (const arg of rest) {
-      // arg is flag-value
-      if (nextFlag) {
-        flagVals[nextFlag.name] = convert(arg, typeof nextFlag.initial);
-        nextFlag = null;
-        continue;
-      }
-      // arg is command-flag
-      const m = /^-(-?)(\S+)$/.exec(arg);
-      if (m) {
-        const long = Boolean(m[1]);
-        const name = m[2];
-        const fs = flagSpecs.find((f) => {
-          if (!long) {
-            const letters = name.split("");
-            return letters.includes(f.name[0]);
-          }
-          return f.name === name;
-        });
-        if (!fs) {
-          return cmdHelp(`unknown flag "${name}"`);
-        }
-        if (typeof fs.initial === "boolean") {
-          flagVals[fs.name] = true;
-        } else {
-          nextFlag = fs; // collect String/Number flags
-        }
-        continue;
-      }
-      // arg is command-arg
-      cmdArgs.push(arg);
-      continue;
-    }
-    // missing flag value
-    if (nextFlag) {
-      cmdHelp(`missing value for flag: ${nextFlag.name}`);
-    }
-    // help requested
-    if (flagVals.help) {
-      cmdHelp();
-    }
-    // set default values
-    for (const flag of flagSpecs) {
-      const { name, env, initial } = flag;
-      if (!env || name in flagVals) {
-        continue;
-      }
-      const val = process.env[env];
-      if (val) {
-        flagVals[name] = convert(val, typeof flag.initial);
-        continue;
-      }
-      if (initial) {
-        flagVals[name] = initial;
-      }
-    }
-    // exec targets 'run' function
-    const t = timer();
-    try {
-      await match.run({
-        flags: flagVals as FlagValues<typeof match.flags>,
-        args: cmdArgs,
-        cmd,
-        cmdName: match.name,
-        help: cmdHelp,
-      });
-    } catch (err) {
-      if (typeof err === "string") {
-        cmdHelp(err);
-      }
-      throw err;
-    }
-    console.log(`${scriptName} "${match.name}" ran in ${t}`);
-  }
-  // "root" command
-  // process.argv: [node, script, ...args]
-  const args = process.argv.slice(2);
-  // help intercept
-  if (args.length === 0 || args[0] === "-h" || args[0] === "--help") {
-    help();
-  }
-  // normal command execution
-  try {
-    await cmd(...args);
-  } catch (err) {
-    if (typeof err === "string") {
-      help(err);
-    }
-    // parse and display error
-    const eo = err as Record<string, any>;
-    if (eo && typeof eo === "object") {
-      // handle command output
-      if (typeof eo.code === "number") {
-        process.exit(eo.code);
-      }
-      // handle js error
-      const msg = err ? eo.stack || eo.message : `${err}`;
-      if (/exit with (\d+)/.test(msg)) {
-        process.exit(parseInt(RegExp.$1, 10));
-      }
-      console.log("ERROR: " + msg + "\n");
-    }
-    // caught error -> exit 1
-    process.exit(1);
-  }
-}
-
-export function Command<F extends Flags>(
-  command: TakeCommand<F>,
-): NewCommand<F> {
-  return { ...command, flagValues: (null as any), input: (null as any) };
-}
-
-// deno-lint-ignore no-constant-condition
-if (42 < 7) {
-  // TYPE CHECK
-  Register(
-    Command({
-      name: "foo",
-      description: "...",
-      flags: {
-        zip: {
-          initial: 42,
-          description: "this is a test",
-        },
-      },
-      run(input) {
-        input.flags.zip; // (property) zip: number
-      },
-    }),
-    Command({
-      name: "bar",
-      description: "test command",
-      flags: {
-        zop: {
-          initial: "hello",
-          description: "string flag",
-        },
-      },
-      run(input) {
-        console.log("zop:", input.flags.zop); // (property) zop: string
-      },
-    }),
-  );
-}