@outfitter/cli 0.4.0 → 0.5.0

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/shared/@outfitter/cli-n1k0d23k.d.ts

@@ -0,0 +1,33 @@
+import { ActionManifest, ActionSource } from "@outfitter/schema";
+import { Command } from "commander";
+import { ActionManifest as ActionManifest2, ActionManifestEntry, ActionSource as ActionSource2, GenerateManifestOptions } from "@outfitter/schema";
+import { generateManifest } from "@outfitter/schema";
+interface SurfaceCommandOptions {
+	readonly cwd?: string;
+	readonly outputDir?: string;
+}
+interface SchemaCommandOptions {
+	readonly programName?: string;
+	readonly surface?: SurfaceCommandOptions;
+}
+/**
+* Format a manifest for human-readable terminal output.
+*
+* @param manifest - The manifest to format
+* @param programName - CLI program name (for header)
+* @param actionId - If provided, show detail for this single action
+* @returns Formatted string
+*/
+declare function formatManifestHuman(manifest: ActionManifest, programName?: string, actionId?: string): string;
+/**
+* Create a `schema` command for CLI introspection.
+*
+* When `options.surface` is provided, adds `generate` and `diff` subcommands
+* for surface map file I/O and drift detection.
+*
+* @param source - ActionRegistry or array of ActionSpec
+* @param options - Command configuration
+* @returns A Commander command instance
+*/
+declare function createSchemaCommand(source: ActionSource, options?: SchemaCommandOptions): Command;
+export { SurfaceCommandOptions, SchemaCommandOptions, formatManifestHuman, createSchemaCommand, ActionManifest2 as ActionManifest, ActionManifestEntry, ActionSource2 as ActionSource, GenerateManifestOptions, generateManifest };

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.5.0",
   "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,18 @@
         "default": "./dist/pagination.js"
       }
     },
+    "./query": {
+      "import": {
+        "types": "./dist/query.d.ts",
+        "default": "./dist/query.js"
+      }
+    },
+    "./schema": {
+      "import": {
+        "types": "./dist/schema.d.ts",
+        "default": "./dist/schema.js"
+      }
+    },
     "./terminal": {
       "import": {
         "types": "./dist/terminal/index.d.ts",
@@ -75,6 +99,12 @@
         "types": "./dist/types.d.ts",
         "default": "./dist/types.js"
       }
+    },
+    "./verbs": {
+      "import": {
+        "types": "./dist/verbs.d.ts",
+        "default": "./dist/verbs.js"
+      }
     }
   },
   "sideEffects": false,
@@ -95,12 +125,14 @@
   "peerDependencies": {
     "@outfitter/config": ">=0.3.0",
     "@outfitter/contracts": ">=0.2.0",
+    "@outfitter/schema": ">=0.1.0",
     "@outfitter/types": ">=0.2.0",
     "zod": "^4.3.5"
   },
   "devDependencies": {
-    "@outfitter/config": "0.3.1",
-    "@outfitter/contracts": "0.3.0",
+    "@outfitter/config": "0.3.2",
+    "@outfitter/contracts": "0.4.0",
+    "@outfitter/schema": "0.2.0",
     "@types/bun": "^1.3.7",
     "@types/node": "^25.0.10",
     "typescript": "^5.9.3"