@outfitter/contracts 0.4.2 → 0.5.0

package/dist/shared/@outfitter/contracts-qpbv29bg.d.ts

@@ -0,0 +1,59 @@
+import { TaggedErrorClass } from "better-result";
+declare const ValidationErrorBase: TaggedErrorClass<"ValidationError", {
+	message: string;
+	field?: string;
+	context?: Record<string, unknown>;
+}>;
+declare const AmbiguousErrorBase: TaggedErrorClass<"AmbiguousError", {
+	message: string;
+	candidates: string[];
+	context?: Record<string, unknown>;
+}>;
+declare const AssertionErrorBase: TaggedErrorClass<"AssertionError", {
+	message: string;
+}>;
+declare const NotFoundErrorBase: TaggedErrorClass<"NotFoundError", {
+	message: string;
+	resourceType: string;
+	resourceId: string;
+	context?: Record<string, unknown>;
+}>;
+declare const AlreadyExistsErrorBase: TaggedErrorClass<"AlreadyExistsError", {
+	message: string;
+	resourceType: string;
+	resourceId: string;
+	context?: Record<string, unknown>;
+}>;
+declare const ConflictErrorBase: TaggedErrorClass<"ConflictError", {
+	message: string;
+	context?: Record<string, unknown>;
+}>;
+declare const PermissionErrorBase: TaggedErrorClass<"PermissionError", {
+	message: string;
+	context?: Record<string, unknown>;
+}>;
+declare const TimeoutErrorBase: TaggedErrorClass<"TimeoutError", {
+	message: string;
+	operation: string;
+	timeoutMs: number;
+}>;
+declare const RateLimitErrorBase: TaggedErrorClass<"RateLimitError", {
+	message: string;
+	retryAfterSeconds?: number;
+}>;
+declare const NetworkErrorBase: TaggedErrorClass<"NetworkError", {
+	message: string;
+	context?: Record<string, unknown>;
+}>;
+declare const InternalErrorBase: TaggedErrorClass<"InternalError", {
+	message: string;
+	context?: Record<string, unknown>;
+}>;
+declare const AuthErrorBase: TaggedErrorClass<"AuthError", {
+	message: string;
+	reason?: "missing" | "invalid" | "expired";
+}>;
+declare const CancelledErrorBase: TaggedErrorClass<"CancelledError", {
+	message: string;
+}>;
+export { ValidationErrorBase, AmbiguousErrorBase, AssertionErrorBase, NotFoundErrorBase, AlreadyExistsErrorBase, ConflictErrorBase, PermissionErrorBase, TimeoutErrorBase, RateLimitErrorBase, NetworkErrorBase, InternalErrorBase, AuthErrorBase, CancelledErrorBase };

package/dist/shared/@outfitter/contracts-sawwfgb5.js

@@ -0,0 +1,111 @@
+// @bun
+// packages/contracts/src/internal/error-taxonomy.ts
+var exitCodeMap = {
+  validation: 1,
+  not_found: 2,
+  conflict: 3,
+  permission: 4,
+  timeout: 5,
+  rate_limit: 6,
+  network: 7,
+  internal: 8,
+  auth: 9,
+  cancelled: 130
+};
+var statusCodeMap = {
+  validation: 400,
+  not_found: 404,
+  conflict: 409,
+  permission: 403,
+  timeout: 504,
+  rate_limit: 429,
+  network: 502,
+  internal: 500,
+  auth: 401,
+  cancelled: 499
+};
+var jsonRpcCodeMap = {
+  validation: -32602,
+  not_found: -32007,
+  internal: -32603,
+  auth: -32000,
+  timeout: -32001,
+  conflict: -32002,
+  permission: -32003,
+  rate_limit: -32004,
+  network: -32005,
+  cancelled: -32006
+};
+var retryableMap = {
+  validation: false,
+  not_found: false,
+  conflict: false,
+  permission: false,
+  timeout: true,
+  rate_limit: true,
+  network: true,
+  internal: false,
+  auth: false,
+  cancelled: false
+};
+function errorCategoryMeta(category) {
+  return {
+    exitCode: exitCodeMap[category],
+    statusCode: statusCodeMap[category],
+    jsonRpcCode: jsonRpcCodeMap[category],
+    retryable: retryableMap[category]
+  };
+}
+var ERROR_CODES = {
+  validation: {
+    FIELD_REQUIRED: 1001,
+    INVALID_FORMAT: 1002,
+    OUT_OF_RANGE: 1003,
+    TYPE_MISMATCH: 1004,
+    AMBIGUOUS_MATCH: 1005
+  },
+  not_found: {
+    RESOURCE_NOT_FOUND: 2001,
+    FILE_NOT_FOUND: 2002
+  },
+  conflict: {
+    ALREADY_EXISTS: 3001,
+    VERSION_MISMATCH: 3002
+  },
+  permission: {
+    FORBIDDEN: 4001,
+    INSUFFICIENT_RIGHTS: 4002
+  },
+  timeout: {
+    OPERATION_TIMEOUT: 5001,
+    CONNECTION_TIMEOUT: 5002
+  },
+  rate_limit: {
+    QUOTA_EXCEEDED: 6001,
+    THROTTLED: 6002
+  },
+  network: {
+    CONNECTION_REFUSED: 7001,
+    DNS_FAILED: 7002
+  },
+  internal: {
+    UNEXPECTED_STATE: 8001,
+    ASSERTION_FAILED: 8002
+  },
+  auth: {
+    INVALID_TOKEN: 9001,
+    EXPIRED_TOKEN: 9002
+  },
+  cancelled: {
+    USER_CANCELLED: 10001,
+    SIGNAL_RECEIVED: 10002
+  }
+};
+function getExitCode(category) {
+  return exitCodeMap[category];
+}
+function getStatusCode(category) {
+  return statusCodeMap[category];
+}
+
+export { exitCodeMap, statusCodeMap, jsonRpcCodeMap, retryableMap, errorCategoryMeta, ERROR_CODES, getExitCode, getStatusCode };

package/dist/shared/@outfitter/{contracts-e4m948m7.d.ts → contracts-t4txv24h.d.ts}

@@ -1,4 +1,5 @@
-import { OutfitterError, SerializedError } from "./contracts-3gswmhb1.js";
+import { OutfitterError } from "./contracts-7a0xmwbg.js";
+import { SerializedError } from "./contracts-njb2art4.js";
 import { Result } from "better-result";
 /**
 * Metadata attached to every response envelope.

package/dist/shared/@outfitter/contracts-vbgt9rfn.d.ts

@@ -0,0 +1,74 @@
+/**
+* Hint types for agent-navigable responses.
+*
+* Hints are transport-local suggestions attached to command/tool responses.
+* They guide agents (and humans) toward next actions without coupling
+* handler logic to any specific transport.
+*
+* - {@link ActionHint} — Base hint with description and optional params
+* - {@link CLIHint} — CLI-specific hint with a runnable command
+* - {@link MCPHint} — MCP-specific hint with tool name and optional input
+*
+* @packageDocumentation
+*/
+/**
+* Base hint type for action responses.
+*
+* Describes a suggested next action with optional structured parameters.
+* Transport-specific hints ({@link CLIHint}, {@link MCPHint}) extend this
+* with transport-appropriate fields.
+*
+* @example
+* ```typescript
+* const hint: ActionHint = {
+*   description: "Retry the operation with a longer timeout",
+*   params: { timeoutMs: 10_000 },
+* };
+* ```
+*/
+interface ActionHint {
+	/** Human-readable description of the suggested action. */
+	readonly description: string;
+	/** Optional structured parameters for the suggested action. */
+	readonly params?: Record<string, unknown>;
+}
+/**
+* CLI-specific hint with a runnable command string.
+*
+* Extends {@link ActionHint} with a `command` field that agents or users
+* can execute directly in the terminal.
+*
+* @example
+* ```typescript
+* const hint: CLIHint = {
+*   description: "Fix lint issues automatically",
+*   command: "outfitter lint --fix",
+* };
+* ```
+*/
+interface CLIHint extends ActionHint {
+	/** CLI command string that can be executed to perform the suggested action. */
+	readonly command: string;
+}
+/**
+* MCP-specific hint with a tool name and optional input.
+*
+* Extends {@link ActionHint} with a `tool` field identifying the MCP tool
+* to invoke, and an optional `input` payload for that tool.
+*
+* @example
+* ```typescript
+* const hint: MCPHint = {
+*   description: "Search for related notes",
+*   tool: "search-notes",
+*   input: { query: "architecture patterns", limit: 5 },
+* };
+* ```
+*/
+interface MCPHint extends ActionHint {
+	/** MCP tool name to invoke for the suggested action. */
+	readonly tool: string;
+	/** Optional input payload for the MCP tool. */
+	readonly input?: unknown;
+}
+export { ActionHint, CLIHint, MCPHint };

package/dist/shared/@outfitter/{contracts-56pcsavx.d.ts → contracts-vhajx4gg.d.ts}

@@ -1,5 +1,5 @@
-import { Handler, SyncHandler } from "./contracts-0akf2sm6.js";
-import { OutfitterError } from "./contracts-3gswmhb1.js";
+import { Handler, SyncHandler } from "./contracts-zma4mscd.js";
+import { OutfitterError } from "./contracts-7a0xmwbg.js";
 import { z } from "zod";
 declare const ACTION_SURFACES: readonly ["cli", "mcp", "api", "server"];
 type ActionSurface = (typeof ACTION_SURFACES)[number];
@@ -25,7 +25,13 @@ interface ActionCliSpec<TInput = unknown> {
 interface ActionMcpSpec<TInput = unknown> {
 	readonly deferLoading?: boolean;
 	readonly description?: string;
+	/** When true, the action modifies or deletes data */
+	readonly destructive?: boolean;
+	/** When true, calling the action multiple times with the same input has the same effect */
+	readonly idempotent?: boolean;
 	readonly mapInput?: (input: unknown) => TInput;
+	/** When true, the action does not modify any state */
+	readonly readOnly?: boolean;
 	readonly tool?: string;
 }
 type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";

package/dist/shared/@outfitter/contracts-vhr2ep6b.js

@@ -0,0 +1,3 @@
+export { ERROR_CODES, errorCategoryMeta, exitCodeMap, getExitCode, getStatusCode, jsonRpcCodeMap, retryableMap, statusCodeMap } from "../../internal/error-taxonomy.js";
+export { AlreadyExistsError, AmbiguousError, AssertionError, ConflictError, NotFoundError, ValidationError } from "../../internal/error-validation.js";
+export { AuthError, CancelledError, InternalError, NetworkError, PermissionError, RateLimitError, TimeoutError } from "../../internal/error-operational.js";

package/dist/shared/@outfitter/contracts-w7nvcwrp.d.ts

@@ -0,0 +1,44 @@
+/**
+* JSON Schema type definitions and Zod introspection helpers.
+*
+* @internal
+*/
+/**
+* JSON Schema representation.
+*/
+interface JsonSchema {
+	$defs?: Record<string, JsonSchema>;
+	$ref?: string;
+	$schema?: string;
+	additionalProperties?: boolean | JsonSchema;
+	allOf?: JsonSchema[];
+	anyOf?: JsonSchema[];
+	const?: unknown;
+	default?: unknown;
+	definitions?: Record<string, JsonSchema>;
+	description?: string;
+	enum?: unknown[];
+	exclusiveMaximum?: number;
+	exclusiveMinimum?: number;
+	format?: string;
+	items?: JsonSchema | JsonSchema[];
+	maximum?: number;
+	maxLength?: number;
+	minimum?: number;
+	minLength?: number;
+	not?: JsonSchema | Record<string, never>;
+	oneOf?: JsonSchema[];
+	pattern?: string;
+	properties?: Record<string, JsonSchema>;
+	required?: string[];
+	type?: string;
+}
+/**
+* Extract the internal _def object from a Zod schema or def.
+*/
+declare function getDef(schemaOrDef: any): any;
+/**
+* Extract description from a Zod schema or its def.
+*/
+declare function getDescription(schema: any, def: any): string | undefined;
+export { JsonSchema, getDef, getDescription };

package/dist/shared/@outfitter/contracts-x0ppyt7e.d.ts

@@ -0,0 +1,76 @@
+import { ValidationError } from "./contracts-mehpmvwp.js";
+import { Result } from "better-result";
+import { z } from "zod";
+/**
+* Format Zod issues into a human-readable error message.
+*
+* @param issues - Array of Zod validation issues
+* @returns Formatted error message string
+*/
+declare function formatZodIssues(issues: z.ZodIssue[]): string;
+/**
+* Create a validator function from a Zod schema.
+*
+* @typeParam T - The validated output type
+* @param schema - Zod schema to validate against
+* @returns A function that validates input and returns Result
+*
+* @example
+* ```typescript
+* const NoteSchema = z.object({
+*   id: z.string().uuid(),
+*   title: z.string().min(1),
+* });
+*
+* const validateNote = createValidator(NoteSchema);
+* const result = validateNote(input); // Result<Note, ValidationError>
+* ```
+*/
+declare function createValidator<T>(schema: z.ZodType<T>): (input: unknown) => Result<T, ValidationError>;
+/**
+* Validate input against a Zod schema.
+*
+* Standardized wrapper for Zod schemas that returns Result instead of throwing.
+*
+* @typeParam T - The validated output type
+* @param schema - Zod schema to validate against
+* @param input - Unknown input to validate
+* @returns Result with validated data or ValidationError
+*
+* @example
+* ```typescript
+* const result = validateInput(NoteSchema, userInput);
+* if (result.isErr()) {
+*   console.error(result.unwrapErr().message);
+* }
+* ```
+*/
+declare function validateInput<T>(schema: z.ZodType<T>, input: unknown): Result<T, ValidationError>;
+/**
+* Parse and validate data against a Zod schema, returning a Result.
+*
+* Wraps Zod's `safeParse` into `Result<T, ValidationError>` where `T` is
+* automatically inferred from the schema — no manual type argument needed.
+*
+* @typeParam TSchema - The Zod schema type (inferred from `schema` argument)
+* @param schema - Zod schema to parse/validate against
+* @param data - Unknown data to parse
+* @returns `Ok<z.infer<TSchema>>` for valid data, `Err<ValidationError>` for invalid data
+*
+* @example
+* ```typescript
+* const UserSchema = z.object({
+*   name: z.string().min(1),
+*   email: z.string().email(),
+* });
+*
+* const result = parseInput(UserSchema, input);
+* // Result<{ name: string; email: string }, ValidationError>
+*
+* if (result.isOk()) {
+*   result.value.name; // string — fully typed, no manual annotation
+* }
+* ```
+*/
+declare function parseInput<TSchema extends z.ZodType>(schema: TSchema, data: unknown): Result<z.infer<TSchema>, ValidationError>;
+export { formatZodIssues, createValidator, validateInput, parseInput };

package/dist/shared/@outfitter/{contracts-0akf2sm6.d.ts → contracts-zma4mscd.d.ts}

@@ -1,4 +1,5 @@
-import { OutfitterError } from "./contracts-3gswmhb1.js";
+import { ProgressCallback } from "./contracts-msxdg52h.js";
+import { OutfitterError } from "./contracts-7a0xmwbg.js";
 import { Logger } from "./contracts-rwzqy9rn.js";
 import { Result } from "better-result";
 /**
@@ -29,6 +30,20 @@ interface HandlerContext {
 	env: Record<string, string | undefined>;
 	/** Structured logger with automatic redaction */
 	logger: Logger;
+	/**
+	* Optional streaming progress callback.
+	*
+	* When provided by a transport adapter, the handler can emit progress
+	* events without knowing which transport consumes them. When `undefined`,
+	* the handler does not stream — it simply returns its final result.
+	*
+	* @example
+	* ```typescript
+	* ctx.progress?.({ type: "start", command: "check", ts: new Date().toISOString() });
+	* ctx.progress?.({ type: "progress", current: 5, total: 10 });
+	* ```
+	*/
+	progress?: ProgressCallback;
 	/** Unique request identifier for tracing (UUIDv7) */
 	requestId: string;
 	/** Abort signal for cancellation propagation */

package/dist/shared/@outfitter/contracts-zsgxsa91.d.ts

@@ -0,0 +1,84 @@
+import { OutfitterError } from "./contracts-7a0xmwbg.js";
+/**
+* An error mapper converts an unknown error into a typed OutfitterError.
+*
+* Return `undefined` if the mapper does not handle this error (pass to next mapper or default).
+*/
+type ErrorMapper = (error: unknown) => OutfitterError | undefined;
+/**
+* Type guard: checks whether `value` is a typed Outfitter error (has a `category` field
+* matching a known {@link ErrorCategory}).
+*/
+declare function isOutfitterError(value: unknown): value is OutfitterError;
+/**
+* Extract a human-readable message from an unknown error value.
+*
+* Handles Error instances, plain strings, objects with a `message` property,
+* and falls back to `"Unknown error"` for everything else.
+*/
+declare function extractMessage(error: unknown): string;
+/**
+* Normalize an unknown error into a typed OutfitterError.
+*
+* - Typed Outfitter errors pass through unchanged (same reference, mapper NOT called).
+* - Untyped errors go through optional mapper.
+* - Without mapper or when mapper returns `undefined`, wraps as {@link InternalError}.
+* - Plain strings are wrapped as InternalError with the string as message.
+*
+* @param error - The unknown error to normalize
+* @param mapper - Optional mapper to convert untyped errors into typed OutfitterErrors
+* @returns A typed OutfitterError
+*
+* @example
+* ```typescript
+* // Typed errors pass through
+* const typed = new ValidationError({ message: "bad input" });
+* wrapError(typed) === typed; // true — same reference
+*
+* // Untyped errors go through mapper
+* const mapper: ErrorMapper = (err) => {
+*   if (err instanceof Error && err.message.includes("ECONNREFUSED")) {
+*     return new NetworkError({ message: err.message });
+*   }
+*   return undefined;
+* };
+* wrapError(new Error("ECONNREFUSED"), mapper); // NetworkError
+*
+* // Unmatched errors become InternalError
+* wrapError(new Error("unknown")); // InternalError
+*
+* // Strings become InternalError with message
+* wrapError("something failed"); // InternalError { message: "something failed" }
+* ```
+*/
+declare function wrapError(error: unknown, mapper?: ErrorMapper): OutfitterError;
+/**
+* Compose multiple error mappers into a single mapper.
+*
+* Mappers run in declared order and short-circuit on the first match
+* (first mapper to return a non-`undefined` value wins).
+*
+* @param mappers - Error mappers to compose
+* @returns A single composed error mapper
+*
+* @example
+* ```typescript
+* const networkMapper: ErrorMapper = (err) => {
+*   if (err instanceof Error && err.message.includes("ECONNREFUSED")) {
+*     return new NetworkError({ message: err.message });
+*   }
+*   return undefined;
+* };
+* const timeoutMapper: ErrorMapper = (err) => {
+*   if (err instanceof Error && err.message.includes("ETIMEDOUT")) {
+*     return TimeoutError.create("request", 5000);
+*   }
+*   return undefined;
+* };
+*
+* const composed = composeMappers(networkMapper, timeoutMapper);
+* wrapError(new Error("ECONNREFUSED"), composed); // NetworkError
+* ```
+*/
+declare function composeMappers(...mappers: ErrorMapper[]): ErrorMapper;
+export { ErrorMapper, isOutfitterError, extractMessage, wrapError, composeMappers };

package/dist/stream.d.ts

@@ -0,0 +1,2 @@
+import { ProgressCallback, StreamEvent, StreamProgressEvent, StreamStartEvent, StreamStepEvent } from "./shared/@outfitter/contracts-msxdg52h.js";
+export { StreamStepEvent, StreamStartEvent, StreamProgressEvent, StreamEvent, ProgressCallback };

package/dist/stream.js

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

package/dist/validation.d.ts

@@ -1,3 +1,7 @@
-import { createValidator, validateInput } from "./shared/@outfitter/contracts-9wtm5nsw.js";
-import "./shared/@outfitter/contracts-3gswmhb1.js";
-export { validateInput, createValidator };
+import { createValidator, formatZodIssues, parseInput, validateInput } from "./shared/@outfitter/contracts-x0ppyt7e.js";
+import "./shared/@outfitter/contracts-7a0xmwbg.js";
+import "./shared/@outfitter/contracts-735ecmbq.js";
+import "./shared/@outfitter/contracts-mehpmvwp.js";
+import "./shared/@outfitter/contracts-qpbv29bg.js";
+import "./shared/@outfitter/contracts-njb2art4.js";
+export { validateInput, parseInput, formatZodIssues, createValidator };

package/dist/validation.js

@@ -1,42 +1,14 @@
 // @bun
 import {
-  ValidationError
-} from "./shared/@outfitter/contracts-phjhz5q3.js";
-
-// packages/contracts/src/validation.ts
-import { Result } from "better-result";
-function formatZodIssues(issues) {
-  return issues.map((issue) => {
-    const path = issue.path.length > 0 ? issue.path.join(".") : "(root)";
-    return `${path}: ${issue.message}`;
-  }).join("; ");
-}
-function extractField(issues) {
-  const firstIssue = issues[0];
-  if (firstIssue && firstIssue.path.length > 0) {
-    return firstIssue.path.join(".");
-  }
-  return;
-}
-function createValidator(schema) {
-  return (input) => {
-    return validateInput(schema, input);
-  };
-}
-function validateInput(schema, input) {
-  const parseResult = schema.safeParse(input);
-  if (parseResult.success) {
-    return Result.ok(parseResult.data);
-  }
-  const message = formatZodIssues(parseResult.error.issues);
-  const field = extractField(parseResult.error.issues);
-  const errorProps = { message };
-  if (field !== undefined) {
-    errorProps.field = field;
-  }
-  return Result.err(new ValidationError(errorProps));
-}
+  createValidator,
+  formatZodIssues,
+  parseInput,
+  validateInput
+} from "./shared/@outfitter/contracts-hgh47193.js";
+import"./shared/@outfitter/contracts-vhr2ep6b.js";
 export {
   validateInput,
+  parseInput,
+  formatZodIssues,
   createValidator
 };

package/dist/wrap-error.d.ts

@@ -0,0 +1,7 @@
+import { ErrorMapper, composeMappers, extractMessage, isOutfitterError, wrapError } from "./shared/@outfitter/contracts-zsgxsa91.js";
+import "./shared/@outfitter/contracts-7a0xmwbg.js";
+import "./shared/@outfitter/contracts-735ecmbq.js";
+import "./shared/@outfitter/contracts-mehpmvwp.js";
+import "./shared/@outfitter/contracts-qpbv29bg.js";
+import "./shared/@outfitter/contracts-njb2art4.js";
+export { wrapError, isOutfitterError, extractMessage, composeMappers, ErrorMapper };

package/dist/wrap-error.js

@@ -0,0 +1,71 @@
+// @bun
+import {
+  InternalError
+} from "./shared/@outfitter/contracts-vhr2ep6b.js";
+
+// packages/contracts/src/wrap-error.ts
+function isOutfitterError(value) {
+  if (!(value instanceof Error)) {
+    return false;
+  }
+  const candidate = value;
+  return typeof candidate["category"] === "string" && typeof candidate["message"] === "string" && typeof candidate["_tag"] === "string" && isErrorCategory(candidate["category"]);
+}
+var ERROR_CATEGORIES = new Set([
+  "validation",
+  "not_found",
+  "conflict",
+  "permission",
+  "timeout",
+  "rate_limit",
+  "network",
+  "internal",
+  "auth",
+  "cancelled"
+]);
+function isErrorCategory(value) {
+  return ERROR_CATEGORIES.has(value);
+}
+function extractMessage(error) {
+  if (typeof error === "string") {
+    return error || "Unknown error";
+  }
+  if (error instanceof Error) {
+    return error.message || "Unknown error";
+  }
+  if (error != null && typeof error === "object" && "message" in error) {
+    const msg = error["message"];
+    return typeof msg === "string" && msg ? msg : "Unknown error";
+  }
+  return "Unknown error";
+}
+function wrapError(error, mapper) {
+  if (isOutfitterError(error)) {
+    return error;
+  }
+  if (mapper != null) {
+    const mapped = mapper(error);
+    if (mapped != null) {
+      return mapped;
+    }
+  }
+  const message = extractMessage(error);
+  return new InternalError({ message });
+}
+function composeMappers(...mappers) {
+  return (error) => {
+    for (const mapper of mappers) {
+      const result = mapper(error);
+      if (result != null) {
+        return result;
+      }
+    }
+    return;
+  };
+}
+export {
+  wrapError,
+  isOutfitterError,
+  extractMessage,
+  composeMappers
+};