@outfitter/cli 0.3.0 → 0.4.1

package/dist/pagination.d.ts

@@ -1,4 +1,4 @@
-import { CursorOptions, PaginationState } from "./shared/@outfitter/cli-ttt7r0j7";
+import { CursorOptions, PaginationState } from "./shared/@outfitter/cli-md9347gn";
 /**
 * Load persisted pagination state for a command.
 *

package/dist/pagination.js

@@ -1,6 +1,4 @@
 // @bun
-import"./shared/@outfitter/cli-v1tzwxkt.js";
-
 // packages/cli/src/pagination.ts
 import fs from "fs";
 import os from "os";

package/dist/query.d.ts

@@ -0,0 +1,50 @@
+import { FlagPreset, OutputMode } from "./shared/@outfitter/cli-md9347gn";
+/**
+* Configuration for the output mode preset.
+*/
+interface OutputModePresetConfig {
+	/** Allowed output modes (default: ["human", "json"]) */
+	readonly modes?: readonly OutputMode[];
+	/** Default mode when not specified (default: "human") */
+	readonly defaultMode?: OutputMode;
+	/** Whether to include "jsonl" in allowed modes (default: false) */
+	readonly includeJsonl?: boolean;
+}
+/**
+* Resolved output mode from CLI input.
+*/
+type OutputModeFlags = {
+	/** The resolved output mode */
+	readonly outputMode: OutputMode;
+};
+/**
+* Output mode flag preset.
+*
+* Adds: `-o, --output <mode>`
+* Resolves: `{ outputMode: string }`
+*
+* Replaces ad-hoc `--json`/`--jsonl` handling with a single
+* `--output` flag that accepts a mode name. Invalid modes
+* fall back to the configured default.
+*
+* @param config - Optional configuration for allowed modes and default
+*/
+declare function outputModePreset(config?: OutputModePresetConfig): FlagPreset<OutputModeFlags>;
+/**
+* Resolved jq expression from CLI input.
+*/
+type JqFlags = {
+	/** The jq expression, or undefined if not provided */
+	readonly jq: string | undefined;
+};
+/**
+* JQ expression flag preset.
+*
+* Adds: `--jq <expr>`
+* Resolves: `{ jq: string | undefined }`
+*
+* The resolver returns the expression string or `undefined`.
+* Actual jq execution is a consumer concern.
+*/
+declare function jqPreset(): FlagPreset<JqFlags>;
+export { outputModePreset, jqPreset, OutputModePresetConfig, OutputModeFlags, JqFlags };

package/dist/query.js

@@ -0,0 +1,51 @@
+// @bun
+import {
+  createPreset
+} from "./shared/@outfitter/cli-b2zk8fb3.js";
+
+// packages/cli/src/query.ts
+function outputModePreset(config) {
+  const defaultMode = config?.defaultMode ?? "human";
+  const baseModes = config?.modes ?? ["human", "json"];
+  const modes = new Set(config?.includeJsonl ? [...baseModes, "jsonl"] : baseModes);
+  modes.add(defaultMode);
+  return createPreset({
+    id: "outputMode",
+    options: [
+      {
+        flags: "-o, --output <mode>",
+        description: `Output mode (${[...modes].join(", ")})`,
+        defaultValue: defaultMode
+      }
+    ],
+    resolve: (flags) => {
+      const raw = flags["output"];
+      if (typeof raw === "string" && modes.has(raw)) {
+        return { outputMode: raw };
+      }
+      return { outputMode: defaultMode };
+    }
+  });
+}
+function jqPreset() {
+  return createPreset({
+    id: "jq",
+    options: [
+      {
+        flags: "--jq <expr>",
+        description: "Filter JSON output with a jq expression"
+      }
+    ],
+    resolve: (flags) => {
+      const raw = flags["jq"];
+      if (typeof raw === "string" && raw.length > 0) {
+        return { jq: raw };
+      }
+      return { jq: undefined };
+    }
+  });
+}
+export {
+  outputModePreset,
+  jqPreset
+};

package/dist/shared/@outfitter/cli-b2zk8fb3.js

@@ -0,0 +1,357 @@
+// @bun
+// packages/cli/src/flags.ts
+function createPreset(config) {
+  const preset = {
+    id: config.id,
+    options: config.options,
+    resolve: config.resolve
+  };
+  preset[PRESET_IDS] = [config.id];
+  return preset;
+}
+var PRESET_IDS = Symbol("presetIds");
+function getPresetIds(preset) {
+  const ids = preset[PRESET_IDS];
+  return ids && ids.length > 0 ? ids : [preset.id];
+}
+function composePresets(...presets) {
+  const seen = new Set;
+  const mergedIds = [];
+  const mergedOptions = [];
+  const resolvers = [];
+  for (const preset of presets) {
+    const presetIds = getPresetIds(preset);
+    if (presetIds.every((id) => seen.has(id)))
+      continue;
+    for (const id of presetIds) {
+      if (seen.has(id))
+        continue;
+      seen.add(id);
+      mergedIds.push(id);
+    }
+    mergedOptions.push(...preset.options);
+    resolvers.push(preset.resolve);
+  }
+  const composed = {
+    id: mergedIds.join("+"),
+    options: mergedOptions,
+    resolve: (flags) => {
+      let result = {};
+      for (const resolver of resolvers) {
+        result = { ...result, ...resolver(flags) };
+      }
+      return result;
+    }
+  };
+  composed[PRESET_IDS] = mergedIds;
+  return composed;
+}
+function verbosePreset() {
+  return createPreset({
+    id: "verbose",
+    options: [
+      {
+        flags: "-v, --verbose",
+        description: "Verbose output",
+        defaultValue: false
+      }
+    ],
+    resolve: (flags) => ({
+      verbose: Boolean(flags["verbose"])
+    })
+  });
+}
+function cwdPreset() {
+  return createPreset({
+    id: "cwd",
+    options: [
+      {
+        flags: "--cwd <path>",
+        description: "Working directory"
+      }
+    ],
+    resolve: (flags) => ({
+      cwd: typeof flags["cwd"] === "string" ? flags["cwd"] : process.cwd()
+    })
+  });
+}
+function dryRunPreset() {
+  return createPreset({
+    id: "dryRun",
+    options: [
+      {
+        flags: "--dry-run",
+        description: "Preview changes without applying",
+        defaultValue: false
+      }
+    ],
+    resolve: (flags) => ({
+      dryRun: Boolean(flags["dryRun"] ?? flags["dry-run"])
+    })
+  });
+}
+function forcePreset() {
+  return createPreset({
+    id: "force",
+    options: [
+      {
+        flags: "-f, --force",
+        description: "Force operation (skip confirmations)",
+        defaultValue: false
+      }
+    ],
+    resolve: (flags) => ({
+      force: Boolean(flags["force"])
+    })
+  });
+}
+function interactionPreset() {
+  return createPreset({
+    id: "interaction",
+    options: [
+      {
+        flags: "--non-interactive",
+        description: "Disable interactive prompts",
+        defaultValue: false
+      },
+      {
+        flags: "--no-input",
+        description: "Disable interactive prompts (alias)"
+      },
+      {
+        flags: "-y, --yes",
+        description: "Auto-confirm prompts",
+        defaultValue: false
+      }
+    ],
+    resolve: (flags) => {
+      const nonInteractive = flags["input"] === false || Boolean(flags["nonInteractive"]) || Boolean(flags["non-interactive"]) || Boolean(flags["noInput"]) || Boolean(flags["no-input"]);
+      return {
+        interactive: !nonInteractive,
+        yes: Boolean(flags["yes"])
+      };
+    }
+  });
+}
+function strictPreset() {
+  return createPreset({
+    id: "strict",
+    options: [
+      {
+        flags: "--strict",
+        description: "Enable strict mode (treat warnings as errors)",
+        defaultValue: false
+      }
+    ],
+    resolve: (flags) => ({
+      strict: Boolean(flags["strict"])
+    })
+  });
+}
+var COLOR_MODES = new Set(["auto", "always", "never"]);
+function colorPreset() {
+  return createPreset({
+    id: "color",
+    options: [
+      {
+        flags: "--color [mode]",
+        description: "Color output mode (auto, always, never)",
+        defaultValue: "auto"
+      },
+      {
+        flags: "--no-color",
+        description: "Disable color output"
+      }
+    ],
+    resolve: (flags) => {
+      const raw = flags["color"];
+      if (raw === false)
+        return { color: "never" };
+      if (raw === true)
+        return { color: "always" };
+      if (typeof raw === "string" && COLOR_MODES.has(raw)) {
+        return { color: raw };
+      }
+      return { color: "auto" };
+    }
+  });
+}
+function parseCommaSeparated(value) {
+  if (typeof value !== "string")
+    return;
+  const items = value.split(",").map((s) => s.trim()).filter(Boolean);
+  return items.length > 0 ? items : undefined;
+}
+function projectionPreset() {
+  return createPreset({
+    id: "projection",
+    options: [
+      {
+        flags: "--fields <fields>",
+        description: "Comma-separated list of fields to include"
+      },
+      {
+        flags: "--exclude-fields <fields>",
+        description: "Comma-separated list of fields to exclude"
+      },
+      {
+        flags: "--count",
+        description: "Output only the count of results",
+        defaultValue: false
+      }
+    ],
+    resolve: (flags) => ({
+      fields: parseCommaSeparated(flags["fields"]),
+      excludeFields: parseCommaSeparated(flags["excludeFields"] ?? flags["exclude-fields"]),
+      count: Boolean(flags["count"])
+    })
+  });
+}
+var DURATION_SUFFIXES = {
+  w: 7 * 24 * 60 * 60 * 1000,
+  d: 24 * 60 * 60 * 1000,
+  h: 60 * 60 * 1000,
+  m: 60 * 1000
+};
+function parseDate(value, nowMs = Date.now()) {
+  if (typeof value !== "string" || value === "")
+    return;
+  const durationMatch = value.match(/^(\d+(?:\.\d+)?)(w|d|h|m)$/);
+  if (durationMatch) {
+    const amount = Number(durationMatch[1]);
+    const suffix = durationMatch[2];
+    const multiplier = suffix ? DURATION_SUFFIXES[suffix] : undefined;
+    if (amount > 0 && multiplier !== undefined) {
+      return new Date(nowMs - amount * multiplier);
+    }
+    return;
+  }
+  const date = new Date(value);
+  if (Number.isNaN(date.getTime()))
+    return;
+  return date;
+}
+function sanitizePositiveInteger(value, fallback) {
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed) || parsed <= 0)
+    return fallback;
+  return Math.floor(parsed);
+}
+function timeWindowPreset(config) {
+  return createPreset({
+    id: "timeWindow",
+    options: [
+      {
+        flags: "--since <date>",
+        description: "Start of time window (ISO date or duration: 7d, 24h, 2w)"
+      },
+      {
+        flags: "--until <date>",
+        description: "End of time window (ISO date or duration: 7d, 24h, 2w)"
+      }
+    ],
+    resolve: (flags) => {
+      const now = Date.now();
+      const since = parseDate(flags["since"], now);
+      const until = parseDate(flags["until"], now);
+      if (since && until && typeof config?.maxRange === "number" && Number.isFinite(config.maxRange) && config.maxRange > 0) {
+        const range = Math.abs(until.getTime() - since.getTime());
+        if (range > config.maxRange) {
+          return {
+            since: undefined,
+            until: undefined
+          };
+        }
+      }
+      return { since, until };
+    }
+  });
+}
+function executionPreset(config) {
+  const defaultTimeout = config?.defaultTimeout;
+  const defaultRetries = config?.defaultRetries ?? 0;
+  const maxRetries = config?.maxRetries ?? 10;
+  return createPreset({
+    id: "execution",
+    options: [
+      {
+        flags: "--timeout <ms>",
+        description: "Timeout in milliseconds"
+      },
+      {
+        flags: "--retries <n>",
+        description: `Number of retries (default: ${defaultRetries}, max: ${maxRetries})`
+      },
+      {
+        flags: "--offline",
+        description: "Operate in offline mode",
+        defaultValue: false
+      }
+    ],
+    resolve: (flags) => {
+      let timeout = defaultTimeout;
+      const rawTimeout = flags["timeout"];
+      if (rawTimeout !== undefined) {
+        const parsed = Number(rawTimeout);
+        if (Number.isFinite(parsed) && parsed > 0) {
+          timeout = Math.floor(parsed);
+        } else {
+          timeout = undefined;
+        }
+      }
+      let retries = defaultRetries;
+      const rawRetries = flags["retries"];
+      if (rawRetries !== undefined) {
+        const parsed = Number(rawRetries);
+        if (Number.isFinite(parsed) && parsed >= 0) {
+          retries = Math.min(Math.floor(parsed), maxRetries);
+        }
+      }
+      return {
+        timeout,
+        retries,
+        offline: Boolean(flags["offline"])
+      };
+    }
+  });
+}
+function paginationPreset(config) {
+  const maxLimit = sanitizePositiveInteger(config?.maxLimit, 100);
+  const defaultLimit = Math.min(sanitizePositiveInteger(config?.defaultLimit, 20), maxLimit);
+  return createPreset({
+    id: "pagination",
+    options: [
+      {
+        flags: "-l, --limit <n>",
+        description: `Maximum number of results (default: ${defaultLimit}, max: ${maxLimit})`
+      },
+      {
+        flags: "--next",
+        description: "Continue from last position",
+        defaultValue: false
+      },
+      {
+        flags: "--reset",
+        description: "Clear saved cursor and start fresh",
+        defaultValue: false
+      }
+    ],
+    resolve: (flags) => {
+      let limit = defaultLimit;
+      const rawLimit = flags["limit"];
+      if (rawLimit !== undefined) {
+        const parsed = Number(rawLimit);
+        if (Number.isFinite(parsed) && parsed > 0) {
+          limit = Math.min(Math.floor(parsed), maxLimit);
+        }
+      }
+      return {
+        limit,
+        next: Boolean(flags["next"]),
+        reset: Boolean(flags["reset"])
+      };
+    }
+  });
+}
+
+export { createPreset, composePresets, verbosePreset, cwdPreset, dryRunPreset, forcePreset, interactionPreset, strictPreset, colorPreset, projectionPreset, timeWindowPreset, executionPreset, paginationPreset };

package/dist/shared/@outfitter/{cli-d9ad0rqj.js → cli-jbj78ac5.js}

@@ -1,8 +1,4 @@
 // @bun
-import {
-  __esm
-} from "./cli-v1tzwxkt.js";
-
 // packages/cli/src/terminal/detection.ts
 import { getEnvBoolean } from "@outfitter/config";
 function getEnvValue(key) {
@@ -70,6 +66,5 @@ function isInteractive(options) {
   const isTTY = options?.isTTY ?? process.stdout.isTTY ?? false;
   return isTTY;
 }
-var init_detection = () => {};
 
-export { getEnvValue, hasNoColorEnv, resolveForceColorEnv, resolveColorEnv, supportsColor, getTerminalWidth, isInteractive, init_detection };
+export { getEnvValue, hasNoColorEnv, resolveForceColorEnv, resolveColorEnv, supportsColor, getTerminalWidth, isInteractive };

package/dist/shared/@outfitter/{cli-e6yv2764.d.ts → cli-k0yvzn6d.d.ts}

@@ -1,4 +1,4 @@
-import { OutputOptions } from "./cli-ttt7r0j7";
+import { OutputOptions } from "./cli-md9347gn";
 /**
 * Output data to the console with automatic mode selection.
 *

package/dist/shared/@outfitter/{cli-ttt7r0j7.d.ts → cli-md9347gn.d.ts}

@@ -1,3 +1,4 @@
+import { ActionCliOption } from "@outfitter/contracts";
 import { Command } from "commander";
 import { CancelledError, ErrorCategory, ValidationError } from "@outfitter/contracts";
 import { Result } from "better-result";
@@ -23,7 +24,7 @@ interface CLIConfig {
 	/** Custom error handler */
 	readonly onError?: (error: Error) => void;
 	/** Custom exit handler (defaults to process.exit) */
-	readonly onExit?: (code: number) => never;
+	readonly onExit?: (code: number) => void | Promise<void>;
 }
 /**
 * CLI instance returned by createCLI.
@@ -79,12 +80,164 @@ interface CommandBuilder {
 	requiredOption(flags: string, description: string, defaultValue?: unknown): this;
 	/** Add command aliases */
 	alias(alias: string): this;
+	/** Apply a flag preset (adds its options to the command) */
+	preset(preset: FlagPreset<Record<string, unknown>>): this;
 	/** Set the action handler */
 	action<TFlags extends CommandFlags = CommandFlags>(handler: CommandAction<TFlags>): this;
 	/** Build the underlying Commander command */
 	build(): Command;
 }
 /**
+* A family of related command verbs with a primary name and aliases.
+*/
+interface VerbFamily {
+	/** Primary verb name */
+	readonly primary: string;
+	/** Alternative names for this verb */
+	readonly aliases: readonly string[];
+	/** Description of what this verb family does */
+	readonly description: string;
+}
+/**
+* Configuration for resolving a verb family with project-level overrides.
+*/
+interface VerbConfig {
+	/** Override the primary verb (e.g., "edit" instead of "modify") */
+	readonly primary?: string;
+	/** Whether to include aliases (default: true) */
+	readonly aliases?: boolean;
+	/** Additional aliases beyond defaults */
+	readonly extraAliases?: readonly string[];
+	/** Aliases to exclude */
+	readonly excludeAliases?: readonly string[];
+}
+/**
+* A composable set of CLI flags with typed resolution.
+*
+* Presets bundle flag definitions with a resolver that coerces
+* raw Commander output into typed values.
+*/
+interface FlagPreset<TResolved extends Record<string, unknown>> {
+	/** Unique identifier for deduplication in composePresets */
+	readonly id: string;
+	/** Commander option definitions */
+	readonly options: readonly ActionCliOption[];
+	/** Resolve raw Commander flags into typed values */
+	readonly resolve: (flags: Record<string, unknown>) => TResolved;
+}
+/**
+* Configuration for creating a flag preset.
+*/
+interface FlagPresetConfig<TResolved extends Record<string, unknown>> {
+	/** Unique identifier for deduplication */
+	readonly id: string;
+	/** Commander option definitions */
+	readonly options: readonly ActionCliOption[];
+	/** Resolve raw Commander flags into typed values */
+	readonly resolve: (flags: Record<string, unknown>) => TResolved;
+}
+/**
+* Result of composing multiple presets together.
+* Options are deduplicated by preset id (first wins).
+*/
+type ComposedPreset<TResolved extends Record<string, unknown>> = FlagPreset<TResolved>;
+/**
+* Configuration for the pagination flag preset.
+*/
+interface PaginationPresetConfig {
+	/** Default limit when not specified (default: 20) */
+	readonly defaultLimit?: number;
+	/** Maximum allowed limit (default: 100) */
+	readonly maxLimit?: number;
+}
+/**
+* Resolved interaction flags from CLI input.
+*/
+type InteractionFlags = {
+	/** Whether interactive prompts are allowed */
+	readonly interactive: boolean;
+	/** Whether to auto-confirm prompts */
+	readonly yes: boolean;
+};
+/**
+* Resolved strict mode flags from CLI input.
+*/
+type StrictFlags = {
+	/** Whether strict mode is enabled */
+	readonly strict: boolean;
+};
+/**
+* Resolved time-window flags from CLI input.
+*/
+type TimeWindowFlags = {
+	/** Start of time window */
+	readonly since: Date | undefined;
+	/** End of time window */
+	readonly until: Date | undefined;
+};
+/**
+* Configuration for the time-window flag preset.
+*/
+interface TimeWindowPresetConfig {
+	/** Maximum range in milliseconds between since and until (optional guard) */
+	readonly maxRange?: number;
+}
+/**
+* Resolved execution flags from CLI input.
+*/
+type ExecutionFlags = {
+	/** Timeout in milliseconds (undefined = no timeout) */
+	readonly timeout: number | undefined;
+	/** Number of retries */
+	readonly retries: number;
+	/** Whether to operate in offline mode */
+	readonly offline: boolean;
+};
+/**
+* Configuration for the execution flag preset.
+*/
+interface ExecutionPresetConfig {
+	/** Default timeout in milliseconds (default: undefined) */
+	readonly defaultTimeout?: number;
+	/** Default number of retries (default: 0) */
+	readonly defaultRetries?: number;
+	/** Maximum number of retries (default: 10) */
+	readonly maxRetries?: number;
+}
+/**
+* Resolved projection flags from CLI input.
+*/
+type ProjectionFlags = {
+	/** Fields to include (undefined = all) */
+	readonly fields: string[] | undefined;
+	/** Fields to exclude (undefined = none) */
+	readonly excludeFields: string[] | undefined;
+	/** Whether to output only the count of results */
+	readonly count: boolean;
+};
+/**
+* Color mode for CLI output.
+*/
+type ColorMode = "auto" | "always" | "never";
+/**
+* Resolved color flags from CLI input.
+*/
+type ColorFlags = {
+	/** Color output mode */
+	readonly color: ColorMode;
+};
+/**
+* Resolved pagination flags from CLI input.
+*/
+type PaginationFlags = {
+	/** Number of results to return */
+	readonly limit: number;
+	/** Continue from last position */
+	readonly next: boolean;
+	/** Clear saved cursor and start fresh */
+	readonly reset: boolean;
+};
+/**
 * Available output modes for CLI commands.
 */
 type OutputMode = "human" | "json" | "jsonl" | "tree" | "table";
@@ -164,17 +317,6 @@ interface NormalizeIdOptions {
 	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;
@@ -250,4 +392,4 @@ interface CursorOptions {
 	/** Total count of results (if known) */
 	readonly total?: number;
 }
-export { CLIConfig, CLI, CommandConfig, CommandAction, CommandFlags, CommandBuilder, OutputMode, OutputOptions, CollectIdsOptions, ExpandFileOptions, ParseGlobOptions, NormalizeIdOptions, ConfirmDestructiveOptions, Range, NumericRange, DateRange, FilterExpression, SortCriteria, KeyValuePair, PaginationState, CursorOptions, CancelledError, ErrorCategory, ValidationError, Result };
+export { CLIConfig, CLI, CommandConfig, CommandAction, CommandFlags, CommandBuilder, VerbFamily, VerbConfig, FlagPreset, FlagPresetConfig, ComposedPreset, PaginationPresetConfig, InteractionFlags, StrictFlags, TimeWindowFlags, TimeWindowPresetConfig, ExecutionFlags, ExecutionPresetConfig, ProjectionFlags, ColorMode, ColorFlags, PaginationFlags, OutputMode, OutputOptions, CollectIdsOptions, ExpandFileOptions, ParseGlobOptions, NormalizeIdOptions, Range, NumericRange, DateRange, FilterExpression, SortCriteria, KeyValuePair, PaginationState, CursorOptions, CancelledError, ErrorCategory, ValidationError, Result };