@outfitter/contracts 0.1.0-rc.1

package/dist/assert/index.d.ts

@@ -0,0 +1,63 @@
+import { TaggedErrorClass } from "better-result";
+declare const AssertionErrorBase: TaggedErrorClass<"AssertionError", {
+	message: string;
+}>;
+/**
+* Assertion failed (invariant violation).
+*
+* Used by assertion utilities that return Result types instead of throwing.
+* AssertionError indicates a programming bug — an invariant that should
+* never be violated was broken. These are internal errors, not user input
+* validation failures.
+*
+* **Category rationale**: Uses `internal` (not `validation`) because:
+* - Assertions check **invariants** (programmer assumptions), not user input
+* - A failed assertion means "this should be impossible if the code is correct"
+* - User-facing validation uses {@link ValidationError} with helpful field info
+* - HTTP 500 is correct: this is a server bug, not a client mistake
+*
+* @example
+* ```typescript
+* // In domain logic after validation has passed
+* const result = assertDefined(cachedValue, "Cache should always have value after init");
+* if (result.isErr()) {
+*   return result; // Propagate as internal error
+* }
+* ```
+*
+* @see ValidationError - For user input validation failures (HTTP 400)
+*/
+declare class AssertionError extends AssertionErrorBase {
+	readonly category: "internal";
+	exitCode(): number;
+	statusCode(): number;
+}
+import { Result } from "better-result";
+/**
+* Array type guaranteed to have at least one element.
+*/
+type NonEmptyArray<T> = [T, ...T[]];
+/**
+* Type guard for NonEmptyArray.
+*/
+declare const isNonEmptyArray: <T>(arr: readonly T[]) => arr is NonEmptyArray<T>;
+/**
+* Assert a value is defined (not null or undefined).
+* Returns Result instead of throwing.
+*/
+declare const assertDefined: <T>(value: T | null | undefined, message?: string) => Result<T, InstanceType<typeof AssertionError>>;
+/**
+* Assert array has at least one element.
+* Returns NonEmptyArray on success.
+*/
+declare const assertNonEmpty: <T>(arr: readonly T[], message?: string) => Result<NonEmptyArray<T>, InstanceType<typeof AssertionError>>;
+/**
+* Assert value matches a predicate.
+* Supports type guard predicates for narrowing.
+*/
+declare function assertMatches<
+	T,
+	U extends T
+>(value: T, predicate: (v: T) => v is U, message?: string): Result<U, InstanceType<typeof AssertionError>>;
+declare function assertMatches<T>(value: T, predicate: (v: T) => boolean, message?: string): Result<T, InstanceType<typeof AssertionError>>;
+export { isNonEmptyArray, assertNonEmpty, assertMatches, assertDefined, NonEmptyArray };

package/dist/assert/index.js

@@ -0,0 +1,36 @@
+// @bun
+import {
+  AssertionError
+} from "../errors.js";
+
+// packages/contracts/src/assert/index.ts
+import { Result } from "better-result";
+var isNonEmptyArray = (arr) => {
+  return arr.length > 0;
+};
+var assertDefined = (value, message) => {
+  if (value === null || value === undefined) {
+    return Result.err(new AssertionError({ message: message ?? "Value is null or undefined" }));
+  }
+  return Result.ok(value);
+};
+var assertNonEmpty = (arr, message) => {
+  if (arr.length === 0) {
+    return Result.err(new AssertionError({ message: message ?? "Array is empty" }));
+  }
+  return Result.ok(arr);
+};
+function assertMatches(value, predicate, message) {
+  if (!predicate(value)) {
+    return Result.err(new AssertionError({
+      message: message ?? "Value does not match predicate"
+    }));
+  }
+  return Result.ok(value);
+}
+export {
+  isNonEmptyArray,
+  assertNonEmpty,
+  assertMatches,
+  assertDefined
+};

package/dist/capabilities.d.ts

@@ -0,0 +1,19 @@
+/**
+* @outfitter/contracts - Capability manifest
+*
+* Shared action capability manifest for CLI/MCP/API/server parity.
+*
+* @packageDocumentation
+*/
+declare const CAPABILITY_SURFACES: readonly ["cli", "mcp", "api", "server"];
+type CapabilitySurface = (typeof CAPABILITY_SURFACES)[number];
+interface ActionCapability {
+	surfaces: readonly CapabilitySurface[];
+	notes?: string;
+}
+declare const DEFAULT_ACTION_SURFACES: readonly ["cli", "mcp"];
+declare function capability(surfaces?: readonly CapabilitySurface[], notes?: string): ActionCapability;
+declare function capabilityAll(notes?: string): ActionCapability;
+declare const ACTION_CAPABILITIES: Record<string, ActionCapability>;
+declare function getActionsForSurface(surface: CapabilitySurface): string[];
+export { getActionsForSurface, capabilityAll, capability, DEFAULT_ACTION_SURFACES, CapabilitySurface, CAPABILITY_SURFACES, ActionCapability, ACTION_CAPABILITIES };

package/dist/capabilities.js

@@ -0,0 +1,66 @@
+// @bun
+// packages/contracts/src/capabilities.ts
+var CAPABILITY_SURFACES = ["cli", "mcp", "api", "server"];
+var DEFAULT_ACTION_SURFACES = ["cli", "mcp"];
+function capability(surfaces = DEFAULT_ACTION_SURFACES, notes) {
+  return notes ? { surfaces, notes } : { surfaces };
+}
+function capabilityAll(notes) {
+  return capability(CAPABILITY_SURFACES, notes);
+}
+var ACTION_CAPABILITIES = {
+  navigate: capability(),
+  back: capability(),
+  forward: capability(),
+  reload: capability(),
+  tab: capability(),
+  tabs: capability(),
+  newTab: capability(),
+  closeTab: capability(),
+  click: capability(),
+  type: capability(),
+  select: capability(),
+  hover: capability(),
+  focus: capability(["mcp"]),
+  scroll: capability(),
+  press: capability(),
+  fill: capability(),
+  find: capability(),
+  check: capability(),
+  uncheck: capability(),
+  upload: capability(),
+  download: capability(["server"], "Server-only for now"),
+  dialog: capability(),
+  waitFor: capability(["mcp"]),
+  waitForNavigation: capability(["mcp"]),
+  wait: capability(["mcp"]),
+  snap: capability(),
+  screenshot: capability(),
+  html: capability(["mcp"]),
+  text: capability(["mcp"]),
+  marker: capability(),
+  markers: capability(),
+  markerGet: capability(),
+  markerRead: capability(["mcp"]),
+  markerCompare: capability(),
+  markerDelete: capability(),
+  markerResolve: capability(["cli"], "CLI-only for now"),
+  viewport: capability(),
+  colorScheme: capability(),
+  mode: capability(["mcp"]),
+  evaluate: capability(["mcp"]),
+  session: capability(),
+  sessions: capability(["mcp"]),
+  steps: capability()
+};
+function getActionsForSurface(surface) {
+  return Object.entries(ACTION_CAPABILITIES).filter(([, capability2]) => capability2.surfaces.includes(surface)).map(([action]) => action);
+}
+export {
+  getActionsForSurface,
+  capabilityAll,
+  capability,
+  DEFAULT_ACTION_SURFACES,
+  CAPABILITY_SURFACES,
+  ACTION_CAPABILITIES
+};

package/dist/context.d.ts

@@ -0,0 +1,125 @@
+/**
+* Logger interface for handler context.
+* Implementations provided by @outfitter/logging.
+*
+* All log methods accept an optional context object that will be merged
+* with any context inherited from parent loggers created via `child()`.
+*/
+interface Logger {
+	trace(message: string, metadata?: Record<string, unknown>): void;
+	debug(message: string, metadata?: Record<string, unknown>): void;
+	info(message: string, metadata?: Record<string, unknown>): void;
+	warn(message: string, metadata?: Record<string, unknown>): void;
+	error(message: string, metadata?: Record<string, unknown>): void;
+	fatal(message: string, metadata?: Record<string, unknown>): void;
+	/**
+	* Creates a child logger with additional context.
+	*
+	* Context from the child is merged with the parent's context,
+	* with child context taking precedence for duplicate keys.
+	* Child loggers are composable (can create nested children).
+	*
+	* @param context - Additional context to include in all log messages
+	* @returns A new Logger instance with the merged context
+	*
+	* @example
+	* ```typescript
+	* const requestLogger = ctx.logger.child({ requestId: ctx.requestId });
+	* requestLogger.info("Processing request"); // includes requestId
+	*
+	* const opLogger = requestLogger.child({ operation: "create" });
+	* opLogger.debug("Starting"); // includes requestId + operation
+	* ```
+	*/
+	child(context: Record<string, unknown>): Logger;
+}
+/**
+* Resolved configuration interface.
+* Implementations provided by @outfitter/config.
+*/
+interface ResolvedConfig {
+	get<T>(key: string): T | undefined;
+	getRequired<T>(key: string): T;
+}
+/**
+* Handler context - provides cross-cutting concerns without polluting handler signatures.
+*
+* @example
+* ```typescript
+* const handler: Handler<Input, Output, NotFoundError> = async (input, ctx) => {
+*   ctx.logger.debug("Processing request", { requestId: ctx.requestId });
+*   // ... handler logic
+* };
+* ```
+*/
+interface HandlerContext {
+	/** Abort signal for cancellation propagation */
+	signal?: AbortSignal;
+	/** Unique request identifier for tracing (UUIDv7) */
+	requestId: string;
+	/** Structured logger with automatic redaction */
+	logger: Logger;
+	/** Resolved configuration values */
+	config?: ResolvedConfig;
+	/** Workspace root path, if detected */
+	workspaceRoot?: string;
+	/** Current working directory */
+	cwd: string;
+	/** Environment variables (filtered, redacted) */
+	env: Record<string, string | undefined>;
+}
+/**
+* Options for creating a handler context.
+*/
+interface CreateContextOptions {
+	/** Logger instance (uses no-op logger if not provided) */
+	logger?: Logger;
+	/** Resolved configuration */
+	config?: ResolvedConfig;
+	/** Abort signal for cancellation */
+	signal?: AbortSignal;
+	/** Explicit request ID (generates UUIDv7 if not provided) */
+	requestId?: string;
+	/** Workspace root path */
+	workspaceRoot?: string;
+	/** Current working directory (defaults to process.cwd()) */
+	cwd?: string;
+	/** Environment variables to include */
+	env?: Record<string, string | undefined>;
+}
+/**
+* Create a HandlerContext for a new request.
+*
+* Auto-generates requestId using Bun.randomUUIDv7() if not provided.
+*
+* @param options - Context configuration options
+* @returns Fully populated HandlerContext
+*
+* @example
+* ```typescript
+* const ctx = createContext({
+*   logger: createLogger(),
+*   config: resolvedConfig,
+*   signal: controller.signal,
+* });
+*
+* const result = await handler(input, ctx);
+* ```
+*/
+declare function createContext(options: CreateContextOptions): HandlerContext;
+/**
+* Generate a sortable request ID (UUIDv7).
+*
+* UUIDv7 is time-ordered, making it ideal for request tracing
+* as IDs sort chronologically.
+*
+* @returns UUIDv7 string
+*
+* @example
+* ```typescript
+* const requestId = generateRequestId();
+* // "018e4f3c-1a2b-7000-8000-000000000001"
+* ```
+*/
+declare function generateRequestId(): string;
+export { generateRequestId, createContext, CreateContextOptions };

package/dist/context.js

@@ -0,0 +1,36 @@
+// @bun
+// packages/contracts/src/context.ts
+var noopLogger = {
+  trace: () => {},
+  debug: () => {},
+  info: () => {},
+  warn: () => {},
+  error: () => {},
+  fatal: () => {},
+  child: () => noopLogger
+};
+function createContext(options) {
+  const ctx = {
+    requestId: options.requestId ?? generateRequestId(),
+    logger: options.logger ?? noopLogger,
+    cwd: options.cwd ?? process.cwd(),
+    env: options.env ?? {}
+  };
+  if (options.config !== undefined) {
+    ctx.config = options.config;
+  }
+  if (options.signal !== undefined) {
+    ctx.signal = options.signal;
+  }
+  if (options.workspaceRoot !== undefined) {
+    ctx.workspaceRoot = options.workspaceRoot;
+  }
+  return ctx;
+}
+function generateRequestId() {
+  return Bun.randomUUIDv7();
+}
+export {
+  generateRequestId,
+  createContext
+};

package/dist/envelope.d.ts

@@ -0,0 +1,328 @@
+import { TaggedErrorClass } from "better-result";
+/**
+* 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";
+/**
+* Serialized error format for JSON transport.
+*/
+interface SerializedError {
+	_tag: string;
+	category: ErrorCategory;
+	message: string;
+	context?: Record<string, unknown>;
+}
+declare const ValidationErrorBase: TaggedErrorClass<"ValidationError", {
+	message: string;
+	field?: string;
+}>;
+declare const AssertionErrorBase: TaggedErrorClass<"AssertionError", {
+	message: string;
+}>;
+declare const NotFoundErrorBase: TaggedErrorClass<"NotFoundError", {
+	message: string;
+	resourceType: string;
+	resourceId: string;
+}>;
+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;
+}>;
+/**
+* Input validation failed.
+*
+* @example
+* ```typescript
+* new ValidationError({ message: "Email format invalid", field: "email" });
+* ```
+*/
+declare class ValidationError extends ValidationErrorBase {
+	readonly category: "validation";
+	exitCode(): number;
+	statusCode(): number;
+}
+/**
+* Assertion failed (invariant violation).
+*
+* Used by assertion utilities that return Result types instead of throwing.
+* AssertionError indicates a programming bug — an invariant that should
+* never be violated was broken. These are internal errors, not user input
+* validation failures.
+*
+* **Category rationale**: Uses `internal` (not `validation`) because:
+* - Assertions check **invariants** (programmer assumptions), not user input
+* - A failed assertion means "this should be impossible if the code is correct"
+* - User-facing validation uses {@link ValidationError} with helpful field info
+* - HTTP 500 is correct: this is a server bug, not a client mistake
+*
+* @example
+* ```typescript
+* // In domain logic after validation has passed
+* const result = assertDefined(cachedValue, "Cache should always have value after init");
+* if (result.isErr()) {
+*   return result; // Propagate as internal error
+* }
+* ```
+*
+* @see ValidationError - For user input validation failures (HTTP 400)
+*/
+declare class AssertionError extends AssertionErrorBase {
+	readonly category: "internal";
+	exitCode(): number;
+	statusCode(): number;
+}
+/**
+* Requested resource not found.
+*
+* @example
+* ```typescript
+* new NotFoundError({ message: "note not found: abc123", resourceType: "note", resourceId: "abc123" });
+* ```
+*/
+declare class NotFoundError extends NotFoundErrorBase {
+	readonly category: "not_found";
+	exitCode(): number;
+	statusCode(): number;
+}
+/**
+* State conflict (optimistic locking, concurrent modification).
+*
+* @example
+* ```typescript
+* new ConflictError({ message: "Resource was modified by another process" });
+* ```
+*/
+declare class ConflictError extends ConflictErrorBase {
+	readonly category: "conflict";
+	exitCode(): number;
+	statusCode(): number;
+}
+/**
+* Authorization denied.
+*
+* @example
+* ```typescript
+* new PermissionError({ message: "Cannot delete read-only resource" });
+* ```
+*/
+declare class PermissionError extends PermissionErrorBase {
+	readonly category: "permission";
+	exitCode(): number;
+	statusCode(): number;
+}
+/**
+* Operation timed out.
+*
+* @example
+* ```typescript
+* new TimeoutError({ message: "Database query timed out after 5000ms", operation: "Database query", timeoutMs: 5000 });
+* ```
+*/
+declare class TimeoutError extends TimeoutErrorBase {
+	readonly category: "timeout";
+	exitCode(): number;
+	statusCode(): number;
+}
+/**
+* Rate limit exceeded.
+*
+* @example
+* ```typescript
+* new RateLimitError({ message: "Rate limit exceeded, retry after 60s", retryAfterSeconds: 60 });
+* ```
+*/
+declare class RateLimitError extends RateLimitErrorBase {
+	readonly category: "rate_limit";
+	exitCode(): number;
+	statusCode(): number;
+}
+/**
+* Network/transport failure.
+*
+* @example
+* ```typescript
+* new NetworkError({ message: "Connection refused to api.example.com" });
+* ```
+*/
+declare class NetworkError extends NetworkErrorBase {
+	readonly category: "network";
+	exitCode(): number;
+	statusCode(): number;
+}
+/**
+* Unexpected internal error.
+*
+* @example
+* ```typescript
+* new InternalError({ message: "Unexpected state in processor" });
+* ```
+*/
+declare class InternalError extends InternalErrorBase {
+	readonly category: "internal";
+	exitCode(): number;
+	statusCode(): number;
+}
+/**
+* Authentication failed (missing or invalid credentials).
+*
+* @example
+* ```typescript
+* new AuthError({ message: "Invalid API key", reason: "invalid" });
+* ```
+*/
+declare class AuthError extends AuthErrorBase {
+	readonly category: "auth";
+	exitCode(): number;
+	statusCode(): number;
+}
+/**
+* Operation cancelled by user or signal.
+*
+* @example
+* ```typescript
+* new CancelledError({ message: "Operation cancelled by user" });
+* ```
+*/
+declare class CancelledError extends CancelledErrorBase {
+	readonly category: "cancelled";
+	exitCode(): number;
+	statusCode(): number;
+}
+/**
+* Union type of all concrete error class instances.
+*/
+type AnyKitError = InstanceType<typeof ValidationError> | InstanceType<typeof AssertionError> | InstanceType<typeof NotFoundError> | InstanceType<typeof ConflictError> | InstanceType<typeof PermissionError> | InstanceType<typeof TimeoutError> | InstanceType<typeof RateLimitError> | InstanceType<typeof NetworkError> | InstanceType<typeof InternalError> | InstanceType<typeof AuthError> | InstanceType<typeof CancelledError>;
+/**
+* Type alias for backwards compatibility with handler signatures.
+* Use AnyKitError for the union type.
+*/
+type OutfitterError = AnyKitError;
+import { Result } from "better-result";
+/**
+* Metadata attached to every response envelope.
+*/
+interface EnvelopeMeta {
+	/** Unique request identifier for tracing */
+	requestId: string;
+	/** ISO timestamp of response generation */
+	timestamp: string;
+	/** Operation duration in milliseconds */
+	durationMs?: number;
+}
+/**
+* Pagination metadata for list responses.
+*/
+interface PaginationMeta {
+	/** Total number of items (if known) */
+	total?: number;
+	/** Number of items returned */
+	count: number;
+	/** Cursor for next page (null if no more pages) */
+	nextCursor: string | null;
+	/** Whether more pages exist */
+	hasMore: boolean;
+}
+/**
+* Success envelope structure.
+*/
+interface SuccessEnvelope<T> {
+	ok: true;
+	data: T;
+	meta: EnvelopeMeta;
+	pagination?: PaginationMeta;
+}
+/**
+* Error envelope structure.
+*/
+interface ErrorEnvelope {
+	ok: false;
+	error: SerializedError;
+	meta: EnvelopeMeta;
+}
+/**
+* Response envelope - consistent wrapper for all handler responses.
+*/
+type Envelope<T> = SuccessEnvelope<T> | ErrorEnvelope;
+/**
+* HTTP-style response with status code.
+*/
+interface HttpResponse<T> {
+	status: number;
+	body: Envelope<T>;
+}
+/**
+* Convert a Result to a response envelope.
+*
+* @typeParam T - Success data type
+* @typeParam E - Error type (extends OutfitterError)
+* @param result - Handler result to wrap
+* @param meta - Optional metadata overrides
+* @returns Envelope with success data or serialized error
+*
+* @example
+* ```typescript
+* const result = await getNote({ id: "abc123" }, ctx);
+* const envelope = toEnvelope(result, { requestId: ctx.requestId });
+* ```
+*/
+declare function toEnvelope<
+	T,
+	E extends OutfitterError
+>(result: Result<T, E>, meta?: Partial<EnvelopeMeta>): Envelope<T>;
+/**
+* Convert a Result to HTTP-style response (for MCP over HTTP).
+*
+* Maps error category to appropriate HTTP status code.
+*
+* @typeParam T - Success data type
+* @typeParam E - Error type (extends OutfitterError)
+* @param result - Handler result to convert
+* @returns HTTP response with status code and envelope body
+*
+* @example
+* ```typescript
+* const result = await getNote({ id: "abc123" }, ctx);
+* const response = toHttpResponse(result);
+* // { status: 200, body: { ok: true, data: note, meta: {...} } }
+* // or { status: 404, body: { ok: false, error: {...}, meta: {...} } }
+* ```
+*/
+declare function toHttpResponse<
+	T,
+	E extends OutfitterError
+>(result: Result<T, E>): HttpResponse<T>;
+export { toHttpResponse, toEnvelope, SuccessEnvelope, PaginationMeta, HttpResponse, ErrorEnvelope, EnvelopeMeta, Envelope };