@outfitter/cli 0.5.2 → 1.0.0

package/README.md

@@ -56,11 +56,11 @@ output(errors, { stream: process.stderr });
 
 **Options:**
 
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `mode` | `OutputMode` | auto | Force a specific output mode |
-| `stream` | `WritableStream` | `stdout` | Stream to write to |
-| `pretty` | `boolean` | `false` | Pretty-print JSON output |
+| Option   | Type             | Default  | Description                  |
+| -------- | ---------------- | -------- | ---------------------------- |
+| `mode`   | `OutputMode`     | auto     | Force a specific output mode |
+| `stream` | `WritableStream` | `stdout` | Stream to write to           |
+| `pretty` | `boolean`        | `false`  | Pretty-print JSON output     |
 
 **Output Modes:**
 
@@ -108,10 +108,10 @@ const ids = await collectIds(args.ids, {
 
 **Options:**
 
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `allowFile` | `boolean` | `true` | Allow `@file` expansion |
-| `allowStdin` | `boolean` | `true` | Allow `@-` for stdin |
+| Option       | Type      | Default | Description             |
+| ------------ | --------- | ------- | ----------------------- |
+| `allowFile`  | `boolean` | `true`  | Allow `@file` expansion |
+| `allowStdin` | `boolean` | `true`  | Allow `@-` for stdin    |
 
 #### `expandFileArg(input, options?)`
 
@@ -132,11 +132,11 @@ const content = await expandFileArg(args.content, {
 
 **Options:**
 
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `encoding` | `BufferEncoding` | `utf-8` | File encoding |
-| `maxSize` | `number` | - | Maximum file size in bytes |
-| `trim` | `boolean` | `false` | Trim whitespace |
+| Option     | Type             | Default | Description                |
+| ---------- | ---------------- | ------- | -------------------------- |
+| `encoding` | `BufferEncoding` | `utf-8` | File encoding              |
+| `maxSize`  | `number`         | -       | Maximum file size in bytes |
+| `trim`     | `boolean`        | `false` | Trim whitespace            |
 
 #### `parseGlob(pattern, options?)`
 
@@ -154,13 +154,13 @@ const files = await parseGlob("src/**/*.ts", {
 
 **Options:**
 
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `cwd` | `string` | `process.cwd()` | Working directory |
-| `ignore` | `string[]` | `[]` | Patterns to exclude |
-| `onlyFiles` | `boolean` | `false` | Only match files |
-| `onlyDirectories` | `boolean` | `false` | Only match directories |
-| `followSymlinks` | `boolean` | `false` | Follow symbolic links |
+| Option            | Type       | Default         | Description            |
+| ----------------- | ---------- | --------------- | ---------------------- |
+| `cwd`             | `string`   | `process.cwd()` | Working directory      |
+| `ignore`          | `string[]` | `[]`            | Patterns to exclude    |
+| `onlyFiles`       | `boolean`  | `false`         | Only match files       |
+| `onlyDirectories` | `boolean`  | `false`         | Only match directories |
+| `followSymlinks`  | `boolean`  | `false`         | Follow symbolic links  |
 
 #### `parseKeyValue(input)`
 
@@ -219,15 +219,15 @@ if (result.isOk()) {
 
 **Filter Operators:**
 
-| Prefix | Operator | Description |
-|--------|----------|-------------|
-| (none) | `eq` | Equals (default) |
-| `!` | `ne` | Not equals |
-| `>` | `gt` | Greater than |
-| `<` | `lt` | Less than |
-| `>=` | `gte` | Greater than or equal |
-| `<=` | `lte` | Less than or equal |
-| `~` | `contains` | Contains substring |
+| Prefix | Operator   | Description           |
+| ------ | ---------- | --------------------- |
+| (none) | `eq`       | Equals (default)      |
+| `!`    | `ne`       | Not equals            |
+| `>`    | `gt`       | Greater than          |
+| `<`    | `lt`       | Less than             |
+| `>=`   | `gte`      | Greater than or equal |
+| `<=`   | `lte`      | Less than or equal    |
+| `~`    | `contains` | Contains substring    |
 
 #### `parseSortSpec(input)`
 
@@ -268,13 +268,13 @@ if (result.isOk()) {
 
 **Options:**
 
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `trim` | `boolean` | `false` | Trim whitespace |
+| Option      | Type      | Default | Description          |
+| ----------- | --------- | ------- | -------------------- |
+| `trim`      | `boolean` | `false` | Trim whitespace      |
 | `lowercase` | `boolean` | `false` | Convert to lowercase |
-| `minLength` | `number` | - | Minimum length |
-| `maxLength` | `number` | - | Maximum length |
-| `pattern` | `RegExp` | - | Required pattern |
+| `minLength` | `number`  | -       | Minimum length       |
+| `maxLength` | `number`  | -       | Maximum length       |
+| `pattern`   | `RegExp`  | -       | Required pattern     |
 
 #### `confirmDestructive(options)`
 
@@ -361,12 +361,116 @@ 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.
 
 ```typescript
-import { composePresets, verbosePreset, cwdPreset, forcePreset } from "@outfitter/cli/flags";
+import {
+  composePresets,
+  verbosePreset,
+  cwdPreset,
+  forcePreset,
+} from "@outfitter/cli/flags";
 import { outputModePreset } from "@outfitter/cli/query";
 
 const preset = composePresets(verbosePreset(), cwdPreset(), forcePreset());
@@ -379,30 +483,36 @@ 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
 
 ### Environment Variables
 
-| Variable | Description | Default |
-|----------|-------------|---------|
-| `OUTFITTER_ENV` | Environment profile (`development`, `production`, `test`) | `production` |
-| `OUTFITTER_VERBOSE` | Override verbose mode (`1` or `0`) | - |
-| `OUTFITTER_JSON` | Set to `1` to force JSON output | - |
-| `OUTFITTER_JSONL` | Set to `1` to force JSONL output (takes priority over JSON) | - |
-| `XDG_STATE_HOME` | State directory for pagination | Platform-specific |
+| Variable            | Description                                                 | Default           |
+| ------------------- | ----------------------------------------------------------- | ----------------- |
+| `OUTFITTER_ENV`     | Environment profile (`development`, `production`, `test`)   | `production`      |
+| `OUTFITTER_VERBOSE` | Override verbose mode (`1` or `0`)                          | -                 |
+| `OUTFITTER_JSON`    | Set to `1` to force JSON output                             | -                 |
+| `OUTFITTER_JSONL`   | Set to `1` to force JSONL output (takes priority over JSON) | -                 |
+| `XDG_STATE_HOME`    | State directory for pagination                              | Platform-specific |
 
 ### `resolveVerbose(verbose?)`
 
 Resolve verbose mode from environment configuration. Use this instead of hardcoding verbosity so your CLI responds to `OUTFITTER_ENV` and `OUTFITTER_VERBOSE` automatically.
 
 **Precedence** (highest wins):
+
 1. `OUTFITTER_VERBOSE` environment variable (`"1"` or `"0"`)
 2. Explicit `verbose` parameter (from `--verbose` CLI flag)
 3. `OUTFITTER_ENV` profile defaults (`true` in development)
@@ -449,18 +559,18 @@ The bridge uses `optsWithGlobals()` so global and subcommand `--json` flags both
 
 Exit codes are automatically determined from error categories:
 
-| Category | Exit Code |
-|----------|-----------|
-| `validation` | 1 |
-| `not_found` | 2 |
-| `conflict` | 3 |
-| `permission` | 4 |
-| `timeout` | 5 |
-| `rate_limit` | 6 |
-| `network` | 7 |
-| `internal` | 8 |
-| `auth` | 9 |
-| `cancelled` | 130 |
+| Category     | Exit Code |
+| ------------ | --------- |
+| `validation` | 1         |
+| `not_found`  | 2         |
+| `conflict`   | 3         |
+| `permission` | 4         |
+| `timeout`    | 5         |
+| `rate_limit` | 6         |
+| `network`    | 7         |
+| `internal`   | 8         |
+| `auth`       | 9         |
+| `cancelled`  | 130       |
 
 ### Tagged Errors
 
@@ -478,9 +588,18 @@ exitWithError(error); // Exits with code 2
 All types are exported for TypeScript consumers:
 
 ```typescript
-import type { CLIConfig, CommandConfig, CommandAction, CommandFlags } from "@outfitter/cli/command";
+import type {
+  CLIConfig,
+  CommandConfig,
+  CommandAction,
+  CommandFlags,
+} from "@outfitter/cli/command";
 import type { OutputMode, OutputOptions } from "@outfitter/cli/output";
-import type { CollectIdsOptions, ExpandFileOptions, ParseGlobOptions } from "@outfitter/cli/input";
+import type {
+  CollectIdsOptions,
+  ExpandFileOptions,
+  ParseGlobOptions,
+} from "@outfitter/cli/input";
 import type { PaginationState, CursorOptions } from "@outfitter/cli/pagination";
 ```
 

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-0cjts94k.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/colors/index.js

@@ -1,17 +1 @@
-// @bun
-import"../shared/@outfitter/cli-zw75pdk8.js";
-import {
-  ANSI,
-  applyColor,
-  createTheme,
-  createTokens,
-  resolveTokenColorEnabled
-} from "../shared/@outfitter/cli-rk9zagkm.js";
-import"../shared/@outfitter/cli-jbj78ac5.js";
-export {
-  resolveTokenColorEnabled,
-  createTokens,
-  createTheme,
-  applyColor,
-  ANSI
-};
+export { ANSI, applyColor, createTheme, createTokens, resolveTokenColorEnabled } from "./colors.js";

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 };