@outfitter/cli 0.1.0-rc.1

package/dist/index.d.ts

@@ -0,0 +1,607 @@
+import { Command } from "commander";
+import { CancelledError, ValidationError } from "@outfitter/contracts";
+/**
+* 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;
+}
+/**
+* Configuration for a single command.
+*/
+interface CommandConfig {
+	/** Command name and argument syntax (e.g., "list" or "get <id>") */
+	readonly name: string;
+	/** Command description */
+	readonly description?: string;
+	/** Command aliases */
+	readonly aliases?: readonly string[];
+	/** Whether to hide from help output */
+	readonly hidden?: boolean;
+}
+/**
+* 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;
+}
+/**
+* Available output modes for CLI commands.
+*/
+type OutputMode = "human" | "json" | "jsonl" | "tree" | "table";
+/**
+* Options for the output() function.
+*/
+interface OutputOptions {
+	/** Force a specific output mode (overrides flag detection) */
+	readonly mode?: OutputMode;
+	/** Stream to write to (defaults to stdout) */
+	readonly stream?: NodeJS.WritableStream;
+	/** Whether to pretty-print JSON output */
+	readonly pretty?: boolean;
+	/** Exit code to use after output (undefined = don't exit) */
+	readonly exitCode?: number;
+}
+/**
+* Options for collectIds() input utility.
+*
+* @example
+* ```typescript
+* const ids = await collectIds(args, {
+*   allowFile: true,   // @file expansion
+*   allowStdin: true,  // - reads from stdin
+* });
+* ```
+*/
+interface CollectIdsOptions {
+	/** Allow @file expansion (reads IDs from file) */
+	readonly allowFile?: boolean;
+	/** Allow glob patterns */
+	readonly allowGlob?: boolean;
+	/** Allow reading from stdin with "-" */
+	readonly allowStdin?: boolean;
+	/** Separator for comma-separated values */
+	readonly separator?: string;
+}
+/**
+* Options for expandFileArg() input utility.
+*/
+interface ExpandFileOptions {
+	/** Encoding for file reads (defaults to utf-8) */
+	readonly encoding?: BufferEncoding;
+	/** Maximum file size to read (in bytes) */
+	readonly maxSize?: number;
+	/** Whether to trim the file content */
+	readonly trim?: boolean;
+}
+/**
+* Options for parseGlob() input utility.
+*/
+interface ParseGlobOptions {
+	/** Current working directory for glob resolution */
+	readonly cwd?: string;
+	/** Whether to follow symlinks */
+	readonly followSymlinks?: boolean;
+	/** Patterns to exclude */
+	readonly ignore?: readonly string[];
+	/** Only match files (not directories) */
+	readonly onlyFiles?: boolean;
+	/** Only match directories (not files) */
+	readonly onlyDirectories?: boolean;
+}
+/**
+* Options for normalizeId().
+*/
+interface NormalizeIdOptions {
+	/** Whether to lowercase the ID */
+	readonly lowercase?: boolean;
+	/** Whether to trim whitespace */
+	readonly trim?: boolean;
+	/** Minimum length requirement */
+	readonly minLength?: number;
+	/** Maximum length requirement */
+	readonly maxLength?: number;
+	/** Pattern the ID must match */
+	readonly pattern?: RegExp;
+}
+/**
+* Options for confirmDestructive().
+*/
+interface ConfirmDestructiveOptions {
+	/** Message to display to the user */
+	readonly message: string;
+	/** Whether to bypass confirmation (e.g., --yes flag) */
+	readonly bypassFlag?: boolean;
+	/** Number of items affected (shown in confirmation) */
+	readonly itemCount?: number;
+}
+/**
+* Numeric or date range parsed from CLI input.
+*/
+type Range = NumericRange | DateRange;
+/**
+* Numeric range (e.g., "1-10").
+*/
+interface NumericRange {
+	readonly type: "number";
+	readonly min: number;
+	readonly max: number;
+}
+/**
+* Date range (e.g., "2024-01-01..2024-12-31").
+*/
+interface DateRange {
+	readonly type: "date";
+	readonly start: Date;
+	readonly end: Date;
+}
+/**
+* Filter expression parsed from CLI input.
+*/
+interface FilterExpression {
+	readonly field: string;
+	readonly value: string;
+	readonly operator?: "eq" | "ne" | "gt" | "lt" | "gte" | "lte" | "contains";
+}
+/**
+* Sort criteria parsed from CLI input.
+*/
+interface SortCriteria {
+	readonly field: string;
+	readonly direction: "asc" | "desc";
+}
+/**
+* Key-value pair parsed from CLI input.
+*/
+interface KeyValuePair {
+	readonly key: string;
+	readonly value: string;
+}
+/**
+* State for paginated command results.
+*/
+interface PaginationState {
+	/** Cursor for the next page */
+	readonly cursor: string;
+	/** Command that generated this state */
+	readonly command: string;
+	/** Context key for scoping pagination */
+	readonly context?: string;
+	/** Timestamp when state was created */
+	readonly timestamp: number;
+	/** Whether there are more results */
+	readonly hasMore: boolean;
+	/** Total count (if known) */
+	readonly total?: number;
+}
+/**
+* Options for cursor persistence operations.
+*/
+interface CursorOptions {
+	/** Command name for cursor scoping */
+	readonly command: string;
+	/** Context key for additional scoping */
+	readonly context?: string;
+	/** Tool name for XDG path resolution */
+	readonly toolName: string;
+	/** Maximum age in milliseconds before a cursor is treated as expired */
+	readonly maxAgeMs?: number;
+	/** Whether there are more results (defaults to true) */
+	readonly hasMore?: boolean;
+	/** Total count of results (if known) */
+	readonly total?: number;
+}
+/**
+* Output data to the console with automatic mode selection.
+*
+* Respects --json, --jsonl, --tree, --table flags automatically.
+* Defaults to human-friendly output when no flags are present.
+*
+* @param data - The data to output
+* @param options - Output configuration options
+*
+* @example
+* ```typescript
+* import { output } from "@outfitter/cli";
+*
+* // Basic usage - mode auto-detected from flags
+* output(results);
+*
+* // Force JSON mode
+* output(results, { mode: "json" });
+*
+* // Pretty-print JSON
+* output(results, { mode: "json", pretty: true });
+*
+* // Output to stderr
+* output(errors, { stream: process.stderr });
+*
+* // Await for large outputs (recommended)
+* await output(largeDataset, { mode: "jsonl" });
+* ```
+*/
+declare function output(data: unknown, options?: OutputOptions): Promise<void>;
+/**
+* Exit the process with an error message.
+*
+* Formats the error according to the current output mode (human or JSON)
+* and exits with an appropriate exit code.
+*
+* @param error - The error to display
+* @returns Never returns (exits the process)
+*
+* @example
+* ```typescript
+* import { exitWithError } from "@outfitter/cli";
+*
+* try {
+*   await riskyOperation();
+* } catch (error) {
+*   exitWithError(error instanceof Error ? error : new Error(String(error)));
+* }
+* ```
+*/
+declare function exitWithError(error: Error, options?: OutputOptions): never;
+/**
+* Load persisted pagination state for a command.
+*
+* @param options - Cursor options specifying command and context
+* @returns The pagination state if it exists, undefined otherwise
+*
+* @example
+* ```typescript
+* const state = loadCursor({
+*   command: "list",
+*   toolName: "waymark",
+* });
+*
+* if (state) {
+*   // Continue from last position
+*   const results = await listNotes({ cursor: state.cursor });
+* }
+* ```
+*/
+declare function loadCursor(options: CursorOptions): PaginationState | undefined;
+/**
+* Save pagination state for a command.
+*
+* The cursor is persisted to XDG state directory, scoped by
+* tool name, command, and optional context.
+*
+* @param cursor - The cursor string to persist
+* @param options - Cursor options specifying command and context
+*
+* @example
+* ```typescript
+* const results = await listNotes({ limit: 20 });
+*
+* if (results.hasMore) {
+*   saveCursor(results.cursor, {
+*     command: "list",
+*     toolName: "waymark",
+*   });
+* }
+* ```
+*/
+declare function saveCursor(cursor: string, options: CursorOptions): void;
+/**
+* Clear persisted pagination state for a command.
+*
+* Called when --reset flag is passed or when pagination completes.
+*
+* @param options - Cursor options specifying command and context
+*
+* @example
+* ```typescript
+* // User passed --reset flag
+* if (flags.reset) {
+*   clearCursor({
+*     command: "list",
+*     toolName: "waymark",
+*   });
+* }
+* ```
+*/
+declare function clearCursor(options: CursorOptions): void;
+import { CancelledError as CancelledError2, ValidationError as ValidationError2 } from "@outfitter/contracts";
+import { Result as Result2 } from "better-result";
+/**
+* Collect IDs from various input formats.
+*
+* Handles space-separated, comma-separated, repeated flags, @file, and stdin.
+*
+* @param input - Raw input from CLI arguments
+* @param options - Collection options
+* @returns Array of collected IDs
+*
+* @example
+* ```typescript
+* // All these produce the same result:
+* // wm show id1 id2 id3
+* // wm show id1,id2,id3
+* // wm show --ids id1 --ids id2
+* // wm show @ids.txt
+* const ids = await collectIds(args.ids, {
+*   allowFile: true,
+*   allowStdin: true,
+* });
+* ```
+*/
+declare function collectIds(input: string | readonly string[], options?: CollectIdsOptions): Promise<string[]>;
+/**
+* Expand @file references to file contents.
+*
+* If the input starts with @, reads the file and returns its contents.
+* Otherwise, returns the input unchanged.
+*
+* @param input - Raw input that may be a @file reference
+* @param options - Expansion options
+* @returns File contents or original input
+*
+* @example
+* ```typescript
+* // wm create @template.md
+* const content = await expandFileArg(args.content);
+* ```
+*/
+declare function expandFileArg(input: string, options?: ExpandFileOptions): Promise<string>;
+/**
+* Parse and expand glob patterns.
+*
+* Uses Bun.Glob with workspace constraints.
+*
+* @param pattern - Glob pattern to expand
+* @param options - Glob options
+* @returns Array of matched file paths
+*
+* @example
+* ```typescript
+* // wm index "src/**\/*.ts"
+* const files = await parseGlob(args.pattern, {
+*   cwd: workspaceRoot,
+*   ignore: ["node_modules/**"],
+* });
+* ```
+*/
+declare function parseGlob(pattern: string, options?: ParseGlobOptions): Promise<string[]>;
+/**
+* Parse key=value pairs from CLI input.
+*
+* @param input - Raw input containing key=value pairs
+* @returns Array of parsed key-value pairs
+*
+* @example
+* ```typescript
+* // --set key=value --set key2=value2
+* // --set key=value,key2=value2
+* const pairs = parseKeyValue(args.set);
+* // => [{ key: "key", value: "value" }, { key: "key2", value: "value2" }]
+* ```
+*/
+declare function parseKeyValue(input: string | readonly string[]): Result2<KeyValuePair[], InstanceType<typeof ValidationError2>>;
+/**
+* Parse range inputs (numeric or date).
+*
+* @param input - Range string (e.g., "1-10" or "2024-01-01..2024-12-31")
+* @param type - Type of range to parse
+* @returns Parsed range
+*
+* @example
+* ```typescript
+* parseRange("1-10", "number");
+* // => Result<{ type: "number", min: 1, max: 10 }, ValidationError>
+*
+* parseRange("2024-01-01..2024-12-31", "date");
+* // => Result<{ type: "date", start: Date, end: Date }, ValidationError>
+* ```
+*/
+declare function parseRange(input: string, type: "number" | "date"): Result2<Range, InstanceType<typeof ValidationError2>>;
+/**
+* Parse filter expressions from CLI input.
+*
+* @param input - Filter string (e.g., "status:active,priority:high")
+* @returns Array of parsed filter expressions
+*
+* @example
+* ```typescript
+* parseFilter("status:active,priority:high");
+* // => Result<[
+* //   { field: "status", value: "active" },
+* //   { field: "priority", value: "high" }
+* // ], ValidationError>
+* ```
+*/
+declare function parseFilter(input: string): Result2<FilterExpression[], InstanceType<typeof ValidationError2>>;
+/**
+* Parse sort specification from CLI input.
+*
+* @param input - Sort string (e.g., "modified:desc,title:asc")
+* @returns Array of parsed sort criteria
+*
+* @example
+* ```typescript
+* parseSortSpec("modified:desc,title:asc");
+* // => Result<[
+* //   { field: "modified", direction: "desc" },
+* //   { field: "title", direction: "asc" }
+* // ], ValidationError>
+* ```
+*/
+declare function parseSortSpec(input: string): Result2<SortCriteria[], InstanceType<typeof ValidationError2>>;
+/**
+* Normalize an identifier (trim, lowercase where appropriate).
+*
+* @param input - Raw identifier input
+* @param options - Normalization options
+* @returns Normalized identifier
+*
+* @example
+* ```typescript
+* normalizeId("  MY-ID  ", { lowercase: true, trim: true });
+* // => Result<"my-id", ValidationError>
+* ```
+*/
+declare function normalizeId(input: string, options?: NormalizeIdOptions): Result2<string, InstanceType<typeof ValidationError2>>;
+/**
+* Prompt for confirmation before destructive operations.
+*
+* Respects --yes flag for non-interactive mode.
+*
+* @param options - Confirmation options
+* @returns Whether the user confirmed
+*
+* @example
+* ```typescript
+* const confirmed = await confirmDestructive({
+*   message: "Delete 5 notes?",
+*   bypassFlag: flags.yes,
+*   itemCount: 5,
+* });
+*
+* if (confirmed.isErr()) {
+*   // User cancelled
+*   process.exit(0);
+* }
+* ```
+*/
+declare function confirmDestructive(options: ConfirmDestructiveOptions): Promise<Result2<boolean, InstanceType<typeof CancelledError2>>>;
+/**
+* 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;
+import { ActionRegistry, ActionSurface, AnyActionSpec, HandlerContext } from "@outfitter/contracts";
+import { Command as Command2 } from "commander";
+interface BuildCliCommandsOptions {
+	readonly createContext?: (input: {
+		action: AnyActionSpec;
+		args: readonly string[];
+		flags: Record<string, unknown>;
+	}) => HandlerContext;
+	readonly includeSurfaces?: readonly ActionSurface[];
+}
+type ActionSource = ActionRegistry | readonly AnyActionSpec[];
+declare function buildCliCommands(source: ActionSource, options?: BuildCliCommandsOptions): Command2[];
+/**
+* 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 { saveCursor, parseSortSpec, parseRange, parseKeyValue, parseGlob, parseFilter, output, normalizeId, loadCursor, expandFileArg, exitWithError, createCLI, confirmDestructive, command, collectIds, clearCursor, buildCliCommands, ValidationError, SortCriteria, Range, ParseGlobOptions, PaginationState, OutputOptions, OutputMode, NumericRange, NormalizeIdOptions, KeyValuePair, FilterExpression, ExpandFileOptions, DateRange, CursorOptions, ConfirmDestructiveOptions, CommandFlags, CommandConfig, CommandBuilder, CommandAction, CollectIdsOptions, CancelledError, CLIConfig, CLI, BuildCliCommandsOptions };

package/dist/index.js

@@ -0,0 +1,50 @@
+// @bun
+import {
+  exitWithError,
+  output
+} from "./output.js";
+import"./shared/@outfitter/cli-4yy82cmp.js";
+import {
+  clearCursor,
+  loadCursor,
+  saveCursor
+} from "./pagination.js";
+import {
+  collectIds,
+  confirmDestructive,
+  expandFileArg,
+  normalizeId,
+  parseFilter,
+  parseGlob,
+  parseKeyValue,
+  parseRange,
+  parseSortSpec
+} from "./input.js";
+import {
+  createCLI
+} from "./cli.js";
+import {
+  buildCliCommands
+} from "./actions.js";
+import {
+  command
+} from "./command.js";
+export {
+  saveCursor,
+  parseSortSpec,
+  parseRange,
+  parseKeyValue,
+  parseGlob,
+  parseFilter,
+  output,
+  normalizeId,
+  loadCursor,
+  expandFileArg,
+  exitWithError,
+  createCLI,
+  confirmDestructive,
+  command,
+  collectIds,
+  clearCursor,
+  buildCliCommands
+};