@outfitter/cli 0.1.0-rc.1

package/dist/output.d.ts

@@ -0,0 +1,69 @@
+/**
+* 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;
+}
+/**
+* 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;
+export { output, exitWithError };

package/dist/output.js

@@ -0,0 +1,156 @@
+// @bun
+import"./shared/@outfitter/cli-4yy82cmp.js";
+
+// packages/cli/src/output.ts
+import {
+  safeStringify as contractsSafeStringify,
+  exitCodeMap
+} from "@outfitter/contracts";
+var DEFAULT_EXIT_CODE = 1;
+function writeWithBackpressure(stream, data) {
+  return new Promise((resolve, reject) => {
+    const canContinue = stream.write(data, (error) => {
+      if (error)
+        reject(error);
+    });
+    if (canContinue) {
+      resolve();
+    } else {
+      stream.once("drain", () => resolve());
+      stream.once("error", reject);
+    }
+  });
+}
+function detectMode(options) {
+  if (options?.mode) {
+    return options.mode;
+  }
+  const envJsonl = process.env["OUTFITTER_JSONL"];
+  const envJson = process.env["OUTFITTER_JSON"];
+  if (envJsonl === "1")
+    return "jsonl";
+  if (envJson === "1")
+    return "json";
+  if (envJsonl === "0" || envJson === "0")
+    return "human";
+  return process.stdout.isTTY ? "human" : "json";
+}
+function isValidCategory(category) {
+  return category in exitCodeMap;
+}
+function safeStringify(value, pretty) {
+  const wrappedValue = value === undefined ? null : value;
+  return contractsSafeStringify(wrappedValue, pretty ? 2 : undefined);
+}
+function formatHuman(data) {
+  if (data === null || data === undefined) {
+    return "";
+  }
+  if (typeof data === "string") {
+    return data;
+  }
+  if (typeof data === "number" || typeof data === "boolean") {
+    return String(data);
+  }
+  if (Array.isArray(data)) {
+    return data.map((item) => formatHuman(item)).join(`
+`);
+  }
+  if (typeof data === "object") {
+    const lines = [];
+    for (const [key, value] of Object.entries(data)) {
+      lines.push(`${key}: ${formatHuman(value)}`);
+    }
+    return lines.join(`
+`);
+  }
+  return String(data);
+}
+function getErrorProperties(error) {
+  const errorObj = error;
+  return {
+    _tag: errorObj._tag,
+    category: errorObj.category,
+    context: errorObj.context
+  };
+}
+function getExitCode(error) {
+  const { category } = getErrorProperties(error);
+  if (category !== undefined && isValidCategory(category)) {
+    return exitCodeMap[category];
+  }
+  return DEFAULT_EXIT_CODE;
+}
+function serializeErrorToJson(error) {
+  const { _tag, category, context } = getErrorProperties(error);
+  const result = {
+    message: error.message
+  };
+  if (_tag !== undefined) {
+    result._tag = _tag;
+  }
+  if (category !== undefined) {
+    result.category = category;
+  }
+  if (context !== undefined) {
+    result.context = context;
+  }
+  return JSON.stringify(result);
+}
+function formatErrorHuman(error) {
+  const { _tag } = getErrorProperties(error);
+  if (_tag) {
+    return `${_tag}: ${error.message}`;
+  }
+  return error.message;
+}
+async function output(data, options) {
+  const mode = detectMode(options);
+  const stream = options?.stream ?? process.stdout;
+  let outputText;
+  switch (mode) {
+    case "json": {
+      const jsonData = data === undefined ? null : data;
+      outputText = safeStringify(jsonData, options?.pretty);
+      break;
+    }
+    case "jsonl": {
+      if (Array.isArray(data)) {
+        if (data.length === 0) {
+          outputText = "";
+        } else {
+          outputText = data.map((item) => safeStringify(item)).join(`
+`);
+        }
+      } else {
+        outputText = safeStringify(data);
+      }
+      break;
+    }
+    default: {
+      outputText = formatHuman(data);
+      break;
+    }
+  }
+  if (outputText) {
+    await writeWithBackpressure(stream, `${outputText}
+`);
+  }
+}
+function exitWithError(error, options) {
+  const exitCode = getExitCode(error);
+  const mode = detectMode(options);
+  const isJsonMode = mode === "json" || mode === "jsonl";
+  if (isJsonMode) {
+    process.stderr.write(`${serializeErrorToJson(error)}
+`);
+  } else {
+    process.stderr.write(`${formatErrorHuman(error)}
+`);
+  }
+  process.exit(exitCode);
+}
+export {
+  output,
+  exitWithError
+};

package/dist/pagination.d.ts

@@ -0,0 +1,96 @@
+/**
+* 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;
+}
+/**
+* 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;
+export { saveCursor, loadCursor, clearCursor };

package/dist/pagination.js

@@ -0,0 +1,90 @@
+// @bun
+import"./shared/@outfitter/cli-4yy82cmp.js";
+
+// packages/cli/src/pagination.ts
+import fs from "fs";
+import os from "os";
+import path from "path";
+var UNSAFE_PATH_PATTERN = /(?:^|[\\/])\.\.(?:[\\/]|$)|^[\\/]|^[a-zA-Z]:/;
+function validatePathComponent(component, name) {
+  if (UNSAFE_PATH_PATTERN.test(component)) {
+    throw new Error(`Security: path traversal detected in ${name}`);
+  }
+}
+function getDefaultStateHome() {
+  const home = os.homedir();
+  switch (process.platform) {
+    case "darwin":
+      return path.join(home, "Library", "Application Support");
+    case "win32":
+      return process.env["LOCALAPPDATA"] ?? path.join(home, "AppData", "Local");
+    default:
+      return path.join(home, ".local", "state");
+  }
+}
+function getStatePath(options) {
+  validatePathComponent(options.command, "command");
+  validatePathComponent(options.toolName, "toolName");
+  if (options.context) {
+    validatePathComponent(options.context, "context");
+  }
+  const xdgState = process.env["XDG_STATE_HOME"] ?? getDefaultStateHome();
+  const parts = [xdgState, options.toolName, "cursors", options.command];
+  if (options.context) {
+    parts.push(options.context);
+  }
+  return path.join(...parts, "cursor.json");
+}
+function loadCursor(options) {
+  const statePath = getStatePath(options);
+  if (!fs.existsSync(statePath)) {
+    return;
+  }
+  try {
+    const content = fs.readFileSync(statePath, "utf-8");
+    const parsed = JSON.parse(content);
+    if (typeof parsed !== "object" || parsed === null || typeof parsed["cursor"] !== "string") {
+      return;
+    }
+    const state = parsed;
+    if (options.maxAgeMs !== undefined) {
+      if (typeof state.timestamp !== "number") {
+        return;
+      }
+      const ageMs = Date.now() - state.timestamp;
+      if (ageMs > options.maxAgeMs) {
+        return;
+      }
+    }
+    return state;
+  } catch {
+    return;
+  }
+}
+function saveCursor(cursor, options) {
+  const statePath = getStatePath(options);
+  const stateDir = path.dirname(statePath);
+  fs.mkdirSync(stateDir, { recursive: true });
+  const state = {
+    cursor,
+    command: options.command,
+    timestamp: Date.now(),
+    hasMore: options.hasMore ?? true,
+    ...options.context && { context: options.context },
+    ...options.total !== undefined && { total: options.total }
+  };
+  fs.writeFileSync(statePath, JSON.stringify(state), "utf-8");
+}
+function clearCursor(options) {
+  const statePath = getStatePath(options);
+  try {
+    if (fs.existsSync(statePath)) {
+      fs.unlinkSync(statePath);
+    }
+  } catch {}
+}
+export {
+  saveCursor,
+  loadCursor,
+  clearCursor
+};

package/dist/shared/@outfitter/cli-4yy82cmp.js

@@ -0,0 +1,20 @@
+// @bun
+var __create = Object.create;
+var __getProtoOf = Object.getPrototypeOf;
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __toESM = (mod, isNodeMode, target) => {
+  target = mod != null ? __create(__getProtoOf(mod)) : {};
+  const to = isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target;
+  for (let key of __getOwnPropNames(mod))
+    if (!__hasOwnProp.call(to, key))
+      __defProp(to, key, {
+        get: () => mod[key],
+        enumerable: true
+      });
+  return to;
+};
+var __require = import.meta.require;
+
+export { __toESM, __require };

package/dist/types.d.ts

@@ -0,0 +1,253 @@
+import { Command } from "commander";
+import { CancelledError, ErrorCategory, ValidationError } from "@outfitter/contracts";
+import { Result } from "better-result";
+/**
+* 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;
+}
+export { ValidationError, SortCriteria, Result, Range, ParseGlobOptions, PaginationState, OutputOptions, OutputMode, NumericRange, NormalizeIdOptions, KeyValuePair, FilterExpression, ExpandFileOptions, ErrorCategory, DateRange, CursorOptions, ConfirmDestructiveOptions, CommandFlags, CommandConfig, CommandBuilder, CommandAction, CollectIdsOptions, CancelledError, CLIConfig, CLI };

package/dist/types.js

@@ -0,0 +1,12 @@
+// @bun
+import"./shared/@outfitter/cli-4yy82cmp.js";
+
+// packages/cli/src/types.ts
+import {
+  CancelledError,
+  ValidationError
+} from "@outfitter/contracts";
+export {
+  ValidationError,
+  CancelledError
+};