@outfitter/cli 0.4.0 → 0.4.1

package/README.md

@@ -361,6 +361,31 @@ if (flags.reset) {
 }
 ```
 
+## Conventions
+
+Composable flag presets provide typed, reusable CLI flag definitions. See the [full conventions guide](../../docs/CLI-CONVENTIONS.md) for the complete catalog.
+
+```typescript
+import { composePresets, verbosePreset, cwdPreset, forcePreset } from "@outfitter/cli/flags";
+import { outputModePreset } from "@outfitter/cli/query";
+
+const preset = composePresets(verbosePreset(), cwdPreset(), forcePreset());
+
+command("deploy")
+  .preset(preset)
+  .action(async ({ flags }) => {
+    const { verbose, cwd, force } = preset.resolve(flags);
+    // All typed, all composable
+  });
+```
+
+**Available presets:** `verbosePreset`, `cwdPreset`, `dryRunPreset`, `forcePreset`, `interactionPreset`, `strictPreset`, `colorPreset`, `projectionPreset`, `paginationPreset`, `timeWindowPreset`, `executionPreset`, `outputModePreset`, `jqPreset`
+
+**Additional modules:**
+- `@outfitter/cli/verbs` — Standard verb families (`create`, `modify`, `remove`, `list`, `show`)
+- `@outfitter/cli/query` — Output mode and jq expression presets
+- `@outfitter/cli/completion` — Shell completion script generation
+
 ## Configuration
 
 ### Environment Variables

package/dist/cli.d.ts

@@ -1,4 +1,4 @@
-import { CLI, CLIConfig } from "./shared/@outfitter/cli-02kyvj7h";
+import { CLI, CLIConfig } from "./shared/@outfitter/cli-md9347gn";
 /**
 * Create a new CLI instance with the given configuration.
 *

package/dist/command.d.ts

@@ -1,4 +1,4 @@
-import { CLI, CLIConfig, CommandAction, CommandBuilder, CommandConfig, CommandFlags } from "./shared/@outfitter/cli-02kyvj7h";
+import { CLI, CLIConfig, CommandAction, CommandBuilder, CommandConfig, CommandFlags, FlagPreset } from "./shared/@outfitter/cli-md9347gn";
 /**
 * Create a CLI instance with a portable return type from this module.
 */
@@ -40,4 +40,4 @@ declare function createCLI(config: CLIConfig): CLI;
 * ```
 */
 declare function command(name: string): CommandBuilder;
-export { createCLI, command, CommandFlags, CommandConfig, CommandBuilder, CommandAction, CLIConfig, CLI };
+export { createCLI, command, FlagPreset, CommandFlags, CommandConfig, CommandBuilder, CommandAction, CLIConfig, CLI };

package/dist/command.js

@@ -47,6 +47,16 @@ class CommandBuilderImpl {
     this.command.alias(alias);
     return this;
   }
+  preset(preset) {
+    for (const opt of preset.options) {
+      if (opt.required) {
+        this.command.requiredOption(opt.flags, opt.description, opt.defaultValue);
+      } else {
+        this.command.option(opt.flags, opt.description, opt.defaultValue);
+      }
+    }
+    return this;
+  }
   action(handler) {
     this.command.action(async (...args) => {
       const command = args.at(-1);

package/dist/completion.d.ts

@@ -0,0 +1,36 @@
+import { Command } from "commander";
+/**
+* Configuration for the completion command.
+*/
+interface CompletionConfig {
+	/** Supported shells (default: bash, zsh, fish) */
+	readonly shells?: readonly ("bash" | "zsh" | "fish")[];
+	/** Program name for completion scripts (inferred from CLI name if not provided) */
+	readonly programName?: string;
+}
+/**
+* Generate a completion script for the given shell.
+*
+* @param shell - Target shell
+* @param programName - CLI program name
+* @returns The completion script string, or undefined for unsupported shells
+*/
+declare function generateCompletion(shell: string, programName: string): string | undefined;
+/**
+* Create a `completion <shell>` command that outputs install-ready
+* completion scripts.
+*
+* @param config - Optional configuration
+* @returns A Commander command instance
+*
+* @example
+* ```typescript
+* import { createCLI } from "@outfitter/cli";
+* import { createCompletionCommand } from "@outfitter/cli/completion";
+*
+* const cli = createCLI({ name: "mycli", version: "1.0.0" });
+* cli.register(createCompletionCommand({ programName: "mycli" }));
+* ```
+*/
+declare function createCompletionCommand(config?: CompletionConfig): Command;
+export { generateCompletion, createCompletionCommand, CompletionConfig };

package/dist/completion.js

@@ -0,0 +1,91 @@
+// @bun
+// packages/cli/src/completion.ts
+import { Command } from "commander";
+var SHELL_SAFE_PROGRAM_NAME = /^[A-Za-z0-9._-]+$/;
+function assertSafeProgramName(programName) {
+  if (SHELL_SAFE_PROGRAM_NAME.test(programName))
+    return;
+  throw new Error(`Invalid program name for shell completion: "${programName}".` + " Must match /^[A-Za-z0-9._-]+$/.");
+}
+function toShellIdentifier(programName) {
+  assertSafeProgramName(programName);
+  return programName.replaceAll(/[^A-Za-z0-9_]/g, "_");
+}
+function generateBashCompletion(programName) {
+  assertSafeProgramName(programName);
+  const shellIdentifier = toShellIdentifier(programName);
+  return `# bash completion for ${programName}
+# Add to ~/.bashrc or ~/.bash_profile:
+#   eval "$(${programName} completion bash)"
+
+_${shellIdentifier}_completions() {
+  local cur
+  cur="\${COMP_WORDS[COMP_CWORD]}"
+
+  COMPREPLY=( $(compgen -W "$(${programName} --help 2>/dev/null | grep -oE '^  [a-z][-a-z]*' | tr -d ' ')" -- "\${cur}") )
+}
+
+complete -F _${shellIdentifier}_completions ${programName}
+`;
+}
+function generateZshCompletion(programName) {
+  assertSafeProgramName(programName);
+  const shellIdentifier = toShellIdentifier(programName);
+  return `#compdef ${programName}
+# zsh completion for ${programName}
+# Add to ~/.zshrc:
+#   eval "$(${programName} completion zsh)"
+
+_${shellIdentifier}() {
+  local -a commands
+  commands=($(${programName} --help 2>/dev/null | grep -oE '^  [a-z][-a-z]*' | tr -d ' '))
+
+  _arguments \\
+    '1:command:compadd -a commands' \\
+    '*::arg:->args'
+}
+
+compdef _${shellIdentifier} ${programName}
+`;
+}
+function generateFishCompletion(programName) {
+  assertSafeProgramName(programName);
+  return `# fish completion for ${programName}
+# Add to ~/.config/fish/completions/${programName}.fish:
+#   ${programName} completion fish > ~/.config/fish/completions/${programName}.fish
+
+complete -c ${programName} -f
+complete -c ${programName} -n "__fish_use_subcommand" -a "(${programName} --help 2>/dev/null | string match -r '^  [a-z][-a-z]*' | string trim)"
+`;
+}
+var GENERATORS = {
+  bash: generateBashCompletion,
+  zsh: generateZshCompletion,
+  fish: generateFishCompletion
+};
+function generateCompletion(shell, programName) {
+  const generator = Object.hasOwn(GENERATORS, shell) ? GENERATORS[shell] : undefined;
+  return generator?.(programName);
+}
+function createCompletionCommand(config) {
+  const shells = config?.shells ?? ["bash", "zsh", "fish"];
+  const shellSet = new Set(shells);
+  const cmd = new Command("completion").description(`Generate shell completion script (${shells.join(", ")})`).argument("<shell>", `Shell type (${shells.join(", ")})`).action((shell) => {
+    if (!shellSet.has(shell)) {
+      cmd.error(`error: unsupported shell '${shell}'. Supported: ${shells.join(", ")}`);
+      return;
+    }
+    const generator = GENERATORS[shell];
+    if (generator) {
+      const programName = config?.programName ?? cmd.parent?.name() ?? "program";
+      assertSafeProgramName(programName);
+      const script = generator(programName);
+      process.stdout.write(script);
+    }
+  });
+  return cmd;
+}
+export {
+  generateCompletion,
+  createCompletionCommand
+};

package/dist/flags.d.ts

@@ -0,0 +1,167 @@
+import { ColorFlags, ColorMode, ComposedPreset, ExecutionFlags, ExecutionPresetConfig, FlagPreset, FlagPresetConfig, InteractionFlags, PaginationFlags, PaginationPresetConfig, ProjectionFlags, StrictFlags, TimeWindowFlags, TimeWindowPresetConfig } from "./shared/@outfitter/cli-md9347gn";
+/**
+* Create a typed flag preset.
+*
+* @param config - Preset configuration with id, options, and resolver
+* @returns A flag preset that can be applied to commands or composed
+*
+* @example
+* ```typescript
+* const myPreset = createPreset({
+*   id: "output-format",
+*   options: [{ flags: "--format <type>", description: "Output format" }],
+*   resolve: (flags) => ({
+*     format: String(flags["format"] ?? "text"),
+*   }),
+* });
+* ```
+*/
+declare function createPreset<TResolved extends Record<string, unknown>>(config: FlagPresetConfig<TResolved>): FlagPreset<TResolved>;
+type ResolvedType<T> = T extends FlagPreset<infer R> ? R : never;
+type UnionToIntersection<U> = (U extends unknown ? (k: U) => void : never) extends (k: infer I) => void ? I : never;
+/**
+* Resolves the merged type from a tuple of presets.
+* Falls back to Record<string, unknown> when the tuple is empty
+* (since UnionToIntersection<never> produces unknown).
+*/
+type MergedPresetResult<TPresets extends readonly FlagPreset<Record<string, unknown>>[]> = UnionToIntersection<ResolvedType<TPresets[number]>> extends Record<string, unknown> ? UnionToIntersection<ResolvedType<TPresets[number]>> : Record<string, unknown>;
+/**
+* Compose multiple presets into one, deduplicating by id (first wins).
+*
+* @param presets - Presets to compose together
+* @returns A single preset merging all options and resolvers
+*
+* @example
+* ```typescript
+* const composed = composePresets(
+*   verbosePreset(),
+*   cwdPreset(),
+*   forcePreset(),
+* );
+* // composed.resolve({ verbose: true, cwd: "/tmp", force: false })
+* // => { verbose: true, cwd: "/tmp", force: false }
+* ```
+*/
+declare function composePresets<TPresets extends readonly FlagPreset<Record<string, unknown>>[]>(...presets: TPresets): ComposedPreset<MergedPresetResult<TPresets>>;
+/**
+* Verbose output flag preset.
+*
+* Adds: `-v, --verbose`
+* Resolves: `{ verbose: boolean }`
+*/
+declare function verbosePreset(): FlagPreset<{
+	verbose: boolean;
+}>;
+/**
+* Working directory flag preset.
+*
+* Adds: `--cwd <path>`
+* Resolves: `{ cwd: string }` (defaults to `process.cwd()`)
+*/
+declare function cwdPreset(): FlagPreset<{
+	cwd: string;
+}>;
+/**
+* Dry-run flag preset.
+*
+* Adds: `--dry-run`
+* Resolves: `{ dryRun: boolean }`
+*/
+declare function dryRunPreset(): FlagPreset<{
+	dryRun: boolean;
+}>;
+/**
+* Force flag preset.
+*
+* Adds: `-f, --force`
+* Resolves: `{ force: boolean }`
+*/
+declare function forcePreset(): FlagPreset<{
+	force: boolean;
+}>;
+/**
+* Interaction mode flag preset.
+*
+* Adds: `--non-interactive`, `--no-input`, `-y, --yes`
+* Resolves: `{ interactive: boolean, yes: boolean }`
+*
+* `interactive` defaults to `true` and is set to `false` when
+* `--non-interactive` or `--no-input` is passed. The two flags
+* are synonyms for user convenience.
+*/
+declare function interactionPreset(): FlagPreset<InteractionFlags>;
+/**
+* Strict mode flag preset.
+*
+* Adds: `--strict`
+* Resolves: `{ strict: boolean }`
+*/
+declare function strictPreset(): FlagPreset<StrictFlags>;
+/**
+* Color mode flag preset.
+*
+* Adds: `--color [mode]`, `--no-color`
+* Resolves: `{ color: "auto" | "always" | "never" }`
+*
+* Commander's `--no-color` negation sets `flags["color"]` to `false`,
+* which resolves to `"never"`. Invalid values default to `"auto"`.
+*
+* This preset resolves the user's *intent*. Consumers should compose
+* with terminal detection (`supportsColor()`, `resolveColorEnv()`)
+* to determine actual color output behavior.
+*/
+declare function colorPreset(): FlagPreset<ColorFlags>;
+/**
+* Projection flag preset.
+*
+* Adds: `--fields <fields>`, `--exclude-fields <fields>`, `--count`
+* Resolves: `{ fields: string[] | undefined, excludeFields: string[] | undefined, count: boolean }`
+*
+* Fields are parsed as comma-separated strings with whitespace trimming.
+* `undefined` when not provided (not empty array) to distinguish
+* "not specified" from "empty".
+*
+* Conflict between `--fields` and `--exclude-fields` is a handler
+* concern (documented, not enforced).
+*/
+declare function projectionPreset(): FlagPreset<ProjectionFlags>;
+/**
+* Time-window flag preset.
+*
+* Adds: `--since <date>`, `--until <date>`
+* Resolves: `{ since: Date | undefined, until: Date | undefined }`
+*
+* Accepts ISO 8601 dates (`2024-01-15`) or relative durations
+* (`7d`, `24h`, `30m`, `2w`). Durations are past-relative
+* (subtracted from now).
+*
+* Returns `undefined` for unparseable values (does not throw).
+* When `config.maxRange` is set and both bounds are provided,
+* ranges above the limit are treated as invalid.
+*/
+declare function timeWindowPreset(config?: TimeWindowPresetConfig): FlagPreset<TimeWindowFlags>;
+/**
+* Execution flag preset.
+*
+* Adds: `--timeout <ms>`, `--retries <n>`, `--offline`
+* Resolves: `{ timeout: number | undefined, retries: number, offline: boolean }`
+*
+* Timeout is parsed as a positive integer in milliseconds.
+* Retries are parsed as a non-negative integer, clamped to maxRetries.
+*/
+declare function executionPreset(config?: ExecutionPresetConfig): FlagPreset<ExecutionFlags>;
+/**
+* Pagination flag preset.
+*
+* Adds: `-l, --limit <n>`, `--next`, `--reset`
+* Resolves: `{ limit: number, next: boolean, reset: boolean }`
+*
+* Limit is parsed as an integer, clamped to maxLimit, and defaults
+* to defaultLimit on invalid input. Mutual exclusivity of --next
+* and --reset is a handler concern (not enforced here).
+*
+* Integrates with loadCursor/saveCursor/clearCursor from
+* `@outfitter/cli/pagination`.
+*/
+declare function paginationPreset(config?: PaginationPresetConfig): FlagPreset<PaginationFlags>;
+export { verbosePreset, timeWindowPreset, strictPreset, projectionPreset, paginationPreset, interactionPreset, forcePreset, executionPreset, dryRunPreset, cwdPreset, createPreset, composePresets, colorPreset, TimeWindowPresetConfig, TimeWindowFlags, StrictFlags, ProjectionFlags, PaginationPresetConfig, PaginationFlags, InteractionFlags, FlagPresetConfig, FlagPreset, ExecutionPresetConfig, ExecutionFlags, ComposedPreset, ColorMode, ColorFlags };

package/dist/flags.js

@@ -0,0 +1,31 @@
+// @bun
+import {
+  colorPreset,
+  composePresets,
+  createPreset,
+  cwdPreset,
+  dryRunPreset,
+  executionPreset,
+  forcePreset,
+  interactionPreset,
+  paginationPreset,
+  projectionPreset,
+  strictPreset,
+  timeWindowPreset,
+  verbosePreset
+} from "./shared/@outfitter/cli-b2zk8fb3.js";
+export {
+  verbosePreset,
+  timeWindowPreset,
+  strictPreset,
+  projectionPreset,
+  paginationPreset,
+  interactionPreset,
+  forcePreset,
+  executionPreset,
+  dryRunPreset,
+  cwdPreset,
+  createPreset,
+  composePresets,
+  colorPreset
+};

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import "./shared/@outfitter/cli-qz47jk6d";
 import { ANSI, Theme, Tokens, createTheme } from "./shared/@outfitter/cli-xppg982q";
-import { output } from "./shared/@outfitter/cli-f79bwzsp";
-import { OutputMode } from "./shared/@outfitter/cli-02kyvj7h";
-export { output, createTheme, Tokens, Theme, OutputMode, ANSI };
+import { exitWithError, output } from "./shared/@outfitter/cli-k0yvzn6d";
+import { OutputMode } from "./shared/@outfitter/cli-md9347gn";
+export { output, exitWithError, createTheme, Tokens, Theme, OutputMode, ANSI };

package/dist/index.js

@@ -6,10 +6,12 @@ import {
 } from "./shared/@outfitter/cli-rk9zagkm.js";
 import"./shared/@outfitter/cli-jbj78ac5.js";
 import {
+  exitWithError,
   output
 } from "./shared/@outfitter/cli-7wp5nj0s.js";
 export {
   output,
+  exitWithError,
   createTheme,
   ANSI
 };

package/dist/input.d.ts

@@ -1,4 +1,4 @@
-import { CollectIdsOptions, ExpandFileOptions, FilterExpression, KeyValuePair, NormalizeIdOptions, ParseGlobOptions, Range, SortCriteria } from "./shared/@outfitter/cli-02kyvj7h";
+import { CollectIdsOptions, ExpandFileOptions, FilterExpression, KeyValuePair, NormalizeIdOptions, ParseGlobOptions, Range, SortCriteria } from "./shared/@outfitter/cli-md9347gn";
 import { ValidationError } from "@outfitter/contracts";
 import { Result } from "better-result";
 /**

package/dist/output.d.ts

@@ -1,3 +1,3 @@
-import { exitWithError, output, resolveVerbose } from "./shared/@outfitter/cli-f79bwzsp";
-import "./shared/@outfitter/cli-02kyvj7h";
+import { exitWithError, output, resolveVerbose } from "./shared/@outfitter/cli-k0yvzn6d";
+import "./shared/@outfitter/cli-md9347gn";
 export { resolveVerbose, output, exitWithError };

package/dist/pagination.d.ts

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

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-f79bwzsp.d.ts → cli-k0yvzn6d.d.ts}

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

package/dist/shared/@outfitter/{cli-02kyvj7h.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";
@@ -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";
@@ -239,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, 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 };

package/dist/types.d.ts

@@ -1,2 +1,2 @@
-import { CLI, CLIConfig, CancelledError, CollectIdsOptions, CommandAction, CommandBuilder, CommandConfig, CommandFlags, CursorOptions, DateRange, ErrorCategory, ExpandFileOptions, FilterExpression, KeyValuePair, NormalizeIdOptions, NumericRange, OutputMode, OutputOptions, PaginationState, ParseGlobOptions, Range, Result, SortCriteria, ValidationError } from "./shared/@outfitter/cli-02kyvj7h";
-export { ValidationError, SortCriteria, Result, Range, ParseGlobOptions, PaginationState, OutputOptions, OutputMode, NumericRange, NormalizeIdOptions, KeyValuePair, FilterExpression, ExpandFileOptions, ErrorCategory, DateRange, CursorOptions, CommandFlags, CommandConfig, CommandBuilder, CommandAction, CollectIdsOptions, CancelledError, CLIConfig, CLI };
+import { CLI, CLIConfig, CancelledError, CollectIdsOptions, ColorFlags, ColorMode, CommandAction, CommandBuilder, CommandConfig, CommandFlags, ComposedPreset, CursorOptions, DateRange, ErrorCategory, ExecutionFlags, ExecutionPresetConfig, ExpandFileOptions, FilterExpression, FlagPreset, FlagPresetConfig, InteractionFlags, KeyValuePair, NormalizeIdOptions, NumericRange, OutputMode, OutputOptions, PaginationFlags, PaginationPresetConfig, PaginationState, ParseGlobOptions, ProjectionFlags, Range, Result, SortCriteria, StrictFlags, TimeWindowFlags, TimeWindowPresetConfig, ValidationError, VerbConfig, VerbFamily } from "./shared/@outfitter/cli-md9347gn";
+export { VerbFamily, VerbConfig, ValidationError, TimeWindowPresetConfig, TimeWindowFlags, StrictFlags, SortCriteria, Result, Range, ProjectionFlags, ParseGlobOptions, PaginationState, PaginationPresetConfig, PaginationFlags, OutputOptions, OutputMode, NumericRange, NormalizeIdOptions, KeyValuePair, InteractionFlags, FlagPresetConfig, FlagPreset, FilterExpression, ExpandFileOptions, ExecutionPresetConfig, ExecutionFlags, ErrorCategory, DateRange, CursorOptions, ComposedPreset, CommandFlags, CommandConfig, CommandBuilder, CommandAction, ColorMode, ColorFlags, CollectIdsOptions, CancelledError, CLIConfig, CLI };

package/dist/verbs.d.ts

@@ -0,0 +1,50 @@
+import { CommandBuilder, VerbConfig, VerbFamily } from "./shared/@outfitter/cli-md9347gn";
+/**
+* Built-in verb families with standard primary verbs and aliases.
+*
+* These follow POSIX and modern CLI conventions:
+* - `create` / `new` — Create a new resource
+* - `modify` / `edit` / `update` — Modify an existing resource
+* - `remove` / `delete` / `rm` — Remove a resource
+* - `list` / `ls` — List resources
+* - `show` / `get` / `view` — Show resource details
+*/
+declare const VERB_FAMILIES: Readonly<Record<string, VerbFamily>>;
+/**
+* Resolve a verb family with optional project-level config overrides.
+*
+* @param family - Name of the verb family (e.g., "create", "modify")
+* @param config - Optional overrides for primary verb, aliases, etc.
+* @returns Resolved verb name and aliases
+*
+* @example
+* ```typescript
+* resolveVerb("modify"); // { name: "modify", aliases: ["edit", "update"] }
+* resolveVerb("modify", { primary: "edit" }); // { name: "edit", aliases: ["update"] }
+* resolveVerb("remove", { aliases: false }); // { name: "remove", aliases: [] }
+* ```
+*/
+declare function resolveVerb(family: string, config?: VerbConfig): {
+	name: string;
+	aliases: string[];
+};
+/**
+* Apply verb conventions to a CommandBuilder.
+*
+* Adds aliases from the resolved verb family to the command builder.
+*
+* @param builder - CommandBuilder to apply aliases to
+* @param family - Name of the verb family
+* @param config - Optional overrides
+* @returns The builder for chaining
+*
+* @example
+* ```typescript
+* const cmd = command("remove <id>")
+*   .description("Remove a resource");
+* applyVerb(cmd, "remove");
+* // Adds aliases: "delete", "rm"
+* ```
+*/
+declare function applyVerb(builder: CommandBuilder, family: string, config?: VerbConfig): CommandBuilder;
+export { resolveVerb, applyVerb, VERB_FAMILIES };

package/dist/verbs.js

@@ -0,0 +1,61 @@
+// @bun
+// packages/cli/src/verbs.ts
+var VERB_FAMILIES = {
+  create: {
+    primary: "create",
+    aliases: ["new"],
+    description: "Create a new resource"
+  },
+  modify: {
+    primary: "modify",
+    aliases: ["edit", "update"],
+    description: "Modify a resource"
+  },
+  remove: {
+    primary: "remove",
+    aliases: ["delete", "rm"],
+    description: "Remove a resource"
+  },
+  list: {
+    primary: "list",
+    aliases: ["ls"],
+    description: "List resources"
+  },
+  show: {
+    primary: "show",
+    aliases: ["get", "view"],
+    description: "Show details"
+  }
+};
+function resolveVerb(family, config) {
+  const def = VERB_FAMILIES[family];
+  if (!Object.hasOwn(VERB_FAMILIES, family) || def === undefined) {
+    throw new Error(`Unknown verb family: "${family}"`);
+  }
+  const name = config?.primary ?? def.primary;
+  if (config?.aliases === false) {
+    return { name, aliases: [] };
+  }
+  let aliases = [...def.aliases].filter((a) => a !== name);
+  if (config?.extraAliases) {
+    aliases.push(...config.extraAliases);
+  }
+  if (config?.excludeAliases) {
+    const exclude = new Set(config.excludeAliases);
+    aliases = aliases.filter((a) => !exclude.has(a));
+  }
+  aliases = [...new Set(aliases)];
+  return { name, aliases };
+}
+function applyVerb(builder, family, config) {
+  const { aliases } = resolveVerb(family, config);
+  for (const alias of aliases) {
+    builder.alias(alias);
+  }
+  return builder;
+}
+export {
+  resolveVerb,
+  applyVerb,
+  VERB_FAMILIES
+};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@outfitter/cli",
   "description": "Typed CLI runtime with terminal detection, rendering, output contracts, and input parsing",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "type": "module",
   "files": [
     "dist"
@@ -33,6 +33,18 @@
         "default": "./dist/command.js"
       }
     },
+    "./completion": {
+      "import": {
+        "types": "./dist/completion.d.ts",
+        "default": "./dist/completion.js"
+      }
+    },
+    "./flags": {
+      "import": {
+        "types": "./dist/flags.d.ts",
+        "default": "./dist/flags.js"
+      }
+    },
     "./input": {
       "import": {
         "types": "./dist/input.d.ts",
@@ -52,6 +64,12 @@
         "default": "./dist/pagination.js"
       }
     },
+    "./query": {
+      "import": {
+        "types": "./dist/query.d.ts",
+        "default": "./dist/query.js"
+      }
+    },
     "./terminal": {
       "import": {
         "types": "./dist/terminal/index.d.ts",
@@ -75,6 +93,12 @@
         "types": "./dist/types.d.ts",
         "default": "./dist/types.js"
       }
+    },
+    "./verbs": {
+      "import": {
+        "types": "./dist/verbs.d.ts",
+        "default": "./dist/verbs.js"
+      }
     }
   },
   "sideEffects": false,