@outfitter/cli 0.5.3 → 1.0.0

package/README.md

@@ -361,6 +361,105 @@ if (flags.reset) {
 }
 ```
 
+## NDJSON Streaming (`@outfitter/cli/streaming`)
+
+Real-time progress reporting via newline-delimited JSON. Handlers emit progress events through an optional `ctx.progress` callback; the CLI adapter writes them as NDJSON lines to stdout.
+
+```typescript
+import { streamPreset } from "@outfitter/cli/query";
+import { runHandler } from "@outfitter/cli/envelope";
+
+command("deploy")
+  .preset(streamPreset())
+  .action(async ({ flags, input }) => {
+    await runHandler({
+      command: "deploy",
+      handler: async (input, ctx) => {
+        ctx.progress?.({ type: "progress", current: 1, total: 3 });
+        // ... work ...
+        return Result.ok({ status: "deployed" });
+      },
+      input,
+      stream: Boolean(flags.stream),
+    });
+  });
+```
+
+```
+$ mycli deploy --stream
+{"type":"start","command":"deploy","ts":"2025-01-01T00:00:00.000Z"}
+{"type":"progress","current":1,"total":3}
+{"ok":true,"command":"deploy","result":{"status":"deployed"}}
+```
+
+`--stream` is orthogonal to output mode — it controls delivery (streaming vs batch), not serialization. Types live in `@outfitter/contracts/stream`.
+
+Low-level utilities (`writeNdjsonLine`, `writeStreamEnvelope`, `createNdjsonProgress`) are exported from `@outfitter/cli/streaming` for custom setups.
+
+## Output Truncation (`@outfitter/cli/truncation`)
+
+Truncate array output with pagination hints and optional file pointers for very large results.
+
+```typescript
+import { truncateOutput } from "@outfitter/cli/truncation";
+
+const result = truncateOutput(items, {
+  limit: 20,
+  offset: 0,
+  commandName: "list",
+});
+// result.data      — sliced items (length <= 20)
+// result.metadata  — { showing: 20, total: 500, truncated: true }
+// result.hints     — [{ description: "Show next 20 of 480...", command: "list --offset 20 --limit 20" }]
+```
+
+When output exceeds `filePointerThreshold` (default: 1000 items), the full result is written to a temp file and `metadata.full_output` contains the file path. File write failures degrade gracefully with a warning hint instead of crashing.
+
+**Exports:** `truncateOutput`, `TruncationOptions`, `TruncationResult`, `TruncationMetadata`, `DEFAULT_FILE_POINTER_THRESHOLD`
+
+## CommandBuilder
+
+The `command()` builder provides a fluent API for defining CLI commands with typed input schemas, safety metadata, and hint generation:
+
+```typescript
+import { command } from "@outfitter/cli/command";
+import { runHandler } from "@outfitter/cli/envelope";
+
+command("delete <id>")
+  .description("Delete a resource")
+  .input(z.object({ id: z.string(), force: z.boolean().default(false) }))
+  .destructive(true) // auto-adds --dry-run flag
+  .relatedTo("list", { description: "List remaining resources" })
+  .hints((result, input) => [
+    { description: "Verify", command: `show ${input.id}` },
+  ])
+  .onError((error, input) => [
+    { description: "Check exists", command: `show ${input.id}` },
+  ])
+  .action(async ({ input, flags }) => {
+    await runHandler({
+      command: "delete",
+      handler: deleteHandler,
+      input,
+      dryRun: Boolean(flags.dryRun),
+    });
+  })
+  .build();
+```
+
+**Safety metadata methods:**
+
+| Method              | Effect                                                                        |
+| ------------------- | ----------------------------------------------------------------------------- |
+| `.destructive()`    | Auto-adds `--dry-run` flag; `runHandler({ dryRun })` generates execution hint |
+| `.readOnly()`       | Surfaces in command tree JSON and maps to MCP `readOnlyHint`                  |
+| `.idempotent()`     | Surfaces in command tree JSON and maps to MCP `idempotentHint`                |
+| `.relatedTo()`      | Declares action graph edges for tier-4 hint generation                        |
+| `.input(schema)`    | Zod schema for auto-derived flags and validation                              |
+| `.context(factory)` | Async factory for handler context construction                                |
+| `.hints(fn)`        | Success hint function called with `(result, input)`                           |
+| `.onError(fn)`      | Error hint function called with `(error, input)`                              |
+
 ## Conventions
 
 Composable flag presets provide typed, reusable CLI flag definitions. See the [full conventions guide](../../docs/cli/conventions.md) for the complete catalog.
@@ -384,13 +483,17 @@ command("deploy")
   });
 ```
 
-**Available presets:** `verbosePreset`, `cwdPreset`, `dryRunPreset`, `forcePreset`, `interactionPreset`, `strictPreset`, `colorPreset`, `projectionPreset`, `paginationPreset`, `timeWindowPreset`, `executionPreset`, `outputModePreset`, `jqPreset`
+**Available presets:** `verbosePreset`, `cwdPreset`, `dryRunPreset`, `forcePreset`, `interactionPreset`, `strictPreset`, `colorPreset`, `projectionPreset`, `paginationPreset`, `timeWindowPreset`, `executionPreset`, `outputModePreset`, `jqPreset`, `streamPreset`
 
 **Additional modules:**
 
 - `@outfitter/cli/verbs` — Standard verb families (`create`, `modify`, `remove`, `list`, `show`)
-- `@outfitter/cli/query` — Output mode and jq expression presets
+- `@outfitter/cli/query` — Output mode, jq expression, and streaming presets
 - `@outfitter/cli/completion` — Shell completion script generation
+- `@outfitter/cli/streaming` — NDJSON streaming primitives
+- `@outfitter/cli/truncation` — Output truncation with pagination hints
+- `@outfitter/cli/envelope` — Response envelope construction and `runHandler()` lifecycle
+- `@outfitter/cli/hints` — Hint generation tiers (command tree, error recovery, schema params, action graph)
 
 ## Configuration
 

package/dist/actions.d.ts

@@ -1,5 +1,8 @@
-import { SchemaCommandOptions } from "./shared/@outfitter/cli-n1k0d23k.js";
-import { FlagPreset } from "./shared/@outfitter/cli-98aa9104.js";
+import "./shared/@outfitter/cli-cgha038c.js";
+import "./shared/@outfitter/cli-nbpgw7z7.js";
+import { SchemaCommandOptions } from "./shared/@outfitter/cli-wjv7g1aq.js";
+import "./shared/@outfitter/cli-qcskd96y.js";
+import { FlagPreset } from "./shared/@outfitter/cli-x6qr7bnd.js";
 import { ActionCliInputContext, ActionCliOption, ActionRegistry, ActionSurface, AnyActionSpec, HandlerContext } from "@outfitter/contracts";
 import { Command } from "commander";
 interface BuildCliCommandsOptions {

package/dist/actions.js

@@ -1,10 +1,10 @@
 // @bun
 import {
   createSchemaCommand
-} from "./shared/@outfitter/cli-5vtr4bdt.js";
+} from "./shared/@outfitter/cli-zv3ah6f0.js";
 import {
   composePresets
-} from "./shared/@outfitter/cli-pdb7znbq.js";
+} from "./shared/@outfitter/cli-8999qjdd.js";
 
 // packages/cli/src/actions.ts
 import {

package/dist/cli.d.ts

@@ -1,4 +1,4 @@
-import { CLI, CLIConfig } from "./shared/@outfitter/cli-98aa9104.js";
+import { CLI, CLIConfig } from "./shared/@outfitter/cli-x6qr7bnd.js";
 /**
 * Create a new CLI instance with the given configuration.
 *

package/dist/cli.js

@@ -1,7 +1,14 @@
 // @bun
 import {
   createCLI
-} from "./shared/@outfitter/cli-zahqsaby.js";
+} from "./shared/@outfitter/cli-d40m2x1d.js";
+import"./shared/@outfitter/cli-89335n9a.js";
+import"./shared/@outfitter/cli-htzez8v2.js";
+import"./shared/@outfitter/cli-hvg2m5gf.js";
+import"./shared/@outfitter/cli-2dfxs239.js";
+import"./shared/@outfitter/cli-4h85mpth.js";
+import"./shared/@outfitter/cli-dg0cz7rw.js";
+import"./shared/@outfitter/cli-3jta1h1h.js";
 export {
   createCLI
 };

package/dist/command.d.ts

@@ -1,43 +1,3 @@
-import { CLI, CLIConfig, CommandAction, CommandBuilder, CommandConfig, CommandFlags, FlagPreset } from "./shared/@outfitter/cli-98aa9104.js";
-/**
-* Create a CLI instance with a portable return type from this module.
-*/
-declare function createCLI(config: CLIConfig): CLI;
-/**
-* Create a new command builder with the given name.
-*
-* The command builder provides a fluent API for defining CLI commands
-* with typed flags, arguments, and actions.
-*
-* @param name - Command name and optional argument syntax (e.g., "list" or "get <id>")
-* @returns A CommandBuilder instance for fluent configuration
-*
-* @example
-* ```typescript
-* import { command, output } from "@outfitter/cli";
-*
-* const list = command("list")
-*   .description("List all notes")
-*   .option("--limit <n>", "Max results", "20")
-*   .option("--json", "Output as JSON")
-*   .option("--next", "Continue from last position")
-*   .action(async ({ flags }) => {
-*     const results = await listNotes(flags);
-*     output(results);
-*   });
-* ```
-*
-* @example
-* ```typescript
-* // Command with required argument
-* const get = command("get <id>")
-*   .description("Get a note by ID")
-*   .action(async ({ args }) => {
-*     const [id] = args;
-*     const note = await getNote(id);
-*     output(note);
-*   });
-* ```
-*/
-declare function command(name: string): CommandBuilder;
-export { createCLI, command, FlagPreset, CommandFlags, CommandConfig, CommandBuilder, CommandAction, CLIConfig, CLI };
+import { CommandMetadata, command, createCLI } from "./shared/@outfitter/cli-xde45xcc.js";
+import { AnyPreset, CLI, CLIConfig, CommandAction, CommandBuilder, CommandConfig, CommandFlags, ContextFactory, ErrorHintFn, FlagPreset, RelatedToDeclaration, RelatedToOptions, SchemaPreset, SuccessHintFn, ZodObjectLike } from "./shared/@outfitter/cli-x6qr7bnd.js";
+export { createCLI, command, ZodObjectLike, SuccessHintFn, SchemaPreset, RelatedToOptions, RelatedToDeclaration, FlagPreset, ErrorHintFn, ContextFactory, CommandMetadata, CommandFlags, CommandConfig, CommandBuilder, CommandAction, CLIConfig, CLI, AnyPreset };

package/dist/command.js

@@ -1,10 +1,87 @@
 // @bun
 import {
   createCLI
-} from "./shared/@outfitter/cli-zahqsaby.js";
+} from "./shared/@outfitter/cli-d40m2x1d.js";
+import {
+  resolveOutputMode
+} from "./shared/@outfitter/cli-vvvhjwks.js";
+import {
+  isSchemaPreset
+} from "./shared/@outfitter/cli-8999qjdd.js";
+import"./shared/@outfitter/cli-89335n9a.js";
+import"./shared/@outfitter/cli-htzez8v2.js";
+import"./shared/@outfitter/cli-hvg2m5gf.js";
+import"./shared/@outfitter/cli-2dfxs239.js";
+import {
+  exitWithError
+} from "./shared/@outfitter/cli-4h85mpth.js";
+import"./shared/@outfitter/cli-dg0cz7rw.js";
+import {
+  createCommanderOption,
+  deriveFlags,
+  validateInput
+} from "./shared/@outfitter/cli-3jta1h1h.js";
 
 // packages/cli/src/command.ts
 import { Command } from "commander";
+import { z } from "zod";
+function buildMergedSchema(inputSchema, schemaPresets) {
+  if (!inputSchema && schemaPresets.length === 0)
+    return;
+  if (schemaPresets.length === 0)
+    return inputSchema;
+  if (!inputSchema && schemaPresets.length === 1) {
+    return schemaPresets[0].schema;
+  }
+  const inputKeys = new Set(Object.keys(inputSchema?.shape ?? {}));
+  const omitOverriddenPresetFields = (schema) => {
+    if (inputKeys.size === 0) {
+      return schema;
+    }
+    const filteredEntries = Object.entries(schema.shape).filter(([key]) => !inputKeys.has(key));
+    if (filteredEntries.length === 0) {
+      return;
+    }
+    const filteredShape = Object.fromEntries(filteredEntries);
+    return z.object(filteredShape);
+  };
+  const mergedShape = {};
+  const allSchemas = [];
+  for (const preset of schemaPresets) {
+    const filteredPresetSchema = omitOverriddenPresetFields(preset.schema);
+    if (!filteredPresetSchema) {
+      continue;
+    }
+    Object.assign(mergedShape, filteredPresetSchema.shape);
+    allSchemas.push(filteredPresetSchema);
+  }
+  if (inputSchema) {
+    Object.assign(mergedShape, inputSchema.shape);
+    allSchemas.push(inputSchema);
+  }
+  return {
+    shape: mergedShape,
+    safeParse(data) {
+      let merged = {};
+      for (const schema of allSchemas) {
+        const schemaData = {};
+        if (data && typeof data === "object") {
+          for (const key of Object.keys(schema.shape)) {
+            if (key in data) {
+              schemaData[key] = data[key];
+            }
+          }
+        }
+        const result = schema.safeParse(schemaData);
+        if (!result.success) {
+          return result;
+        }
+        merged = { ...merged, ...result.data };
+      }
+      return { success: true, data: merged };
+    }
+  };
+}
 function parseCommandSignature(signature) {
   const trimmed = signature.trim();
   const firstWhitespace = trimmed.search(/\s/);
@@ -23,51 +100,202 @@ function createCLI2(config) {
 }
 
 class CommandBuilderImpl {
-  command;
+  cmd;
+  inputSchema;
+  ctxFactory;
+  successHintFn;
+  errorHintsFn;
+  explicitLongFlags = new Set;
+  schemaPresets = [];
+  schemaFlagsApplied = false;
+  _destructive = false;
+  _readOnly = false;
+  _idempotent = false;
+  _relatedTo = [];
   constructor(signature) {
     const { name, argumentsSpec } = parseCommandSignature(signature);
-    this.command = new Command(name);
+    this.cmd = new Command(name);
     if (argumentsSpec) {
-      this.command.arguments(argumentsSpec);
+      this.cmd.arguments(argumentsSpec);
     }
   }
   description(text) {
-    this.command.description(text);
+    this.cmd.description(text);
     return this;
   }
   option(flags, description, defaultValue) {
-    this.command.option(flags, description, defaultValue);
+    const longMatch = flags.match(/--([a-z][a-z0-9-]*)/i);
+    if (longMatch) {
+      this.explicitLongFlags.add(`--${longMatch[1]}`);
+    }
+    this.cmd.option(flags, description, defaultValue);
     return this;
   }
   requiredOption(flags, description, defaultValue) {
-    this.command.requiredOption(flags, description, defaultValue);
+    const longMatch = flags.match(/--([a-z][a-z0-9-]*)/i);
+    if (longMatch) {
+      this.explicitLongFlags.add(`--${longMatch[1]}`);
+    }
+    this.cmd.requiredOption(flags, description, defaultValue);
     return this;
   }
   alias(alias) {
-    this.command.alias(alias);
+    this.cmd.alias(alias);
+    return this;
+  }
+  input(schema) {
+    this.inputSchema = schema;
+    return this;
+  }
+  context(factory) {
+    this.ctxFactory = factory;
+    return this;
+  }
+  hints(fn) {
+    this.successHintFn = fn;
+    return this;
+  }
+  onError(fn) {
+    this.errorHintsFn = fn;
+    return this;
+  }
+  destructive(isDest) {
+    this._destructive = isDest;
+    return this;
+  }
+  readOnly(isReadOnly) {
+    this._readOnly = isReadOnly;
+    return this;
+  }
+  idempotent(isIdempotent) {
+    this._idempotent = isIdempotent;
+    return this;
+  }
+  relatedTo(target, options) {
+    this._relatedTo.push({
+      target,
+      ...options?.description ? { description: options.description } : {}
+    });
     return this;
   }
   preset(preset) {
+    if (isSchemaPreset(preset)) {
+      this.schemaPresets.push(preset);
+      return this;
+    }
     for (const opt of preset.options) {
+      const longMatch = opt.flags.match(/--([a-z][a-z0-9-]*)/i);
+      if (longMatch) {
+        this.explicitLongFlags.add(`--${longMatch[1]}`);
+      }
       if (opt.required) {
-        this.command.requiredOption(opt.flags, opt.description, opt.defaultValue);
+        this.cmd.requiredOption(opt.flags, opt.description, opt.defaultValue);
       } else {
-        this.command.option(opt.flags, opt.description, opt.defaultValue);
+        this.cmd.option(opt.flags, opt.description, opt.defaultValue);
       }
     }
     return this;
   }
   action(handler) {
-    this.command.action(async (...args) => {
+    const schema = this.inputSchema;
+    const contextFactory = this.ctxFactory;
+    const presets = [...this.schemaPresets];
+    this.applySchemaFlags();
+    const mergedSchema = buildMergedSchema(schema, presets);
+    this.cmd.action(async (...args) => {
       const command = args.at(-1);
       const flags = command.optsWithGlobals?.() ?? command.opts();
       const positional = command.args;
-      await handler({ args: positional, flags, command });
+      let input;
+      let ctx;
+      try {
+        input = mergedSchema ? validateInput(flags, mergedSchema) : undefined;
+        if (input !== undefined && presets.length > 0) {
+          for (const preset of presets) {
+            const resolved = preset.resolve(flags);
+            Object.assign(input, resolved);
+          }
+        }
+        if (contextFactory) {
+          const factoryArg = input !== undefined ? input : flags;
+          ctx = await contextFactory(factoryArg);
+        }
+      } catch (err) {
+        const error = err instanceof Error ? err : new Error(String(err));
+        const { mode } = resolveOutputMode(flags);
+        exitWithError(error, mode);
+        return;
+      }
+      await handler({
+        args: positional,
+        flags,
+        command,
+        input,
+        ctx
+      });
     });
     return this;
   }
   build() {
-    return this.command;
+    this.applySchemaFlags();
+    this.applyDestructiveFlag();
+    if (this.successHintFn) {
+      this.cmd.__successHintFn = this.successHintFn;
+    }
+    if (this.errorHintsFn) {
+      this.cmd.__errorHintFn = this.errorHintsFn;
+    }
+    const metadata = {};
+    if (this._readOnly) {
+      metadata.readOnly = true;
+    }
+    if (this._idempotent) {
+      metadata.idempotent = true;
+    }
+    if (metadata.readOnly !== undefined || metadata.idempotent !== undefined) {
+      this.cmd.__metadata = metadata;
+    }
+    if (this._relatedTo.length > 0) {
+      this.cmd.__relatedTo = [...this._relatedTo];
+    }
+    return this.cmd;
+  }
+  applySchemaFlags() {
+    if (this.schemaFlagsApplied)
+      return;
+    if (!this.inputSchema && this.schemaPresets.length === 0)
+      return;
+    this.schemaFlagsApplied = true;
+    const existingLongs = new Set(this.explicitLongFlags);
+    for (const opt of this.cmd.options) {
+      if (opt.long) {
+        existingLongs.add(opt.long);
+      }
+    }
+    if (this.inputSchema) {
+      const derived = deriveFlags(this.inputSchema, existingLongs);
+      for (const flag of derived) {
+        const option = createCommanderOption(flag, this.inputSchema);
+        this.cmd.addOption(option);
+        existingLongs.add(flag.longFlag);
+      }
+    }
+    for (const schemaPreset of this.schemaPresets) {
+      const derived = deriveFlags(schemaPreset.schema, existingLongs);
+      for (const flag of derived) {
+        const option = createCommanderOption(flag, schemaPreset.schema);
+        this.cmd.addOption(option);
+        existingLongs.add(flag.longFlag);
+      }
+    }
+  }
+  applyDestructiveFlag() {
+    if (!this._destructive)
+      return;
+    const hasDryRun = this.cmd.options.some((o) => o.long === "--dry-run");
+    if (hasDryRun)
+      return;
+    this.cmd.option("--dry-run", "Preview changes without applying (destructive command safety)", false);
   }
 }
 function command(name) {

package/dist/envelope.d.ts

@@ -0,0 +1,5 @@
+import { runHandler } from "./shared/@outfitter/cli-c09332vm.js";
+import { createErrorEnvelope, createSuccessEnvelope } from "./shared/@outfitter/cli-nkt399zf.js";
+import { CommandEnvelope, ErrorEnvelope, RunHandlerOptions, SuccessEnvelope } from "./shared/@outfitter/cli-30mt7c5w.js";
+import "./shared/@outfitter/cli-x6qr7bnd.js";
+export { runHandler, createSuccessEnvelope, createErrorEnvelope, SuccessEnvelope, RunHandlerOptions, ErrorEnvelope, CommandEnvelope };

package/dist/envelope.js

@@ -0,0 +1,160 @@
+// @bun
+import {
+  buildDryRunHint,
+  createErrorEnvelope,
+  createSuccessEnvelope,
+  extractCategory,
+  extractMessage,
+  extractRetryAfterSeconds,
+  formatEnvelopeHuman,
+  getExitCode,
+  safeCallHintFn
+} from "./shared/@outfitter/cli-ry7btmy4.js";
+import {
+  createNdjsonProgress,
+  writeNdjsonLine,
+  writeStreamEnvelope
+} from "./shared/@outfitter/cli-g43887b7.js";
+import {
+  output
+} from "./shared/@outfitter/cli-4h85mpth.js";
+import {
+  detectMode
+} from "./shared/@outfitter/cli-dg0cz7rw.js";
+
+// packages/cli/src/envelope.ts
+import { safeStringify } from "@outfitter/contracts";
+async function runHandler(options) {
+  const {
+    command: commandName,
+    handler,
+    input,
+    format,
+    contextFactory,
+    hints: hintsFn,
+    onError: onErrorFn,
+    stream: isStreaming = false,
+    dryRun: isDryRun = false
+  } = options;
+  const inputValue = input;
+  const resolvedFormat = format ?? detectMode();
+  const isJsonMode = resolvedFormat === "json" || resolvedFormat === "jsonl";
+  let progressCallback;
+  if (isStreaming) {
+    const startEvent = {
+      type: "start",
+      command: commandName,
+      ts: new Date().toISOString()
+    };
+    writeNdjsonLine(startEvent);
+    const writeProgress = createNdjsonProgress(commandName);
+    progressCallback = (event) => {
+      if (event.type === "start") {
+        return;
+      }
+      writeProgress(event);
+    };
+  }
+  let context;
+  if (contextFactory) {
+    try {
+      const rawContext = await contextFactory(inputValue);
+      if (isStreaming && rawContext && typeof rawContext === "object") {
+        context = Object.assign(Object.create(Object.getPrototypeOf(rawContext)), rawContext, { progress: progressCallback });
+      } else {
+        context = rawContext;
+      }
+    } catch (err) {
+      const error = err instanceof Error ? err : new Error(String(err));
+      const category = extractCategory(error);
+      const message = extractMessage(error);
+      const retryAfter = extractRetryAfterSeconds(error);
+      const errorHints = onErrorFn ? safeCallHintFn(() => onErrorFn(error, inputValue)) : undefined;
+      const envelope = createErrorEnvelope(commandName, category, message, errorHints, retryAfter);
+      if (isStreaming) {
+        writeStreamEnvelope(envelope);
+        const exitCode = getExitCode(category);
+        process.exit(exitCode);
+      }
+      outputErrorEnvelope(envelope, isJsonMode);
+      return;
+    }
+  } else if (isStreaming) {
+    context = { progress: progressCallback };
+  } else {
+    context = undefined;
+  }
+  let result;
+  try {
+    result = await handler(inputValue, context);
+  } catch (err) {
+    const error = err instanceof Error ? err : new Error(String(err));
+    const category = extractCategory(error);
+    const message = extractMessage(error);
+    const retryAfter = extractRetryAfterSeconds(error);
+    const errorHints = onErrorFn ? safeCallHintFn(() => onErrorFn(error, inputValue)) : undefined;
+    const envelope = createErrorEnvelope(commandName, category, message, errorHints, retryAfter);
+    if (isStreaming) {
+      writeStreamEnvelope(envelope);
+      const exitCode = getExitCode(category);
+      process.exit(exitCode);
+    }
+    outputErrorEnvelope(envelope, isJsonMode);
+    return;
+  }
+  if (result.isOk()) {
+    let successHints = hintsFn ? safeCallHintFn(() => hintsFn(result.value, inputValue)) : undefined;
+    if (isDryRun) {
+      const dryRunHint = buildDryRunHint(options.argv);
+      if (dryRunHint) {
+        successHints = successHints ? [...successHints, dryRunHint] : [dryRunHint];
+      }
+    }
+    const envelope = createSuccessEnvelope(commandName, result.value, successHints);
+    if (isStreaming) {
+      writeStreamEnvelope(envelope);
+      return;
+    }
+    if (isJsonMode) {
+      await output(envelope, resolvedFormat);
+    } else {
+      const formatted = formatEnvelopeHuman(envelope);
+      if (formatted.stdout) {
+        process.stdout.write(`${formatted.stdout}
+`);
+      }
+    }
+  } else {
+    const error = result.error;
+    const category = extractCategory(error);
+    const message = extractMessage(error);
+    const retryAfter = extractRetryAfterSeconds(error);
+    const errorHints = onErrorFn ? safeCallHintFn(() => onErrorFn(error, inputValue)) : undefined;
+    const envelope = createErrorEnvelope(commandName, category, message, errorHints, retryAfter);
+    if (isStreaming) {
+      writeStreamEnvelope(envelope);
+      const exitCode = getExitCode(category);
+      process.exit(exitCode);
+    }
+    outputErrorEnvelope(envelope, isJsonMode);
+  }
+}
+function outputErrorEnvelope(envelope, isJsonMode) {
+  const exitCode = getExitCode(envelope.error.category);
+  if (isJsonMode) {
+    process.stderr.write(`${safeStringify(envelope)}
+`);
+  } else {
+    const formatted = formatEnvelopeHuman(envelope);
+    if (formatted.stderr) {
+      process.stderr.write(`${formatted.stderr}
+`);
+    }
+  }
+  process.exit(exitCode);
+}
+export {
+  runHandler,
+  createSuccessEnvelope,
+  createErrorEnvelope
+};