@outfitter/cli 0.5.2 → 1.0.0

package/dist/shared/@outfitter/cli-hvg2m5gf.js

@@ -0,0 +1,79 @@
+// @bun
+// packages/cli/src/internal/hint-action-graph.ts
+function buildActionGraph(program) {
+  const nodes = [];
+  const edges = [];
+  const warnings = [];
+  const commandNames = new Set;
+  function collectCommandNames(cmds, prefix = "") {
+    for (const cmd of cmds) {
+      const leaf = cmd.name();
+      const fullName = prefix ? `${prefix} ${leaf}` : leaf;
+      commandNames.add(fullName);
+      if (cmd.commands.length > 0) {
+        collectCommandNames(cmd.commands, fullName);
+      }
+    }
+  }
+  collectCommandNames(program.commands);
+  function walkCommands(cmds, prefix = "") {
+    for (const cmd of cmds) {
+      const leaf = cmd.name();
+      const fullName = prefix ? `${prefix} ${leaf}` : leaf;
+      nodes.push(fullName);
+      const relatedTo = cmd.__relatedTo;
+      if (relatedTo) {
+        for (const decl of relatedTo) {
+          const edge = {
+            from: fullName,
+            to: decl.target,
+            ...decl.description ? { description: decl.description } : {}
+          };
+          edges.push(edge);
+          if (!commandNames.has(decl.target)) {
+            warnings.push(`Unknown relationship target "${decl.target}" from command "${fullName}"`);
+          }
+        }
+      }
+      if (cmd.commands.length > 0) {
+        walkCommands(cmd.commands, fullName);
+      }
+    }
+  }
+  walkCommands(program.commands);
+  return {
+    nodes,
+    edges,
+    ...warnings.length > 0 ? { warnings } : {}
+  };
+}
+function graphSuccessHints(graph, commandName, cliName) {
+  const hints = [];
+  for (const edge of graph.edges) {
+    if (edge.from === commandName && edge.to !== commandName) {
+      const prefix = cliName ? `${cliName} ` : "";
+      const description = edge.description ?? `Run ${edge.to}`;
+      hints.push({
+        description,
+        command: `${prefix}${edge.to}`
+      });
+    }
+  }
+  return hints;
+}
+function graphErrorHints(graph, commandName, cliName) {
+  const hints = [];
+  for (const edge of graph.edges) {
+    if (edge.from === commandName && edge.to !== commandName) {
+      const prefix = cliName ? `${cliName} ` : "";
+      const description = edge.description ? `Try: ${edge.description}` : `Try: ${edge.to}`;
+      hints.push({
+        description,
+        command: `${prefix}${edge.to}`
+      });
+    }
+  }
+  return hints;
+}
+
+export { buildActionGraph, graphSuccessHints, graphErrorHints };

package/dist/shared/@outfitter/cli-n54zs151.d.ts

@@ -0,0 +1,78 @@
+import { ComposedPreset, FlagPreset, FlagPresetConfig, SchemaPreset, SchemaPresetConfig } from "./cli-x6qr7bnd.js";
+/** Extracts the resolved type from a flag preset. */
+type ResolvedType<T> = T extends FlagPreset<infer R> ? R : never;
+/** Converts a union type into an intersection type. */
+type UnionToIntersection<U> = (U extends unknown ? (k: U) => void : never) extends (k: infer I) => void ? I : never;
+/**
+* Resolves the merged type from a tuple of presets.
+* Falls back to Record<string, unknown> when the tuple is empty
+* (since UnionToIntersection<never> produces unknown).
+*/
+type MergedPresetResult<TPresets extends readonly FlagPreset<Record<string, unknown>>[]> = UnionToIntersection<ResolvedType<TPresets[number]>> extends Record<string, unknown> ? UnionToIntersection<ResolvedType<TPresets[number]>> : Record<string, unknown>;
+/**
+* Create a typed flag preset.
+*
+* @param config - Preset configuration with id, options, and resolver
+* @returns A flag preset that can be applied to commands or composed
+*
+* @example
+* ```typescript
+* const myPreset = createPreset({
+*   id: "output-format",
+*   options: [{ flags: "--format <type>", description: "Output format" }],
+*   resolve: (flags) => ({
+*     format: String(flags["format"] ?? "text"),
+*   }),
+* });
+* ```
+*/
+declare function createPreset<TResolved extends Record<string, unknown>>(config: FlagPresetConfig<TResolved>): FlagPreset<TResolved>;
+/**
+* Create a schema-driven preset using a Zod schema fragment.
+*
+* Instead of declaring Commander options manually, the schema fragment
+* is introspected to auto-derive flags (same as `.input()`). The resolve
+* function maps raw Commander flags into typed values.
+*
+* @param config - Preset configuration with id, schema, and resolver
+* @returns A schema preset that can be applied to commands via `.preset()`
+*
+* @example
+* ```typescript
+* const outputPreset = createSchemaPreset({
+*   id: "output-format",
+*   schema: z.object({
+*     format: z.enum(["json", "text"]).default("text").describe("Output format"),
+*     pretty: z.boolean().default(false).describe("Pretty print"),
+*   }),
+*   resolve: (flags) => ({
+*     format: String(flags["format"] ?? "text"),
+*     pretty: Boolean(flags["pretty"]),
+*   }),
+* });
+* ```
+*/
+declare function createSchemaPreset<TResolved extends Record<string, unknown>>(config: SchemaPresetConfig<TResolved>): SchemaPreset<TResolved>;
+/**
+* Type guard to check whether a preset is a schema-driven preset.
+*/
+declare function isSchemaPreset(preset: FlagPreset<Record<string, unknown>> | SchemaPreset<Record<string, unknown>>): preset is SchemaPreset<Record<string, unknown>>;
+/**
+* Compose multiple presets into one, deduplicating by id (first wins).
+*
+* @param presets - Presets to compose together
+* @returns A single preset merging all options and resolvers
+*
+* @example
+* ```typescript
+* const composed = composePresets(
+*   verbosePreset(),
+*   cwdPreset(),
+*   forcePreset(),
+* );
+* // composed.resolve({ verbose: true, cwd: "/tmp", force: false })
+* // => { verbose: true, cwd: "/tmp", force: false }
+* ```
+*/
+declare function composePresets<TPresets extends readonly FlagPreset<Record<string, unknown>>[]>(...presets: TPresets): ComposedPreset<MergedPresetResult<TPresets>>;
+export { createPreset, createSchemaPreset, isSchemaPreset, composePresets };

package/dist/shared/@outfitter/cli-nbpgw7z7.d.ts

@@ -0,0 +1,15 @@
+import { SchemaCommandOptions } from "./cli-wjv7g1aq.js";
+import { ActionSource } from "@outfitter/schema";
+import { Command } from "commander";
+/**
+* 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 { createSchemaCommand };

package/dist/shared/@outfitter/cli-nkt399zf.d.ts

@@ -0,0 +1,94 @@
+import { CommandEnvelope, ErrorEnvelope, SuccessEnvelope } from "./cli-30mt7c5w.js";
+import { CLIHint, ErrorCategory } from "@outfitter/contracts";
+/**
+* Create a success envelope wrapping a command result.
+*
+* The `hints` field is omitted when hints is undefined, null, or empty.
+*
+* @param command - Command name
+* @param result - Handler result value
+* @param hints - Optional CLI hints for next actions
+* @returns A success envelope
+*
+* @example
+* ```typescript
+* const envelope = createSuccessEnvelope("deploy", { status: "deployed" }, [
+*   { description: "Check status", command: "deploy status" },
+* ]);
+* ```
+*/
+declare function createSuccessEnvelope<T>(command: string, result: T, hints?: CLIHint[]): SuccessEnvelope<T>;
+/**
+* Create an error envelope wrapping a command failure.
+*
+* The `hints` field is omitted when hints is undefined, null, or empty.
+* The `retryable` field is derived from the error category metadata.
+* The `retry_after` field is included only when `retryAfterSeconds` is provided
+* (typically from a `RateLimitError`).
+*
+* @param command - Command name
+* @param category - Error category from the taxonomy
+* @param message - Human-readable error message
+* @param hints - Optional CLI hints for error recovery
+* @param retryAfterSeconds - Optional retry delay in seconds (from RateLimitError)
+* @returns An error envelope
+*
+* @example
+* ```typescript
+* const envelope = createErrorEnvelope("deploy", "validation", "Missing env", [
+*   { description: "Specify env", command: "deploy --env prod" },
+* ]);
+* // envelope.error.retryable === false
+*
+* const rateLimitEnvelope = createErrorEnvelope(
+*   "fetch",
+*   "rate_limit",
+*   "Too many requests",
+*   undefined,
+*   60
+* );
+* // rateLimitEnvelope.error.retryable === true, retry_after === 60
+* ```
+*/
+declare function createErrorEnvelope(command: string, category: ErrorCategory, message: string, hints?: CLIHint[], retryAfterSeconds?: number): ErrorEnvelope;
+/**
+* Build a CLIHint for executing the current command without --dry-run.
+*
+* Strips the --dry-run flag and its variants (--dry-run=true, --dry-run=false, etc.),
+* producing a hint like: `delete --id abc --force` (without --dry-run).
+*
+* @param argv - Parsed argv to strip --dry-run from. Defaults to `process.argv.slice(2)`.
+*/
+declare function buildDryRunHint(argv?: readonly string[]): CLIHint | undefined;
+/**
+* Extract error category from an error object.
+* Works with OutfitterError instances and duck-typed errors.
+*/
+declare function extractCategory(error: unknown): ErrorCategory;
+/**
+* Extract error message from an error object.
+*/
+declare function extractMessage(error: unknown): string;
+/**
+* Extract retryAfterSeconds from an error object (if present).
+* Works with RateLimitError instances and duck-typed errors.
+*/
+declare function extractRetryAfterSeconds(error: unknown): number | undefined;
+/**
+* Get exit code for an error category.
+*/
+declare function getExitCode(category: ErrorCategory): number;
+/**
+* Format an envelope for human-readable output.
+* Returns stdout and stderr portions separately.
+*/
+declare function formatEnvelopeHuman(envelope: CommandEnvelope): {
+	stdout: string;
+	stderr: string;
+};
+/**
+* Safely call a hint function, returning undefined if it throws.
+* Hint functions should never cause the command to fail.
+*/
+declare function safeCallHintFn(fn: () => CLIHint[]): CLIHint[] | undefined;
+export { createSuccessEnvelope, createErrorEnvelope, buildDryRunHint, extractCategory, extractMessage, extractRetryAfterSeconds, getExitCode, formatEnvelopeHuman, safeCallHintFn };

package/dist/shared/@outfitter/cli-pmd04gtv.d.ts

@@ -0,0 +1,60 @@
+import { ActionGraph } from "./cli-16wg5mka.js";
+import { CLIHint } from "@outfitter/contracts";
+import { Command } from "commander";
+/**
+* Build an action graph from a Commander program's registered commands.
+*
+* Walks all commands, collecting `.relatedTo()` declarations as edges.
+* Unknown targets produce warnings (not crashes). Self-links and cycles
+* are preserved in the graph — callers handle them during traversal.
+*
+* @param program - The Commander program (root command)
+* @returns An action graph with nodes, edges, and optional warnings
+*
+* @example
+* ```typescript
+* const graph = buildActionGraph(program);
+* // graph.nodes: ["deploy", "status", "rollback"]
+* // graph.edges: [{ from: "deploy", to: "status", description: "Check status" }]
+* ```
+*/
+declare function buildActionGraph(program: Command): ActionGraph;
+/**
+* Generate tier-4 success hints from action graph neighbors (Tier 4).
+*
+* For a given command, returns CLIHint[] for all outgoing edges in the
+* action graph. Self-links are excluded (they would be confusing as
+* "next action" suggestions).
+*
+* @param graph - The action graph
+* @param commandName - The command that just succeeded
+* @param cliName - CLI name for hint command prefix
+* @returns Array of CLI hints for related next-actions
+*
+* @example
+* ```typescript
+* const hints = graphSuccessHints(graph, "deploy", "my-cli");
+* // [{ description: "Check deployment status", command: "my-cli status" }]
+* ```
+*/
+declare function graphSuccessHints(graph: ActionGraph, commandName: string, cliName?: string): CLIHint[];
+/**
+* Generate tier-4 error hints from action graph neighbors (Tier 4).
+*
+* For a given command that failed, returns CLIHint[] for related
+* remediation paths. Self-links are excluded. Error hints use the
+* relationship description as remediation context.
+*
+* @param graph - The action graph
+* @param commandName - The command that failed
+* @param cliName - CLI name for hint command prefix
+* @returns Array of CLI hints for remediation paths
+*
+* @example
+* ```typescript
+* const hints = graphErrorHints(graph, "deploy", "my-cli");
+* // [{ description: "Try: Rollback deployment", command: "my-cli rollback" }]
+* ```
+*/
+declare function graphErrorHints(graph: ActionGraph, commandName: string, cliName?: string): CLIHint[];
+export { buildActionGraph, graphSuccessHints, graphErrorHints };

package/dist/shared/@outfitter/{cli-xy3gs50c.d.ts → cli-q6csxmeh.d.ts}

@@ -1,34 +1,40 @@
-import { OutputOptions } from "./cli-98aa9104.js";
+import { OutputMode, OutputOptions } from "./cli-x6qr7bnd.js";
 /**
 * Output data to the console with automatic mode selection.
 *
 * Respects --json, --jsonl, --tree, --table flags automatically.
 * Defaults to human-friendly output when no flags are present.
 *
+* Detection hierarchy (highest wins):
+* 1. Explicit `format` parameter
+* 2. Environment variables (`OUTFITTER_JSON`, `OUTFITTER_JSONL`)
+* 3. Default: `"human"`
+*
 * @param data - The data to output
+* @param format - Explicit output format (e.g. from a resolved CLI flag)
 * @param options - Output configuration options
 *
 * @example
 * ```typescript
 * import { output } from "@outfitter/cli";
 *
-* // Basic usage - mode auto-detected from flags
+* // Basic usage - mode auto-detected from env
 * output(results);
 *
-* // Force JSON mode
-* output(results, { mode: "json" });
+* // Explicit format from resolved flag
+* output(results, "json");
 *
 * // Pretty-print JSON
-* output(results, { mode: "json", pretty: true });
+* output(results, "json", { pretty: true });
 *
 * // Output to stderr
-* output(errors, { stream: process.stderr });
+* output(errors, undefined, { stream: process.stderr });
 *
 * // Await for large outputs (recommended)
-* await output(largeDataset, { mode: "jsonl" });
+* await output(largeDataset, "jsonl");
 * ```
 */
-declare function output(data: unknown, options?: OutputOptions): Promise<void>;
+declare function output(data: unknown, format?: OutputMode, options?: OutputOptions): Promise<void>;
 /**
 * Exit the process with an error message.
 *
@@ -36,6 +42,7 @@ declare function output(data: unknown, options?: OutputOptions): Promise<void>;
 * and exits with an appropriate exit code.
 *
 * @param error - The error to display
+* @param format - Explicit output format (e.g. from a resolved CLI flag)
 * @returns Never returns (exits the process)
 *
 * @example
@@ -49,7 +56,7 @@ declare function output(data: unknown, options?: OutputOptions): Promise<void>;
 * }
 * ```
 */
-declare function exitWithError(error: Error, options?: OutputOptions): never;
+declare function exitWithError(error: Error, format?: OutputMode): never;
 /**
 * Resolve verbose mode from environment configuration.
 *
@@ -69,9 +76,9 @@ declare function exitWithError(error: Error, options?: OutputOptions): never;
 * // Auto-resolve from environment
 * const isVerbose = resolveVerbose();
 *
-* // With OUTFITTER_ENV=development → true
-* // With OUTFITTER_VERBOSE=0 → false (overrides everything)
-* // With nothing set → false
+* // With OUTFITTER_ENV=development -> true
+* // With OUTFITTER_VERBOSE=0 -> false (overrides everything)
+* // With nothing set -> false
 *
 * // From CLI flag
 * const isVerbose = resolveVerbose(cliFlags.verbose);

package/dist/shared/@outfitter/cli-qcskd96y.d.ts

@@ -0,0 +1,11 @@
+import { ActionManifest } from "@outfitter/schema";
+/**
+* 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;
+export { formatManifestHuman };

package/dist/shared/@outfitter/cli-ry7btmy4.js

@@ -0,0 +1,118 @@
+// @bun
+import {
+  formatHuman
+} from "./cli-dg0cz7rw.js";
+
+// packages/cli/src/internal/envelope-helpers.ts
+import { errorCategoryMeta, exitCodeMap } from "@outfitter/contracts";
+function createSuccessEnvelope(command, result, hints) {
+  const envelope = {
+    ok: true,
+    command,
+    result
+  };
+  if (hints && hints.length > 0) {
+    return { ...envelope, hints };
+  }
+  return envelope;
+}
+function createErrorEnvelope(command, category, message, hints, retryAfterSeconds) {
+  const meta = errorCategoryMeta(category);
+  const includeRetryAfter = retryAfterSeconds != null && category === "rate_limit";
+  const errorField = includeRetryAfter ? {
+    category,
+    message,
+    retryable: meta.retryable,
+    retry_after: retryAfterSeconds
+  } : { category, message, retryable: meta.retryable };
+  const envelope = {
+    ok: false,
+    command,
+    error: errorField
+  };
+  if (hints && hints.length > 0) {
+    return { ...envelope, hints };
+  }
+  return envelope;
+}
+function buildDryRunHint(argv = process.argv.slice(2)) {
+  const filteredArgs = argv.filter((arg) => arg !== "--dry-run" && !arg.startsWith("--dry-run="));
+  const command = filteredArgs.join(" ");
+  if (!command)
+    return;
+  return {
+    description: "Execute without dry-run",
+    command
+  };
+}
+var DEFAULT_CATEGORY = "internal";
+var DEFAULT_EXIT_CODE = 1;
+function extractCategory(error) {
+  if (error !== null && typeof error === "object" && "category" in error && typeof error["category"] === "string") {
+    const cat = error["category"];
+    if (cat in exitCodeMap) {
+      return cat;
+    }
+  }
+  return DEFAULT_CATEGORY;
+}
+function extractMessage(error) {
+  if (error instanceof Error) {
+    return error.message;
+  }
+  return String(error);
+}
+function extractRetryAfterSeconds(error) {
+  if (error !== null && typeof error === "object" && "retryAfterSeconds" in error && typeof error["retryAfterSeconds"] === "number") {
+    return error["retryAfterSeconds"];
+  }
+  return;
+}
+function getExitCode(category) {
+  return exitCodeMap[category] ?? DEFAULT_EXIT_CODE;
+}
+function formatEnvelopeHuman(envelope) {
+  if (envelope.ok) {
+    const parts2 = [];
+    const formatted = formatHuman(envelope.result);
+    if (formatted) {
+      parts2.push(formatted);
+    }
+    if (envelope.hints && envelope.hints.length > 0) {
+      parts2.push("");
+      parts2.push("Hints:");
+      for (const hint of envelope.hints) {
+        parts2.push(`  ${hint.description}`);
+        if (hint.command) {
+          parts2.push(`    $ ${hint.command}`);
+        }
+      }
+    }
+    return { stdout: parts2.join(`
+`), stderr: "" };
+  }
+  const parts = [];
+  parts.push(`Error: ${envelope.error.message}`);
+  if (envelope.hints && envelope.hints.length > 0) {
+    parts.push("");
+    parts.push("Hints:");
+    for (const hint of envelope.hints) {
+      parts.push(`  ${hint.description}`);
+      if (hint.command) {
+        parts.push(`    $ ${hint.command}`);
+      }
+    }
+  }
+  return { stdout: "", stderr: parts.join(`
+`) };
+}
+function safeCallHintFn(fn) {
+  try {
+    const hints = fn();
+    return hints.length > 0 ? hints : undefined;
+  } catch {
+    return;
+  }
+}
+
+export { createSuccessEnvelope, createErrorEnvelope, buildDryRunHint, extractCategory, extractMessage, extractRetryAfterSeconds, getExitCode, formatEnvelopeHuman, safeCallHintFn };

package/dist/shared/@outfitter/cli-sy99pjyj.js

@@ -0,0 +1,32 @@
+// @bun
+// packages/cli/src/internal/input-security.ts
+import path from "path";
+function isSecurePath(filePath, allowAbsolute = false) {
+  if (filePath.includes("\x00")) {
+    return false;
+  }
+  if (filePath.includes("..")) {
+    return false;
+  }
+  const normalized = path.normalize(filePath);
+  if (!allowAbsolute && path.isAbsolute(normalized)) {
+    return false;
+  }
+  return true;
+}
+function isSecureGlobPattern(pattern) {
+  if (pattern.startsWith("..")) {
+    return false;
+  }
+  if (pattern.includes("/../")) {
+    return false;
+  }
+  return true;
+}
+function isWithinWorkspace(resolvedPath, workspaceRoot) {
+  const normalizedPath = path.normalize(resolvedPath);
+  const normalizedRoot = path.normalize(workspaceRoot);
+  return normalizedPath === normalizedRoot || normalizedPath.startsWith(normalizedRoot + path.sep);
+}
+
+export { isSecurePath, isSecureGlobPattern, isWithinWorkspace };

package/dist/shared/@outfitter/cli-tm2fzngs.d.ts

@@ -0,0 +1,23 @@
+import { CLIHint, ErrorCategory } from "@outfitter/contracts";
+/**
+* Produce standard recovery CLIHints for an error category (Tier 2).
+*
+* Uses the enriched ErrorCategory metadata (retryable flags from OS-347)
+* to generate appropriate recovery actions. Retryable categories include
+* retry hints; non-retryable categories guide toward root cause resolution.
+*
+* @param category - The error category
+* @param cliName - Optional CLI name for command hints
+* @param commandName - Optional command name to replace `<previous-command>` placeholder
+* @returns Array of recovery hints
+*
+* @example
+* ```typescript
+* const hints = errorRecoveryHints("conflict", "my-cli", "update");
+* // [{ description: "Resolve the conflict and retry",
+* //    command: "my-cli update --force",
+* //    params: { retryable: true } }]
+* ```
+*/
+declare function errorRecoveryHints(category: ErrorCategory, cliName?: string, commandName?: string): CLIHint[];
+export { errorRecoveryHints };