@outfitter/cli 0.1.0-rc.1

package/dist/cli.d.ts

@@ -0,0 +1,104 @@
+import { Command } from "commander";
+/**
+* Configuration for creating a CLI instance.
+*
+* @example
+* ```typescript
+* const config: CLIConfig = {
+*   name: "waymark",
+*   version: "1.0.0",
+*   description: "A note management CLI",
+* };
+* ```
+*/
+interface CLIConfig {
+	/** CLI name (used in help output and error messages) */
+	readonly name: string;
+	/** CLI version (displayed with --version) */
+	readonly version: string;
+	/** CLI description (displayed in help output) */
+	readonly description?: string;
+	/** Custom error handler */
+	readonly onError?: (error: Error) => void;
+	/** Custom exit handler (defaults to process.exit) */
+	readonly onExit?: (code: number) => never;
+}
+/**
+* CLI instance returned by createCLI.
+*/
+interface CLI {
+	/** Register a command with the CLI */
+	register(command: CommandBuilder | Command): this;
+	/** Parse arguments and execute the matched command */
+	parse(argv?: readonly string[]): Promise<void>;
+	/** Get the underlying Commander program */
+	readonly program: Command;
+}
+/**
+* Action function executed when a command is invoked.
+*
+* @typeParam TFlags - Type of parsed command flags
+*/
+type CommandAction<TFlags extends CommandFlags = CommandFlags> = (context: {
+	/** Parsed command-line arguments */
+	readonly args: readonly string[];
+	/** Parsed command flags */
+	readonly flags: TFlags;
+	/** Raw Commander command instance */
+	readonly command: Command;
+}) => Promise<void> | void;
+/**
+* Base type for command flags.
+* All flag types must extend this.
+*/
+type CommandFlags = Record<string, unknown>;
+/**
+* Builder interface for constructing commands fluently.
+*/
+interface CommandBuilder {
+	/** Set command description */
+	description(text: string): this;
+	/** Add a command option/flag */
+	option(flags: string, description: string, defaultValue?: unknown): this;
+	/** Add a required option */
+	requiredOption(flags: string, description: string, defaultValue?: unknown): this;
+	/** Add command aliases */
+	alias(alias: string): this;
+	/** Set the action handler */
+	action<TFlags extends CommandFlags = CommandFlags>(handler: CommandAction<TFlags>): this;
+	/** Build the underlying Commander command */
+	build(): Command;
+}
+/**
+* Create a new CLI instance with the given configuration.
+*
+* The CLI wraps Commander.js with typed helpers, output contract enforcement,
+* and pagination state management.
+*
+* @param config - CLI configuration options
+* @returns A CLI instance ready for command registration
+*
+* @example
+* ```typescript
+* import { createCLI, command, output } from "@outfitter/cli";
+*
+* const cli = createCLI({
+*   name: "waymark",
+*   version: "1.0.0",
+*   description: "A note management CLI",
+* });
+*
+* cli.register(
+*   command("list")
+*     .description("List all notes")
+*     .action(async () => {
+*       const notes = await getNotes();
+*       output(notes);
+*     })
+* );
+*
+* await cli.parse();
+* ```
+*/
+declare function createCLI(config: CLIConfig): CLI;
+export { createCLI };

package/dist/cli.js

@@ -0,0 +1,55 @@
+// @bun
+import"./shared/@outfitter/cli-4yy82cmp.js";
+
+// packages/cli/src/cli.ts
+import { Command } from "commander";
+function isCommanderHelp(error) {
+  return error.code === "commander.helpDisplayed" || error.code === "commander.version" || error.code === "commander.help";
+}
+function createCLI(config) {
+  const program = new Command;
+  program.name(config.name).version(config.version);
+  if (config.description) {
+    program.description(config.description);
+  }
+  const exit = config.onExit ?? ((code) => process.exit(code));
+  program.exitOverride((error) => {
+    if (isCommanderHelp(error)) {
+      exit(0);
+    }
+    if (config.onError) {
+      config.onError(error);
+    }
+    const exitCode = typeof error.exitCode === "number" && Number.isFinite(error.exitCode) ? error.exitCode : 1;
+    exit(exitCode);
+  });
+  const parse = async (argv) => {
+    try {
+      await program.parseAsync(argv ?? process.argv);
+    } catch (error) {
+      const err = error instanceof Error ? error : new Error(String(error));
+      if (config.onError) {
+        config.onError(err);
+      }
+      const errorExitCode = error.exitCode;
+      const exitCode = typeof errorExitCode === "number" ? errorExitCode : 1;
+      exit(exitCode);
+    }
+  };
+  const cli = {
+    program,
+    register: (builderOrCommand) => {
+      if ("build" in builderOrCommand) {
+        program.addCommand(builderOrCommand.build());
+      } else {
+        program.addCommand(builderOrCommand);
+      }
+      return cli;
+    },
+    parse
+  };
+  return cli;
+}
+export {
+  createCLI
+};

package/dist/command.d.ts

@@ -0,0 +1,74 @@
+import { Command } from "commander";
+/**
+* Action function executed when a command is invoked.
+*
+* @typeParam TFlags - Type of parsed command flags
+*/
+type CommandAction<TFlags extends CommandFlags = CommandFlags> = (context: {
+	/** Parsed command-line arguments */
+	readonly args: readonly string[];
+	/** Parsed command flags */
+	readonly flags: TFlags;
+	/** Raw Commander command instance */
+	readonly command: Command;
+}) => Promise<void> | void;
+/**
+* Base type for command flags.
+* All flag types must extend this.
+*/
+type CommandFlags = Record<string, unknown>;
+/**
+* Builder interface for constructing commands fluently.
+*/
+interface CommandBuilder {
+	/** Set command description */
+	description(text: string): this;
+	/** Add a command option/flag */
+	option(flags: string, description: string, defaultValue?: unknown): this;
+	/** Add a required option */
+	requiredOption(flags: string, description: string, defaultValue?: unknown): this;
+	/** Add command aliases */
+	alias(alias: string): this;
+	/** Set the action handler */
+	action<TFlags extends CommandFlags = CommandFlags>(handler: CommandAction<TFlags>): this;
+	/** Build the underlying Commander command */
+	build(): Command;
+}
+/**
+* Create a new command builder with the given name.
+*
+* The command builder provides a fluent API for defining CLI commands
+* with typed flags, arguments, and actions.
+*
+* @param name - Command name and optional argument syntax (e.g., "list" or "get <id>")
+* @returns A CommandBuilder instance for fluent configuration
+*
+* @example
+* ```typescript
+* import { command, output } from "@outfitter/cli";
+*
+* const list = command("list")
+*   .description("List all notes")
+*   .option("--limit <n>", "Max results", "20")
+*   .option("--json", "Output as JSON")
+*   .option("--next", "Continue from last position")
+*   .action(async ({ flags }) => {
+*     const results = await listNotes(flags);
+*     output(results);
+*   });
+* ```
+*
+* @example
+* ```typescript
+* // Command with required argument
+* const get = command("get <id>")
+*   .description("Get a note by ID")
+*   .action(async ({ args }) => {
+*     const [id] = args;
+*     const note = await getNote(id);
+*     output(note);
+*   });
+* ```
+*/
+declare function command(name: string): CommandBuilder;
+export { command };

package/dist/command.js

@@ -0,0 +1,46 @@
+// @bun
+import"./shared/@outfitter/cli-4yy82cmp.js";
+
+// packages/cli/src/command.ts
+import { Command } from "commander";
+
+class CommandBuilderImpl {
+  command;
+  constructor(name) {
+    this.command = new Command(name);
+  }
+  description(text) {
+    this.command.description(text);
+    return this;
+  }
+  option(flags, description, defaultValue) {
+    this.command.option(flags, description, defaultValue);
+    return this;
+  }
+  requiredOption(flags, description, defaultValue) {
+    this.command.requiredOption(flags, description, defaultValue);
+    return this;
+  }
+  alias(alias) {
+    this.command.alias(alias);
+    return this;
+  }
+  action(handler) {
+    this.command.action(async (...args) => {
+      const command = args.at(-1);
+      const flags = command.optsWithGlobals?.() ?? command.opts();
+      const positional = command.args;
+      await handler({ args: positional, flags, command });
+    });
+    return this;
+  }
+  build() {
+    return this.command;
+  }
+}
+function command(name) {
+  return new CommandBuilderImpl(name);
+}
+export {
+  command
+};