@outfitter/presets 0.2.1 → 0.3.0

package/presets/library/CLAUDE.md.template

@@ -0,0 +1,68 @@
+# CLAUDE.md
+
+Bun-first TypeScript library. Tests before code. Result types, not exceptions.
+
+## Commands
+
+```bash
+bun run build        # Build library with bunup (ESM + types)
+bun run dev          # Watch mode
+bun run test         # Run tests
+bun run typecheck    # TypeScript validation
+bun run check        # Lint + format check (ultracite)
+bun run lint         # Lint checks (oxlint)
+bun run lint:fix     # Auto-fix lint issues
+bun run format       # Auto-fix formatting (oxfmt)
+bun run verify:ci    # Full CI validation (typecheck + check + build + test)
+```
+
+## Architecture
+
+Publishable TypeScript library built with Bun and bunup.
+
+### Project Structure
+
+- `src/types.ts` — Zod schemas with explicit `ZodType` annotations + TypeScript interfaces
+- `src/handlers.ts` — Pure handler functions returning `Result<T, E>`
+- `src/index.ts` — Re-exports from types + handlers
+- `src/index.test.ts` — Tests with `createContext()`, testing success + error paths
+
+### Handler Contract
+
+All domain logic uses transport-agnostic handlers returning `Result<T, E>`:
+
+```typescript
+async function handler(
+  input: unknown,
+  ctx: HandlerContext
+): Promise<Result<Output, ValidationError>> {
+  const parsed = inputSchema.safeParse(input);
+  if (!parsed.success) {
+    return Result.err(new ValidationError({ message: "...", field: "name" }));
+  }
+  // business logic
+  return Result.ok(result);
+}
+```
+
+### Schema Convention
+
+Exported Zod schemas must have explicit type annotations:
+
+```typescript
+export const inputSchema: ZodType<Input> = z.object({ ... });
+```
+
+## Development Principles
+
+- **TDD-First** — Write the test before the code (Red / Green / Refactor)
+- **Result Types** — Handlers return `Result<T, E>`, not exceptions
+- **Bun-First** — Use Bun-native APIs before npm packages
+- **Strict TypeScript** — No `any`, no `as` casts; narrow instead of assert
+
+## Testing
+
+- Runner: Bun test runner
+- Files: `src/*.test.ts`
+- Run: `bun test` or `bun run test`
+- Test handlers with `createContext()` from `@outfitter/contracts`

package/presets/library/bunup.config.ts.template

@@ -1,20 +1,20 @@
 import { defineWorkspace } from "bunup";
 
 export default defineWorkspace(
-	[
-		{
-			name: "{{packageName}}",
-			root: ".",
-		},
-	],
-	{
-		entry: ["src/**/*.ts", "!src/**/*.test.ts", "!src/**/__tests__/**"],
-		sourceBase: "./src",
-		format: ["esm", "cjs"],
-		dts: true,
-		exports: true,
-		splitting: true,
-		clean: true,
-		target: "bun",
-	}
+  [
+    {
+      name: "{{packageName}}",
+      root: ".",
+    },
+  ],
+  {
+    entry: ["src/**/*.ts", "!src/**/*.test.ts", "!src/**/__tests__/**"],
+    sourceBase: "./src",
+    format: ["esm", "cjs"],
+    dts: true,
+    exports: true,
+    splitting: true,
+    clean: true,
+    target: "bun",
+  }
 );

package/presets/library/package.json.template

@@ -1,52 +1,53 @@
 {
-	"name": "{{packageName}}",
-	"version": "{{version}}",
-	"description": "{{description}}",
-	"type": "module",
-	"main": "./dist/index.cjs",
-	"module": "./dist/index.js",
-	"types": "./dist/index.d.ts",
-	"files": [
-		"dist"
-	],
-	"sideEffects": false,
-	"exports": {
-		".": {
-			"types": "./dist/index.d.ts",
-			"import": "./dist/index.js",
-			"require": "./dist/index.cjs"
-		}
-	},
-	"scripts": {
-		"build": "bunup",
-		"dev": "bun --watch src/index.ts",
-		"test": "bun test",
-		"test:watch": "bun test --watch",
-		"typecheck": "tsc --noEmit",
-		"lint": "oxlint .",
-		"lint:fix": "oxlint --fix .",
-		"format": "oxfmt --write .",
-		"clean:artifacts": "rm -rf dist .turbo",
-		"clean": "rm -rf dist"
-	},
-	"dependencies": {
-		"@outfitter/contracts": "workspace:*",
-		"@outfitter/logging": "workspace:*",
-		"zod": "^4.3.5"
-	},
-	"devDependencies": {
-		"bunup": "^0.16.29"
-	},
-	"outfitter": {
-		"template": {
-			"kind": "library",
-			"placement": "packages",
-			"surfaces": []
-		}
-	},
-	"engines": {
-		"bun": ">=1.3.10"
-	},
-	"keywords": [],
-	"license": "MIT"
+  "name": "{{packageName}}",
+  "version": "{{version}}",
+  "description": "{{description}}",
+  "keywords": [],
+  "license": "MIT",
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "scripts": {
+    "build": "bunup",
+    "dev": "bun --watch src/index.ts",
+    "test": "bun test",
+    "test:watch": "bun test --watch",
+    "typecheck": "tsc --noEmit",
+    "check": "ultracite check",
+    "lint": "oxlint .",
+    "lint:fix": "oxlint --fix .",
+    "format": "oxfmt --write .",
+    "verify:ci": "bun run typecheck && bun run check && bun run build && bun run test",
+    "clean:artifacts": "rm -rf dist .turbo",
+    "clean": "rm -rf dist"
+  },
+  "dependencies": {
+    "@outfitter/contracts": "workspace:*",
+    "zod": "catalog:"
+  },
+  "devDependencies": {
+    "bunup": "catalog:"
+  },
+  "engines": {
+    "bun": ">=1.3.10"
+  },
+  "outfitter": {
+    "template": {
+      "kind": "library",
+      "placement": "packages",
+      "surfaces": []
+    }
+  }
 }

package/presets/library/src/handlers.ts.template

@@ -1,31 +1,55 @@
-import { Result, ValidationError, type Handler } from "@outfitter/contracts";
-import { createLogger } from "@outfitter/logging";
-import { greetingInputSchema, type Greeting } from "./types.js";
+import {
+  Result,
+  ValidationError,
+  type HandlerContext,
+} from "@outfitter/contracts";
 
-const logger = createLogger({ name: "{{projectName}}" });
+import { greetingInputSchema, type Greeting } from "./types.js";
 
-export const createGreeting: Handler<unknown, Greeting, ValidationError> = async (
-	input,
-	ctx
-) => {
-	const parsed = greetingInputSchema.safeParse(input);
-	if (!parsed.success) {
-		return Result.err(
-			new ValidationError({
-				message: "Invalid greeting input",
-				field: "name",
-			})
-		);
-	}
+/**
+ * Create a greeting from unvalidated input.
+ *
+ * @param input - Raw input to validate against {@link greetingInputSchema}
+ * @param ctx - Handler context with logger and request metadata
+ * @returns Validated greeting or a `ValidationError` with field-level validation details
+ *
+ * @example
+ * ```typescript
+ * const result = await createGreeting({ name: "World" }, ctx);
+ * if (result.isOk()) {
+ *   console.log(result.value.message); // "Hello, World."
+ * }
+ * ```
+ */
+export async function createGreeting(
+  input: unknown,
+  ctx: HandlerContext
+): Promise<Result<Greeting, ValidationError>> {
+  const parsed = greetingInputSchema.safeParse(input);
+  if (!parsed.success) {
+    const issue = parsed.error.issues[0];
+    return Result.err(
+      new ValidationError({
+        message: issue?.message ?? "Invalid greeting input",
+        field: issue?.path.join(".") || "input",
+        context: {
+          fields: parsed.error.issues.map((i) => ({
+            path: i.path.join(".") || "input",
+            message: i.message,
+          })),
+        },
+      })
+    );
+  }
 
-	const suffix = parsed.data.excited ? "!" : ".";
-	const greeting: Greeting = {
-		message: `Hello, ${parsed.data.name}${suffix}`,
-		issuedAt: new Date().toISOString(),
-	};
+  const suffix = parsed.data.excited ? "!" : ".";
+  const greeting: Greeting = {
+    message: `Hello, ${parsed.data.name}${suffix}`,
+    issuedAt: new Date().toISOString(),
+  };
 
-	logger.info(`Created greeting for ${parsed.data.name}`, {
-		requestId: ctx.requestId,
-	});
-	return Result.ok(greeting);
-};
+  ctx.logger.info(`Created greeting for ${parsed.data.name}`, {
+    requestId: ctx.requestId,
+  });
+  return Result.ok(greeting);
+}

package/presets/library/src/index.test.ts.template

@@ -1,35 +1,46 @@
 import { describe, expect, test } from "bun:test";
+
 import { createContext } from "@outfitter/contracts";
+
 import { createGreeting } from "./handlers.js";
 
 describe("createGreeting", () => {
-	test("returns greeting for valid input", async () => {
-		const ctx = createContext({
-			cwd: process.cwd(),
-			env: process.env,
-		});
-		const result = await createGreeting(
-			{ name: "Outfitter", excited: true },
-			ctx
-		);
-
-		expect(result.isOk()).toBe(true);
-		if (result.isErr()) {
-			return;
-		}
-		expect(result.value.message).toBe("Hello, Outfitter!");
-	});
-
-	test("returns validation error for invalid input", async () => {
-		const ctx = createContext({
-			cwd: process.cwd(),
-			env: process.env,
-		});
-		const result = await createGreeting({ name: "" }, ctx);
-
-		expect(result.isErr()).toBe(true);
-		if (result.isErr()) {
-			expect(result.error.name).toBe("ValidationError");
-		}
-	});
+  const ctx = createContext({ cwd: process.cwd(), env: process.env });
+
+  test("returns greeting for valid input", async () => {
+    const result = await createGreeting(
+      { name: "Outfitter", excited: true },
+      ctx
+    );
+
+    expect(result.isOk()).toBe(true);
+    if (result.isErr()) return;
+    expect(result.value.message).toBe("Hello, Outfitter!");
+  });
+
+  test("returns validation error for empty name", async () => {
+    const result = await createGreeting({ name: "" }, ctx);
+
+    expect(result.isErr()).toBe(true);
+    if (!result.isErr()) return;
+    expect(result.error.name).toBe("ValidationError");
+    expect(result.error.message).toBe("name is required");
+    expect(result.error.context).toEqual({
+      fields: [{ path: "name", message: "name is required" }],
+    });
+  });
+
+  test("returns validation error for missing input", async () => {
+    const result = await createGreeting({}, ctx);
+
+    expect(result.isErr()).toBe(true);
+    if (!result.isErr()) return;
+    expect(result.error.name).toBe("ValidationError");
+    // Check error field rather than message text — Zod error messages
+    // differ between v3 ("Required") and v4 ("Invalid input: ...").
+    const fields = result.error.context?.fields as
+      | Array<{ path: string }>
+      | undefined;
+    expect(fields?.some((f) => f.path === "name")).toBe(true);
+  });
 });

package/presets/library/src/types.ts.template

@@ -1,13 +1,19 @@
-import { z } from "zod";
+import { type ZodType, z } from "zod";
 
-export const greetingInputSchema = z.object({
-	name: z.string().min(1, "name is required"),
-	excited: z.boolean().default(false),
-});
+/** Input for the greeting handler. */
+export interface GreetingInput {
+  readonly name: string;
+  readonly excited: boolean;
+}
 
-export type GreetingInput = z.infer<typeof greetingInputSchema>;
+/** Zod schema for validating greeting input at the boundary. */
+export const greetingInputSchema: ZodType<GreetingInput> = z.object({
+  name: z.string().min(1, "name is required"),
+  excited: z.boolean().default(false),
+});
 
+/** A generated greeting with timestamp. */
 export interface Greeting {
-	readonly message: string;
-	readonly issuedAt: string;
+  readonly message: string;
+  readonly issuedAt: string;
 }

package/presets/library/tsconfig.json.template

@@ -1,34 +1,34 @@
 {
-	"$schema": "https://json.schemastore.org/tsconfig",
-	"compilerOptions": {
-		"target": "ESNext",
-		"module": "ESNext",
-		"moduleResolution": "bundler",
-		"lib": ["ESNext"],
-		"types": ["@types/bun"],
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "lib": ["ESNext"],
+    "types": ["@types/bun"],
 
-		"strict": true,
-		"noImplicitAny": true,
-		"strictNullChecks": true,
-		"noUncheckedIndexedAccess": true,
-		"exactOptionalPropertyTypes": true,
-		"noPropertyAccessFromIndexSignature": true,
-		"noImplicitReturns": true,
-		"noFallthroughCasesInSwitch": true,
+    "strict": true,
+    "noImplicitAny": true,
+    "strictNullChecks": true,
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true,
+    "noPropertyAccessFromIndexSignature": true,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true,
 
-		"declaration": true,
-		"declarationMap": true,
-		"sourceMap": true,
-		"outDir": "./dist",
-		"rootDir": "./src",
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
 
-		"esModuleInterop": true,
-		"forceConsistentCasingInFileNames": true,
-		"isolatedModules": true,
-		"verbatimModuleSyntax": true,
-		"skipLibCheck": true,
-		"resolveJsonModule": true
-	},
-	"include": ["src/**/*"],
-	"exclude": ["node_modules", "dist"]
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "isolatedModules": true,
+    "verbatimModuleSyntax": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
 }

package/presets/mcp/CLAUDE.md.template

@@ -0,0 +1,97 @@
+# CLAUDE.md
+
+Bun-first TypeScript MCP server. Tests before code. Result types, not exceptions.
+
+## Commands
+
+```bash
+bun run build        # Build server + library to dist/
+bun run dev          # Watch mode (auto-restart on changes)
+bun run test         # Run tests
+bun run typecheck    # TypeScript validation
+bun run check        # Lint + format check
+bun run lint:fix     # Auto-fix lint issues
+bun run format       # Auto-fix formatting
+bun run verify:ci    # Full CI validation (typecheck + check + build + test)
+```
+
+## Architecture
+
+MCP (Model Context Protocol) server built with `@modelcontextprotocol/sdk` and `@outfitter/mcp`.
+
+### Project Structure
+
+- `src/server.ts` — Server entry point (stdio transport)
+- `src/mcp.ts` — Tool and resource registration
+- `src/tools/` — Tool definitions with Zod schemas and handler logic
+- `src/index.ts` — Library re-exports for testing
+
+### Tool Definition
+
+Tools are defined with `defineTool()` using Zod schemas for input validation and Result types for output:
+
+```typescript
+import { Result, ValidationError } from "@outfitter/contracts";
+import { defineTool } from "@outfitter/mcp";
+import { z } from "zod";
+
+const myTool = defineTool({
+  name: "my-tool",
+  description: "Does something useful",
+  inputSchema: z.object({ query: z.string().min(1) }),
+  annotations: { readOnlyHint: true },
+  handler: async (input, ctx): Promise<Result<MyOutput, ValidationError>> => {
+    if (!isValid(input.query)) {
+      return Result.err(ValidationError.create("query", "invalid format"));
+    }
+    return Result.ok({ data: await fetchData(input.query) });
+  },
+});
+```
+
+### Resource Definition
+
+Static resources use `defineResource()`:
+
+```typescript
+import { Result } from "@outfitter/contracts";
+import { defineResource } from "@outfitter/mcp";
+
+const myResource = defineResource({
+  uri: "myapp:///config",
+  name: "Config",
+  handler: async (uri, _ctx) =>
+    Result.ok([{ uri, text: JSON.stringify(config) }]),
+});
+```
+
+### Adding a Resource
+
+Simple, self-contained resources (like `versionResource` in `src/mcp.ts`) can be defined inline — no separate file or re-export needed. For resources with non-trivial logic, extract to a dedicated file:
+
+1. Create resource file in `src/resources/<name>.ts` with `defineResource()`
+2. Import and register in `src/mcp.ts` via `server.registerResource()`
+3. Re-export from `src/index.ts`
+4. Add tests in `src/<name>.test.ts`
+
+### Adding a Tool
+
+1. Create tool file in `src/tools/<name>.ts` with `defineTool()`
+2. Import and register in `src/mcp.ts`
+3. Re-export from `src/index.ts`
+4. Add tests in `src/<name>.test.ts`
+
+## Development Principles
+
+- **TDD-First** — Write the test before the code (Red / Green / Refactor)
+- **Result Types** — Handlers return `Result<T, E>`, not exceptions
+- **Bun-First** — Use Bun-native APIs before npm packages
+- **Strict TypeScript** — No `any`, no `as` casts; narrow instead of assert
+
+## Testing
+
+- Runner: Bun test runner
+- Harness: `createMcpHarness()` from `@outfitter/testing` for protocol-level tests
+- Files: `src/*.test.ts`
+- Run: `bun test` or `bun run test`
+- Test tool handlers directly by importing from `src/index.ts`

package/presets/mcp/README.md.template

@@ -4,26 +4,28 @@
 
 MCP (Model Context Protocol) server for integration with AI assistants.
 
-## Installation
-
-```bash
-bun add {{packageName}}
-```
-
-## Usage with Claude Desktop
+## Claude Desktop Configuration
 
 Add to your Claude Desktop config:
 
+- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+
 ```json
 {
   "mcpServers": {
-    "{{binName}}": {
-      "command": "{{binName}}"
+    "{{projectName}}": {
+      "command": "bun",
+      "args": ["run", "/absolute/path/to/{{projectName}}/src/server.ts"]
     }
   }
 }
 ```
 
+Replace `/absolute/path/to/` with the actual path to your project directory.
+
+> **Note:** On macOS, `bun` may not be on Claude Desktop's PATH. If the server fails to start, replace `"bun"` with the full path (e.g., `"/Users/you/.bun/bin/bun"` — run `which bun` to find it).
+
 ## Available Tools
 
 ### hello
@@ -31,6 +33,7 @@ Add to your Claude Desktop config:
 Say hello to someone.
 
 **Parameters:**
+
 - `name` (string, optional): Name to greet. Default: "World"
 
 ## Development