@outfitter/contracts 0.4.1 → 0.5.0

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

@@ -0,0 +1,125 @@
+/**
+* Transport-agnostic streaming types for handler progress reporting.
+*
+* {@link StreamEvent} is a discriminated union of events that handlers emit
+* via {@link ProgressCallback} to report progress. Transport adapters (CLI NDJSON,
+* MCP notifications) consume these events without the handler knowing the transport.
+*
+* - {@link StreamStartEvent} — Emitted once at the beginning of a streaming operation
+* - {@link StreamStepEvent} — Emitted when a named phase completes
+* - {@link StreamProgressEvent} — Emitted for incremental progress updates
+*
+* @packageDocumentation
+*/
+/**
+* Emitted once at the beginning of a streaming operation.
+*
+* @example
+* ```typescript
+* ctx.progress?.({
+*   type: "start",
+*   command: "check tsdoc",
+*   ts: new Date().toISOString(),
+* });
+* ```
+*/
+interface StreamStartEvent {
+	/** Discriminator — always `"start"`. */
+	type: "start";
+	/** The command or operation being executed. */
+	command: string;
+	/** ISO-8601 timestamp of when the operation started. */
+	ts: string;
+}
+/**
+* Emitted when a named phase or step completes.
+*
+* @example
+* ```typescript
+* ctx.progress?.({
+*   type: "step",
+*   name: "scanning files",
+*   status: "complete",
+*   duration_ms: 42,
+* });
+* ```
+*/
+interface StreamStepEvent {
+	/** Discriminator — always `"step"`. */
+	type: "step";
+	/** Name of the phase or step. */
+	name: string;
+	/**
+	* Status of the step.
+	*
+	* Common values are `"running"`, `"complete"`, and `"failed"`.
+	* Custom values are still allowed for forward compatibility.
+	*/
+	status: "running" | "complete" | "failed" | (string & {});
+	/** Optional duration of the step in milliseconds. */
+	duration_ms?: number;
+}
+/**
+* Emitted for incremental progress updates (e.g., processing N of M items).
+*
+* @example
+* ```typescript
+* ctx.progress?.({
+*   type: "progress",
+*   current: 5,
+*   total: 10,
+*   message: "Processing file 5 of 10",
+* });
+* ```
+*/
+interface StreamProgressEvent {
+	/** Discriminator — always `"progress"`. */
+	type: "progress";
+	/** Current progress count. */
+	current: number;
+	/** Total expected count. */
+	total: number;
+	/** Optional human-readable progress message. */
+	message?: string;
+}
+/**
+* Discriminated union of all stream event types.
+*
+* Handlers emit these events via `ctx.progress?.()` to report progress
+* without coupling to any specific transport. The `type` field serves
+* as the discriminator for narrowing.
+*
+* @example
+* ```typescript
+* function handleEvent(event: StreamEvent) {
+*   switch (event.type) {
+*     case "start":
+*       console.log(`Starting: ${event.command}`);
+*       break;
+*     case "step":
+*       console.log(`Step: ${event.name} — ${event.status}`);
+*       break;
+*     case "progress":
+*       console.log(`${event.current}/${event.total}`);
+*       break;
+*   }
+* }
+* ```
+*/
+type StreamEvent = StreamStartEvent | StreamStepEvent | StreamProgressEvent;
+/**
+* Callback type for reporting streaming progress events.
+*
+* Transport adapters provide this callback to handlers via `ctx.progress`.
+* When `progress` is `undefined` on {@link HandlerContext}, the handler
+* does not stream — it simply returns its final result.
+*
+* @example
+* ```typescript
+* const progress: ProgressCallback = (event) => {
+*   process.stdout.write(JSON.stringify(event) + "\n");
+* };
+* ```
+*/
+type ProgressCallback = (event: StreamEvent) => void;
+export { StreamStartEvent, StreamStepEvent, StreamProgressEvent, StreamEvent, ProgressCallback };

package/dist/shared/@outfitter/{contracts-95cc3y06.d.ts → contracts-mt027fqj.d.ts}

@@ -1,4 +1,5 @@
-import { OutfitterError, TimeoutError } from "./contracts-3gswmhb1.js";
+import { OutfitterError } from "./contracts-7a0xmwbg.js";
+import { TimeoutError } from "./contracts-735ecmbq.js";
 import { Result } from "better-result";
 /**
 * Options for retry behavior.

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

@@ -0,0 +1,174 @@
+/**
+* Error taxonomy: categories, code maps, metadata, and lookup functions.
+*
+* @internal
+*/
+/**
+* Error categories for classification, exit codes, and HTTP status mapping.
+*
+* Used for:
+* - CLI exit code determination
+* - HTTP status code mapping
+* - Error grouping in logs and metrics
+* - Client retry decisions (transient vs permanent)
+*/
+type ErrorCategory = "validation" | "not_found" | "conflict" | "permission" | "timeout" | "rate_limit" | "network" | "internal" | "auth" | "cancelled";
+/**
+* Maps error category to CLI exit code.
+* Non-zero exit indicates error; specific values for script automation.
+*/
+declare const exitCodeMap: Record<ErrorCategory, number>;
+/**
+* Maps error category to HTTP status code.
+* Used by MCP servers and API responses.
+*/
+declare const statusCodeMap: Record<ErrorCategory, number>;
+/**
+* Maps error category to JSON-RPC 2.0 error code (for MCP protocol compliance).
+*
+* Standard protocol codes (-32600 series) for direct mappings:
+* - validation -> -32602 (Invalid params)
+* - internal -> -32603 (Internal error)
+*
+* Implementation-defined server error codes (-32000 to -32099) for domain categories:
+* - auth -> -32000
+* - timeout -> -32001
+* - conflict -> -32002
+* - permission -> -32003
+* - rate_limit -> -32004
+* - network -> -32005
+* - cancelled -> -32006
+* - not_found -> -32007
+*/
+declare const jsonRpcCodeMap: Record<ErrorCategory, number>;
+/**
+* Maps error category to whether the error is safe to retry (for agent safety).
+*
+* Transient errors (timeout, rate_limit, network) are retryable — they may
+* succeed on a subsequent attempt. Permanent errors require human intervention
+* or input correction before retrying would help.
+*/
+declare const retryableMap: Record<ErrorCategory, boolean>;
+/**
+* Unified metadata for an error category.
+*
+* Combines exit code, HTTP status, JSON-RPC code, and retryable flag
+* into a single lookup for transport adapters and agent tooling.
+*/
+interface ErrorCategoryMeta {
+	exitCode: number;
+	statusCode: number;
+	jsonRpcCode: number;
+	retryable: boolean;
+}
+/**
+* Get unified metadata for an error category.
+*
+* Returns exit code, HTTP status code, JSON-RPC error code, and retryable
+* flag in a single object. Useful for transport adapters that need all
+* metadata at once.
+*
+* @example
+* ```typescript
+* const meta = errorCategoryMeta("validation");
+* // { exitCode: 1, statusCode: 400, jsonRpcCode: -32602, retryable: false }
+*
+* const meta = errorCategoryMeta("timeout");
+* // { exitCode: 5, statusCode: 504, jsonRpcCode: -32001, retryable: true }
+* ```
+*/
+declare function errorCategoryMeta(category: ErrorCategory): ErrorCategoryMeta;
+/**
+* Numeric error codes for granular error identification.
+*
+* Ranges by category:
+* - validation: 1000-1999
+* - not_found: 2000-2999
+* - conflict: 3000-3999
+* - permission: 4000-4999
+* - timeout: 5000-5999
+* - rate_limit: 6000-6999
+* - network: 7000-7999
+* - internal: 8000-8999
+* - auth: 9000-9999
+* - cancelled: 10000-10999
+*/
+declare const ERROR_CODES: {
+	readonly validation: {
+		readonly FIELD_REQUIRED: 1001;
+		readonly INVALID_FORMAT: 1002;
+		readonly OUT_OF_RANGE: 1003;
+		readonly TYPE_MISMATCH: 1004;
+		readonly AMBIGUOUS_MATCH: 1005;
+	};
+	readonly not_found: {
+		readonly RESOURCE_NOT_FOUND: 2001;
+		readonly FILE_NOT_FOUND: 2002;
+	};
+	readonly conflict: {
+		readonly ALREADY_EXISTS: 3001;
+		readonly VERSION_MISMATCH: 3002;
+	};
+	readonly permission: {
+		readonly FORBIDDEN: 4001;
+		readonly INSUFFICIENT_RIGHTS: 4002;
+	};
+	readonly timeout: {
+		readonly OPERATION_TIMEOUT: 5001;
+		readonly CONNECTION_TIMEOUT: 5002;
+	};
+	readonly rate_limit: {
+		readonly QUOTA_EXCEEDED: 6001;
+		readonly THROTTLED: 6002;
+	};
+	readonly network: {
+		readonly CONNECTION_REFUSED: 7001;
+		readonly DNS_FAILED: 7002;
+	};
+	readonly internal: {
+		readonly UNEXPECTED_STATE: 8001;
+		readonly ASSERTION_FAILED: 8002;
+	};
+	readonly auth: {
+		readonly INVALID_TOKEN: 9001;
+		readonly EXPIRED_TOKEN: 9002;
+	};
+	readonly cancelled: {
+		readonly USER_CANCELLED: 10_001;
+		readonly SIGNAL_RECEIVED: 10_002;
+	};
+};
+/**
+* Union type of all numeric error codes.
+* Useful for type-safe error code handling.
+*/
+type ErrorCode = (typeof ERROR_CODES)[keyof typeof ERROR_CODES][keyof (typeof ERROR_CODES)[keyof typeof ERROR_CODES]];
+/**
+* Serialized error format for JSON transport.
+*/
+interface SerializedError {
+	_tag: string;
+	category: ErrorCategory;
+	context?: Record<string, unknown>;
+	message: string;
+}
+/**
+* Base interface for OutfitterError properties.
+* All concrete error classes must include these fields.
+*
+* @deprecated Use `OutfitterError` (or concrete error class constructor props) instead. This alias will be removed in v1.0.
+*/
+interface KitErrorProps {
+	category: ErrorCategory;
+	context?: Record<string, unknown>;
+	message: string;
+}
+/**
+* Get CLI exit code for an error category.
+*/
+declare function getExitCode(category: ErrorCategory): number;
+/**
+* Get HTTP status code for an error category.
+*/
+declare function getStatusCode(category: ErrorCategory): number;
+export { ErrorCategory, exitCodeMap, statusCodeMap, jsonRpcCodeMap, retryableMap, ErrorCategoryMeta, errorCategoryMeta, ERROR_CODES, ErrorCode, SerializedError, KitErrorProps, getExitCode, getStatusCode };

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

@@ -0,0 +1,46 @@
+import { OutfitterError } from "./contracts-7a0xmwbg.js";
+import { SerializedError } from "./contracts-njb2art4.js";
+/**
+* Options for error serialization.
+*/
+interface SerializeErrorOptions {
+	/** Include stack trace (default: false in production, true otherwise). */
+	includeStack?: boolean;
+}
+/**
+* Serialize a OutfitterError to JSON-safe format.
+*
+* Strips stack traces in production, preserves in development.
+* Automatically redacts sensitive values from context.
+*
+* @param error - The error to serialize
+* @param options - Serialization options
+* @param isProduction - Whether the environment is production. When omitted, falls back to
+*   `process.env["NODE_ENV"] === "production"` for safe-by-default stack stripping.
+* @returns JSON-safe serialized error
+*
+* @example
+* ```typescript
+* const serialized = serializeError(new NotFoundError("note", "abc123"));
+* // { _tag: "NotFoundError", category: "not_found", message: "note not found: abc123", context: { resourceType: "note", resourceId: "abc123" } }
+* ```
+*/
+declare function serializeError(error: OutfitterError, options?: SerializeErrorOptions, isProduction?: boolean): SerializedError;
+/**
+* Deserialize error from JSON (e.g., from MCP response).
+*
+* Returns a typed OutfitterError subclass based on _tag.
+*
+* @param data - Serialized error data
+* @returns Reconstructed OutfitterError instance
+*
+* @example
+* ```typescript
+* const error = deserializeError(jsonData);
+* if (error._tag === "NotFoundError") {
+*   // TypeScript knows error.resourceType exists
+* }
+* ```
+*/
+declare function deserializeError(data: SerializedError): OutfitterError;
+export { SerializeErrorOptions, serializeError, deserializeError };

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