@outfitter/cli 0.5.3 → 1.0.0

package/dist/output.js

@@ -1,172 +1,19 @@
 // @bun
-// packages/cli/src/output.ts
-import { getEnvironment, getEnvironmentDefaults } from "@outfitter/config";
 import {
-  safeStringify as contractsSafeStringify,
-  exitCodeMap
-} from "@outfitter/contracts";
-var DEFAULT_EXIT_CODE = 1;
-function writeWithBackpressure(stream, data) {
-  return new Promise((resolve, reject) => {
-    const canContinue = stream.write(data, (error) => {
-      if (error)
-        reject(error);
-    });
-    if (canContinue) {
-      resolve();
-    } else {
-      stream.once("drain", () => resolve());
-      stream.once("error", reject);
-    }
-  });
-}
-function detectMode(options) {
-  if (options?.mode) {
-    return options.mode;
-  }
-  const envJsonl = process.env["OUTFITTER_JSONL"];
-  const envJson = process.env["OUTFITTER_JSON"];
-  if (envJsonl === "1")
-    return "jsonl";
-  if (envJson === "1")
-    return "json";
-  if (envJsonl === "0" || envJson === "0")
-    return "human";
-  return "human";
-}
-function isValidCategory(category) {
-  return category in exitCodeMap;
-}
-function safeStringify(value, pretty) {
-  const wrappedValue = value === undefined ? null : value;
-  return contractsSafeStringify(wrappedValue, pretty ? 2 : undefined);
-}
-function formatHuman(data) {
-  if (data === null || data === undefined) {
-    return "";
-  }
-  if (typeof data === "string") {
-    return data;
-  }
-  if (typeof data === "number" || typeof data === "boolean") {
-    return String(data);
-  }
-  if (Array.isArray(data)) {
-    return data.map((item) => formatHuman(item)).join(`
-`);
-  }
-  if (typeof data === "object") {
-    const lines = [];
-    for (const [key, value] of Object.entries(data)) {
-      lines.push(`${key}: ${formatHuman(value)}`);
-    }
-    return lines.join(`
-`);
-  }
-  return String(data);
-}
-function getErrorProperties(error) {
-  const errorObj = error;
-  return {
-    _tag: errorObj._tag,
-    category: errorObj.category,
-    context: errorObj.context
-  };
-}
-function getExitCode(error) {
-  const { category } = getErrorProperties(error);
-  if (category !== undefined && isValidCategory(category)) {
-    return exitCodeMap[category];
-  }
-  return DEFAULT_EXIT_CODE;
-}
-function serializeErrorToJson(error) {
-  const { _tag, category, context } = getErrorProperties(error);
-  const result = {
-    message: error.message
-  };
-  if (_tag !== undefined) {
-    result._tag = _tag;
-  }
-  if (category !== undefined) {
-    result.category = category;
-  }
-  if (context !== undefined) {
-    result.context = context;
-  }
-  return JSON.stringify(result);
-}
-function formatErrorHuman(error) {
-  const { _tag } = getErrorProperties(error);
-  if (_tag) {
-    return `${_tag}: ${error.message}`;
-  }
-  return error.message;
-}
-async function output(data, options) {
-  const mode = detectMode(options);
-  const stream = options?.stream ?? process.stdout;
-  let outputText;
-  switch (mode) {
-    case "json": {
-      const jsonData = data === undefined ? null : data;
-      outputText = safeStringify(jsonData, options?.pretty);
-      break;
-    }
-    case "jsonl": {
-      if (Array.isArray(data)) {
-        if (data.length === 0) {
-          outputText = "";
-        } else {
-          outputText = data.map((item) => safeStringify(item)).join(`
-`);
-        }
-      } else {
-        outputText = safeStringify(data);
-      }
-      break;
-    }
-    default: {
-      outputText = formatHuman(data);
-      break;
-    }
-  }
-  if (outputText) {
-    await writeWithBackpressure(stream, `${outputText}
-`);
-  }
-}
-function exitWithError(error, options) {
-  const exitCode = getExitCode(error);
-  const mode = detectMode({
-    ...options,
-    stream: options?.stream ?? process.stderr
-  });
-  const isJsonMode = mode === "json" || mode === "jsonl";
-  if (isJsonMode) {
-    process.stderr.write(`${serializeErrorToJson(error)}
-`);
-  } else {
-    process.stderr.write(`${formatErrorHuman(error)}
-`);
-  }
-  process.exit(exitCode);
-}
-function resolveVerbose(verbose) {
-  const envVerbose = process.env["OUTFITTER_VERBOSE"];
-  if (envVerbose === "1")
-    return true;
-  if (envVerbose === "0")
-    return false;
-  if (verbose !== undefined) {
-    return verbose;
-  }
-  const env = getEnvironment();
-  const defaults = getEnvironmentDefaults(env);
-  return defaults.verbose;
-}
+  exitWithError,
+  output,
+  resolveVerbose
+} 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-5vtr4bdt.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 };