feat: add tab completions

build.config.ts

@@ -1,5 +1,5 @@
 import { defineBuildConfig } from "obuild/config";
 
 export default defineBuildConfig({
-  entries: ["src/index.ts"],
+  entries: ["src/index.ts", "src/tab.ts"],
 });

package.json

@@ -7,7 +7,8 @@
   "sideEffects": false,
   "type": "module",
   "exports": {
-    ".": "./dist/index.mjs"
+    ".": "./dist/index.mjs",
+    "./tab": "./dist/tab.mjs"
   },
   "types": "./dist/index.d.mts",
   "files": [
@@ -28,6 +29,7 @@
     "consola": "^3.4.2"
   },
   "devDependencies": {
+    "@bomb.sh/tab": "^0.0.11",
     "@types/node": "^25.0.9",
     "@vitest/coverage-v8": "^4.0.17",
     "automd": "^0.4.2",
@@ -40,5 +42,13 @@
     "typescript": "^5.9.3",
     "vitest": "^4.0.17"
   },
+  "peerDependencies": {
+    "@bomb.sh/tab": "*"
+  },
+  "peerDependenciesMeta": {
+    "@bomb.sh/tab": {
+      "optional": true
+    }
+  },
   "packageManager": "pnpm@10.28.1"
 }

playground/cli.ts

@@ -1,4 +1,5 @@
 import { defineCommand, runMain } from "../src/index.ts";
+import { registerTabCompletions } from "../src/tab.ts";
 
 const main = defineCommand({
   meta: {
@@ -19,4 +20,6 @@ const main = defineCommand({
   },
 });
 
+await registerTabCompletions(main);
+
 runMain(main);

src/main.ts

@@ -1,9 +1,10 @@
 import consola from "consola";
-import type { ArgsDef, CommandDef } from "./types.ts";
 import { resolveSubCommand, runCommand } from "./command.ts";
 import { CLIError } from "./_utils.ts";
 import { showUsage as _showUsage } from "./usage.ts";
 
+import type { ArgsDef, CommandDef } from "./types.ts";
+
 export interface RunMainOptions {
   rawArgs?: string[];
   showUsage?: typeof _showUsage;
@@ -15,6 +16,7 @@ export async function runMain<T extends ArgsDef = ArgsDef>(
 ) {
   const rawArgs = opts.rawArgs || process.argv.slice(2);
   const showUsage = opts.showUsage || _showUsage;
+
   try {
     if (rawArgs.includes("--help") || rawArgs.includes("-h")) {
       await showUsage(...(await resolveSubCommand(cmd, rawArgs)));

src/tab.ts

@@ -0,0 +1,83 @@
+import tab from "@bomb.sh/tab";
+import { resolveValue } from "./_utils.ts";
+
+import type { ArgsDef, CommandDef, ArgDef } from "./types.ts";
+import type { Command, RootCommand } from "@bomb.sh/tab";
+
+export type TabCommand = Command | RootCommand;
+
+export async function registerTabCompletions(
+  cmd: CommandDef<ArgsDef>,
+): Promise<void> {
+  await registerCommand(cmd, tab);
+
+  const meta = await resolveValue(cmd.meta);
+  const name = meta?.name || "cli";
+  const subCommands = await resolveValue(cmd.subCommands);
+
+  if (subCommands && !subCommands.complete) {
+    subCommands.complete = {
+      meta: {
+        name: "complete",
+        description: "Generate shell completion scripts",
+      },
+      args: {
+        shell: {
+          type: "positional",
+          description: "Shell type (zsh, bash, fish, powershell)",
+          required: false,
+        },
+      },
+      run({ rawArgs }) {
+        const shell = rawArgs[0];
+        if (shell === "--") {
+          tab.parse(rawArgs.slice(1));
+        } else if (shell) {
+          const exec = `${process.execPath} ${process.argv[1]}`;
+          tab.setup(name, exec, shell);
+        }
+      },
+    } satisfies CommandDef<ArgsDef>;
+  }
+}
+
+async function registerCommand(
+  cmd: CommandDef<ArgsDef>,
+  tabCmd: TabCommand,
+  path = "",
+): Promise<void> {
+  const args = await resolveValue(cmd.args);
+  if (args) {
+    for (const name in args) {
+      const arg = args[name] as ArgDef;
+      const handler = arg.complete
+        ? (complete: (value: string, description: string) => void) =>
+            arg.complete!(complete)
+        : undefined;
+
+      if (arg.type === "positional") {
+        tabCmd.argument(name, handler, arg.required === false);
+      } else {
+        const alias =
+          "alias" in arg && arg.alias
+            ? // eslint-disable-next-line unicorn/no-nested-ternary
+              typeof arg.alias === "string"
+              ? arg.alias
+              : arg.alias[0]
+            : undefined;
+        tabCmd.option(name, arg.description || "", handler || alias, alias);
+      }
+    }
+  }
+
+  const subCommands = await resolveValue(cmd.subCommands);
+  if (!subCommands) return;
+  for (const name in subCommands) {
+    const sub = await resolveValue(subCommands[name]);
+    if (!sub) continue;
+    const meta = await resolveValue(sub.meta);
+    const subPath = path ? `${path} ${name}` : name;
+    const subTab = tab.command(subPath, meta?.description || "");
+    await registerCommand(sub, subTab, subPath);
+  }
+}

src/types.ts

@@ -4,13 +4,18 @@ export type ArgType = "boolean" | "string" | "enum" | "positional" | undefined;
 
 // Args: Definition
 
+export type CompletionHandler = (
+  complete: (value: string, description: string) => void,
+) => void | Promise<void>;
+
 export type _ArgDef<T extends ArgType, VT extends boolean | number | string> = {
   type?: T;
   description?: string;
   valueHint?: string;
   alias?: string | string[];
   default?: VT;
   required?: boolean;
+  complete?: CompletionHandler;
   options?: string[];
 };