@outfitter/contracts 0.4.1 → 0.5.0

package/dist/shared/@outfitter/contracts-3gswmhb1.d.ts

@@ -1,446 +0,0 @@
-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";
-/**
-* 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>;
-/**
-* 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.
-*/
-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;
-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;
-}>;
-/**
-* Input validation failed.
-*
-* @example
-* ```typescript
-* new ValidationError({ message: "Email format invalid", field: "email" });
-* new ValidationError({
-*   message: "Value out of range",
-*   field: "age",
-*   context: { min: 0, max: 150, received: -1 },
-* });
-* ```
-*/
-declare class ValidationError extends ValidationErrorBase {
-	readonly category: "validation";
-	/** Create a ValidationError with auto-generated message from field name. */
-	static create(field: string, reason: string, context?: Record<string, unknown>): ValidationError;
-	/**
-	* Create a freeform ValidationError without a specific field.
-	*
-	* Use when the validation failure applies to the input as a whole
-	* rather than a single field (e.g., "Invalid pipeline configuration").
-	*
-	* @param message - Human-readable validation error message
-	* @param context - Optional structured context for debugging
-	*/
-	static fromMessage(message: string, context?: Record<string, unknown>): ValidationError;
-	exitCode(): number;
-	statusCode(): number;
-}
-/**
-* Multiple matches found — user must disambiguate.
-*
-* Used in search/resolution systems where partial input matches
-* multiple candidates. Carries the candidate list so transport
-* layers can prompt disambiguation.
-*
-* @example
-* ```typescript
-* new AmbiguousError({
-*   message: "Multiple headings match 'Intro'",
-*   candidates: ["Introduction", "Intro to APIs"],
-* });
-* AmbiguousError.create("heading", ["Introduction", "Intro to APIs"]);
-* ```
-*/
-declare class AmbiguousError extends AmbiguousErrorBase {
-	readonly category: "validation";
-	/** Create an AmbiguousError with auto-generated message. */
-	static create(what: string, candidates: string[], context?: Record<string, unknown>): AmbiguousError;
-	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" });
-* new NotFoundError({
-*   message: "Heading not found",
-*   resourceType: "heading",
-*   resourceId: "h:Intro",
-*   context: { availableHeadings: ["Introduction", "Getting Started"] },
-* });
-* ```
-*/
-declare class NotFoundError extends NotFoundErrorBase {
-	readonly category: "not_found";
-	/** Create a NotFoundError with auto-generated message. */
-	static create(resourceType: string, resourceId: string, context?: Record<string, unknown>): NotFoundError;
-	exitCode(): number;
-	statusCode(): number;
-}
-/**
-* Resource already exists — the inverse of {@link NotFoundError}.
-*
-* Use when a create/write operation fails because the target resource
-* is already present. Carries `resourceType` and `resourceId` to identify
-* what already exists, mirroring {@link NotFoundError}'s structure.
-*
-* Maps to HTTP 409 (Conflict) and exit code 3.
-*
-* @example
-* ```typescript
-* new AlreadyExistsError({
-*   message: "File already exists: notes/meeting.md",
-*   resourceType: "file",
-*   resourceId: "notes/meeting.md",
-* });
-* AlreadyExistsError.create("file", "notes/meeting.md");
-* ```
-*
-* @see ConflictError - For general state conflicts (version mismatch, concurrent modification)
-* @see NotFoundError - The inverse: resource does not exist
-*/
-declare class AlreadyExistsError extends AlreadyExistsErrorBase {
-	readonly category: "conflict";
-	/** Create an AlreadyExistsError with auto-generated message. */
-	static create(resourceType: string, resourceId: string, context?: Record<string, unknown>): AlreadyExistsError;
-	exitCode(): number;
-	statusCode(): number;
-}
-/**
-* State conflict (version mismatch, concurrent modification).
-*
-* Use for general conflicts that don't fit {@link AlreadyExistsError}:
-* optimistic locking failures, concurrent writes, ETag mismatches,
-* or any case where the operation can't proceed due to state divergence.
-*
-* Maps to HTTP 409 (Conflict) and exit code 3.
-*
-* **Choosing the right conflict error:**
-* - Resource already exists? Use {@link AlreadyExistsError}
-* - Version/ETag mismatch? Use {@link ConflictError}
-* - Concurrent modification detected? Use {@link ConflictError}
-*
-* @example
-* ```typescript
-* new ConflictError({ message: "Resource was modified by another process" });
-* ConflictError.create("ETag mismatch: expected abc, got def");
-* ```
-*
-* @see AlreadyExistsError - For "resource already exists" specifically
-*/
-declare class ConflictError extends ConflictErrorBase {
-	readonly category: "conflict";
-	/** Create a ConflictError with optional context. */
-	static create(message: string, context?: Record<string, unknown>): ConflictError;
-	exitCode(): number;
-	statusCode(): number;
-}
-/**
-* Authorization denied.
-*
-* @example
-* ```typescript
-* new PermissionError({ message: "Cannot delete read-only resource" });
-* ```
-*/
-declare class PermissionError extends PermissionErrorBase {
-	readonly category: "permission";
-	/** Create a PermissionError with optional context. */
-	static create(message: string, context?: Record<string, unknown>): PermissionError;
-	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";
-	/** Create a TimeoutError with auto-generated message. */
-	static create(operation: string, timeoutMs: number): TimeoutError;
-	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";
-	/** Create a RateLimitError with optional retry hint. */
-	static create(message: string, retryAfterSeconds?: number): RateLimitError;
-	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";
-	/** Create a NetworkError with optional context. */
-	static create(message: string, context?: Record<string, unknown>): NetworkError;
-	exitCode(): number;
-	statusCode(): number;
-}
-/**
-* Unexpected internal error.
-*
-* @example
-* ```typescript
-* new InternalError({ message: "Unexpected state in processor" });
-* ```
-*/
-declare class InternalError extends InternalErrorBase {
-	readonly category: "internal";
-	/** Create an InternalError with optional context. */
-	static create(message: string, context?: Record<string, unknown>): InternalError;
-	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";
-	/** Create an AuthError with optional reason. */
-	static create(message: string, reason?: "missing" | "invalid" | "expired"): AuthError;
-	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";
-	/** Create a CancelledError. */
-	static create(message: string): CancelledError;
-	exitCode(): number;
-	statusCode(): number;
-}
-/**
-* Union type of all concrete error class instances.
-*/
-type AnyKitError = InstanceType<typeof ValidationError> | InstanceType<typeof AmbiguousError> | InstanceType<typeof AssertionError> | InstanceType<typeof NotFoundError> | InstanceType<typeof AlreadyExistsError> | 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;
-export { ErrorCategory, exitCodeMap, statusCodeMap, ERROR_CODES, ErrorCode, SerializedError, KitErrorProps, getExitCode, getStatusCode, ValidationError, AmbiguousError, AssertionError, NotFoundError, AlreadyExistsError, ConflictError, PermissionError, TimeoutError, RateLimitError, NetworkError, InternalError, AuthError, CancelledError, AnyKitError, OutfitterError };

package/dist/shared/@outfitter/contracts-4zaj7ejb.js

@@ -1,52 +0,0 @@
-// @bun
-// packages/contracts/src/recovery.ts
-var RECOVERABLE_CATEGORIES = [
-  "network",
-  "timeout",
-  "rate_limit",
-  "conflict"
-];
-var RETRYABLE_CATEGORIES = ["network", "timeout"];
-var isRecoverable = (error) => {
-  return RECOVERABLE_CATEGORIES.includes(error.category);
-};
-var isRetryable = (error) => {
-  return RETRYABLE_CATEGORIES.includes(error.category);
-};
-var getBackoffDelay = (attempt, options = {}) => {
-  const {
-    baseDelayMs = 100,
-    maxDelayMs = 30000,
-    strategy = "exponential",
-    useJitter = true
-  } = options;
-  let delay;
-  switch (strategy) {
-    case "constant": {
-      delay = baseDelayMs;
-      break;
-    }
-    case "linear": {
-      delay = baseDelayMs * (attempt + 1);
-      break;
-    }
-    default: {
-      delay = baseDelayMs * 2 ** attempt;
-    }
-  }
-  delay = Math.min(delay, maxDelayMs);
-  if (useJitter) {
-    const jitterFactor = 0.1;
-    const jitter = delay * jitterFactor * (Math.random() * 2 - 1);
-    delay = Math.round(delay + jitter);
-  }
-  return Math.min(delay, maxDelayMs);
-};
-var shouldRetry = (error, attempt, maxAttempts = 3) => {
-  if (attempt >= maxAttempts) {
-    return false;
-  }
-  return isRetryable(error);
-};
-
-export { isRecoverable, isRetryable, getBackoffDelay, shouldRetry };

package/dist/shared/@outfitter/contracts-85nd53s9.js

@@ -1,53 +0,0 @@
-// @bun
-import {
-  serializeError
-} from "./contracts-3wj7xghe.js";
-import {
-  statusCodeMap
-} from "./contracts-phjhz5q3.js";
-import {
-  generateRequestId
-} from "./contracts-agmt8915.js";
-
-// packages/contracts/src/envelope.ts
-function buildMeta(overrides) {
-  const meta = {
-    requestId: overrides?.requestId ?? generateRequestId(),
-    timestamp: new Date().toISOString()
-  };
-  if (overrides?.durationMs !== undefined) {
-    meta.durationMs = overrides.durationMs;
-  }
-  return meta;
-}
-function toEnvelope(result, meta) {
-  const envelopeMeta = buildMeta(meta);
-  if (result.isOk()) {
-    return {
-      ok: true,
-      data: result.value,
-      meta: envelopeMeta
-    };
-  }
-  return {
-    ok: false,
-    error: serializeError(result.error),
-    meta: envelopeMeta
-  };
-}
-function toHttpResponse(result) {
-  const envelope = toEnvelope(result);
-  if (envelope.ok) {
-    return {
-      status: 200,
-      body: envelope
-    };
-  }
-  const status = statusCodeMap[envelope.error.category];
-  return {
-    status,
-    body: envelope
-  };
-}
-
-export { toEnvelope, toHttpResponse };

package/dist/shared/@outfitter/contracts-9wtm5nsw.d.ts

@@ -1,42 +0,0 @@
-import { ValidationError } from "./contracts-3gswmhb1.js";
-import { Result } from "better-result";
-import { z } from "zod";
-/**
-* 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>;
-export { createValidator, validateInput };

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

@@ -1,32 +0,0 @@
-// @bun
-import {
-  AssertionError
-} from "./contracts-phjhz5q3.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, assertDefined, assertNonEmpty, assertMatches };

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

@@ -1,60 +0,0 @@
-// @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 { CAPABILITY_SURFACES, DEFAULT_ACTION_SURFACES, capability, capabilityAll, ACTION_CAPABILITIES, getActionsForSurface };