@outfitter/cli 0.4.1 → 0.5.0

package/dist/actions.d.ts

@@ -1,3 +1,4 @@
+import { SchemaCommandOptions } from "./shared/@outfitter/cli-n1k0d23k";
 import { ActionRegistry, ActionSurface, AnyActionSpec, HandlerContext } from "@outfitter/contracts";
 import { Command } from "commander";
 interface BuildCliCommandsOptions {
@@ -7,6 +8,7 @@ interface BuildCliCommandsOptions {
 		flags: Record<string, unknown>;
 	}) => HandlerContext;
 	readonly includeSurfaces?: readonly ActionSurface[];
+	readonly schema?: boolean | SchemaCommandOptions;
 }
 type ActionSource = ActionRegistry | readonly AnyActionSpec[];
 declare function buildCliCommands(source: ActionSource, options?: BuildCliCommandsOptions): Command[];

package/dist/actions.js

@@ -1,4 +1,8 @@
 // @bun
+import {
+  createSchemaCommand
+} from "./shared/@outfitter/cli-g0sn0r0b.js";
+
 // packages/cli/src/actions.ts
 import {
   createContext as createHandlerContext,
@@ -163,6 +167,13 @@ 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) {

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-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/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.0",
   "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",
@@ -119,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"