Outfitter Field Guide

Your trail map for building with @outfitter/* packages. This guide covers the patterns, the templates, and—just as importantly—the why behind it all.

Why We Built This

We kept solving the same problems across projects: config loading, error handling, CLI output modes, MCP server boilerplate. Every tool needed the same foundation. So we extracted it.

Agents Are the New Users

The patterns assume you're building tools that agents will consume—structured output, typed errors, predictable behavior. Humans benefit too; agents just make the stakes clearer.

When an AI agent calls your CLI or MCP tool, it needs:

• •Structured output it can parse (JSON when piped, human-readable otherwise)
• •Typed errors with categories it can reason about (retry? abort? ask user?)
• •Predictable exit codes for scripting and automation
• •Consistent behavior across transport surfaces

The stack enforces these properties by design, not discipline.

Errors Are Data, Not Exceptions

Traditional error handling (throw/catch) loses context, breaks type safety, and makes control flow unpredictable. We treat errors as first-class data:

const error = new NotFoundError("user", "user-123");
error._tag;        // "NotFoundError" — for pattern matching
error.category;    // "not_found" — maps to exit code 2, HTTP 404
error.message;     // Human-readable
error.toJSON();    // Serializes cleanly for agents

Ten categories cover all failure modes. Each maps to exit codes (CLI) and HTTP status (API/MCP). Agents can make retry decisions without parsing error strings.

Tests First, Always

Tests define behavior; implementations follow. The workflow:

1. •Red: Write a failing test that defines expected behavior
2. •Green: Minimal code to pass
3. •Refactor: Improve while staying green

The test proves the behavior exists. A failing test proves it doesn't—yet.

One Definition, Many Derivations

Types, schemas, and contracts have exactly one source:

If two things must stay in sync, one derives from the other.

Bun-Native When Possible

Bun APIs before npm packages—faster, zero-dependency:

The Core Idea

Handlers are pure functions returning Result<T, E>. CLI and MCP are thin adapters over the same logic. Write the handler once, expose it everywhere.

type Handler<TInput, TOutput, TError extends OutfitterError> = (
  input: TInput,
  ctx: HandlerContext
) => Promise<Result<TOutput, TError>>;

This buys you:

• •Testability — Call the function directly, no transport mocking
• •Reusability — Same handler serves CLI, MCP, HTTP
• •Type Safety — Input, output, and error types are explicit
• •Composability — Handlers wrap handlers

The Package Landscape

Dependencies flow one direction: Foundation → Runtime → Tooling.

┌─────────────────────────────────────────────────────────────────┐
│                        TOOLING TIER                              │
│  @outfitter/testing   @outfitter/tooling                        │
└─────────────────────────────────────────────────────────────────┘
                              ▲
┌─────────────────────────────────────────────────────────────────┐
│                        RUNTIME TIER                              │
│  @outfitter/cli    @outfitter/mcp    @outfitter/daemon          │
│  @outfitter/config @outfitter/logging @outfitter/file-ops       │
│  @outfitter/state  @outfitter/index                             │
└─────────────────────────────────────────────────────────────────┘
                              ▲
┌─────────────────────────────────────────────────────────────────┐
│                       FOUNDATION TIER                            │
│  @outfitter/contracts    @outfitter/types                       │
└─────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────┐
│  META: @outfitter/kit (version coordination across all tiers) │
└─────────────────────────────────────────────────────────────────┘

Trail Map: Designing a System

Five things to know when building with the Outfitter stack. For the complete design process with templates, see guides/architecture.md.

1. Know Your Terrain

Before writing code, understand:

• •Transport surfaces — CLI, MCP, HTTP, or all three?
• •Domain operations — What actions does the system perform?
• •Failure modes — What can go wrong? (these map to error taxonomy)
• •External dependencies — APIs, databases, file system?

2. Design the Handler Layer

For each domain operation:

1. •Define input type (Zod schema)
2. •Define output type
3. •Identify error types (from taxonomy)
4. •Write the signature: Handler<Input, Output, Error1 | Error2>

const CreateUserInputSchema = z.object({
  email: z.string().email(),
  name: z.string().min(1),
});

interface User {
  id: string;
  email: string;
  name: string;
}

const createUser: Handler<unknown, User, ValidationError | ConflictError>;

3. Map Errors to the Taxonomy

Ten categories. Memorize the exit codes—you'll use them.

4. Pick Your Packages

Start with @outfitter/contracts. Always.

• •Building a CLI? Add @outfitter/cli
• •Building MCP tools? Add @outfitter/mcp
• •Touching files? Add @outfitter/config (paths) + @outfitter/file-ops (safety)

5. Wire Up Context Flow

Decide:

• •Entry points — Where does context get created?
• •What's in context — Logger, config, signal, workspaceRoot
• •Tracing — How does requestId flow through?

Guides

Deeper dives into specific topics.

Pattern Deep Dives

When you need the details, not just the overview.

Templates: Just Add Code

Copy, paste, customize.

Quick Start

# Foundation first
bun add @outfitter/contracts

# Then what you need
bun add @outfitter/cli       # CLI apps
bun add @outfitter/mcp       # MCP servers
bun add @outfitter/logging   # Structured logging
bun add @outfitter/config    # XDG-compliant config
bun add @outfitter/index     # Full-text search

# Dev dependencies
bun add -D @outfitter/testing @outfitter/tooling

# Version coordination (optional)
bun add @outfitter/kit

New here? Start with guides/getting-started.md.

The Rules

Do

• •Use Result types, not exceptions
• •Map domain errors to taxonomy categories
• •Design handlers as pure functions: (input, ctx) => Result
• •Include error types in handler signatures
• •Validate at handler entry with createValidator
• •Pass context through all handler calls
• •Test handlers directly—no transport layer needed

Don't

• •Throw exceptions in handlers
• •Put transport-specific logic in handlers
• •Hardcode paths (use XDG via @outfitter/config)
• •Skip error type planning
• •Couple handlers to specific transports
• •Use console.log (use ctx.logger)

Troubleshooting

Something not working? Use kit:debug-outfitter for systematic investigation with structured reports. Common issues:

• •Result always error — Check for missing await on async handlers
• •Type narrowing broken — Don't reassign Result variables after checking
• •MCP tool not appearing — Register before start(), add .describe() to schema fields
• •Wrong exit code — Use exitWithError(), not process.exit()

If the issue is in Outfitter itself, use kit:outfitter-feedback to file a bug.