@outfitter/cli 0.1.0-rc.1

package/README.md

@@ -0,0 +1,436 @@
+# @outfitter/cli
+
+Typed CLI runtime with output contracts, input parsing, and pagination for Bun.
+
+## Installation
+
+```bash
+bun add @outfitter/cli
+```
+
+## Quick Start
+
+```typescript
+import { output, collectIds, loadCursor, saveCursor } from "@outfitter/cli";
+
+// Output data with automatic mode detection
+output({ id: "123", name: "Example" });
+
+// Collect IDs from various input formats
+const ids = await collectIds("id1,id2,id3");
+
+// Handle pagination state
+const cursor = loadCursor({ command: "list", toolName: "myapp" });
+if (cursor) {
+  // Continue from last position
+}
+```
+
+## API Reference
+
+### Output Utilities
+
+#### `output(data, options?)`
+
+Output data to the console with automatic mode selection.
+
+Defaults to human-friendly output for TTY, JSON for non-TTY. Override via `mode` option or `OUTFITTER_JSON`/`OUTFITTER_JSONL` environment variables.
+
+```typescript
+import { output } from "@outfitter/cli";
+
+// Basic usage - mode auto-detected
+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 });
+```
+
+**Options:**
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `mode` | `OutputMode` | auto | Force a specific output mode |
+| `stream` | `WritableStream` | `stdout` | Stream to write to |
+| `pretty` | `boolean` | `false` | Pretty-print JSON output |
+
+**Output Modes:**
+
+- `human` - Human-readable key: value format
+- `json` - Single JSON object
+- `jsonl` - JSON Lines (one object per line)
+- `tree` - Tree structure (reserved)
+- `table` - Table format (reserved)
+
+#### `exitWithError(error)`
+
+Exit the process with an error message and appropriate exit code.
+
+```typescript
+import { exitWithError } from "@outfitter/cli";
+
+try {
+  await riskyOperation();
+} catch (error) {
+  exitWithError(error instanceof Error ? error : new Error(String(error)));
+}
+```
+
+### Input Utilities
+
+#### `collectIds(input, options?)`
+
+Collect IDs from various input formats: space-separated, comma-separated, repeated flags, `@file`, and stdin.
+
+```typescript
+import { collectIds } from "@outfitter/cli";
+
+// All these produce the same result:
+// myapp show id1 id2 id3
+// myapp show id1,id2,id3
+// myapp show --ids id1 --ids id2
+// myapp show @ids.txt
+// echo "id1\nid2" | myapp show @-
+
+const ids = await collectIds(args.ids, {
+  allowFile: true,
+  allowStdin: true,
+});
+```
+
+**Options:**
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `allowFile` | `boolean` | `true` | Allow `@file` expansion |
+| `allowStdin` | `boolean` | `true` | Allow `@-` for stdin |
+
+#### `expandFileArg(input, options?)`
+
+Expand `@file` references to file contents. Returns input unchanged if not a file reference.
+
+```typescript
+import { expandFileArg } from "@outfitter/cli";
+
+// myapp create @template.md
+const content = await expandFileArg(args.content);
+
+// With options
+const content = await expandFileArg(args.content, {
+  maxSize: 1024 * 1024, // 1MB limit
+  trim: true,
+});
+```
+
+**Options:**
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `encoding` | `BufferEncoding` | `utf-8` | File encoding |
+| `maxSize` | `number` | - | Maximum file size in bytes |
+| `trim` | `boolean` | `false` | Trim whitespace |
+
+#### `parseGlob(pattern, options?)`
+
+Parse and expand glob patterns using `Bun.Glob`.
+
+```typescript
+import { parseGlob } from "@outfitter/cli";
+
+const files = await parseGlob("src/**/*.ts", {
+  cwd: workspaceRoot,
+  ignore: ["node_modules/**", "**/*.test.ts"],
+  onlyFiles: true,
+});
+```
+
+**Options:**
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `cwd` | `string` | `process.cwd()` | Working directory |
+| `ignore` | `string[]` | `[]` | Patterns to exclude |
+| `onlyFiles` | `boolean` | `false` | Only match files |
+| `onlyDirectories` | `boolean` | `false` | Only match directories |
+| `followSymlinks` | `boolean` | `false` | Follow symbolic links |
+
+#### `parseKeyValue(input)`
+
+Parse `key=value` pairs from CLI input.
+
+```typescript
+import { parseKeyValue } from "@outfitter/cli";
+
+// --set key=value --set key2=value2
+// --set key=value,key2=value2
+const result = parseKeyValue(args.set);
+
+if (result.isOk()) {
+  // [{ key: "key", value: "value" }, { key: "key2", value: "value2" }]
+  console.log(result.value);
+}
+```
+
+#### `parseRange(input, type)`
+
+Parse numeric or date range inputs.
+
+```typescript
+import { parseRange } from "@outfitter/cli";
+
+// Numeric range
+const numResult = parseRange("1-10", "number");
+// => { type: "number", min: 1, max: 10 }
+
+// Date range
+const dateResult = parseRange("2024-01-01..2024-12-31", "date");
+// => { type: "date", start: Date, end: Date }
+
+// Single value
+const single = parseRange("5", "number");
+// => { type: "number", min: 5, max: 5 }
+```
+
+#### `parseFilter(input)`
+
+Parse filter expressions from CLI input.
+
+```typescript
+import { parseFilter } from "@outfitter/cli";
+
+const result = parseFilter("status:active,priority:>=high,!archived:true");
+
+if (result.isOk()) {
+  // [
+  //   { field: "status", value: "active" },
+  //   { field: "priority", value: "high", operator: "gte" },
+  //   { field: "archived", value: "true", operator: "ne" }
+  // ]
+}
+```
+
+**Filter Operators:**
+
+| Prefix | Operator | Description |
+|--------|----------|-------------|
+| (none) | `eq` | Equals (default) |
+| `!` | `ne` | Not equals |
+| `>` | `gt` | Greater than |
+| `<` | `lt` | Less than |
+| `>=` | `gte` | Greater than or equal |
+| `<=` | `lte` | Less than or equal |
+| `~` | `contains` | Contains substring |
+
+#### `parseSortSpec(input)`
+
+Parse sort specification from CLI input.
+
+```typescript
+import { parseSortSpec } from "@outfitter/cli";
+
+const result = parseSortSpec("modified:desc,title:asc");
+
+if (result.isOk()) {
+  // [
+  //   { field: "modified", direction: "desc" },
+  //   { field: "title", direction: "asc" }
+  // ]
+}
+```
+
+#### `normalizeId(input, options?)`
+
+Normalize an identifier with validation.
+
+```typescript
+import { normalizeId } from "@outfitter/cli";
+
+const result = normalizeId("  MY-ID  ", {
+  trim: true,
+  lowercase: true,
+  minLength: 3,
+  maxLength: 50,
+  pattern: /^[a-z0-9-]+$/,
+});
+
+if (result.isOk()) {
+  // "my-id"
+}
+```
+
+**Options:**
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `trim` | `boolean` | `false` | Trim whitespace |
+| `lowercase` | `boolean` | `false` | Convert to lowercase |
+| `minLength` | `number` | - | Minimum length |
+| `maxLength` | `number` | - | Maximum length |
+| `pattern` | `RegExp` | - | Required pattern |
+
+#### `confirmDestructive(options)`
+
+Prompt for confirmation before destructive operations. Respects `--yes` flag for non-interactive mode.
+
+```typescript
+import { confirmDestructive } from "@outfitter/cli";
+
+const result = await confirmDestructive({
+  message: "Delete 5 notes?",
+  bypassFlag: flags.yes,
+  itemCount: 5,
+});
+
+if (result.isErr()) {
+  // User cancelled or non-TTY environment
+  console.error("Operation cancelled");
+  process.exit(0);
+}
+
+// Proceed with destructive operation
+```
+
+### Pagination Utilities
+
+Pagination state persists per-command to support `--next` and `--reset` functionality.
+
+**XDG State Directory Pattern:**
+
+```
+$XDG_STATE_HOME/{toolName}/cursors/{command}[/{context}]/cursor.json
+```
+
+#### `loadCursor(options)`
+
+Load persisted pagination state for a command.
+
+```typescript
+import { loadCursor } from "@outfitter/cli";
+
+const state = loadCursor({
+  command: "list",
+  toolName: "waymark",
+  context: "workspace-123", // optional
+  maxAgeMs: 30 * 60 * 1000, // optional expiration window
+});
+
+if (state) {
+  // Continue from last position
+  const results = await listNotes({ cursor: state.cursor });
+}
+```
+
+#### `saveCursor(cursor, options)`
+
+Save pagination state for a command.
+
+```typescript
+import { saveCursor } from "@outfitter/cli";
+
+const results = await listNotes({ limit: 20 });
+
+if (results.hasMore) {
+  saveCursor(results.cursor, {
+    command: "list",
+    toolName: "waymark",
+  });
+}
+```
+
+#### `clearCursor(options)`
+
+Clear persisted pagination state for a command.
+
+```typescript
+import { clearCursor } from "@outfitter/cli";
+
+// User passed --reset flag
+if (flags.reset) {
+  clearCursor({
+    command: "list",
+    toolName: "waymark",
+  });
+}
+```
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `OUTFITTER_JSON` | Set to `1` to force JSON output | - |
+| `OUTFITTER_JSONL` | Set to `1` to force JSONL output (takes priority over JSON) | - |
+| `XDG_STATE_HOME` | State directory for pagination | Platform-specific |
+
+### Output Mode Priority
+
+1. Explicit `mode` option in `output()` call
+2. `OUTFITTER_JSONL=1` environment variable (highest env priority)
+3. `OUTFITTER_JSON=1` environment variable
+4. `OUTFITTER_JSON=0` or `OUTFITTER_JSONL=0` forces human mode
+5. TTY detection: `json` for non-TTY, `human` for TTY
+
+## Error Handling
+
+### Exit Code Mapping
+
+Exit codes are automatically determined from error categories:
+
+| Category | Exit Code |
+|----------|-----------|
+| `validation` | 1 |
+| `not_found` | 2 |
+| `conflict` | 3 |
+| `permission` | 4 |
+| `timeout` | 5 |
+| `rate_limit` | 6 |
+| `network` | 7 |
+| `internal` | 8 |
+| `auth` | 9 |
+| `cancelled` | 130 |
+
+### Tagged Errors
+
+Errors with a `category` property are automatically mapped to exit codes:
+
+```typescript
+const error = new Error("File not found") as Error & { category: string };
+error.category = "not_found";
+
+exitWithError(error); // Exits with code 2
+```
+
+## Types
+
+All types are exported for TypeScript consumers:
+
+```typescript
+import type {
+  // Core types
+  CLIConfig,
+  CommandConfig,
+  CommandAction,
+  CommandFlags,
+  // Output types
+  OutputMode,
+  OutputOptions,
+  // Input types
+  CollectIdsOptions,
+  ExpandFileOptions,
+  ParseGlobOptions,
+  // Pagination types
+  PaginationState,
+  CursorOptions,
+} from "@outfitter/cli";
+```
+
+## License
+
+MIT

package/dist/actions.d.ts

@@ -0,0 +1,13 @@
+import { ActionRegistry, ActionSurface, AnyActionSpec, HandlerContext } from "@outfitter/contracts";
+import { Command } 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): Command[];
+export { buildCliCommands, BuildCliCommandsOptions };

package/dist/actions.js

@@ -0,0 +1,175 @@
+// @bun
+import"./shared/@outfitter/cli-4yy82cmp.js";
+
+// packages/cli/src/actions.ts
+import {
+  createContext as createHandlerContext,
+  DEFAULT_REGISTRY_SURFACES,
+  validateInput
+} from "@outfitter/contracts";
+import { Command } from "commander";
+var ARGUMENT_PREFIXES = ["<", "["];
+function isArgumentToken(token) {
+  if (!token) {
+    return false;
+  }
+  return ARGUMENT_PREFIXES.some((prefix) => token.startsWith(prefix));
+}
+function splitCommandSpec(spec) {
+  const parts = spec.trim().split(/\s+/).filter(Boolean);
+  if (parts.length === 0) {
+    return { name: undefined, args: [] };
+  }
+  return { name: parts[0], args: parts.slice(1) };
+}
+function applyArguments(command, args) {
+  for (const arg of args) {
+    command.argument(arg);
+  }
+}
+function applyCliOptions(command, action) {
+  const options = action.cli?.options ?? [];
+  for (const option of options) {
+    if (option.required) {
+      command.requiredOption(option.flags, option.description, option.defaultValue);
+    } else {
+      command.option(option.flags, option.description, option.defaultValue);
+    }
+  }
+}
+function resolveDescription(action) {
+  return action.cli?.description ?? action.description ?? action.id;
+}
+function resolveAliases(action) {
+  return action.cli?.aliases ?? [];
+}
+function resolveCommandSpec(action) {
+  return action.cli?.command ?? action.id;
+}
+function resolveFlags(command) {
+  return command.optsWithGlobals?.() ?? command.opts();
+}
+function resolveInput(action, context) {
+  if (action.cli?.mapInput) {
+    return action.cli.mapInput(context);
+  }
+  const hasFlags = Object.keys(context.flags).length > 0;
+  if (!hasFlags && context.args.length === 0) {
+    return {};
+  }
+  return {
+    ...context.flags,
+    ...context.args.length > 0 ? { args: context.args } : {}
+  };
+}
+async function runAction(action, command, createContext) {
+  const flags = resolveFlags(command);
+  const args = command.args;
+  const inputContext = { args, flags };
+  const input = resolveInput(action, inputContext);
+  const validation = validateInput(action.input, input);
+  if (validation.isErr()) {
+    throw validation.error;
+  }
+  const ctx = createContext({ action, args, flags });
+  const result = await action.handler(validation.value, ctx);
+  if (result.isErr()) {
+    throw result.error;
+  }
+}
+function createCommand(action, createContext, spec) {
+  const commandSpec = spec ?? resolveCommandSpec(action);
+  const { name, args } = splitCommandSpec(commandSpec);
+  if (!name) {
+    throw new Error(`Missing CLI command name for action ${action.id}`);
+  }
+  const command = new Command(name);
+  command.description(resolveDescription(action));
+  applyCliOptions(command, action);
+  applyArguments(command, args);
+  for (const alias of resolveAliases(action)) {
+    command.alias(alias);
+  }
+  command.action(async (...argsList) => {
+    const commandInstance = argsList.at(-1);
+    await runAction(action, commandInstance, createContext);
+  });
+  return command;
+}
+function buildCliCommands(source, options = {}) {
+  const actions = isActionRegistry(source) ? source.list() : source;
+  const includeSurfaces = options.includeSurfaces ?? [
+    "cli"
+  ];
+  const commands = [];
+  const createContext = options.createContext ?? ((_input) => createHandlerContext({
+    cwd: process.cwd(),
+    env: process.env
+  }));
+  const grouped = new Map;
+  const ungrouped = [];
+  for (const action of actions) {
+    const surfaces = action.surfaces ?? DEFAULT_REGISTRY_SURFACES;
+    if (!surfaces.some((surface) => includeSurfaces.includes(surface))) {
+      continue;
+    }
+    const group = action.cli?.group;
+    if (group) {
+      const groupActions = grouped.get(group) ?? [];
+      groupActions.push(action);
+      grouped.set(group, groupActions);
+    } else {
+      ungrouped.push(action);
+    }
+  }
+  for (const action of ungrouped) {
+    commands.push(createCommand(action, createContext));
+  }
+  for (const [groupName, groupActions] of grouped.entries()) {
+    const groupCommand = new Command(groupName);
+    let baseAction;
+    const subcommands = [];
+    for (const action of groupActions) {
+      const spec = action.cli?.command?.trim() ?? "";
+      const { name, args } = splitCommandSpec(spec);
+      if (!name || isArgumentToken(name)) {
+        if (baseAction) {
+          throw new Error(`Group '${groupName}' defines multiple base actions: '${baseAction.id}' and '${action.id}'.`);
+        }
+        baseAction = action;
+        groupCommand.description(resolveDescription(action));
+        applyCliOptions(groupCommand, action);
+        applyArguments(groupCommand, name ? [name, ...args] : args);
+        for (const alias of resolveAliases(action)) {
+          groupCommand.alias(alias);
+        }
+        groupCommand.action(async (...argsList) => {
+          const commandInstance = argsList.at(-1);
+          await runAction(action, commandInstance, createContext);
+        });
+      } else {
+        subcommands.push(action);
+      }
+    }
+    for (const action of subcommands) {
+      const spec = resolveCommandSpec(action);
+      const { name, args } = splitCommandSpec(spec);
+      if (!name) {
+        continue;
+      }
+      const subcommand = createCommand(action, createContext, [name, ...args].join(" "));
+      groupCommand.addCommand(subcommand);
+    }
+    if (!baseAction) {
+      groupCommand.description(groupName);
+    }
+    commands.push(groupCommand);
+  }
+  return commands;
+}
+function isActionRegistry(source) {
+  return "list" in source;
+}
+export {
+  buildCliCommands
+};