@outfitter/cli 0.5.2 → 1.0.0

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

@@ -0,0 +1,106 @@
+// @bun
+import {
+  createPreset
+} from "./cli-8999qjdd.js";
+
+// packages/cli/src/query.ts
+function argvContainsOutputFlag(argv) {
+  for (const arg of argv) {
+    if (!arg)
+      continue;
+    if (arg === "-o" || arg === "--output")
+      return true;
+    if (arg.startsWith("--output=") || arg.startsWith("-o="))
+      return true;
+  }
+  return false;
+}
+function hasExplicitOutputFlag(flags, config) {
+  const mode = flags["output"];
+  if (typeof mode !== "string")
+    return false;
+  const defaultMode = config?.defaultMode ?? "human";
+  if (mode !== defaultMode)
+    return true;
+  return argvContainsOutputFlag(config?.argv ?? process.argv.slice(2));
+}
+function resolveOutputMode(flags, config) {
+  const defaultMode = config?.defaultMode ?? "human";
+  if (hasExplicitOutputFlag(flags, config)) {
+    const raw = flags["output"];
+    const mode = raw === "json" || raw === "jsonl" || raw === "human" ? raw : defaultMode;
+    return { mode, source: "flag" };
+  }
+  if (flags["json"] === true)
+    return { mode: "json", source: "flag" };
+  if (flags["jsonl"] === true)
+    return { mode: "jsonl", source: "flag" };
+  if (config?.forceHumanWhenImplicit) {
+    return { mode: defaultMode, source: "default" };
+  }
+  if (process.env["OUTFITTER_JSONL"] === "1") {
+    return { mode: "jsonl", source: "env" };
+  }
+  if (process.env["OUTFITTER_JSON"] === "1") {
+    return { mode: "json", source: "env" };
+  }
+  return { mode: defaultMode, source: "default" };
+}
+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 streamPreset() {
+  return createPreset({
+    id: "stream",
+    options: [
+      {
+        flags: "--stream",
+        description: "Stream progress events as NDJSON to stdout",
+        defaultValue: false
+      }
+    ],
+    resolve: (flags) => ({
+      stream: Boolean(flags["stream"])
+    })
+  });
+}
+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 { resolveOutputMode, outputModePreset, streamPreset, jqPreset };

package/dist/shared/@outfitter/cli-wjv7g1aq.d.ts

@@ -0,0 +1,16 @@
+/**
+* Types for schema introspection commands.
+*
+* @internal
+*/
+/** Options for surface map subcommands (generate, diff). */
+interface SurfaceCommandOptions {
+	readonly cwd?: string;
+	readonly outputDir?: string;
+}
+/** Options for the schema Commander command. */
+interface SchemaCommandOptions {
+	readonly programName?: string;
+	readonly surface?: SurfaceCommandOptions;
+}
+export { SurfaceCommandOptions, SchemaCommandOptions };

package/dist/shared/@outfitter/{cli-98aa9104.d.ts → cli-x6qr7bnd.d.ts}

@@ -1,4 +1,4 @@
-import { ActionCliOption } from "@outfitter/contracts";
+import { ActionCliOption, CLIHint } from "@outfitter/contracts";
 import { Command } from "commander";
 import { CancelledError, ErrorCategory, ValidationError } from "@outfitter/contracts";
 import { Result } from "better-result";
@@ -51,17 +51,59 @@ interface CommandConfig {
 	readonly name: string;
 }
 /**
+* Factory function for constructing command context.
+*
+* Called after schema validation (if `.input()` is used), before the handler.
+* When `.input()` is used, receives the validated typed input.
+* When `.input()` is not used, receives the raw parsed flags.
+*
+* @typeParam TInput - Type of validated input (from .input() schema)
+* @typeParam TContext - Type of the constructed context object
+*/
+type ContextFactory<
+	TInput,
+	TContext
+> = (input: TInput extends undefined ? Record<string, unknown> : TInput) => Promise<TContext> | TContext;
+/**
+* Success hint function for transport-local hint generation.
+*
+* Called at output time (not during handler execution) with the handler's
+* result and the validated input. Returns CLI-specific hints for the response.
+*
+* @typeParam TInput - Type of validated input (from .input() schema)
+*/
+type SuccessHintFn<TInput = undefined> = (result: unknown, input: TInput extends undefined ? Record<string, unknown> : TInput) => CLIHint[];
+/**
+* Error hint function for transport-local error hint generation.
+*
+* Called at output time (not during handler execution) with the error
+* and the validated input. Returns CLI-specific hints for error recovery.
+*
+* @typeParam TInput - Type of validated input (from .input() schema)
+*/
+type ErrorHintFn<TInput = undefined> = (error: unknown, input: TInput extends undefined ? Record<string, unknown> : TInput) => CLIHint[];
+/**
 * Action function executed when a command is invoked.
 *
 * @typeParam TFlags - Type of parsed command flags
-*/
-type CommandAction<TFlags extends CommandFlags = CommandFlags> = (context: {
+* @typeParam TInput - Type of validated input (from .input() schema)
+* @typeParam TContext - Type of context object (from .context() factory)
+*/
+type CommandAction<
+	TFlags extends CommandFlags = CommandFlags,
+	TInput = undefined,
+	TContext = undefined
+> = (context: {
 	/** Parsed command-line arguments */
 	readonly args: readonly string[];
-	/** Parsed command flags */
-	readonly flags: TFlags;
 	/** Raw Commander command instance */
 	readonly command: Command;
+	/** Context object constructed by .context() factory (undefined when .context() is not used) */
+	readonly ctx: TContext;
+	/** Parsed command flags */
+	readonly flags: TFlags;
+	/** Validated input from Zod schema (present when .input() is used) */
+	readonly input: TInput;
 }) => Promise<void> | void;
 /**
 * Base type for command flags.
@@ -70,24 +112,250 @@ type CommandAction<TFlags extends CommandFlags = CommandFlags> = (context: {
 type CommandFlags = Record<string, unknown>;
 /**
 * Builder interface for constructing commands fluently.
+*
+* @typeParam TInput - Type of validated input when .input() is used
+* @typeParam TContext - Type of context object when .context() is used
 */
-interface CommandBuilder {
+interface CommandBuilder<
+	TInput = undefined,
+	TContext = undefined
+> {
 	/** Set the action handler */
-	action<TFlags extends CommandFlags = CommandFlags>(handler: CommandAction<TFlags>): this;
+	action<TFlags extends CommandFlags = CommandFlags>(handler: CommandAction<TFlags, TInput, TContext>): this;
 	/** Add command aliases */
 	alias(alias: string): this;
 	/** Build the underlying Commander command */
 	build(): Command;
+	/**
+	* Set an async context factory.
+	*
+	* The factory is called after schema validation (if `.input()` is used),
+	* before the handler. It receives the validated typed input (or raw parsed
+	* flags when `.input()` is not used) and returns a typed context object.
+	*
+	* Context factory errors are caught and produce proper exit codes.
+	*
+	* @typeParam T - Type of the context object returned by the factory
+	*
+	* @example
+	* ```typescript
+	* command("deploy")
+	*   .input(z.object({ env: z.string() }))
+	*   .context(async (input) => ({
+	*     config: await loadConfig(input.env),
+	*     client: createClient(input.env),
+	*   }))
+	*   .action(async ({ input, ctx }) => {
+	*     await ctx.client.deploy(ctx.config);
+	*   });
+	* ```
+	*/
+	context<T>(factory: ContextFactory<TInput, T>): CommandBuilder<TInput, T>;
 	/** Set command description */
 	description(text: string): this;
+	/**
+	* Mark the command as destructive.
+	*
+	* When `isDest` is `true`, a `--dry-run` flag is auto-added to the command
+	* (deduplicated if already present from `.option()` or `.preset()`).
+	* The handler is responsible for checking the dry-run flag and performing
+	* preview-only logic when active.
+	*
+	* When used with `runHandler({ dryRun: true })`, the response envelope
+	* includes a CLIHint with the command to execute without `--dry-run`
+	* (preview-then-commit pattern).
+	*
+	* Default (no `.destructive()` call) is non-destructive.
+	*
+	* @param isDest - Whether the command is destructive
+	*
+	* @example
+	* ```typescript
+	* command("delete")
+	*   .description("Delete resources")
+	*   .destructive(true)
+	*   .action(async ({ flags }) => {
+	*     const isDryRun = Boolean(flags.dryRun);
+	*     await runHandler({
+	*       command: "delete",
+	*       handler: async (input) => isDryRun
+	*         ? Result.ok({ preview: true, count: 5 })
+	*         : deleteResources(input),
+	*       dryRun: isDryRun,
+	*     });
+	*   });
+	* ```
+	*/
+	destructive(isDest: boolean): this;
+	/**
+	* Mark the command as idempotent.
+	*
+	* When `true`, indicates that calling this command multiple times with the
+	* same input produces the same effect (PUT-like semantics). This metadata
+	* is included in the self-documenting command tree (JSON mode) and maps to
+	* `idempotentHint` in MCP tool annotations.
+	*
+	* Default (no `.idempotent()` call) is non-idempotent.
+	*
+	* @param isIdempotent - Whether the command is idempotent
+	*
+	* @example
+	* ```typescript
+	* command("set")
+	*   .description("Set a configuration value")
+	*   .idempotent(true)
+	*   .action(async ({ flags }) => { ... });
+	* ```
+	*/
+	idempotent(isIdempotent: boolean): this;
+	/**
+	* Set a success hint function.
+	*
+	* The hint function is stored on the builder and invoked at output time
+	* (not during handler execution). It receives the handler's result and the
+	* validated input (or raw flags when `.input()` is not used), and returns
+	* CLI-specific hints for the response.
+	*
+	* Hint functions are transport-local — handlers remain transport-agnostic.
+	*
+	* @example
+	* ```typescript
+	* command("deploy")
+	*   .input(z.object({ env: z.string() }))
+	*   .hints((result, input) => [
+	*     {
+	*       description: `Check status for ${input.env}`,
+	*       command: `deploy status --env ${input.env}`,
+	*     },
+	*   ])
+	*   .action(async ({ input }) => { ... });
+	* ```
+	*/
+	hints(fn: SuccessHintFn<TInput>): this;
+	/**
+	* Set a Zod object schema for auto-deriving Commander flags.
+	*
+	* Handles the 80% case automatically:
+	* - `z.string()` → string option
+	* - `z.number()` → number option with coercion
+	* - `z.boolean()` → boolean flag
+	* - `z.enum()` → choices option
+	*
+	* `.describe()` text becomes the option description.
+	* `.default()` values become option defaults.
+	*
+	* Explicit `.option()` / `.requiredOption()` / `.argument()` calls
+	* compose alongside `.input()` — they override or supplement auto-derived flags.
+	*/
+	input<T extends Record<string, unknown>>(schema: ZodObjectLike<T>): CommandBuilder<T, TContext>;
+	/**
+	* Set an error hint function.
+	*
+	* The hint function is stored on the builder and invoked at output time
+	* (not during handler execution). It receives the error and the validated
+	* input (or raw flags when `.input()` is not used), and returns CLI-specific
+	* hints for error recovery.
+	*
+	* Hint functions are transport-local — handlers remain transport-agnostic.
+	*
+	* @example
+	* ```typescript
+	* command("deploy")
+	*   .input(z.object({ env: z.string() }))
+	*   .onError((error, input) => [
+	*     {
+	*       description: "Retry with --force",
+	*       command: `deploy --env ${input.env} --force`,
+	*     },
+	*   ])
+	*   .action(async ({ input }) => { ... });
+	* ```
+	*/
+	onError(fn: ErrorHintFn<TInput>): this;
+	/**
+	* Declare a relationship to another command for action graph navigation.
+	*
+	* Relationships build a navigable action graph (tier-4 hints) that agents
+	* use to discover workflows. Success envelopes include related next-actions
+	* from graph neighbors; error envelopes include remediation paths.
+	*
+	* Multiple `.relatedTo()` calls accumulate — each declares a separate edge.
+	*
+	* @param target - Name of the related command
+	* @param options - Optional relationship metadata (description)
+	*
+	* @example
+	* ```typescript
+	* command("deploy")
+	*   .description("Deploy application")
+	*   .relatedTo("status", { description: "Check deployment status" })
+	*   .relatedTo("rollback", { description: "Rollback if needed" })
+	*   .action(async ({ flags }) => { ... });
+	* ```
+	*/
+	relatedTo(target: string, options?: RelatedToOptions): this;
 	/** Add a command option/flag */
 	option(flags: string, description: string, defaultValue?: unknown): this;
-	/** Apply a flag preset (adds its options to the command) */
-	preset(preset: FlagPreset<Record<string, unknown>>): this;
+	/**
+	* Mark the command as read-only.
+	*
+	* When `true`, indicates that this command does not modify any state.
+	* This metadata is included in the self-documenting command tree (JSON mode)
+	* and maps to `readOnlyHint` in MCP tool annotations.
+	*
+	* Default (no `.readOnly()` call) is non-read-only.
+	*
+	* @param isReadOnly - Whether the command is read-only
+	*
+	* @example
+	* ```typescript
+	* command("list")
+	*   .description("List all resources")
+	*   .readOnly(true)
+	*   .action(async ({ flags }) => { ... });
+	* ```
+	*/
+	readOnly(isReadOnly: boolean): this;
+	/**
+	* Apply a preset to the command.
+	*
+	* Accepts either a `FlagPreset` (Commander option definitions with resolver)
+	* or a `SchemaPreset` (Zod schema fragment with resolver). Schema presets
+	* auto-derive Commander flags from the schema, composing with `.input()`.
+	*/
+	preset(preset: AnyPreset<Record<string, unknown>>): this;
 	/** Add a required option */
 	requiredOption(flags: string, description: string, defaultValue?: unknown): this;
 }
 /**
+* Options for declaring a command relationship via `.relatedTo()`.
+*/
+interface RelatedToOptions {
+	/** Description of the relationship (used in hints) */
+	readonly description?: string;
+}
+/**
+* A stored relationship declaration from `.relatedTo()`.
+*/
+interface RelatedToDeclaration {
+	/** Target command name */
+	readonly target: string;
+	/** Description of the relationship */
+	readonly description?: string;
+}
+/**
+* Minimal interface for a Zod-like object schema.
+* Avoids tight coupling to a specific Zod version.
+*/
+interface ZodObjectLike<T extends Record<string, unknown> = Record<string, unknown>> {
+	readonly shape: Record<string, unknown>;
+	safeParse(data: unknown): {
+		success: boolean;
+		data?: T;
+		error?: unknown;
+	};
+}
+/**
 * A family of related command verbs with a primary name and aliases.
 */
 interface VerbFamily {
@@ -137,6 +405,39 @@ interface FlagPresetConfig<TResolved extends Record<string, unknown>> {
 	readonly resolve: (flags: Record<string, unknown>) => TResolved;
 }
 /**
+* A schema-driven preset that uses a Zod schema fragment for flag derivation.
+*
+* Instead of declaring Commander options manually, the schema fragment is
+* introspected to auto-derive flags (same as `.input()`). The schema merges
+* with `.input()` schema automatically when both are used.
+*
+* Eliminates the need for separate `.resolve()` / `preAction` hooks.
+*/
+interface SchemaPreset<TResolved extends Record<string, unknown>> {
+	/** Unique identifier for deduplication */
+	readonly id: string;
+	/** Resolve raw Commander flags into typed values */
+	readonly resolve: (flags: Record<string, unknown>) => TResolved;
+	/** Zod schema fragment defining the preset's flags */
+	readonly schema: ZodObjectLike;
+}
+/**
+* Configuration for creating a schema-driven preset.
+*/
+interface SchemaPresetConfig<TResolved extends Record<string, unknown>> {
+	/** Unique identifier for deduplication */
+	readonly id: string;
+	/** Resolve raw Commander flags into typed values */
+	readonly resolve: (flags: Record<string, unknown>) => TResolved;
+	/** Zod schema fragment defining the preset's flags */
+	readonly schema: ZodObjectLike;
+}
+/**
+* Union type for any preset accepted by `.preset()`.
+* Includes both flag-based presets and schema-driven presets.
+*/
+type AnyPreset<TResolved extends Record<string, unknown> = Record<string, unknown>> = FlagPreset<TResolved> | SchemaPreset<TResolved>;
+/**
 * Configuration for creating a custom boolean flag preset.
 */
 interface BooleanFlagPresetConfig<TKey extends string> {
@@ -340,12 +641,37 @@ type OutputMode = "human" | "json" | "jsonl" | "tree" | "table";
 interface OutputOptions {
 	/** Exit code to use after output (undefined = don't exit) */
 	readonly exitCode?: number;
-	/** Force a specific output mode (overrides flag detection) */
-	readonly mode?: OutputMode;
 	/** Whether to pretty-print JSON output */
 	readonly pretty?: boolean;
 	/** Stream to write to (defaults to stdout) */
 	readonly stream?: NodeJS.WritableStream;
+	/**
+	* Optional truncation configuration metadata.
+	*
+	* `output()` applies array slicing when this option is provided.
+	* For array data, it uses `offset` + `limit` before rendering.
+	*
+	* If you need pagination hints or file-pointer metadata, call
+	* `truncateOutput()` first and pass `truncated.hints` / `truncated.metadata`
+	* through your envelope separately.
+	*
+	* @example
+	* ```typescript
+	* await output(items, "json", {
+	*   truncation: { limit: 50, offset: 0 },
+	* });
+	* ```
+	*/
+	readonly truncation?: {
+		/** Command name for pagination hints (used by `truncateOutput()`, not `output()`). */
+		readonly commandName?: string;
+		/** File-pointer threshold (used by `truncateOutput()`, not `output()`). */
+		readonly filePointerThreshold?: number;
+		/** Maximum items to show. */
+		readonly limit: number;
+		/** Starting offset (0-based). */
+		readonly offset?: number;
+	};
 }
 /**
 * Options for collectIds() input utility.
@@ -361,12 +687,8 @@ interface OutputOptions {
 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.
@@ -485,4 +807,4 @@ interface CursorOptions {
 	/** Total count of results (if known) */
 	readonly total?: number;
 }
-export { CLIConfig, CLI, CommandConfig, CommandAction, CommandFlags, CommandBuilder, VerbFamily, VerbConfig, FlagPreset, FlagPresetConfig, BooleanFlagPresetConfig, EnumFlagPresetConfig, NumberFlagPresetConfig, StringListFlagPresetConfig, 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 };
+export { CLIConfig, CLI, CommandConfig, ContextFactory, SuccessHintFn, ErrorHintFn, CommandAction, CommandFlags, CommandBuilder, RelatedToOptions, RelatedToDeclaration, ZodObjectLike, VerbFamily, VerbConfig, FlagPreset, FlagPresetConfig, SchemaPreset, SchemaPresetConfig, AnyPreset, BooleanFlagPresetConfig, EnumFlagPresetConfig, NumberFlagPresetConfig, StringListFlagPresetConfig, 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-xde45xcc.d.ts

@@ -0,0 +1,53 @@
+import { CLI, CLIConfig, CommandBuilder } from "./cli-x6qr7bnd.js";
+/**
+* Command metadata for safety signals (readOnly, idempotent).
+* Stored on Commander commands and surfaced in the command tree.
+*/
+interface CommandMetadata {
+	/** When true, the command does not modify any state */
+	readonly readOnly?: boolean;
+	/** When true, calling the command multiple times with the same input has the same effect */
+	readonly idempotent?: boolean;
+}
+/**
+* Create a CLI instance with a portable return type from this module.
+*/
+declare function createCLI(config: CLIConfig): CLI;
+/**
+* Create a new command builder with the given name.
+*
+* The command builder provides a fluent API for defining CLI commands
+* with typed flags, arguments, and actions.
+*
+* @param name - Command name and optional argument syntax (e.g., "list" or "get <id>")
+* @returns A CommandBuilder instance for fluent configuration
+*
+* @example
+* ```typescript
+* import { command, output } from "@outfitter/cli";
+*
+* const list = command("list")
+*   .description("List all notes")
+*   .option("--limit <n>", "Max results", "20")
+*   .option("--json", "Output as JSON")
+*   .option("--next", "Continue from last position")
+*   .action(async ({ flags }) => {
+*     const results = await listNotes(flags);
+*     output(results);
+*   });
+* ```
+*
+* @example
+* ```typescript
+* // Command with required argument
+* const get = command("get <id>")
+*   .description("Get a note by ID")
+*   .action(async ({ args }) => {
+*     const [id] = args;
+*     const note = await getNote(id);
+*     output(note);
+*   });
+* ```
+*/
+declare function command(name: string): CommandBuilder;
+export { CommandMetadata, createCLI, command };