@outfitter/presets 0.2.1 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@outfitter/presets",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Scaffold presets and shared dependency versions for Outfitter projects",
   "keywords": [
     "outfitter",
@@ -32,7 +32,7 @@
     "./package.json": "./package.json"
   },
   "scripts": {
-    "build": "cd ../.. && bunup --filter @outfitter/presets",
+    "build": "cd ../.. && bash ./scripts/run-bunup-with-lock.sh bunup --filter @outfitter/presets",
     "clean": "rm -rf dist .turbo",
     "test": "bun test",
     "typecheck": "tsc --noEmit",

package/presets/_base/AGENTS.md.template

@@ -0,0 +1,3 @@
+# AGENTS.md
+
+@CLAUDE.md

package/presets/_base/CLAUDE.md.template

@@ -0,0 +1,35 @@
+# CLAUDE.md
+
+Bun-first TypeScript project. Tests before code. Result types, not exceptions.
+
+## Commands
+
+```bash
+bun run build        # Build the project
+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
+
+Single-package TypeScript project built with Bun.
+
+Handlers are pure functions returning `Result<T, E>`. Write the handler once, test it directly.
+
+## 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`

package/presets/_examples/cli-todo/src/program.ts.template

@@ -0,0 +1,202 @@
+/**
+ * {{projectName}} - CLI program definition
+ *
+ * Demonstrates the v0.5 builder pattern:
+ * - `.input(schema)` for Zod-to-Commander auto-derived flags
+ * - `runHandler()` for the full lifecycle bridge
+ * - `contextFactory` + `hints` passed in one canonical place
+ */
+
+import { command, createCLI } from "@outfitter/cli/command";
+import { runHandler } from "@outfitter/cli/envelope";
+import type { CLIHint } from "@outfitter/contracts";
+import { Result } from "@outfitter/contracts";
+import { createLogger } from "@outfitter/logging";
+import { z } from "zod";
+
+const logger = createLogger({ name: "{{binName}}" });
+
+// =============================================================================
+// Domain Types
+// =============================================================================
+
+interface Todo {
+  readonly id: number;
+  readonly title: string;
+  readonly done: boolean;
+}
+
+/** In-memory store (replace with file/DB in a real app). */
+const store: Todo[] = [];
+let nextId = 1;
+
+// =============================================================================
+// Context
+// =============================================================================
+
+/**
+ * Shared context constructed once per command invocation.
+ * The `.context()` builder method calls this factory with the validated input.
+ */
+interface TodoContext {
+  readonly count: number;
+  readonly pendingCount: number;
+}
+
+async function buildTodoContext(): Promise<TodoContext> {
+  return {
+    count: store.length,
+    pendingCount: store.filter((t) => !t.done).length,
+  };
+}
+
+// =============================================================================
+// Schemas
+// =============================================================================
+
+const addInputSchema = z.object({
+  title: z.string().describe("Title of the todo item"),
+});
+
+const completeInputSchema = z.object({
+  id: z.number().describe("ID of the todo to complete"),
+});
+
+const listInputSchema = z.object({
+  all: z.boolean().default(false).describe("Show completed todos too"),
+});
+
+// =============================================================================
+// Hint Functions
+// =============================================================================
+
+function addHints(
+  _result: unknown,
+  _input: z.infer<typeof addInputSchema>
+): CLIHint[] {
+  return [
+    { description: "List your todos", command: "{{binName}} list" },
+    {
+      description: "Add another todo",
+      command: `{{binName}} add --title "next task"`,
+    },
+  ];
+}
+
+function completeHints(
+  _result: unknown,
+  _input: z.infer<typeof completeInputSchema>
+): CLIHint[] {
+  return [
+    { description: "List remaining todos", command: "{{binName}} list" },
+    {
+      description: "Show all including completed",
+      command: "{{binName}} list --all",
+    },
+  ];
+}
+
+// =============================================================================
+// CLI Program
+// =============================================================================
+
+export const program = createCLI({
+  name: "{{binName}}",
+  version: "{{version}}",
+  description: "{{description}}",
+});
+
+/**
+ * `add` — Create a new todo item.
+ *
+ * Uses `.input()` to auto-derive `--title` from the Zod schema and
+ * `runHandler()` to provide context + hints in one place.
+ */
+program.register(
+  command("add")
+    .description("Add a new todo item")
+    .input(addInputSchema)
+    .action(async ({ input }) => {
+      await runHandler({
+        command: "add",
+        input,
+        format: "json",
+        contextFactory: buildTodoContext,
+        hints: addHints,
+        handler: async (inp, context) => {
+          const todo: Todo = { id: nextId++, title: inp.title, done: false };
+          store.push(todo);
+          logger.info(`Added todo #${todo.id}: ${todo.title}`);
+          return Result.ok({
+            id: todo.id,
+            title: todo.title,
+            pending: context.pendingCount + 1,
+          });
+        },
+      });
+    })
+);
+
+/**
+ * `list` — Show current todo items.
+ *
+ * Uses `.input()` with a boolean flag auto-derived from the schema.
+ */
+program.register(
+  command("list")
+    .description("List todo items")
+    .input(listInputSchema)
+    .action(async ({ input }) => {
+      await runHandler({
+        command: "list",
+        input,
+        format: "json",
+        contextFactory: buildTodoContext,
+        handler: async (inp, context) => {
+          const items = inp.all ? store : store.filter((t) => !t.done);
+          return Result.ok({
+            items: items.map((t) => ({
+              id: t.id,
+              title: t.title,
+              done: t.done,
+            })),
+            total: context.count,
+            pending: context.pendingCount,
+          });
+        },
+      });
+    })
+);
+
+/**
+ * `complete` — Mark a todo as done.
+ *
+ * Uses `.input()` with a number flag and delegates hints/error handling
+ * through `runHandler()`.
+ */
+program.register(
+  command("complete")
+    .description("Mark a todo as completed")
+    .input(completeInputSchema)
+    .action(async ({ input }) => {
+      await runHandler({
+        command: "complete",
+        input,
+        format: "json",
+        contextFactory: buildTodoContext,
+        hints: completeHints,
+        onError: () => [
+          { description: "List available todos", command: "{{binName}} list" },
+        ],
+        handler: async (inp) => {
+          const todo = store.find((t) => t.id === inp.id);
+          if (!todo) {
+            return Result.err(new Error(`Todo #${inp.id} not found`));
+          }
+          (todo as { done: boolean }).done = true;
+          logger.info(`Completed todo #${todo.id}: ${todo.title}`);
+          return Result.ok({ id: todo.id, title: todo.title, done: true });
+        },
+      });
+    })
+);

package/presets/_examples/mcp-files/src/mcp.ts.template

@@ -0,0 +1,181 @@
+/**
+ * {{projectName}} - MCP server definition
+ *
+ * Demonstrates v0.5 MCP patterns:
+ * - `defineResource()` for static resources
+ * - `defineResourceTemplate()` with Zod schema validation for parameterized resources
+ * - `defineTool()` for file operations with Result patterns
+ */
+
+import { Result } from "@outfitter/contracts";
+import {
+  createMcpServer,
+  connectStdio,
+  defineResource,
+  defineResourceTemplate,
+  defineTool,
+} from "@outfitter/mcp";
+import { z } from "zod";
+
+// =============================================================================
+// In-memory file store (replace with real filesystem in production)
+// =============================================================================
+
+const files = new Map<string, string>([
+  ["README.md", "# {{projectName}}\n\nWelcome to the project."],
+  [
+    "config.json",
+    JSON.stringify({ name: "{{binName}}", version: "{{version}}" }, null, 2),
+  ],
+]);
+
+// =============================================================================
+// Resources — Static
+// =============================================================================
+
+/**
+ * List all known files as a static resource.
+ * Clients can read this resource to discover available files.
+ */
+const fileListResource = defineResource({
+  uri: "files:///index",
+  name: "File Index",
+  description: "List of all available files in the workspace",
+  mimeType: "application/json",
+  handler: async (_uri, ctx) => {
+    ctx.logger.info("Listing files", { count: files.size });
+    const listing = [...files.keys()].map((name) => ({
+      name,
+      size: files.get(name)?.length ?? 0,
+    }));
+    return Result.ok([{ uri: _uri, text: JSON.stringify(listing, null, 2) }]);
+  },
+});
+
+// =============================================================================
+// Resources — Parameterized (Templates)
+// =============================================================================
+
+/**
+ * Read a file by name using a URI template.
+ * Uses `defineResourceTemplate()` with Zod schema validation
+ * for the `filename` parameter.
+ */
+const fileContentTemplate = defineResourceTemplate({
+  uriTemplate: "files:///{filename}",
+  name: "File Content",
+  description: "Read the content of a specific file",
+  mimeType: "text/plain",
+  paramSchema: z.object({
+    filename: z.string().describe("Name of the file to read"),
+  }),
+  handler: async (uri, params, ctx) => {
+    const { filename } = params as { filename: string };
+    ctx.logger.info("Reading file", { filename });
+
+    const content = files.get(filename);
+    if (content === undefined) {
+      return Result.err(new Error(`File not found: ${filename}`));
+    }
+
+    return Result.ok([{ uri, text: content }]);
+  },
+});
+
+// =============================================================================
+// Tools — File Operations
+// =============================================================================
+
+/**
+ * Write content to a file.
+ * Demonstrates `defineTool()` with a Zod input schema and Result return.
+ */
+const writeFileTool = defineTool({
+  name: "write_file",
+  description: "Write content to a file (creates or overwrites)",
+  inputSchema: z.object({
+    filename: z.string().describe("Name of the file to write"),
+    content: z.string().describe("Content to write to the file"),
+  }),
+  handler: async (input, ctx) => {
+    ctx.logger.info("Writing file", { filename: input.filename });
+    const existed = files.has(input.filename);
+    files.set(input.filename, input.content);
+    return Result.ok({
+      filename: input.filename,
+      action: existed ? "updated" : "created",
+      size: input.content.length,
+    });
+  },
+});
+
+/**
+ * Delete a file.
+ * Shows error handling with Result.err for missing files.
+ */
+const deleteFileTool = defineTool({
+  name: "delete_file",
+  description: "Delete a file from the workspace",
+  inputSchema: z.object({
+    filename: z.string().describe("Name of the file to delete"),
+  }),
+  handler: async (input, ctx) => {
+    ctx.logger.info("Deleting file", { filename: input.filename });
+    if (!files.has(input.filename)) {
+      return Result.err(new Error(`File not found: ${input.filename}`));
+    }
+    files.delete(input.filename);
+    return Result.ok({ filename: input.filename, deleted: true });
+  },
+});
+
+/**
+ * Search files by content pattern.
+ * Demonstrates a read-only tool that queries the file store.
+ */
+const searchFilesTool = defineTool({
+  name: "search_files",
+  description: "Search for files containing a text pattern",
+  inputSchema: z.object({
+    pattern: z.string().describe("Text pattern to search for"),
+  }),
+  handler: async (input, ctx) => {
+    ctx.logger.info("Searching files", { pattern: input.pattern });
+    const matches: Array<{ filename: string; lineCount: number }> = [];
+    for (const [name, content] of files) {
+      if (content.includes(input.pattern)) {
+        matches.push({ filename: name, lineCount: content.split("\n").length });
+      }
+    }
+    return Result.ok({
+      pattern: input.pattern,
+      matches,
+      total: matches.length,
+    });
+  },
+});
+
+// =============================================================================
+// Server Setup
+// =============================================================================
+
+const server = createMcpServer({
+  name: "{{binName}}",
+  version: "{{version}}",
+});
+
+// Register resources
+server.registerResource(fileListResource);
+server.registerResourceTemplate(fileContentTemplate);
+
+// Register tools
+server.registerTool(writeFileTool);
+server.registerTool(deleteFileTool);
+server.registerTool(searchFilesTool);
+
+export { server };
+
+/** Start the MCP server over stdio transport. */
+export async function startServer(): Promise<void> {
+  await connectStdio(server);
+}

package/presets/basic/README.md.template

@@ -0,0 +1,22 @@
+# {{projectName}}
+
+{{description}}
+
+## Getting Started
+
+```bash
+bun install
+bun run dev
+```
+
+## Development
+
+```bash
+bun test          # Run tests
+bun run build     # Build for production
+bun run typecheck # Type checking
+```
+
+## License
+
+MIT

package/presets/basic/package.json.template

@@ -1,39 +1,43 @@
 {
-	"name": "{{packageName}}",
-	"version": "{{version}}",
-	"description": "{{description}}",
-	"type": "module",
-	"main": "./dist/index.js",
-	"types": "./dist/index.d.ts",
-	"files": [
-		"dist"
-	],
-	"exports": {
-		".": {
-			"import": {
-				"types": "./dist/index.d.ts",
-				"default": "./dist/index.js"
-			}
-		}
-	},
-	"scripts": {
-		"build": "bun build ./src/index.ts --outdir=dist --format=esm",
-		"dev": "bun run --watch src/index.ts",
-		"test": "bun test",
-		"test:watch": "bun test --watch",
-		"typecheck": "tsc --noEmit",
-		"check": "ultracite check",
-		"verify:ci": "bun run typecheck && bun run check && bun run build && bun run test",
-		"lint": "oxlint .",
-		"lint:fix": "oxlint --fix .",
-		"format": "oxfmt --write .",
-		"clean:artifacts": "rm -rf dist .turbo",
-		"clean": "rm -rf dist"
-	},
-	"devDependencies": {},
-	"engines": {
-		"bun": ">=1.3.10"
-	},
-	"keywords": [],
-	"license": "MIT"
+  "name": "{{packageName}}",
+  "version": "{{version}}",
+  "description": "{{description}}",
+  "keywords": [],
+  "license": "MIT",
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
+    }
+  },
+  "scripts": {
+    "build": "bun build ./src/index.ts --outdir=dist --format=esm && tsc --emitDeclarationOnly",
+    "dev": "bun run --watch src/index.ts",
+    "test": "bun test",
+    "test:watch": "bun test --watch",
+    "typecheck": "tsc --noEmit",
+    "check": "ultracite check",
+    "verify:ci": "bun run typecheck && bun run check && bun run build && bun run test",
+    "lint": "oxlint .",
+    "lint:fix": "oxlint --fix .",
+    "format": "oxfmt --write .",
+    "clean:artifacts": "rm -rf dist .turbo",
+    "clean": "rm -rf dist"
+  },
+  "dependencies": {
+    "@outfitter/contracts": "workspace:*",
+    "zod": "catalog:"
+  },
+  "devDependencies": {},
+  "engines": {
+    "bun": ">=1.3.10"
+  }
 }

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

@@ -0,0 +1,26 @@
+import { describe, expect, test } from "bun:test";
+
+import { createContext } from "@outfitter/contracts";
+
+import { greet } from "./index.js";
+
+describe("greet", () => {
+  const ctx = createContext({ cwd: process.cwd(), env: process.env });
+
+  test("returns greeting for valid input", async () => {
+    const result = await greet({ name: "World" }, ctx);
+
+    expect(result.isOk()).toBe(true);
+    if (result.isErr()) return;
+    expect(result.value.message).toBe("Hello, World!");
+  });
+
+  test("returns validation error for empty name", async () => {
+    const result = await greet({ name: "" }, ctx);
+
+    expect(result.isErr()).toBe(true);
+    if (result.isErr()) {
+      expect(result.error.name).toBe("ValidationError");
+    }
+  });
+});

package/presets/basic/src/index.ts.template

@@ -6,21 +6,38 @@
  * @packageDocumentation
  */
 
-/**
- * Main entry point for {{projectName}}.
- *
- * @example
- * ```typescript
- * import { main } from "{{packageName}}";
- *
- * main();
- * ```
- */
-export function main(): void {
-	console.log("Hello from {{projectName}}!");
+import {
+  type HandlerContext,
+  Result,
+  ValidationError,
+} from "@outfitter/contracts";
+import { type ZodType, z } from "zod";
+
+export interface GreetingInput {
+  readonly name: string;
 }
 
-// Run if executed directly
-if (import.meta.main) {
-	main();
+export const greetingInputSchema: ZodType<GreetingInput> = z.object({
+  name: z.string().min(1, "name is required"),
+});
+
+export interface Greeting {
+  readonly message: string;
+}
+
+export async function greet(
+  input: unknown,
+  ctx: HandlerContext
+): Promise<Result<Greeting, ValidationError>> {
+  const parsed = greetingInputSchema.safeParse(input);
+  if (!parsed.success) {
+    return Result.err(
+      new ValidationError({ message: "Invalid input", field: "name" })
+    );
+  }
+
+  ctx.logger.info(`Greeting ${parsed.data.name}`, {
+    requestId: ctx.requestId,
+  });
+  return Result.ok({ message: `Hello, ${parsed.data.name}!` });
 }