@outfitter/cli 0.4.1 → 0.5.1

package/README.md

@@ -486,7 +486,7 @@ import type { PaginationState, CursorOptions } from "@outfitter/cli/pagination";
 
 ## Upgrading
 
-Run `outfitter update --guide` for version-specific migration instructions, or check the [migration docs](https://github.com/outfitter-dev/outfitter/tree/main/plugins/outfitter/shared/migrations) for detailed upgrade steps.
+Run `outfitter upgrade --guide` for version-specific migration instructions, or check the [migration docs](https://github.com/outfitter-dev/outfitter/tree/main/plugins/outfitter/shared/migrations) for detailed upgrade steps.
 
 ## License
 

package/dist/actions.d.ts

@@ -1,4 +1,6 @@
-import { ActionRegistry, ActionSurface, AnyActionSpec, HandlerContext } from "@outfitter/contracts";
+import { SchemaCommandOptions } from "./shared/@outfitter/cli-n1k0d23k";
+import { FlagPreset } from "./shared/@outfitter/cli-7n5zmndx";
+import { ActionCliInputContext, ActionCliOption, ActionRegistry, ActionSurface, AnyActionSpec, HandlerContext } from "@outfitter/contracts";
 import { Command } from "commander";
 interface BuildCliCommandsOptions {
 	readonly createContext?: (input: {
@@ -7,7 +9,22 @@ interface BuildCliCommandsOptions {
 		flags: Record<string, unknown>;
 	}) => HandlerContext;
 	readonly includeSurfaces?: readonly ActionSurface[];
+	readonly schema?: boolean | SchemaCommandOptions;
 }
 type ActionSource = ActionRegistry | readonly AnyActionSpec[];
+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;
+type MergedPresetResult<TPresets extends readonly FlagPreset<Record<string, unknown>>[]> = UnionToIntersection<ResolvedType<TPresets[number]>> extends Record<string, unknown> ? UnionToIntersection<ResolvedType<TPresets[number]>> : Record<string, unknown>;
+interface ActionCliPresetAdapter<TResolved extends Record<string, unknown>> {
+	readonly options: readonly ActionCliOption[];
+	readonly resolve: (input: ActionCliInputContext | Record<string, unknown>) => TResolved;
+}
+/**
+* Compose flag presets for action-spec CLI definitions.
+*
+* Returns an options array for `action.cli.options` and a typed `resolve()`
+* that accepts either raw flags or full `ActionCliInputContext`.
+*/
+declare function actionCliPresets<TPresets extends readonly FlagPreset<Record<string, unknown>>[]>(...presets: TPresets): ActionCliPresetAdapter<MergedPresetResult<TPresets>>;
 declare function buildCliCommands(source: ActionSource, options?: BuildCliCommandsOptions): Command[];
-export { buildCliCommands, BuildCliCommandsOptions };
+export { buildCliCommands, actionCliPresets, BuildCliCommandsOptions, ActionCliPresetAdapter };

package/dist/actions.js

@@ -1,4 +1,11 @@
 // @bun
+import {
+  createSchemaCommand
+} from "./shared/@outfitter/cli-g0sn0r0b.js";
+import {
+  composePresets
+} from "./shared/@outfitter/cli-pdb7znbq.js";
+
 // packages/cli/src/actions.ts
 import {
   createContext as createHandlerContext,
@@ -7,6 +14,19 @@ import {
 } from "@outfitter/contracts";
 import { Command } from "commander";
 var ARGUMENT_PREFIXES = ["<", "["];
+function isInputContext(input) {
+  return "flags" in input && typeof input.flags === "object" && "args" in input && Array.isArray(input.args);
+}
+function actionCliPresets(...presets) {
+  const composed = composePresets(...presets);
+  return {
+    options: composed.options,
+    resolve: (input) => {
+      const flags = isInputContext(input) ? input.flags : input;
+      return composed.resolve(flags);
+    }
+  };
+}
 function isArgumentToken(token) {
   if (!token) {
     return false;
@@ -163,11 +183,19 @@ function buildCliCommands(source, options = {}) {
     }
     commands.push(groupCommand);
   }
+  if (options.schema !== false) {
+    const hasSchemaCommand = commands.some((cmd) => cmd.name() === "schema");
+    if (!hasSchemaCommand) {
+      const schemaOptions = typeof options.schema === "object" ? options.schema : undefined;
+      commands.push(createSchemaCommand(source, schemaOptions));
+    }
+  }
   return commands;
 }
 function isActionRegistry(source) {
   return "list" in source;
 }
 export {
-  buildCliCommands
+  buildCliCommands,
+  actionCliPresets
 };

package/dist/cli.d.ts

@@ -1,4 +1,4 @@
-import { CLI, CLIConfig } from "./shared/@outfitter/cli-md9347gn";
+import { CLI, CLIConfig } from "./shared/@outfitter/cli-7n5zmndx";
 /**
 * 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, FlagPreset } from "./shared/@outfitter/cli-md9347gn";
+import { CLI, CLIConfig, CommandAction, CommandBuilder, CommandConfig, CommandFlags, FlagPreset } from "./shared/@outfitter/cli-7n5zmndx";
 /**
 * Create a CLI instance with a portable return type from this module.
 */

package/dist/flags.d.ts

@@ -1,4 +1,4 @@
-import { ColorFlags, ColorMode, ComposedPreset, ExecutionFlags, ExecutionPresetConfig, FlagPreset, FlagPresetConfig, InteractionFlags, PaginationFlags, PaginationPresetConfig, ProjectionFlags, StrictFlags, TimeWindowFlags, TimeWindowPresetConfig } from "./shared/@outfitter/cli-md9347gn";
+import { BooleanFlagPresetConfig, ColorFlags, ColorMode, ComposedPreset, EnumFlagPresetConfig, ExecutionFlags, ExecutionPresetConfig, FlagPreset, FlagPresetConfig, InteractionFlags, NumberFlagPresetConfig, PaginationFlags, PaginationPresetConfig, ProjectionFlags, StrictFlags, StringListFlagPresetConfig, TimeWindowFlags, TimeWindowPresetConfig } from "./shared/@outfitter/cli-7n5zmndx";
 /**
 * Create a typed flag preset.
 *
@@ -44,6 +44,28 @@ type MergedPresetResult<TPresets extends readonly FlagPreset<Record<string, unkn
 */
 declare function composePresets<TPresets extends readonly FlagPreset<Record<string, unknown>>[]>(...presets: TPresets): ComposedPreset<MergedPresetResult<TPresets>>;
 /**
+* Generic boolean custom-flag builder.
+*
+* Supports normal sources and negated sources so `--no-foo` patterns can
+* resolve consistently across Commander flag-shape differences.
+*/
+declare function booleanFlagPreset<TKey extends string>(config: BooleanFlagPresetConfig<TKey>): FlagPreset<{ [K in TKey] : boolean }>;
+/**
+* Generic enum custom-flag builder.
+*/
+declare function enumFlagPreset<
+	TKey extends string,
+	TValue extends string
+>(config: EnumFlagPresetConfig<TKey, TValue>): FlagPreset<{ [K in TKey] : TValue }>;
+/**
+* Generic number custom-flag builder.
+*/
+declare function numberFlagPreset<TKey extends string>(config: NumberFlagPresetConfig<TKey>): FlagPreset<{ [K in TKey] : number }>;
+/**
+* Generic string-list custom-flag builder.
+*/
+declare function stringListFlagPreset<TKey extends string>(config: StringListFlagPresetConfig<TKey>): FlagPreset<{ [K in TKey] : string[] | undefined }>;
+/**
 * Verbose output flag preset.
 *
 * Adds: `-v, --verbose`
@@ -164,4 +186,4 @@ declare function executionPreset(config?: ExecutionPresetConfig): FlagPreset<Exe
 * `@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 };
+export { verbosePreset, timeWindowPreset, stringListFlagPreset, strictPreset, projectionPreset, paginationPreset, numberFlagPreset, interactionPreset, forcePreset, executionPreset, enumFlagPreset, dryRunPreset, cwdPreset, createPreset, composePresets, colorPreset, booleanFlagPreset, TimeWindowPresetConfig, TimeWindowFlags, StringListFlagPresetConfig, StrictFlags, ProjectionFlags, PaginationPresetConfig, PaginationFlags, NumberFlagPresetConfig, InteractionFlags, FlagPresetConfig, FlagPreset, ExecutionPresetConfig, ExecutionFlags, EnumFlagPresetConfig, ComposedPreset, ColorMode, ColorFlags, BooleanFlagPresetConfig };

package/dist/flags.js

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

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 { exitWithError, output } from "./shared/@outfitter/cli-k0yvzn6d";
-import { OutputMode } from "./shared/@outfitter/cli-md9347gn";
+import { exitWithError, output } from "./shared/@outfitter/cli-z7mgapx5";
+import { OutputMode } from "./shared/@outfitter/cli-7n5zmndx";
 export { output, exitWithError, createTheme, Tokens, Theme, OutputMode, ANSI };

package/dist/input.d.ts

@@ -1,4 +1,4 @@
-import { CollectIdsOptions, ExpandFileOptions, FilterExpression, KeyValuePair, NormalizeIdOptions, ParseGlobOptions, Range, SortCriteria } from "./shared/@outfitter/cli-md9347gn";
+import { CollectIdsOptions, ExpandFileOptions, FilterExpression, KeyValuePair, NormalizeIdOptions, ParseGlobOptions, Range, SortCriteria } from "./shared/@outfitter/cli-7n5zmndx";
 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-k0yvzn6d";
-import "./shared/@outfitter/cli-md9347gn";
+import { exitWithError, output, resolveVerbose } from "./shared/@outfitter/cli-z7mgapx5";
+import "./shared/@outfitter/cli-7n5zmndx";
 export { resolveVerbose, output, exitWithError };

package/dist/pagination.d.ts

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

package/dist/query.d.ts

@@ -1,4 +1,4 @@
-import { FlagPreset, OutputMode } from "./shared/@outfitter/cli-md9347gn";
+import { FlagPreset, OutputMode } from "./shared/@outfitter/cli-7n5zmndx";
 /**
 * Configuration for the output mode preset.
 */

package/dist/query.js

@@ -1,7 +1,7 @@
 // @bun
 import {
   createPreset
-} from "./shared/@outfitter/cli-b2zk8fb3.js";
+} from "./shared/@outfitter/cli-pdb7znbq.js";
 
 // packages/cli/src/query.ts
 function outputModePreset(config) {

package/dist/schema.d.ts

@@ -0,0 +1,2 @@
+import { ActionManifest, ActionManifestEntry, ActionSource, GenerateManifestOptions, SchemaCommandOptions, SurfaceCommandOptions, createSchemaCommand, formatManifestHuman, generateManifest } from "./shared/@outfitter/cli-n1k0d23k";
+export { generateManifest, formatManifestHuman, createSchemaCommand, SurfaceCommandOptions, SchemaCommandOptions, GenerateManifestOptions, ActionSource, ActionManifestEntry, ActionManifest };

package/dist/schema.js

@@ -0,0 +1,11 @@
+// @bun
+import {
+  createSchemaCommand,
+  formatManifestHuman,
+  generateManifest
+} from "./shared/@outfitter/cli-g0sn0r0b.js";
+export {
+  generateManifest,
+  formatManifestHuman,
+  createSchemaCommand
+};

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

@@ -137,6 +137,99 @@ interface FlagPresetConfig<TResolved extends Record<string, unknown>> {
 	readonly resolve: (flags: Record<string, unknown>) => TResolved;
 }
 /**
+* Configuration for creating a custom boolean flag preset.
+*/
+interface BooleanFlagPresetConfig<TKey extends string> {
+	/** Unique identifier for deduplication */
+	readonly id: string;
+	/** Resolved output property name */
+	readonly key: TKey;
+	/** Commander option definition (e.g., "--force" or "--no-codemods") */
+	readonly flags: string;
+	/** Help description for the option */
+	readonly description: string;
+	/** Default resolved value (defaults to false) */
+	readonly defaultValue?: boolean;
+	/** Candidate raw flag keys to read (defaults to [key]) */
+	readonly sources?: readonly string[];
+	/** Positive keys that should be negated (e.g., "codemods" for --no-codemods) */
+	readonly negatedSources?: readonly string[];
+	/** Whether the option is required */
+	readonly required?: boolean;
+}
+/**
+* Configuration for creating a custom enum flag preset.
+*/
+interface EnumFlagPresetConfig<
+	TKey extends string,
+	TValue extends string
+> {
+	/** Unique identifier for deduplication */
+	readonly id: string;
+	/** Resolved output property name */
+	readonly key: TKey;
+	/** Commander option definition */
+	readonly flags: string;
+	/** Help description for the option */
+	readonly description: string;
+	/** Allowed enum values */
+	readonly values: readonly TValue[];
+	/** Fallback value when input is missing or invalid */
+	readonly defaultValue: TValue;
+	/** Candidate raw flag keys to read (defaults to [key]) */
+	readonly sources?: readonly string[];
+	/** Whether the option is required */
+	readonly required?: boolean;
+}
+/**
+* Configuration for creating a custom numeric flag preset.
+*/
+interface NumberFlagPresetConfig<TKey extends string> {
+	/** Unique identifier for deduplication */
+	readonly id: string;
+	/** Resolved output property name */
+	readonly key: TKey;
+	/** Commander option definition */
+	readonly flags: string;
+	/** Help description for the option */
+	readonly description: string;
+	/** Fallback value when input is missing or invalid */
+	readonly defaultValue: number;
+	/** Candidate raw flag keys to read (defaults to [key]) */
+	readonly sources?: readonly string[];
+	/** Lower bound (inclusive) */
+	readonly min?: number;
+	/** Upper bound (inclusive) */
+	readonly max?: number;
+	/** Floor parsed values (defaults to true) */
+	readonly integer?: boolean;
+	/** Whether the option is required */
+	readonly required?: boolean;
+}
+/**
+* Configuration for creating a custom string-list flag preset.
+*/
+interface StringListFlagPresetConfig<TKey extends string> {
+	/** Unique identifier for deduplication */
+	readonly id: string;
+	/** Resolved output property name */
+	readonly key: TKey;
+	/** Commander option definition */
+	readonly flags: string;
+	/** Help description for the option */
+	readonly description: string;
+	/** Candidate raw flag keys to read (defaults to [key]) */
+	readonly sources?: readonly string[];
+	/** Fallback list when input is missing or invalid */
+	readonly defaultValue?: readonly string[];
+	/** Split string values by this separator (defaults to ",") */
+	readonly separator?: string;
+	/** Remove duplicate values while preserving order */
+	readonly dedupe?: boolean;
+	/** Whether the option is required */
+	readonly required?: boolean;
+}
+/**
 * Result of composing multiple presets together.
 * Options are deduplicated by preset id (first wins).
 */
@@ -392,4 +485,4 @@ interface CursorOptions {
 	/** Total count of results (if known) */
 	readonly total?: number;
 }
-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 };
+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 };

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

@@ -0,0 +1,319 @@
+// @bun
+// packages/cli/src/schema.ts
+import { mkdir, writeFile } from "fs/promises";
+import { dirname, join } from "path";
+import {
+  diffSurfaceMaps,
+  formatManifestMarkdown,
+  generateManifest,
+  generateSurfaceMap,
+  readSurfaceMap,
+  resolveSnapshotPath,
+  writeSurfaceMap
+} from "@outfitter/schema";
+import { Command } from "commander";
+import { generateManifest as generateManifest2 } from "@outfitter/schema";
+function formatManifestHuman(manifest, programName, actionId) {
+  if (actionId) {
+    return formatActionDetail(manifest, actionId);
+  }
+  return formatSummary(manifest, programName);
+}
+function formatSummary(manifest, programName) {
+  const lines = [];
+  const name = programName ?? "cli";
+  const actionCount = manifest.actions.length;
+  const surfaceCount = manifest.surfaces.length;
+  const surfaceLabel = surfaceCount === 1 ? `${surfaceCount} surface` : `${surfaceCount} surfaces`;
+  lines.push(`${name} \u2014 ${actionCount} actions across ${surfaceLabel}`);
+  lines.push("");
+  const grouped = new Map;
+  const ungrouped = [];
+  for (const action of manifest.actions) {
+    const group = action.cli?.group;
+    if (group) {
+      const existing = grouped.get(group) ?? [];
+      existing.push(action);
+      grouped.set(group, existing);
+    } else {
+      ungrouped.push(action);
+    }
+  }
+  for (const [groupName, groupActions] of grouped.entries()) {
+    lines.push(groupName);
+    for (const action of groupActions) {
+      const commandPart = action.cli?.command ?? action.id;
+      const isBase = !commandPart || commandPart.startsWith("[") || commandPart.startsWith("<");
+      const displayCommand = isBase ? `  ${groupName} ${commandPart ?? ""}`.trimEnd() : `  ${groupName} ${commandPart}`;
+      const desc = action.cli?.description ?? action.description ?? "";
+      lines.push(padCommand(displayCommand, desc));
+    }
+    lines.push("");
+  }
+  for (const action of ungrouped) {
+    const commandPart = action.cli?.command ?? action.id;
+    const desc = action.cli?.description ?? action.description ?? "";
+    lines.push(padCommand(`${commandPart}`, desc));
+  }
+  lines.push("");
+  lines.push("Use --output json for machine-readable format.");
+  lines.push("Use --surface <name> to filter (cli, mcp, api, server).");
+  return lines.join(`
+`);
+}
+function padCommand(command, description) {
+  const padding = Math.max(1, 32 - command.length);
+  return `${command}${" ".repeat(padding)}${description}`;
+}
+function formatActionDetail(manifest, actionId) {
+  const entry = manifest.actions.find((a) => a.id === actionId);
+  if (!entry) {
+    return `Unknown action: ${actionId}`;
+  }
+  const lines = [];
+  const desc = entry.cli?.description ?? entry.description ?? "";
+  lines.push(`${entry.id} \u2014 ${desc}`);
+  lines.push("");
+  if (entry.cli) {
+    const group = entry.cli.group;
+    const commandPart = entry.cli.command ?? entry.id;
+    const fullCommand = group ? `${group} ${commandPart}` : commandPart;
+    lines.push(`  Command:  ${fullCommand}`);
+  }
+  lines.push(`  Surfaces: ${entry.surfaces.join(", ")}`);
+  if (entry.cli?.group) {
+    lines.push(`  Group:    ${entry.cli.group}`);
+  }
+  if (entry.cli?.aliases && entry.cli.aliases.length > 0) {
+    lines.push(`  Aliases:  ${entry.cli.aliases.join(", ")}`);
+  }
+  if (entry.cli?.options && entry.cli.options.length > 0) {
+    lines.push("");
+    lines.push("  Options:");
+    for (const opt of entry.cli.options) {
+      const defaultStr = opt.defaultValue !== undefined ? ` [${String(opt.defaultValue)}]` : "";
+      lines.push(padCommand(`    ${opt.flags}`, `${opt.description}${defaultStr}`));
+    }
+  }
+  if (entry.mcp) {
+    lines.push("");
+    lines.push("  MCP:");
+    if (entry.mcp.tool) {
+      lines.push(`    Tool: ${entry.mcp.tool}`);
+    }
+    if (entry.mcp.description) {
+      lines.push(`    Description: ${entry.mcp.description}`);
+    }
+  }
+  return lines.join(`
+`);
+}
+function handleShow(source, programName, parentCmd, actionArg, cmdOptions) {
+  const manifestOptions = {};
+  if (cmdOptions.surface) {
+    manifestOptions.surface = cmdOptions.surface;
+  }
+  const manifest = generateManifest(source, manifestOptions);
+  if (cmdOptions.output === "json") {
+    const indent = cmdOptions.pretty ? 2 : undefined;
+    if (actionArg) {
+      const entry = manifest.actions.find((a) => a.id === actionArg);
+      if (!entry) {
+        process.stderr.write(`Unknown action: ${actionArg}
+`);
+        process.exitCode = 1;
+        return;
+      }
+      process.stdout.write(`${JSON.stringify(entry, null, indent)}
+`);
+    } else {
+      process.stdout.write(`${JSON.stringify(manifest, null, indent)}
+`);
+    }
+    return;
+  }
+  const resolvedName = programName ?? parentCmd.parent?.name() ?? undefined;
+  const output = formatManifestHuman(manifest, resolvedName, actionArg);
+  process.stdout.write(`${output}
+`);
+}
+function createSchemaCommand(source, options) {
+  const cmd = new Command("schema").description("Show CLI schema for machine or human consumption").argument("[action]", "Show detail for a specific action").option("--output <mode>", "Output mode (human, json)", "human").option("--surface <name>", "Filter by surface (cli, mcp, api, server)").option("--pretty", "Pretty-print JSON output").action((actionArg, cmdOptions) => {
+    handleShow(source, options?.programName, cmd, actionArg, cmdOptions);
+  });
+  const showCmd = new Command("show").description("Show schema for all actions or a specific action").argument("[action]", "Show detail for a specific action").option("--output <mode>", "Output mode (human, json)", "human").option("--surface <name>", "Filter by surface (cli, mcp, api, server)").option("--pretty", "Pretty-print JSON output").action((actionArg, cmdOptions) => {
+    handleShow(source, options?.programName, cmd, actionArg, cmdOptions);
+  });
+  cmd.addCommand(showCmd);
+  if (options?.surface) {
+    const surfaceOpts = options.surface;
+    const cwd = surfaceOpts.cwd ?? process.cwd();
+    const outputDir = surfaceOpts.outputDir ?? ".outfitter";
+    const generateCmd = new Command("generate").description("Generate surface map and write to disk").option("--dry-run", "Print surface map without writing to disk").option("--snapshot <version>", "Write snapshot to .outfitter/snapshots/<version>.json").action(async (genOptions) => {
+      const surfaceMap = generateSurfaceMap(source, {
+        generator: "build"
+      });
+      if (genOptions.dryRun) {
+        process.stdout.write(`${JSON.stringify(surfaceMap, null, 2)}
+`);
+        return;
+      }
+      if (genOptions.snapshot) {
+        const snapshotPath = resolveSnapshotPath(cwd, outputDir, genOptions.snapshot);
+        await writeSurfaceMap(surfaceMap, snapshotPath);
+        process.stdout.write(`Snapshot written to ${snapshotPath}
+`);
+        return;
+      }
+      const outputPath = join(cwd, outputDir, "surface.json");
+      await writeSurfaceMap(surfaceMap, outputPath);
+      process.stdout.write(`Surface map written to ${outputPath}
+`);
+    });
+    cmd.addCommand(generateCmd);
+    const diffCmd = new Command("diff").description("Compare runtime schema against committed surface map").option("--output <mode>", "Output mode (human, json)", "human").option("--against <version>", "Compare runtime against a named snapshot").option("--from <version>", "Base snapshot for snapshot-to-snapshot diff").option("--to <version>", "Target snapshot for snapshot-to-snapshot diff").action(async (diffOptions) => {
+      let left;
+      let right;
+      if (diffOptions.from && !diffOptions.to || !diffOptions.from && diffOptions.to) {
+        process.stderr.write(`Both --from and --to are required for snapshot-to-snapshot diff.
+`);
+        process.exitCode = 1;
+        return;
+      }
+      if (diffOptions.from && diffOptions.to) {
+        const fromPath = resolveSnapshotPath(cwd, outputDir, diffOptions.from);
+        const toPath = resolveSnapshotPath(cwd, outputDir, diffOptions.to);
+        try {
+          left = await readSurfaceMap(fromPath);
+        } catch (err) {
+          if (err.code === "ENOENT") {
+            process.stderr.write(`No snapshot at ${fromPath}
+`);
+          } else {
+            process.stderr.write(`Failed to read snapshot at ${fromPath}: ${err instanceof Error ? err.message : String(err)}
+`);
+          }
+          process.exitCode = 1;
+          return;
+        }
+        try {
+          right = await readSurfaceMap(toPath);
+        } catch (err) {
+          if (err.code === "ENOENT") {
+            process.stderr.write(`No snapshot at ${toPath}
+`);
+          } else {
+            process.stderr.write(`Failed to read snapshot at ${toPath}: ${err instanceof Error ? err.message : String(err)}
+`);
+          }
+          process.exitCode = 1;
+          return;
+        }
+      } else if (diffOptions.against) {
+        const snapshotPath = resolveSnapshotPath(cwd, outputDir, diffOptions.against);
+        try {
+          left = await readSurfaceMap(snapshotPath);
+        } catch (err) {
+          if (err.code === "ENOENT") {
+            process.stderr.write(`No snapshot at ${snapshotPath}
+`);
+          } else {
+            process.stderr.write(`Failed to read snapshot at ${snapshotPath}: ${err instanceof Error ? err.message : String(err)}
+`);
+          }
+          process.exitCode = 1;
+          return;
+        }
+        right = generateSurfaceMap(source, { generator: "runtime" });
+      } else {
+        const surfacePath = join(cwd, outputDir, "surface.json");
+        try {
+          left = await readSurfaceMap(surfacePath);
+        } catch (err) {
+          if (err.code === "ENOENT") {
+            process.stderr.write(`No committed surface map at ${surfacePath}
+`);
+            process.stderr.write(`Run 'schema generate' first.
+`);
+          } else {
+            process.stderr.write(`Failed to read surface map at ${surfacePath}: ${err instanceof Error ? err.message : String(err)}
+`);
+          }
+          process.exitCode = 1;
+          return;
+        }
+        right = generateSurfaceMap(source, { generator: "runtime" });
+      }
+      const result = diffSurfaceMaps(left, right);
+      if (diffOptions.output === "json") {
+        process.stdout.write(`${JSON.stringify(result, null, 2)}
+`);
+      } else {
+        if (!result.hasChanges) {
+          process.stdout.write(`No schema drift detected.
+`);
+          return;
+        }
+        const lines = [];
+        lines.push(`Schema drift detected:
+`);
+        if (result.added.length > 0) {
+          lines.push("  Added:");
+          for (const entry of result.added) {
+            lines.push(`    + ${entry.id}`);
+          }
+        }
+        if (result.removed.length > 0) {
+          lines.push("  Removed:");
+          for (const entry of result.removed) {
+            lines.push(`    - ${entry.id}`);
+          }
+        }
+        if (result.modified.length > 0) {
+          lines.push("  Modified:");
+          for (const entry of result.modified) {
+            lines.push(`    ~ ${entry.id} (${entry.changes.join(", ")})`);
+          }
+        }
+        if (result.metadataChanges.length > 0) {
+          lines.push("  Metadata:");
+          for (const field of result.metadataChanges) {
+            lines.push(`    ~ ${field}`);
+          }
+        }
+        process.stdout.write(`${lines.join(`
+`)}
+`);
+      }
+      if (result.hasChanges) {
+        process.exitCode = 1;
+      }
+    });
+    cmd.addCommand(diffCmd);
+    const docsCmd = new Command("docs").description("Generate markdown reference documentation").option("--surface <name>", "Which surface to document (cli, mcp)", "mcp").option("--output-dir <dir>", "Directory to write the reference doc", "docs/reference").option("--dry-run", "Print to stdout instead of writing to disk").action(async (docsOptions) => {
+      const surface = docsOptions.surface ?? "mcp";
+      if (surface !== "mcp" && surface !== "cli") {
+        process.stderr.write(`Unsupported surface for docs: "${surface}". Use "mcp" or "cli".
+`);
+        process.exitCode = 1;
+        return;
+      }
+      const manifest = generateManifest(source, { surface });
+      const markdown = formatManifestMarkdown(manifest, { surface });
+      if (docsOptions.dryRun) {
+        process.stdout.write(markdown);
+        return;
+      }
+      const outDir = docsOptions.outputDir ?? "docs/reference";
+      const outputPath = join(cwd, outDir, `${surface.toUpperCase()}_REFERENCE.md`);
+      await mkdir(dirname(outputPath), { recursive: true });
+      await writeFile(outputPath, markdown, "utf-8");
+      process.stdout.write(`Reference written to ${outputPath}
+`);
+    });
+    cmd.addCommand(docsCmd);
+  }
+  return cmd;
+}
+
+export { formatManifestHuman, createSchemaCommand, generateManifest2 as generateManifest };

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/shared/@outfitter/{cli-b2zk8fb3.js → cli-pdb7znbq.js}

@@ -46,6 +46,149 @@ function composePresets(...presets) {
   composed[PRESET_IDS] = mergedIds;
   return composed;
 }
+function resolveSourceKeys(key, sources) {
+  return sources && sources.length > 0 ? sources : [key];
+}
+function booleanFlagPreset(config) {
+  const sources = resolveSourceKeys(config.key, config.sources);
+  const defaultValue = config.defaultValue ?? false;
+  const isNegatedFlag = config.flags.includes("--no-");
+  const optionDefault = isNegatedFlag && config.defaultValue === undefined ? {} : { defaultValue };
+  return createPreset({
+    id: config.id,
+    options: [
+      {
+        flags: config.flags,
+        description: config.description,
+        ...optionDefault,
+        ...config.required === true ? { required: true } : {}
+      }
+    ],
+    resolve: (flags) => {
+      for (const source of sources) {
+        const value = flags[source];
+        if (typeof value === "boolean") {
+          return { [config.key]: value };
+        }
+      }
+      if (config.negatedSources) {
+        for (const source of config.negatedSources) {
+          const value = flags[source];
+          if (typeof value === "boolean") {
+            return { [config.key]: !value };
+          }
+        }
+      }
+      return { [config.key]: defaultValue };
+    }
+  });
+}
+function enumFlagPreset(config) {
+  const sources = resolveSourceKeys(config.key, config.sources);
+  const allowed = new Set(config.values);
+  return createPreset({
+    id: config.id,
+    options: [
+      {
+        flags: config.flags,
+        description: config.description,
+        ...config.required === true ? { required: true } : {}
+      }
+    ],
+    resolve: (flags) => {
+      for (const source of sources) {
+        const value = flags[source];
+        if (typeof value === "string" && allowed.has(value)) {
+          return { [config.key]: value };
+        }
+      }
+      return {
+        [config.key]: config.defaultValue
+      };
+    }
+  });
+}
+function numberFlagPreset(config) {
+  const sources = resolveSourceKeys(config.key, config.sources);
+  return createPreset({
+    id: config.id,
+    options: [
+      {
+        flags: config.flags,
+        description: config.description,
+        ...config.required === true ? { required: true } : {}
+      }
+    ],
+    resolve: (flags) => {
+      let parsed;
+      for (const source of sources) {
+        const value = flags[source];
+        if (value === "" || value == null || typeof value === "boolean") {
+          continue;
+        }
+        const numeric = Number(value);
+        if (Number.isFinite(numeric)) {
+          parsed = config.integer === false ? numeric : Math.floor(numeric);
+          break;
+        }
+      }
+      if (parsed === undefined) {
+        parsed = config.defaultValue;
+      }
+      if (typeof config.min === "number" && Number.isFinite(config.min)) {
+        parsed = Math.max(parsed, config.min);
+      }
+      if (typeof config.max === "number" && Number.isFinite(config.max)) {
+        parsed = Math.min(parsed, config.max);
+      }
+      return { [config.key]: parsed };
+    }
+  });
+}
+function normalizeStringListInput(value, separator) {
+  if (Array.isArray(value)) {
+    const items2 = value.filter((item) => typeof item === "string").map((item) => item.trim()).filter(Boolean);
+    return items2.length > 0 ? items2 : undefined;
+  }
+  if (typeof value !== "string")
+    return;
+  const items = value.split(separator).map((item) => item.trim()).filter(Boolean);
+  return items.length > 0 ? items : undefined;
+}
+function stringListFlagPreset(config) {
+  const sources = resolveSourceKeys(config.key, config.sources);
+  const separator = config.separator ?? ",";
+  const fallback = config.defaultValue === undefined ? undefined : [...config.defaultValue];
+  return createPreset({
+    id: config.id,
+    options: [
+      {
+        flags: config.flags,
+        description: config.description,
+        ...config.required === true ? { required: true } : {}
+      }
+    ],
+    resolve: (flags) => {
+      let resolved;
+      for (const source of sources) {
+        const parsed = normalizeStringListInput(flags[source], separator);
+        if (parsed !== undefined) {
+          resolved = parsed;
+          break;
+        }
+      }
+      if (resolved === undefined) {
+        resolved = fallback === undefined ? undefined : [...fallback];
+      }
+      if (resolved && config.dedupe) {
+        resolved = [...new Set(resolved)];
+      }
+      return {
+        [config.key]: resolved
+      };
+    }
+  });
+}
 function verbosePreset() {
   return createPreset({
     id: "verbose",
@@ -354,4 +497,4 @@ function paginationPreset(config) {
   });
 }
 
-export { createPreset, composePresets, verbosePreset, cwdPreset, dryRunPreset, forcePreset, interactionPreset, strictPreset, colorPreset, projectionPreset, timeWindowPreset, executionPreset, paginationPreset };
+export { createPreset, composePresets, booleanFlagPreset, enumFlagPreset, numberFlagPreset, stringListFlagPreset, verbosePreset, cwdPreset, dryRunPreset, forcePreset, interactionPreset, strictPreset, colorPreset, projectionPreset, timeWindowPreset, executionPreset, paginationPreset };

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

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

package/dist/types.d.ts

@@ -1,2 +1,2 @@
-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 };
+import { BooleanFlagPresetConfig, CLI, CLIConfig, CancelledError, CollectIdsOptions, ColorFlags, ColorMode, CommandAction, CommandBuilder, CommandConfig, CommandFlags, ComposedPreset, CursorOptions, DateRange, EnumFlagPresetConfig, ErrorCategory, ExecutionFlags, ExecutionPresetConfig, ExpandFileOptions, FilterExpression, FlagPreset, FlagPresetConfig, InteractionFlags, KeyValuePair, NormalizeIdOptions, NumberFlagPresetConfig, NumericRange, OutputMode, OutputOptions, PaginationFlags, PaginationPresetConfig, PaginationState, ParseGlobOptions, ProjectionFlags, Range, Result, SortCriteria, StrictFlags, StringListFlagPresetConfig, TimeWindowFlags, TimeWindowPresetConfig, ValidationError, VerbConfig, VerbFamily } from "./shared/@outfitter/cli-7n5zmndx";
+export { VerbFamily, VerbConfig, ValidationError, TimeWindowPresetConfig, TimeWindowFlags, StringListFlagPresetConfig, StrictFlags, SortCriteria, Result, Range, ProjectionFlags, ParseGlobOptions, PaginationState, PaginationPresetConfig, PaginationFlags, OutputOptions, OutputMode, NumericRange, NumberFlagPresetConfig, NormalizeIdOptions, KeyValuePair, InteractionFlags, FlagPresetConfig, FlagPreset, FilterExpression, ExpandFileOptions, ExecutionPresetConfig, ExecutionFlags, ErrorCategory, EnumFlagPresetConfig, DateRange, CursorOptions, ComposedPreset, CommandFlags, CommandConfig, CommandBuilder, CommandAction, ColorMode, ColorFlags, CollectIdsOptions, CancelledError, CLIConfig, CLI, BooleanFlagPresetConfig };

package/dist/verbs.d.ts

@@ -1,4 +1,4 @@
-import { CommandBuilder, VerbConfig, VerbFamily } from "./shared/@outfitter/cli-md9347gn";
+import { CommandBuilder, VerbConfig, VerbFamily } from "./shared/@outfitter/cli-7n5zmndx";
 /**
 * Built-in verb families with standard primary verbs and aliases.
 *

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.1",
+  "version": "0.5.1",
   "type": "module",
   "files": [
     "dist"
@@ -70,6 +70,12 @@
         "default": "./dist/query.js"
       }
     },
+    "./schema": {
+      "import": {
+        "types": "./dist/schema.d.ts",
+        "default": "./dist/schema.js"
+      }
+    },
     "./terminal": {
       "import": {
         "types": "./dist/terminal/index.d.ts",
@@ -109,7 +115,8 @@
     "lint": "biome lint ./src",
     "lint:fix": "biome lint --write ./src",
     "typecheck": "tsc --noEmit",
-    "clean": "rm -rf dist"
+    "clean": "rm -rf dist",
+    "prepublishOnly": "bun ../../scripts/check-publish-manifest.ts"
   },
   "dependencies": {
     "@clack/prompts": "^0.11.0",
@@ -119,12 +126,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.1",
     "@types/bun": "^1.3.7",
     "@types/node": "^25.0.10",
     "typescript": "^5.9.3"