@outfitter/presets 0.2.1 → 0.3.0

package/presets/basic/tsconfig.json.template

@@ -1,34 +1,33 @@
 {
-	"$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,
+    "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", "src/**/*.test.ts"]
 }

package/presets/cli/CLAUDE.md.template

@@ -0,0 +1,60 @@
+# CLAUDE.md
+
+Bun-first TypeScript CLI. Tests before code. Result types, not exceptions.
+
+## Commands
+
+```bash
+bun run build        # Build CLI + 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
+
+CLI application built with Commander and `@outfitter/cli`.
+
+### Project Structure
+
+- `src/cli.ts` — Entry point, creates and runs the program
+- `src/program.ts` — Command registration and wiring
+- `src/commands/` — Command handlers (pure functions returning `Result<T, E>`)
+- `src/types.ts` — Zod schemas and TypeScript interfaces
+
+### Handler Contract
+
+All domain logic uses handlers returning `Result<T, E>`:
+
+```typescript
+function handler(
+  input: Input,
+  ctx: HandlerContext
+): Promise<Result<Output, Error>>;
+```
+
+CLI commands are thin adapters over shared handlers. Use `runHandler()` from `@outfitter/cli/envelope` to wrap handler results in output envelopes.
+
+### Adding a Command
+
+1. Define types and Zod schema in `src/types.ts`
+2. Create handler in `src/commands/<name>.ts` returning `Result<T, E>`
+3. Wire command in `src/program.ts` using the CommandBuilder pattern
+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
+- Files: `src/*.test.ts`
+- Run: `bun test` or `bun run test`

package/presets/cli/README.md.template

@@ -5,7 +5,11 @@
 ## Installation
 
 ```bash
-bun add {{packageName}}
+# Run directly
+bunx {{packageName}}
+
+# Or install globally
+bun add -g {{packageName}}
 ```
 
 ## Usage

package/presets/cli/package.json.template

@@ -1,46 +1,49 @@
 {
-	"name": "{{packageName}}",
-	"version": "{{version}}",
-	"description": "{{description}}",
-	"type": "module",
-	"bin": {
-		"{{binName}}": "./dist/cli.js"
-	},
-	"main": "./dist/index.js",
-	"types": "./dist/index.d.ts",
-	"exports": {
-		".": {
-			"types": "./dist/index.d.ts",
-			"import": "./dist/index.js"
-		}
-	},
-	"scripts": {
-		"build": "bun build src/cli.ts --outdir dist --target bun && bun build src/index.ts --outdir dist --target bun --sourcemap",
-		"dev": "bun --watch src/cli.ts",
-		"typecheck": "tsc --noEmit",
-		"check": "ultracite check",
-		"verify:ci": "bun run typecheck && bun run check && bun run build && bun run test",
-		"test": "bun test",
-		"test:watch": "bun test --watch",
-		"lint": "oxlint .",
-		"lint:fix": "oxlint --fix .",
-		"format": "oxfmt --write .",
-		"clean:artifacts": "rm -rf dist .turbo"
-	},
-	"dependencies": {
-		"@outfitter/contracts": "workspace:*",
-		"@outfitter/types": "workspace:*",
-		"@outfitter/cli": "workspace:*",
-		"@outfitter/logging": "workspace:*",
-		"commander": "^14.0.2"
-	},
-	"devDependencies": {},
-	"outfitter": {
-		"template": {
-			"kind": "runnable",
-			"placement": "apps",
-			"surfaces": ["cli"]
-		}
-	},
-	"license": "MIT"
+  "name": "{{packageName}}",
+  "version": "{{version}}",
+  "description": "{{description}}",
+  "license": "MIT",
+  "bin": {
+    "{{binName}}": "./dist/cli.js"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "bun build src/cli.ts --outdir dist --target bun && bun build src/index.ts --outdir dist --target bun --sourcemap",
+    "dev": "bun --watch src/cli.ts",
+    "typecheck": "tsc --noEmit",
+    "check": "ultracite check",
+    "verify:ci": "bun run typecheck && bun run check && bun run build && bun run test",
+    "test": "bun test",
+    "test:watch": "bun test --watch",
+    "lint": "oxlint .",
+    "lint:fix": "oxlint --fix .",
+    "format": "oxfmt --write .",
+    "clean:artifacts": "rm -rf dist .turbo"
+  },
+  "dependencies": {
+    "@outfitter/cli": "workspace:*",
+    "@outfitter/contracts": "workspace:*",
+    "@outfitter/logging": "workspace:*",
+    "@outfitter/types": "workspace:*",
+    "commander": "catalog:",
+    "zod": "catalog:"
+  },
+  "devDependencies": {},
+  "outfitter": {
+    "template": {
+      "kind": "runnable",
+      "placement": "apps",
+      "surfaces": [
+        "cli"
+      ]
+    }
+  }
 }

package/presets/cli/src/commands/hello.ts.template

@@ -0,0 +1,26 @@
+import {
+  Result,
+  ValidationError,
+  type HandlerContext,
+} from "@outfitter/contracts";
+import { createLogger } from "@outfitter/logging";
+
+import { greetingInputSchema, type GreetingOutput } from "../types.js";
+
+const logger = createLogger({ name: "{{binName}}" });
+
+export async function greet(
+  input: unknown,
+  ctx: HandlerContext
+): Promise<Result<GreetingOutput, ValidationError>> {
+  const parsed = greetingInputSchema.safeParse(input);
+  if (!parsed.success) {
+    return Result.err(
+      new ValidationError({ message: "Invalid greeting input", field: "name" })
+    );
+  }
+
+  const message = `Hello, ${parsed.data.name}!`;
+  logger.info(message, { requestId: ctx.requestId });
+  return Result.ok({ message });
+}

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

@@ -0,0 +1,38 @@
+import { describe, expect, test } from "bun:test";
+
+import { createContext } from "@outfitter/contracts";
+
+import { greet } from "./commands/hello.js";
+import { program } from "./index.js";
+
+describe("program", () => {
+  test("registers the hello command", () => {
+    expect(program.program.name()).toBe("{{binName}}");
+
+    const registered = program.program.commands.some(
+      (cmd) => cmd.name() === "hello"
+    );
+    expect(registered).toBe(true);
+  });
+});
+
+describe("greet", () => {
+  test("returns greeting for valid input", async () => {
+    const ctx = createContext({ cwd: process.cwd(), env: process.env });
+    const result = await greet({ name: "Outfitter" }, 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 ctx = createContext({ cwd: process.cwd(), env: process.env });
+    const result = await greet({ name: "" }, ctx);
+
+    expect(result.isErr()).toBe(true);
+    if (result.isErr()) {
+      expect(result.error.name).toBe("ValidationError");
+    }
+  });
+});

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

@@ -5,3 +5,5 @@
  */
 
 export { program } from "./program.js";
+export { greet } from "./commands/hello.js";
+export type { GreetingInput, GreetingOutput } from "./types.js";

package/presets/cli/src/program.ts.template

@@ -3,29 +3,27 @@
  */
 
 import { command, createCLI } from "@outfitter/cli/command";
-import { verbosePreset } from "@outfitter/cli/flags";
-import { createLogger } from "@outfitter/logging";
+import { runHandler } from "@outfitter/cli/envelope";
+import { createContext } from "@outfitter/contracts";
 
-const logger = createLogger({ name: "{{binName}}" });
+import { greet } from "./commands/hello.js";
 
 export const program = createCLI({
-	name: "{{binName}}",
-	version: "{{version}}",
-	description: "{{description}}",
+  name: "{{binName}}",
+  version: "{{version}}",
+  description: "{{description}}",
 });
 
-const verbose = verbosePreset();
-
 program.register(
-	command("hello [name]")
-		.description("Say hello")
-		.preset(verbose)
-		.action<{ verbose: boolean }>(async ({ args, flags }) => {
-			const { verbose: isVerbose } = verbose.resolve(flags);
-			const name = args[0] ?? "World";
-			logger.info(`Hello, ${name}!`);
-			if (isVerbose) {
-				logger.debug("Running in verbose mode");
-			}
-		}),
+  command("hello [name]")
+    .description("Say hello")
+    .action(async ({ args }) => {
+      await runHandler({
+        command: "hello",
+        input: { name: args[0] ?? "World" },
+        contextFactory: () =>
+          createContext({ cwd: process.cwd(), env: process.env }),
+        handler: greet,
+      });
+    })
 );

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

@@ -0,0 +1,13 @@
+import { type ZodType, z } from "zod";
+
+export interface GreetingInput {
+  readonly name: string;
+}
+
+export const greetingInputSchema: ZodType<GreetingInput> = z.object({
+  name: z.string().min(1, "name is required"),
+});
+
+export interface GreetingOutput {
+  readonly message: string;
+}

package/presets/cli/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/daemon/CLAUDE.md.template

@@ -0,0 +1,53 @@
+# CLAUDE.md
+
+Bun-first TypeScript daemon. Tests before code. Result types, not exceptions.
+
+## Commands
+
+```bash
+bun run build        # Build CLI + daemon to dist/
+bun run dev          # Watch mode (foreground)
+bun run dev:daemon   # Watch mode (foreground, explicit)
+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
+
+Background daemon with CLI control interface, built with `@outfitter/daemon` and `@outfitter/cli`.
+
+### Project Structure
+
+- `src/daemon.ts` — Daemon entry point (background process)
+- `src/daemon-main.ts` — Daemon lifecycle and HTTP server (Unix socket)
+- `src/cli.ts` — CLI control commands (start, stop, status)
+- `src/index.ts` — Library re-exports
+
+### Daemon Lifecycle
+
+The daemon uses `acquireDaemonLock()` and `releaseDaemonLock()` from `@outfitter/daemon` with `Bun.serve()` on a Unix socket:
+
+- **start** — Checks liveness, spawns background process (or runs in foreground with `--foreground`)
+- **stop** — Checks liveness, then sends POST to `/shutdown` endpoint
+- **status** — Checks liveness via `isDaemonAlive()`, then fetches `/health` for uptime and version
+
+### Handler Contract
+
+CLI commands and daemon operations use handlers returning `Result<T, E>`. Use structured logging via `@outfitter/logging` instead of `console.error`.
+
+## 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/daemon/README.md.template

@@ -4,12 +4,6 @@
 
 A background daemon with CLI control interface.
 
-## Installation
-
-```bash
-bun add {{packageName}}
-```
-
 ## Usage
 
 ```bash
@@ -52,7 +46,12 @@ Gracefully shuts down the daemon.
 # Install dependencies
 bun install
 
-# Run daemon in foreground
+# Run from source (foreground only — background spawn requires a build)
+bun run src/cli.ts start --foreground
+bun run src/cli.ts status
+bun run src/cli.ts stop
+
+# Run daemon in foreground (via dev script)
 bun run dev
 
 # Build

package/presets/daemon/package.json.template

@@ -1,49 +1,52 @@
 {
-	"name": "{{packageName}}",
-	"version": "{{version}}",
-	"description": "{{description}}",
-	"type": "module",
-	"bin": {
-		"{{binName}}": "./dist/cli.js",
-		"{{binName}}d": "./dist/daemon.js"
-	},
-	"main": "./dist/index.js",
-	"types": "./dist/index.d.ts",
-	"exports": {
-		".": {
-			"types": "./dist/index.d.ts",
-			"import": "./dist/index.js"
-		}
-	},
-	"scripts": {
-		"build": "bun build src/cli.ts src/daemon.ts --outdir dist --target bun && bun build src/index.ts --outdir dist --target bun --sourcemap",
-		"dev": "bun --watch src/daemon.ts -- --foreground",
-		"dev:daemon": "bun --watch src/daemon.ts -- --foreground",
-		"typecheck": "tsc --noEmit",
-		"check": "ultracite check",
-		"verify:ci": "bun run typecheck && bun run check && bun run build && bun run test",
-		"test": "bun test",
-		"test:watch": "bun test --watch",
-		"lint": "oxlint .",
-		"lint:fix": "oxlint --fix .",
-		"format": "oxfmt --write .",
-		"clean:artifacts": "rm -rf dist .turbo"
-	},
-	"dependencies": {
-		"@outfitter/contracts": "workspace:*",
-		"@outfitter/types": "workspace:*",
-		"@outfitter/daemon": "workspace:*",
-		"@outfitter/cli": "workspace:*",
-		"@outfitter/logging": "workspace:*",
-		"commander": "^14.0.2"
-	},
-	"devDependencies": {},
-	"outfitter": {
-		"template": {
-			"kind": "runnable",
-			"placement": "apps",
-			"surfaces": ["cli", "daemon"]
-		}
-	},
-	"license": "MIT"
+  "name": "{{packageName}}",
+  "version": "{{version}}",
+  "description": "{{description}}",
+  "license": "MIT",
+  "bin": {
+    "{{binName}}": "./dist/cli.js",
+    "{{binName}}d": "./dist/daemon.js"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "bun build src/cli.ts src/daemon.ts --outdir dist --target bun && bun build src/index.ts --outdir dist --target bun --sourcemap",
+    "dev": "bun --watch src/daemon.ts -- --foreground",
+    "dev:daemon": "bun --watch src/daemon.ts -- --foreground",
+    "typecheck": "tsc --noEmit",
+    "check": "ultracite check",
+    "verify:ci": "bun run typecheck && bun run check && bun run build && bun run test",
+    "test": "bun test",
+    "test:watch": "bun test --watch",
+    "lint": "oxlint .",
+    "lint:fix": "oxlint --fix .",
+    "format": "oxfmt --write .",
+    "clean:artifacts": "rm -rf dist .turbo"
+  },
+  "dependencies": {
+    "@outfitter/cli": "workspace:*",
+    "@outfitter/contracts": "workspace:*",
+    "@outfitter/daemon": "workspace:*",
+    "@outfitter/logging": "workspace:*",
+    "@outfitter/types": "workspace:*",
+    "commander": "catalog:"
+  },
+  "devDependencies": {},
+  "outfitter": {
+    "template": {
+      "kind": "runnable",
+      "placement": "apps",
+      "surfaces": [
+        "cli",
+        "daemon"
+      ]
+    }
+  }
 }