stack-patterns_skill

Overview

This skill is a concise reference for the Outfitter stack patterns, covering the Handler contract, Result types, error taxonomy, and @outfitter/* package conventions. It helps engineers adopt consistent, testable handlers and map domain errors to exit/HTTP codes. Use it to standardize CLI, MCP, daemon, and library behavior across projects.

How this skill works

It documents the canonical Handler signature: a pure function receiving typed input and a HandlerContext and returning Result<T, E>. It explains use of better-result for explicit results, Zod-based validation helpers, and a ten-category error taxonomy that maps to exit and HTTP status codes. It also lists package responsibilities and Bun-first API recommendations to guide implementation choices.

When to use it

• When writing or testing handlers that must be transport-agnostic
• When mapping domain errors to exit codes and HTTP statuses
• When validating inputs with Zod and creating typed Results
• When choosing which @outfitter/* packages to add to a project
• When designing CLI output, MCP tools, or background daemons

Best practices

• Always start new projects with @outfitter/contracts for types, Result utilities, and error classes
• Keep handlers pure and transport-agnostic so they are reusable across CLI, HTTP, and MCP
• Use createValidator with Zod to return typed Result values instead of throwing
• Map domain errors to the 10-category taxonomy to ensure consistent exit and HTTP codes
• Use HandlerContext for cross-cutting concerns: structured logger, requestId, signal, config, and workspace/cwd
• Prefer Bun-native APIs where available for performance and consistency

Example use cases

• Implementing a getUser handler that returns Result.ok(user) or Result.err(NotFoundError) and is called from CLI, MCP, and HTTP layers
• Validating raw CLI input with a Zod schema and returning ValidationError via Result.err
• Mapping database uniqueness conflicts to ConflictError so the CLI returns exit code 3 and HTTP 409
• Building an MCP tool using @outfitter/mcp with registered Zod schemas and handlers
• Writing a daemon with @outfitter/daemon that uses the HandlerContext signal for graceful shutdown