@outfitter/contracts 0.1.0-rc.1

package/README.md

@@ -0,0 +1,50 @@
+# @outfitter/contracts
+
+Result/Error patterns, error taxonomy, handler contracts, and shared interfaces for the Outfitter ecosystem.
+
+## Status
+
+**Scaffold** - Types and interfaces defined, implementations pending.
+
+## Installation
+
+```bash
+bun add @outfitter/contracts
+```
+
+## Overview
+
+This package provides the foundational contracts that all Outfitter packages depend on:
+
+- **Error taxonomy** - 10 concrete error classes with category-based exit/status codes
+- **Handler contract** - Transport-agnostic domain logic interface
+- **Validation** - Zod-based input validation returning Results
+- **Serialization** - Safe JSON handling with redaction
+- **Adapters** - Pluggable interfaces for indexing, caching, auth, and storage
+
+## Usage
+
+```typescript
+import {
+  Result,
+  NotFoundError,
+  Handler,
+  HandlerContext,
+  createContext,
+} from "@outfitter/contracts";
+
+// Define a handler
+const getNote: Handler<{ id: string }, Note, NotFoundError> = async (input, ctx) => {
+  const note = await db.notes.find(input.id);
+  if (!note) return Result.err(new NotFoundError("note", input.id));
+  return Result.ok(note);
+};
+
+// Create context and invoke
+const ctx = createContext({ logger, config });
+const result = await getNote({ id: "abc123" }, ctx);
+```
+
+## License
+
+MIT

package/dist/actions.d.ts

@@ -0,0 +1,388 @@
+import { TaggedErrorClass } from "better-result";
+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";
+/**
+* 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>;
+}
+/**
+* Handler - transport-agnostic domain logic unit.
+*
+* Handlers receive typed input, return Results, and know nothing about
+* transport or output format. CLI and MCP are thin adapters over handlers.
+*
+* @typeParam TInput - Validated input parameters
+* @typeParam TOutput - Success return type
+* @typeParam TError - Error type (must extend OutfitterError)
+*
+* @example
+* ```typescript
+* const getNote: Handler<{ id: string }, Note, NotFoundError> = async (input, ctx) => {
+*   const note = await ctx.db.notes.find(input.id);
+*   if (!note) return Result.err(new NotFoundError("note", input.id));
+*   return Result.ok(note);
+* };
+* ```
+*/
+type Handler<
+	TInput,
+	TOutput,
+	TError extends OutfitterError = OutfitterError
+> = (input: TInput, ctx: HandlerContext) => Promise<Result<TOutput, TError>>;
+/**
+* Synchronous handler variant for operations that don't need async.
+*/
+type SyncHandler<
+	TInput,
+	TOutput,
+	TError extends OutfitterError = OutfitterError
+> = (input: TInput, ctx: HandlerContext) => Result<TOutput, TError>;
+import { z } from "zod";
+declare const ACTION_SURFACES: readonly ["cli", "mcp", "api", "server"];
+type ActionSurface = (typeof ACTION_SURFACES)[number];
+declare const DEFAULT_REGISTRY_SURFACES: readonly ActionSurface[];
+interface ActionCliOption {
+	readonly flags: string;
+	readonly description: string;
+	readonly defaultValue?: string | boolean | string[];
+	readonly required?: boolean;
+}
+interface ActionCliInputContext {
+	readonly args: readonly string[];
+	readonly flags: Record<string, unknown>;
+}
+interface ActionCliSpec<TInput = unknown> {
+	readonly group?: string;
+	readonly command?: string;
+	readonly description?: string;
+	readonly aliases?: readonly string[];
+	readonly options?: readonly ActionCliOption[];
+	readonly mapInput?: (context: ActionCliInputContext) => TInput;
+}
+interface ActionMcpSpec<TInput = unknown> {
+	readonly tool?: string;
+	readonly description?: string;
+	readonly deferLoading?: boolean;
+	readonly mapInput?: (input: unknown) => TInput;
+}
+type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+interface ActionApiSpec {
+	readonly method?: HttpMethod;
+	readonly path?: string;
+	readonly tags?: readonly string[];
+}
+interface ActionTrpcSpec {
+	readonly path?: string;
+}
+interface ActionSpec<
+	TInput,
+	TOutput,
+	TError extends OutfitterError = OutfitterError
+> {
+	readonly id: string;
+	readonly description?: string;
+	readonly surfaces?: readonly ActionSurface[];
+	readonly input: z.ZodType<TInput>;
+	readonly output?: z.ZodType<TOutput>;
+	readonly handler: Handler<TInput, TOutput, TError> | SyncHandler<TInput, TOutput, TError>;
+	readonly cli?: ActionCliSpec<TInput>;
+	readonly mcp?: ActionMcpSpec<TInput>;
+	readonly api?: ActionApiSpec;
+	readonly trpc?: ActionTrpcSpec;
+}
+type AnyActionSpec = ActionSpec<unknown, unknown, OutfitterError>;
+interface ActionRegistry {
+	add<
+		TInput,
+		TOutput,
+		TError extends OutfitterError = OutfitterError
+	>(action: ActionSpec<TInput, TOutput, TError>): ActionRegistry;
+	list(): AnyActionSpec[];
+	get(id: string): AnyActionSpec | undefined;
+	forSurface(surface: ActionSurface): AnyActionSpec[];
+}
+declare function defineAction<
+	TInput,
+	TOutput,
+	TError extends OutfitterError = OutfitterError
+>(action: ActionSpec<TInput, TOutput, TError>): ActionSpec<TInput, TOutput, TError>;
+declare function createActionRegistry(): ActionRegistry;
+export { defineAction, createActionRegistry, HttpMethod, DEFAULT_REGISTRY_SURFACES, AnyActionSpec, ActionTrpcSpec, ActionSurface, ActionSpec, ActionRegistry, ActionMcpSpec, ActionCliSpec, ActionCliOption, ActionCliInputContext, ActionApiSpec, ACTION_SURFACES };

package/dist/actions.js

@@ -0,0 +1,32 @@
+// @bun
+// packages/contracts/src/actions.ts
+var ACTION_SURFACES = ["cli", "mcp", "api", "server"];
+var DEFAULT_REGISTRY_SURFACES = ACTION_SURFACES;
+function defineAction(action) {
+  return action;
+}
+function createActionRegistry() {
+  const actions = new Map;
+  return {
+    add(action) {
+      actions.set(action.id, action);
+      return this;
+    },
+    list() {
+      return Array.from(actions.values());
+    },
+    get(id) {
+      return actions.get(id);
+    },
+    forSurface(surface) {
+      const defaults = DEFAULT_REGISTRY_SURFACES;
+      return Array.from(actions.values()).filter((action) => (action.surfaces ?? defaults).includes(surface));
+    }
+  };
+}
+export {
+  defineAction,
+  createActionRegistry,
+  DEFAULT_REGISTRY_SURFACES,
+  ACTION_SURFACES
+};

package/dist/adapters.d.ts

@@ -0,0 +1,182 @@
+import { Result } from "better-result";
+/**
+* Error types for adapter operations.
+* These extend the base error taxonomy for adapter-specific failures.
+*/
+/** Error during indexing operations */
+interface IndexError {
+	readonly _tag: "IndexError";
+	readonly message: string;
+	readonly cause?: unknown;
+}
+/** Error during cache operations */
+interface CacheError {
+	readonly _tag: "CacheError";
+	readonly message: string;
+	readonly cause?: unknown;
+}
+/** Error during auth/credential operations */
+interface AdapterAuthError {
+	readonly _tag: "AdapterAuthError";
+	readonly message: string;
+	readonly cause?: unknown;
+}
+/** Error during storage operations */
+interface StorageError {
+	readonly _tag: "StorageError";
+	readonly message: string;
+	readonly cause?: unknown;
+}
+/**
+* Search options for index adapter.
+*/
+interface SearchOptions {
+	/** Maximum results to return */
+	limit?: number;
+	/** Offset for pagination */
+	offset?: number;
+	/** Field-specific filters */
+	filters?: Record<string, unknown>;
+	/** Fields to boost in relevance scoring */
+	boostFields?: string[];
+}
+/**
+* Search result from index adapter.
+*/
+interface SearchResult<T> {
+	/** Matched items with relevance scores */
+	hits: Array<{
+		item: T;
+		score: number;
+		highlights?: Record<string, string[]>;
+	}>;
+	/** Total number of matches (for pagination) */
+	total: number;
+	/** Search execution time in milliseconds */
+	took: number;
+}
+/**
+* Index statistics.
+*/
+interface IndexStats {
+	/** Total documents indexed */
+	documentCount: number;
+	/** Index size in bytes (if available) */
+	sizeBytes?: number;
+	/** Last update timestamp */
+	lastUpdated: Date | null;
+}
+/**
+* Index adapter - pluggable full-text search backends.
+*
+* Implementations: SQLite FTS5, future: Tantivy, Meilisearch
+*
+* @typeParam T - The indexed document type
+*
+* @example
+* ```typescript
+* const sqliteIndex = new SqliteFts5Adapter<Note>({
+*   db: database,
+*   table: "notes_fts",
+*   fields: ["title", "content", "tags"],
+* });
+*
+* await sqliteIndex.index(notes);
+* const results = await sqliteIndex.search("authentication patterns");
+* ```
+*/
+interface IndexAdapter<T> {
+	/** Add or update documents in the index */
+	index(items: T[]): Promise<Result<void, IndexError>>;
+	/** Full-text search with optional filters */
+	search(query: string, options?: SearchOptions): Promise<Result<SearchResult<T>, IndexError>>;
+	/** Remove documents by ID */
+	remove(ids: string[]): Promise<Result<void, IndexError>>;
+	/** Clear all indexed documents */
+	clear(): Promise<Result<void, IndexError>>;
+	/** Get index statistics */
+	stats(): Promise<Result<IndexStats, IndexError>>;
+}
+/**
+* Cache adapter - pluggable caching backends.
+*
+* Implementations: SQLite, in-memory LRU, future: Redis via Bun.RedisClient
+*
+* @typeParam T - The cached value type
+*
+* @example
+* ```typescript
+* const cache = new SqliteCacheAdapter<User>({ db, table: "user_cache" });
+*
+* await cache.set("user:123", user, 3600); // 1 hour TTL
+* const cached = await cache.get("user:123");
+* ```
+*/
+interface CacheAdapter<T> {
+	/** Get cached value, null if not found or expired */
+	get(key: string): Promise<Result<T | null, CacheError>>;
+	/** Set value with optional TTL in seconds */
+	set(key: string, value: T, ttlSeconds?: number): Promise<Result<void, CacheError>>;
+	/** Delete cached value, returns true if existed */
+	delete(key: string): Promise<Result<boolean, CacheError>>;
+	/** Clear all cached values */
+	clear(): Promise<Result<void, CacheError>>;
+	/** Check if key exists (without retrieving value) */
+	has(key: string): Promise<Result<boolean, CacheError>>;
+	/** Get multiple values at once */
+	getMany(keys: string[]): Promise<Result<Map<string, T>, CacheError>>;
+}
+/**
+* Auth adapter - pluggable credential storage.
+*
+* Implementations: Environment, OS Keychain (via Bun.secrets), file-based
+*
+* @example
+* ```typescript
+* const auth = new KeychainAuthAdapter({ service: "outfitter" });
+*
+* await auth.set("github_token", token);
+* const stored = await auth.get("github_token");
+* ```
+*/
+interface AuthAdapter {
+	/** Retrieve credential by key */
+	get(key: string): Promise<Result<string | null, AdapterAuthError>>;
+	/** Store credential */
+	set(key: string, value: string): Promise<Result<void, AdapterAuthError>>;
+	/** Remove credential */
+	delete(key: string): Promise<Result<boolean, AdapterAuthError>>;
+	/** List available credential keys (not values) */
+	list(): Promise<Result<string[], AdapterAuthError>>;
+}
+/**
+* Storage adapter - pluggable blob/file storage.
+*
+* Implementations: Local filesystem, S3 via Bun.S3Client, R2
+*
+* @example
+* ```typescript
+* const storage = new LocalStorageAdapter({ basePath: "/data" });
+*
+* await storage.write("notes/abc.md", content);
+* const data = await storage.read("notes/abc.md");
+* ```
+*/
+interface StorageAdapter {
+	/** Read file contents */
+	read(path: string): Promise<Result<Uint8Array, StorageError>>;
+	/** Write file contents */
+	write(path: string, data: Uint8Array): Promise<Result<void, StorageError>>;
+	/** Delete file */
+	delete(path: string): Promise<Result<boolean, StorageError>>;
+	/** Check if file exists */
+	exists(path: string): Promise<Result<boolean, StorageError>>;
+	/** List files in directory */
+	list(prefix: string): Promise<Result<string[], StorageError>>;
+	/** Get file metadata (size, modified time) */
+	stat(path: string): Promise<Result<{
+		size: number;
+		modifiedAt: Date;
+	} | null, StorageError>>;
+}
+export { StorageError, StorageAdapter, SearchResult, SearchOptions, IndexStats, IndexError, IndexAdapter, CacheError, CacheAdapter, AuthAdapter, AdapterAuthError };

package/dist/adapters.js

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