@outfitter/cli 0.5.2 → 1.0.0

package/dist/{shared/@outfitter/cli-0cjts94k.js → internal/schema-commands.js}

@@ -1,5 +1,9 @@
 // @bun
-// packages/cli/src/schema.ts
+import {
+  formatManifestHuman
+} from "../shared/@outfitter/cli-zkzj0q4q.js";
+
+// packages/cli/src/internal/schema-commands.ts
 import { mkdir, writeFile } from "fs/promises";
 import { dirname, join } from "path";
 import {
@@ -12,102 +16,6 @@ import {
   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 ?? "";
-      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 ?? (group ? "" : entry.id);
-    const fullCommand = group ? `${group} ${commandPart}`.trimEnd() : 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) {
@@ -174,6 +82,7 @@ function createSchemaCommand(source, options) {
     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;
+      let diffMode = "committed-to-runtime";
       if (diffOptions.from && !diffOptions.to || !diffOptions.from && diffOptions.to) {
         process.stderr.write(`Both --from and --to are required for snapshot-to-snapshot diff.
 `);
@@ -181,6 +90,7 @@ function createSchemaCommand(source, options) {
         return;
       }
       if (diffOptions.from && diffOptions.to) {
+        diffMode = "snapshot-to-snapshot";
         const fromPath = resolveSnapshotPath(cwd, outputDir, diffOptions.from);
         const toPath = resolveSnapshotPath(cwd, outputDir, diffOptions.to);
         try {
@@ -210,6 +120,7 @@ function createSchemaCommand(source, options) {
           return;
         }
       } else if (diffOptions.against) {
+        diffMode = "snapshot-to-runtime";
         const snapshotPath = resolveSnapshotPath(cwd, outputDir, diffOptions.against);
         try {
           left = await readSurfaceMap(snapshotPath);
@@ -244,7 +155,7 @@ function createSchemaCommand(source, options) {
         }
         right = generateSurfaceMap(source, { generator: "runtime" });
       }
-      const result = diffSurfaceMaps(left, right);
+      const result = diffSurfaceMaps(left, right, { mode: diffMode });
       if (diffOptions.output === "json") {
         process.stdout.write(`${JSON.stringify(result, null, 2)}
 `);
@@ -315,5 +226,6 @@ function createSchemaCommand(source, options) {
   }
   return cmd;
 }
-
-export { formatManifestHuman, createSchemaCommand, generateManifest2 as generateManifest };
+export {
+  createSchemaCommand
+};

package/dist/internal/schema-formatting.d.ts

@@ -0,0 +1,2 @@
+import { formatManifestHuman } from "../shared/@outfitter/cli-qcskd96y.js";
+export { formatManifestHuman };

package/dist/internal/schema-formatting.js

@@ -0,0 +1,7 @@
+// @bun
+import {
+  formatManifestHuman
+} from "../shared/@outfitter/cli-zkzj0q4q.js";
+export {
+  formatManifestHuman
+};

package/dist/internal/schema-types.d.ts

@@ -0,0 +1,2 @@
+import { SchemaCommandOptions, SurfaceCommandOptions } from "../shared/@outfitter/cli-wjv7g1aq.js";
+export { SurfaceCommandOptions, SchemaCommandOptions };

package/dist/internal/schema-types.js

@@ -0,0 +1 @@
+// @bun

package/dist/output.d.ts

@@ -1,3 +1,4 @@
-import { exitWithError, output, resolveVerbose } from "./shared/@outfitter/cli-xy3gs50c.js";
-import "./shared/@outfitter/cli-98aa9104.js";
-export { resolveVerbose, output, exitWithError };
+import { exitWithError, output, resolveVerbose } from "./shared/@outfitter/cli-q6csxmeh.js";
+import { cliStringify, detectMode, formatHuman } from "./shared/@outfitter/cli-10wxfc78.js";
+import "./shared/@outfitter/cli-x6qr7bnd.js";
+export { resolveVerbose, output, formatHuman, exitWithError, detectMode, cliStringify };

package/dist/output.js

@@ -3,9 +3,17 @@ import {
   exitWithError,
   output,
   resolveVerbose
-} from "./shared/@outfitter/cli-7wp5nj0s.js";
+} from "./shared/@outfitter/cli-4h85mpth.js";
+import {
+  cliStringify,
+  detectMode,
+  formatHuman
+} from "./shared/@outfitter/cli-dg0cz7rw.js";
 export {
   resolveVerbose,
   output,
-  exitWithError
+  formatHuman,
+  exitWithError,
+  detectMode,
+  cliStringify
 };

package/dist/pagination.d.ts

@@ -1,4 +1,4 @@
-import { CursorOptions, PaginationState } from "./shared/@outfitter/cli-98aa9104.js";
+import { CursorOptions, PaginationState } from "./shared/@outfitter/cli-x6qr7bnd.js";
 /**
 * Load persisted pagination state for a command.
 *

package/dist/query.d.ts

@@ -1,4 +1,66 @@
-import { FlagPreset, OutputMode } from "./shared/@outfitter/cli-98aa9104.js";
+import { FlagPreset, OutputMode } from "./shared/@outfitter/cli-x6qr7bnd.js";
+/**
+* Source of the resolved output mode, indicating how the mode was determined.
+*
+* - `"flag"` — User explicitly passed `--output`, `-o`, `--json`, or `--jsonl`
+* - `"env"` — Mode set via `OUTFITTER_JSON=1` or `OUTFITTER_JSONL=1`
+* - `"default"` — No explicit input; using the configured default (typically `"human"`)
+*/
+type OutputModeSource = "flag" | "env" | "default";
+/**
+* Result of resolving output mode with source/explicitness tracking.
+*/
+interface ResolvedOutputMode {
+	/** The resolved output mode */
+	readonly mode: "human" | "json" | "jsonl";
+	/** How the mode was determined */
+	readonly source: OutputModeSource;
+}
+/**
+* Configuration for the centralized output mode resolver.
+*/
+interface ResolveOutputModeConfig {
+	/** Custom argv for explicit-flag detection (defaults to `process.argv.slice(2)`) */
+	readonly argv?: readonly string[];
+	/** Default mode when not specified (default: `"human"`) */
+	readonly defaultMode?: "human" | "json" | "jsonl";
+	/**
+	* When `true`, skip env-var fallback and return the default for implicit
+	* modes. Useful for orchestrator modes (e.g., `check --pre-commit`) where
+	* structured output should require an explicit flag.
+	*/
+	readonly forceHumanWhenImplicit?: boolean;
+}
+/**
+* Centralized output-mode resolver with source/explicitness tracking.
+*
+* Resolves the output mode from CLI flags, environment variables, or defaults.
+* Returns both the resolved mode and its source so callers can make decisions
+* based on how the mode was determined.
+*
+* **Resolution order (highest wins):**
+* 1. Explicit `--output` / `-o` flag (source: `"flag"`)
+* 2. Legacy `--json` / `--jsonl` boolean flags (source: `"flag"`)
+* 3. `OUTFITTER_JSONL=1` / `OUTFITTER_JSON=1` env vars (source: `"env"`)
+* 4. Configured default — typically `"human"` (source: `"default"`)
+*
+* When `forceHumanWhenImplicit` is set, steps 3–4 collapse to `"human"`.
+*
+* @param flags - Raw Commander flags (from `context.flags`)
+* @param config - Optional configuration
+* @returns The resolved mode and its source
+*
+* @example
+* ```typescript
+* import { resolveOutputMode } from "@outfitter/cli/query";
+*
+* // In a mapInput function:
+* const { mode, source } = resolveOutputMode(context.flags);
+* // mode: "human" | "json" | "jsonl"
+* // source: "flag" | "env" | "default"
+* ```
+*/
+declare function resolveOutputMode(flags: Record<string, unknown>, config?: ResolveOutputModeConfig): ResolvedOutputMode;
 /**
 * Configuration for the output mode preset.
 */
@@ -38,6 +100,26 @@ type JqFlags = {
 	readonly jq: string | undefined;
 };
 /**
+* Resolved stream flags from CLI input.
+*/
+type StreamFlags = {
+	/** Whether NDJSON streaming mode is enabled */
+	readonly stream: boolean;
+};
+/**
+* NDJSON streaming flag preset.
+*
+* Adds: `--stream`
+* Resolves: `{ stream: boolean }`
+*
+* When enabled, the CLI writes progress events as newline-delimited JSON
+* (NDJSON) to stdout. The final line is the standard command envelope.
+*
+* `--stream` is orthogonal to output mode — it controls delivery, not
+* serialization. Works alongside `--output human|json|jsonl` and env vars.
+*/
+declare function streamPreset(): FlagPreset<StreamFlags>;
+/**
 * JQ expression flag preset.
 *
 * Adds: `--jq <expr>`
@@ -47,4 +129,4 @@ type JqFlags = {
 * Actual jq execution is a consumer concern.
 */
 declare function jqPreset(): FlagPreset<JqFlags>;
-export { outputModePreset, jqPreset, OutputModePresetConfig, OutputModeFlags, JqFlags };
+export { streamPreset, resolveOutputMode, outputModePreset, jqPreset, StreamFlags, ResolvedOutputMode, ResolveOutputModeConfig, OutputModeSource, OutputModePresetConfig, OutputModeFlags, JqFlags };

package/dist/query.js

@@ -1,51 +1,14 @@
 // @bun
 import {
-  createPreset
-} from "./shared/@outfitter/cli-pdb7znbq.js";
-
-// packages/cli/src/query.ts
-function outputModePreset(config) {
-  const defaultMode = config?.defaultMode ?? "human";
-  const baseModes = config?.modes ?? ["human", "json"];
-  const modes = new Set(config?.includeJsonl ? [...baseModes, "jsonl"] : baseModes);
-  modes.add(defaultMode);
-  return createPreset({
-    id: "outputMode",
-    options: [
-      {
-        flags: "-o, --output <mode>",
-        description: `Output mode (${[...modes].join(", ")})`,
-        defaultValue: defaultMode
-      }
-    ],
-    resolve: (flags) => {
-      const raw = flags["output"];
-      if (typeof raw === "string" && modes.has(raw)) {
-        return { outputMode: raw };
-      }
-      return { outputMode: defaultMode };
-    }
-  });
-}
-function jqPreset() {
-  return createPreset({
-    id: "jq",
-    options: [
-      {
-        flags: "--jq <expr>",
-        description: "Filter JSON output with a jq expression"
-      }
-    ],
-    resolve: (flags) => {
-      const raw = flags["jq"];
-      if (typeof raw === "string" && raw.length > 0) {
-        return { jq: raw };
-      }
-      return { jq: undefined };
-    }
-  });
-}
+  jqPreset,
+  outputModePreset,
+  resolveOutputMode,
+  streamPreset
+} from "./shared/@outfitter/cli-vvvhjwks.js";
+import"./shared/@outfitter/cli-8999qjdd.js";
 export {
+  streamPreset,
+  resolveOutputMode,
   outputModePreset,
   jqPreset
 };

package/dist/schema-input.d.ts

@@ -0,0 +1,80 @@
+import { Option } from "commander";
+/** Result of unwrapping a Zod field's type chain. */
+interface ZodFieldInfo {
+	/** The base Zod type name (string, number, boolean, enum). */
+	readonly baseType: string;
+	/** Default value if .default() was used. */
+	readonly defaultValue: unknown;
+	/** Description from .describe(). */
+	readonly description: string | undefined;
+	/** Enum values if baseType is 'enum'. */
+	readonly enumValues: readonly string[] | undefined;
+	/** Whether .default() was used. */
+	readonly hasDefault: boolean;
+	/** Whether the field is optional. */
+	readonly isOptional: boolean;
+}
+/** Derived Commander flag definition from a Zod field. */
+interface DerivedFlag {
+	/** Commander default value. */
+	readonly defaultValue: unknown;
+	/** Commander option description. */
+	readonly description: string;
+	/** Commander flag string (e.g., "--output-dir <value>"). */
+	readonly flagString: string;
+	/** Whether this is a boolean flag (no value). */
+	readonly isBoolean: boolean;
+	/** Whether the field is required (no default, not optional). */
+	readonly isRequired: boolean;
+	/** Long flag name including dashes (e.g., "--output-dir"). */
+	readonly longFlag: string;
+	/** Original camelCase field name from the Zod schema. */
+	readonly name: string;
+}
+/**
+* Convert a camelCase string to kebab-case.
+*/
+declare function camelToKebab(str: string): string;
+/**
+* Unwrap a Zod field to extract its base type, description, default, and optionality.
+*
+* Handles chains like: z.string().optional().default('hi').describe('desc')
+*/
+declare function unwrapZodField(field: unknown): ZodFieldInfo;
+/**
+* Derive Commander flag definitions from a Zod object schema.
+*
+* Handles:
+* - z.string() → `--name <value>` (string option)
+* - z.number() → `--count <n>` (number option with coercion)
+* - z.boolean() → `--verbose` (boolean flag)
+* - z.enum(['a','b']) → `--format <value>` with choices
+* - .describe() → option description
+* - .default() → option default
+* - .optional() → not required
+*/
+declare function deriveFlags(schema: {
+	shape: Record<string, unknown>;
+}, explicitLongFlags: ReadonlySet<string>): DerivedFlag[];
+/**
+* Create a Commander Option from a derived flag definition,
+* including choices for enum types and argParser for number types.
+*/
+declare function createCommanderOption(flag: DerivedFlag, schema: {
+	shape: Record<string, unknown>;
+}): Option;
+/**
+* Extract validated input from parsed Commander flags using a Zod schema.
+*
+* Maps Commander flag values (which use camelCase keys) to the schema
+* field names, then runs Zod validation to apply defaults and coercion.
+*/
+declare function validateInput(flags: Record<string, unknown>, schema: {
+	shape: Record<string, unknown>;
+	safeParse: (data: unknown) => {
+		success: boolean;
+		data?: unknown;
+		error?: unknown;
+	};
+}): Record<string, unknown>;
+export { validateInput, unwrapZodField, deriveFlags, createCommanderOption, camelToKebab, ZodFieldInfo, DerivedFlag };

package/dist/schema-input.js

@@ -0,0 +1,15 @@
+// @bun
+import {
+  camelToKebab,
+  createCommanderOption,
+  deriveFlags,
+  unwrapZodField,
+  validateInput
+} from "./shared/@outfitter/cli-3jta1h1h.js";
+export {
+  validateInput,
+  unwrapZodField,
+  deriveFlags,
+  createCommanderOption,
+  camelToKebab
+};

package/dist/schema.d.ts

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

package/dist/schema.js

@@ -3,7 +3,7 @@ import {
   createSchemaCommand,
   formatManifestHuman,
   generateManifest
-} from "./shared/@outfitter/cli-0cjts94k.js";
+} from "./shared/@outfitter/cli-zv3ah6f0.js";
 export {
   generateManifest,
   formatManifestHuman,

package/dist/shared/@outfitter/cli-10wxfc78.d.ts

@@ -0,0 +1,45 @@
+import { OutputMode, OutputOptions } from "./cli-x6qr7bnd.js";
+/**
+* Detects output mode based on explicit format, environment, and options.
+*
+* Priority: explicit format > env var > default (human)
+*
+* Per CLI conventions (clig.dev), human output is the default.
+* Machine-readable output requires explicit opt-in via --json flag
+* or OUTFITTER_JSON=1 environment variable.
+*/
+declare function detectMode(format?: OutputMode): OutputMode;
+/**
+* Safe JSON stringify that handles circular references and undefined values.
+* Wraps contracts' safeStringify with undefined -> null conversion for CLI JSON output.
+*/
+declare function cliStringify(value: unknown, pretty?: boolean): string;
+/**
+* Formats data for human-readable output.
+*/
+declare function formatHuman(data: unknown): string;
+/**
+* Gets the exit code for an error based on its category.
+* Uses exitCodeMap from @outfitter/contracts for known categories.
+*/
+declare function getExitCode(error: Error): number;
+/**
+* Serializes an error to JSON format for CLI output.
+* Handles both OutfitterError instances and plain Error objects.
+*/
+declare function serializeErrorToJson(error: Error): string;
+/**
+* Formats an error for human-readable output.
+*/
+declare function formatErrorHuman(error: Error): string;
+type OutputSliceTruncation = Pick<NonNullable<OutputOptions["truncation"]>, "limit" | "offset">;
+/**
+* Applies array truncation (limit/offset) to output data.
+*/
+declare function applyOutputTruncation(data: unknown, truncation: OutputSliceTruncation | undefined): unknown;
+/**
+* Writes to a stream with proper backpressure handling.
+* Returns a promise that resolves when the write is complete.
+*/
+declare function writeWithBackpressure(stream: NodeJS.WritableStream, data: string): Promise<void>;
+export { detectMode, cliStringify, formatHuman, getExitCode, serializeErrorToJson, formatErrorHuman, applyOutputTruncation, writeWithBackpressure };

package/dist/shared/@outfitter/cli-16wg5mka.d.ts

@@ -0,0 +1,71 @@
+import { CommandMetadata } from "./cli-xde45xcc.js";
+/**
+* Option metadata in the command tree.
+*/
+interface CommandTreeOption {
+	/** Commander flag string (e.g., "--limit <n>") */
+	readonly flags: string;
+	/** Option description */
+	readonly description: string;
+	/** Default value (absent when no default) */
+	readonly defaultValue?: unknown;
+	/** Whether the option is required */
+	readonly required?: boolean;
+}
+/**
+* A node in the command tree representing a single command or subcommand.
+*/
+interface CommandTreeNode {
+	/** Command name */
+	readonly name: string;
+	/** Command description */
+	readonly description?: string;
+	/** Safety metadata signals (readOnly, idempotent) */
+	readonly metadata?: CommandMetadata;
+	/** Available options/flags */
+	readonly options?: readonly CommandTreeOption[];
+	/** Nested subcommands */
+	readonly subcommands?: readonly CommandTreeNode[];
+}
+/**
+* Full command tree for a CLI application.
+*
+* Used for self-documenting root command output in JSON mode.
+*/
+interface CommandTree {
+	/** CLI name */
+	readonly name: string;
+	/** CLI version */
+	readonly version: string;
+	/** CLI description */
+	readonly description?: string;
+	/** Top-level commands */
+	readonly commands: readonly CommandTreeNode[];
+}
+/**
+* An edge in the action graph representing a relationship between commands.
+*/
+interface ActionGraphEdge {
+	/** Source command name */
+	readonly from: string;
+	/** Target command name */
+	readonly to: string;
+	/** Relationship description (if provided) */
+	readonly description?: string;
+}
+/**
+* An action graph built from `.relatedTo()` declarations on registered commands.
+*
+* Nodes are command names, edges are relationship declarations.
+* Used for tier-4 hint generation — success hints include next-actions
+* from graph neighbors, error hints include remediation paths.
+*/
+interface ActionGraph {
+	/** All registered command names */
+	readonly nodes: readonly string[];
+	/** Relationship edges between commands */
+	readonly edges: readonly ActionGraphEdge[];
+	/** Warnings for invalid references (e.g., unknown targets) */
+	readonly warnings?: readonly string[];
+}
+export { CommandTreeOption, CommandTreeNode, CommandTree, ActionGraphEdge, ActionGraph };