scaffold: add lib and worker templates; harness: round-robin templates, fewer dev/test soft-fails

Scaffold:
- Add lib template (library + vitest), worker template (Effect Queue)
- TEMPLATES now basic, service, cli, http-server, lib, worker

Lifecycle harness:
- Template selection: round-robin by scenario index (even distribution)
- Skip bun run dev for http-server and when code is broken
- Run bun run test with expectFailure when code is broken
- Add soft-fail patterns for vitest/test failures
- Extract isCodeCurrentlyBroken to code-broken.ts with tests
- Output checks, list parsing, scaffold-validate, report-summary modules and tests

ep-cli:
- PatternNotFoundError for ep show when pattern not found; exit non-zero
- Login/auth docs and EP_AUTH_URL support

API server and docs updates.

Made-with: Cursor

Author: PaulJPhilp

docs/README.md

@@ -43,6 +43,7 @@ Development workflows, testing, and CI/CD.
 - **[PUBLISHING_PIPELINE.md](./development/PUBLISHING_PIPELINE.md)** -
   Content publishing workflow
 - **[TESTING.md](./development/TESTING.md)** - Testing guide
+- **[SCAFFOLD_USER_GUIDE.md](./development/SCAFFOLD_USER_GUIDE.md)** - Scaffold a new Effect test project (templates, tools, next steps)
 
 ### [Jobs To Be Done](./jobs-to-be-done/)
 

docs/development/SCAFFOLD_USER_GUIDE.md

@@ -0,0 +1,134 @@
+# Scaffold script user guide
+
+The scaffold script creates a new TypeScript/Effect project with a chosen template and optionally installs Effect Patterns rules for AI tools (Cursor, VS Code, Windsurf, Agents). Run it from the **Effect-Patterns repository root**.
+
+**Quick start:**
+
+```bash
+bun run scaffold my-app --template service
+```
+
+---
+
+## Prerequisites
+
+- **Bun** — used to run the script and to install dependencies in the new project
+- **Git** — the script runs `git init` and an initial commit
+- **Effect Patterns repo** — run the command from the repo root (where `package.json` and `scripts/` live)
+
+Rule installation (`ep install add --tool <tool>`) may call the Effect Patterns API. If the API is unavailable or not configured, the script continues and reports which tools failed; you can retry later from the new project directory.
+
+---
+
+## How to run
+
+**Command:** `bun run scaffold` (defined in the root `package.json`).
+
+### Interactive mode
+
+No arguments: the script prompts for project name, template, and tools.
+
+```bash
+bun run scaffold
+```
+
+### Non-interactive mode
+
+Pass the project name; optionally pass `--template` and one or more `--tool` options.
+
+```bash
+bun run scaffold my-app
+```
+
+- Uses the **basic** template and installs rules for **all** tools.
+
+```bash
+bun run scaffold my-app --template service
+```
+
+- Uses the **service** template and installs rules for all tools.
+
+```bash
+bun run scaffold my-app --template cli --tool cursor --tool agents
+```
+
+- Uses the **cli** template and installs rules only for Cursor and Agents.
+
+---
+
+## Options
+
+| Option | Description |
+|--------|-------------|
+| `--template <name>` | Project template. One of: `basic`, `service`, `cli`, `http-server`. |
+| `--tool <name>` | Tool to install Effect Patterns rules for; repeatable. Values: `agents`, `cursor`, `vscode`, `windsurf`. |
+
+If you provide a project name but omit `--tool`, the script installs rules for all four tools.
+
+---
+
+## Templates
+
+| Template | Description |
+|----------|-------------|
+| **basic** | Minimal Effect app: `Console.log` and `Effect.runPromise`. |
+| **service** | Effect.Service example (Greeter) plus a Vitest test. |
+| **cli** | @effect/cli app with a `hello` subcommand. |
+| **http-server** | @effect/platform HTTP server with a `/health` route. |
+
+Each template adds the right dependencies and starter files under `src/`.
+
+---
+
+## Output location and contents
+
+**Directory:** Projects are created under `$HOME/Projects/TestRepos/<project-name>` (e.g. `~/Projects/TestRepos/my-app`). There is no option to change this path.
+
+**Steps the script performs:**
+
+1. Create the project directory and `src/`
+2. Write `package.json` (template-specific dependencies), `tsconfig.json`, `.gitignore`
+3. Write template files into `src/`
+4. Run `bun install`
+5. Run `git init` and create an initial commit
+6. For each selected tool, run `ep install add --tool <tool>` (using the repo’s ep-cli)
+
+If `ep install add` fails for a tool (e.g. API unavailable), the script prints a warning and continues. The final summary includes a retry command for failed tools.
+
+---
+
+## Environment variables
+
+| Variable | Purpose |
+|----------|---------|
+| **HOME** | Used to build the output path `$HOME/Projects/TestRepos/<name>`. If unset, the script falls back to `/Users/paul`. |
+| **EFFECT_PATTERNS_API_URL** | If set, passed to the `ep install add` subprocess (e.g. for a local or staging API). Rule installation may fail if the API is unreachable or not configured. |
+
+---
+
+## Troubleshooting
+
+**"Directory already exists"** — The script will not overwrite an existing directory. Use a different project name or remove the existing directory.
+
+**"Unknown template" / "Unknown tool"** — Use only the supported values:
+- Templates: `basic`, `service`, `cli`, `http-server`
+- Tools: `agents`, `cursor`, `vscode`, `windsurf`
+
+**ep install failed** — The script prints a warning and a retry command, e.g. `cd <projectDir> && bun run <ep-cli-entry> install add --tool <tool>`. You may need to configure an API key or `EFFECT_PATTERNS_API_URL`; see the [ep-cli README](../../packages/ep-cli/README.md) and project [MCP_CONFIG.md](../../MCP_CONFIG.md) for API and key setup.
+
+---
+
+## Next steps
+
+After scaffolding:
+
+```bash
+cd ~/Projects/TestRepos/<project-name>
+bun run dev
+```
+
+For the **service** template, run tests with:
+
+```bash
+bun run test
+```

packages/api-server/app/api/patterns/[id]/route.ts

@@ -12,22 +12,16 @@ import { getPatternByIdDb } from "@effect-patterns/toolkit";
 import { Effect } from "effect";
 import { type NextRequest, NextResponse } from "next/server";
 import { randomUUID } from "crypto";
-import {
-    validateApiKey,
-} from "../../../../src/auth/apiKey";
 import { PatternNotFoundError } from "../../../../src/errors";
 import { errorHandler, errorToResponse } from "../../../../src/server/errorHandler";
 import { runWithRuntime } from "../../../../src/server/init";
 import { getPatternByIdFallback } from "../../../../src/server/pattern-fallback";
 import { TracingService } from "../../../../src/tracing/otlpLayer";
 
 // Handler implementation with automatic span creation via Effect.fn
-const handleGetPattern = (request: NextRequest, patternId: string) => Effect.gen(function* () {
+const handleGetPattern = (_request: NextRequest, patternId: string) => Effect.gen(function* () {
   const tracing = yield* TracingService;
 
-  // Validate API key
-  yield* validateApiKey(request);
-
   // Annotate span with pattern ID
   yield* Effect.annotateCurrentSpan({
     patternId,

packages/api-server/app/api/patterns/route.ts

@@ -12,9 +12,6 @@ import { searchPatternsDb, type Pattern } from "@effect-patterns/toolkit";
 import { Effect } from "effect";
 import { type NextRequest, NextResponse } from "next/server";
 import { randomUUID } from "crypto";
-import {
-  validateApiKey,
-} from "../../../src/auth/apiKey";
 import { ValidationError } from "../../../src/errors";
 import { errorHandler, errorToResponse } from "../../../src/server/errorHandler";
 import { runWithRuntime } from "../../../src/server/init";
@@ -45,9 +42,6 @@ const handleSearchPatterns = Effect.fn("search-patterns")(function* (
 ) {
   const tracing = yield* TracingService;
 
-  // Validate API key
-  yield* validateApiKey(request);
-
   // Extract query parameters
   const { searchParams } = new URL(request.url);
   const query = searchParams.get("q") || undefined;

packages/ep-cli/README.md

@@ -127,6 +127,7 @@ If stdin is empty, command fails with:
 | `PATTERN_API_KEY` | API key sent as `x-api-key` to pattern API | unset |
 | `EP_API_KEY_FILE` | File containing API key text | unset |
 | `EP_CONFIG_FILE` | Path to JSON config (expects `{"apiKey":"..."}`) | `${XDG_CONFIG_HOME:-~/.config}/ep-cli/config.json` |
+| `EP_AUTH_URL` | Base URL for `ep login` browser auth (use if default returns 404) | `https://effecttalk.dev/cli/auth` |
 | `EFFECT_PATTERNS_API_URL` | Base URL for pattern API | `https://effect-patterns-mcp-server-buddybuilder.vercel.app` |
 | `EP_API_TIMEOUT_MS` | Request timeout in ms | `10000` |
 | `EP_INSTALLED_STATE_FILE` | Installed-rules state file path override | `${XDG_STATE_HOME:-~/.local/state}/ep-cli/installed-rules.json` |
@@ -577,6 +578,21 @@ Other install targets:
 
 ## Troubleshooting
 
+### `ep login` opens a page that returns 404
+
+Symptom:
+
+- Browser opens `https://effecttalk.dev/cli/auth` but the page shows "404 Not Found".
+
+The EffectTalk auth page may not be deployed yet. Use manual API key setup instead:
+
+1. Obtain an API key from your Effect Patterns / API provider.
+2. Set `PATTERN_API_KEY` in your environment, or
+3. Put the key in a file and set `EP_API_KEY_FILE` to its path, or
+4. Write `{"apiKey":"your-key"}` to `~/.config/ep-cli/config.json` (or set `EP_CONFIG_FILE` to another path).
+
+Then run `ep list` or `ep search …` as usual.
+
 ### Unauthorized (401)
 
 Symptom:

packages/ep-cli/src/__tests__/cli-contract.test.ts

@@ -148,4 +148,12 @@ describe("ep-cli stream and machine-mode contracts", () => {
     expect(result.status).toBe(1);
     expect(result.stderr).toContain("No API key was provided on stdin");
   });
+
+  it("exits non-zero and prints not found when pattern id does not exist", () => {
+    const result = runCli(["show", "nonexistent-pattern-id-xyz"]);
+
+    expect(result.status).not.toBe(0);
+    const combined = `${result.stdout}\n${result.stderr}`;
+    expect(combined).toMatch(/not found/i);
+  });
 });

packages/ep-cli/src/__tests__/login-command.test.ts

@@ -4,10 +4,12 @@
 
 import { afterEach, beforeEach, describe, expect, it } from "vitest";
 import { Effect } from "effect";
-import { existsSync, mkdirSync, readFileSync, rmSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, rmSync, statSync } from "node:fs";
+import http from "node:http";
 import path from "node:path";
 import { tmpdir } from "node:os";
 import { resolveConfigPath, writeConfig } from "../services/config/writer.js";
+import { closeServer, tryListen, waitForCallback } from "../commands/login-command.js";
 
 describe("resolveConfigPath", () => {
   const originalEnv = { ...process.env };
@@ -85,6 +87,26 @@ describe("writeConfig", () => {
     expect(existsSync(nestedPath)).toBe(true);
   });
 
+  it("sets config file permissions to 0o600", async () => {
+    const configPath = await Effect.runPromise(
+      writeConfig({ apiKey: "key", email: "e@x.com" })
+    );
+
+    expect(statSync(configPath).mode & 0o777).toBe(0o600);
+  });
+
+  it("creates parent directory with restricted permissions (0o700)", async () => {
+    const nestedPath = path.join(testDir, "restricted-dir", "config.json");
+    process.env.EP_CONFIG_FILE = nestedPath;
+
+    await Effect.runPromise(
+      writeConfig({ apiKey: "key", email: "e@x.com" })
+    );
+
+    const dirMode = statSync(path.dirname(nestedPath)).mode & 0o777;
+    expect(dirMode).toBe(0o700);
+  });
+
   it("overwrites existing config", async () => {
     await Effect.runPromise(
       writeConfig({ apiKey: "old-key", email: "old@x.com" })
@@ -99,3 +121,126 @@ describe("writeConfig", () => {
     expect(content.email).toBe("new@x.com");
   });
 });
+
+describe("tryListen", () => {
+  let server: http.Server;
+
+  beforeEach(() => {
+    server = http.createServer();
+  });
+
+  afterEach(async () => {
+    await Effect.runPromise(closeServer(server)).catch(() => {});
+  });
+
+  it("succeeds on a free port", async () => {
+    const port = await Effect.runPromise(tryListen(server, 0));
+    expect(port).toBe(0);
+  });
+
+  it("fails when port is already in use", async () => {
+    const blocker = http.createServer();
+    // Listen on OS-assigned port first
+    await new Promise<void>((resolve) => {
+      blocker.listen(0, "127.0.0.1", resolve);
+    });
+    const usedPort = (blocker.address() as { port: number }).port;
+
+    const result = await Effect.runPromise(
+      tryListen(server, usedPort).pipe(Effect.either)
+    );
+
+    expect(result._tag).toBe("Left");
+
+    await new Promise<void>((resolve) => {
+      blocker.close(() => resolve());
+    });
+  });
+});
+
+describe("waitForCallback", () => {
+  let server: http.Server;
+  let port: number;
+  const state = "test-state-abc";
+
+  beforeEach(async () => {
+    server = http.createServer();
+    await new Promise<void>((resolve) => {
+      server.listen(0, "127.0.0.1", resolve);
+    });
+    port = (server.address() as { port: number }).port;
+  });
+
+  afterEach(async () => {
+    await Effect.runPromise(closeServer(server)).catch(() => {});
+  });
+
+  it("returns apiKey and email on valid callback", async () => {
+    const resultPromise = Effect.runPromise(waitForCallback(server, port, state));
+
+    // Send a valid callback
+    await fetch(
+      `http://127.0.0.1:${port}/callback?state=${state}&apiKey=key-123&email=test@example.com`
+    );
+
+    const result = await resultPromise;
+    expect(result.apiKey).toBe("key-123");
+    expect(result.email).toBe("test@example.com");
+  });
+
+  it("returns 404 for non-callback paths", async () => {
+    // Start waiting (don't await — it blocks until callback)
+    const resultPromise = Effect.runPromise(waitForCallback(server, port, state));
+
+    const response = await fetch(`http://127.0.0.1:${port}/other`);
+    expect(response.status).toBe(404);
+
+    // Now send valid callback to unblock
+    await fetch(
+      `http://127.0.0.1:${port}/callback?state=${state}&apiKey=key-123&email=e@x.com`
+    );
+    await resultPromise;
+  });
+
+  it("returns 403 for invalid state", async () => {
+    const resultPromise = Effect.runPromise(waitForCallback(server, port, state));
+
+    const response = await fetch(
+      `http://127.0.0.1:${port}/callback?state=wrong-state&apiKey=key-123`
+    );
+    expect(response.status).toBe(403);
+
+    // Clean up by sending valid callback
+    await fetch(
+      `http://127.0.0.1:${port}/callback?state=${state}&apiKey=key-123&email=e@x.com`
+    );
+    await resultPromise;
+  });
+
+  it("fails when apiKey is missing", async () => {
+    const resultPromise = Effect.runPromise(
+      waitForCallback(server, port, state).pipe(Effect.either)
+    );
+
+    await fetch(`http://127.0.0.1:${port}/callback?state=${state}`);
+
+    const either = await resultPromise;
+    expect(either._tag).toBe("Left");
+  });
+
+  it("returns 409 on duplicate callback after resolution", async () => {
+    const resultPromise = Effect.runPromise(waitForCallback(server, port, state));
+
+    // First valid callback
+    await fetch(
+      `http://127.0.0.1:${port}/callback?state=${state}&apiKey=key-123&email=e@x.com`
+    );
+    await resultPromise;
+
+    // Second callback should get 409
+    const response = await fetch(
+      `http://127.0.0.1:${port}/callback?state=${state}&apiKey=key-456&email=e2@x.com`
+    );
+    expect(response.status).toBe(409);
+  });
+});