From c12a23212f6e0584285239b5290f8048b0e2bf90 Mon Sep 17 00:00:00 2001
From: Abdulrahman Magdy
Date: Tue, 20 Oct 2026 17:52:40 +0300
Subject: [PATCH 1/8] Enforce test and env boundaries in generated projects
Adopt rat-stack's lint fence ideas: a local oxlint plugin rejects manual
Effect runners in test files, and no-restricted-imports keeps the
cloudflare:workers env import in server/cloudflare.ts. The generated
AGENTS.md gains a Tests section and a lifecycle rule; decision 0003
records what was adopted and deferred.
---
CHANGELOG.md | 11 +++
docs/decisions/0003-rat-stack-learnings.md | 27 +++++++
.../files/core/llm-crypto.test.ts | 79 ++++++++++---------
templates/base/addon.json | 4 +
templates/base/files/AGENTS.md | 12 +++
.../base/files/root/lint/effect-tests.js | 45 +++++++++++
templates/base/files/root/vite.config.ts | 23 ++++++
7 files changed, 164 insertions(+), 37 deletions(-)
create mode 100644 docs/decisions/0003-rat-stack-learnings.md
create mode 100644 templates/base/files/root/lint/effect-tests.js
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 63162b6..466c83d 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,16 @@
# Changelog
+## Unreleased
+
+### Added
+
+- Generated projects lint two rules that `AGENTS.md` only described before: `Effect.run*` and `ManagedRuntime.make` in test files (a local oxlint plugin, `lint/effect-tests.js`), and importing `env` from `cloudflare:workers` outside `server/cloudflare.ts`.
+- The generated `AGENTS.md` has a Tests section and asks for lifecycles as tagged states. See `docs/decisions/0003-rat-stack-learnings.md`.
+
+### Changed
+
+- The `effect-ai-byok` crypto test uses `it.effect` instead of `Effect.runPromise`.
+
## 0.1.0 (2026-10-19)
First release.
diff --git a/docs/decisions/0003-rat-stack-learnings.md b/docs/decisions/0003-rat-stack-learnings.md
new file mode 100644
index 0000000..f900d3e
--- /dev/null
+++ b/docs/decisions/0003-rat-stack-learnings.md
@@ -0,0 +1,27 @@
+# 0003 — What efforge takes from rat-stack
+
+Date: 2026-10-20. Status: accepted (maintainer).
+
+## Context
+
+[rat-stack](https://github.com/joelhooks/rat-stack) (MIT) is a GitHub template repo with nearly the same stack: Effect 4, Cloudflare Workers, Alchemy v2, Drizzle 1.0 RC, Better Auth, TypeScript 7 with `@effect/tsgo`, and oxlint. It is a working project you trim ("keep or cut"), not a generator, and it makes no support promise. Its main idea is a "fence": rules agents would otherwise only read in `AGENTS.md` are enforced by lint and types instead. We reviewed it at the commit of 2026-10-20.
+
+## Decision
+
+Adopted in the generated project:
+
+- `lint/effect-tests.js`, a local oxlint JS plugin: `Effect.run*` and `ManagedRuntime.make` in `*.test.ts(x)` are errors; tests use `it.effect` and `it.layer`. Adapted from rat-stack's `scripts/oxlint-plugin-effect-tests.ts`. The `effect-ai-byok` crypto test was rewritten to comply.
+- `no-restricted-imports` for `env` from `cloudflare:workers`, switched off for `apps/web/src/server/cloudflare.ts`. The "only cloudflare.ts reads env" rule was documentation; now lint enforces it.
+- `AGENTS.md`: a Tests section (test layers rather than module mocks, check workerd behaviour under `pnpm dev` where a fake can differ) and "model lifecycles as tagged states, not boolean flags".
+
+Not adopted, for now:
+
+- XState v6 and `@xstate/effect`: both are alphas, and Effect plus Cloudflare Workflows and Durable Objects cover what generated apps need. Revisit as an opt-in add-on once they are stable.
+- Cartridge layers that declare their own Alchemy resources (rat-stack's `D1` layer creates the database and provides the binding). It only fits `infra=alchemy` and would split how `efforge add` wires `infra=none` and Alchemy stacks.
+- The Contract to CLI/HTTP/MCP/code-mode projections, Foldkit UI, varlock, and agent hook fences: outside efforge's scope.
+- Generated agent skills (`skills/add-a-capability` and similar): worth doing, but it needs a decision on which agent directories to target.
+
+## Consequences
+
+- A generated project's `pnpm check` fails on manual runners in tests and stray `env` imports. Template tests must use `@effect/vitest`.
+- `lint/effect-tests.js` is plain ESM with no dependency, so it works without `@oxlint/plugins`.
diff --git a/templates/ai/effect-ai-byok/files/core/llm-crypto.test.ts b/templates/ai/effect-ai-byok/files/core/llm-crypto.test.ts
index 8be5d33..f6e5794 100644
--- a/templates/ai/effect-ai-byok/files/core/llm-crypto.test.ts
+++ b/templates/ai/effect-ai-byok/files/core/llm-crypto.test.ts
@@ -1,47 +1,52 @@
+import { describe, expect, it } from "@effect/vitest"
import { Effect } from "effect"
-import { describe, expect, it } from "vitest"
import { decryptSecret, encryptSecret, loadEncryptionKey } from "../src/llm-crypto"
const keyText = btoa(String.fromCharCode(...new Uint8Array(32).fill(7)))
-const run = (effect: Effect.Effect) => Effect.runPromise(effect)
describe("llm-crypto", () => {
- it("round-trips a secret and never stores it in the clear", async () => {
- const key = await run(loadEncryptionKey(keyText))
- const sealed = await run(encryptSecret(key, "sk-secret-1234", "org_1"))
- expect(sealed).not.toContain("sk-secret")
- expect(sealed.startsWith("v1.")).toBe(true)
- expect(await run(decryptSecret(key, sealed, "org_1"))).toBe("sk-secret-1234")
- })
+ it.effect("round-trips a secret and never stores it in the clear", () =>
+ Effect.gen(function* () {
+ const key = yield* loadEncryptionKey(keyText)
+ const sealed = yield* encryptSecret(key, "sk-secret-1234", "org_1")
+ expect(sealed).not.toContain("sk-secret")
+ expect(sealed.startsWith("v1.")).toBe(true)
+ expect(yield* decryptSecret(key, sealed, "org_1")).toBe("sk-secret-1234")
+ }),
+ )
- it("uses a fresh IV each time", async () => {
- const key = await run(loadEncryptionKey(keyText))
- const [a, b] = await Promise.all([
- run(encryptSecret(key, "same", "org_1")),
- run(encryptSecret(key, "same", "org_1")),
- ])
- expect(a).not.toBe(b)
- })
+ it.effect("uses a fresh IV each time", () =>
+ Effect.gen(function* () {
+ const key = yield* loadEncryptionKey(keyText)
+ const [a, b] = yield* Effect.all(
+ [encryptSecret(key, "same", "org_1"), encryptSecret(key, "same", "org_1")],
+ { concurrency: "unbounded" },
+ )
+ expect(a).not.toBe(b)
+ }),
+ )
- it("refuses a ciphertext moved to another organization or tampered with", async () => {
- const key = await run(loadEncryptionKey(keyText))
- const sealed = await run(encryptSecret(key, "sk-secret", "org_1"))
- expect(await run(Effect.flip(decryptSecret(key, sealed, "org_2")))).toMatchObject({
- _tag: "LlmError",
- })
- const parts = sealed.split(".")
- const tampered = `${parts[0]}.${parts[1]}.${btoa("x".repeat(24))}`
- expect(await run(Effect.flip(decryptSecret(key, tampered, "org_1")))).toMatchObject({
- _tag: "LlmError",
- })
- })
+ it.effect("refuses a ciphertext moved to another organization or tampered with", () =>
+ Effect.gen(function* () {
+ const key = yield* loadEncryptionKey(keyText)
+ const sealed = yield* encryptSecret(key, "sk-secret", "org_1")
+ expect(yield* Effect.flip(decryptSecret(key, sealed, "org_2"))).toMatchObject({
+ _tag: "LlmError",
+ })
+ const parts = sealed.split(".")
+ const tampered = `${parts[0]}.${parts[1]}.${btoa("x".repeat(24))}`
+ expect(yield* Effect.flip(decryptSecret(key, tampered, "org_1"))).toMatchObject({
+ _tag: "LlmError",
+ })
+ }),
+ )
- it("rejects a missing, malformed or wrong-sized key at load time", async () => {
- const errors = await Promise.all(
- [undefined, "", "not base64!", btoa("short")].map((bad) =>
- run(Effect.flip(loadEncryptionKey(bad))),
- ),
- )
- for (const error of errors) expect(error).toMatchObject({ _tag: "LlmConfigError" })
- })
+ it.effect("rejects a missing, malformed or wrong-sized key at load time", () =>
+ Effect.gen(function* () {
+ const errors = yield* Effect.forEach([undefined, "", "not base64!", btoa("short")], (bad) =>
+ Effect.flip(loadEncryptionKey(bad)),
+ )
+ for (const error of errors) expect(error).toMatchObject({ _tag: "LlmConfigError" })
+ }),
+ )
})
diff --git a/templates/base/addon.json b/templates/base/addon.json
index 9d978d0..d6d34c5 100644
--- a/templates/base/addon.json
+++ b/templates/base/addon.json
@@ -55,6 +55,10 @@
"path": "files/root/vite.config.ts",
"target": "vite.config.ts"
},
+ {
+ "path": "files/root/lint/effect-tests.js",
+ "target": "lint/effect-tests.js"
+ },
{
"path": "files/web/components.json",
"target": "apps/web/components.json"
diff --git a/templates/base/files/AGENTS.md b/templates/base/files/AGENTS.md
index 9941d62..f9d1b5d 100644
--- a/templates/base/files/AGENTS.md
+++ b/templates/base/files/AGENTS.md
@@ -19,10 +19,22 @@ Rules for AI agents (and humans) working in this repo. Read this before changing
- Failures are tagged errors (`Data.TaggedError`) in the error channel, handled with `Effect.catchTag`.
- Validate data at boundaries (requests, env, storage, third-party responses) with `Schema`.
- Reach Cloudflare bindings (R2, D1, KV, Durable Objects, ...) only through `effect-cf`.
+ `apps/web/src/server/cloudflare.ts` is the one file that imports `env` from `cloudflare:workers`;
+ lint rejects it anywhere else.
- Never wrap an Effect in `try/catch`, and never use `async`/`await` inside `Effect.gen`; use `yield*`.
- Provide layers at entry points only (`runtime.ts`, scripts), not inside library code.
- No `any`. Use `unknown` and narrow it with `Schema` or a type guard.
- Keep `E` types specific; `unknown` or `any` in an error channel is a lint error.
+- Model a multi-step lifecycle (order, invite, job) as a tagged union of states
+ (`Data.TaggedEnum`) and match on it, not as a set of boolean flags.
+
+## Tests
+
+- Write Effect tests with `it.effect` and `it.layer` from `@effect/vitest`. `Effect.run*` and
+ `ManagedRuntime.make` in a test file are lint errors (`lint/effect-tests.js`).
+- Swap services with test layers; do not mock modules.
+- Where a fake would behave differently from the platform (D1, R2, Durable Objects, Workflows),
+ check the behaviour under `pnpm dev` too: it runs your Worker in workerd with local bindings.
## UI
diff --git a/templates/base/files/root/lint/effect-tests.js b/templates/base/files/root/lint/effect-tests.js
new file mode 100644
index 0000000..bae1832
--- /dev/null
+++ b/templates/base/files/root/lint/effect-tests.js
@@ -0,0 +1,45 @@
+// Effect tests run through @effect/vitest (`it.effect`, `it.layer`), which supplies the test
+// services and reports failures with their full cause. Running an Effect by hand skips both.
+const runners = new Set([
+ "runCallback",
+ "runFork",
+ "runPromise",
+ "runPromiseExit",
+ "runSync",
+ "runSyncExit",
+])
+
+const manualRunner = (callee) => {
+ if (callee.type !== "MemberExpression" || callee.object.type !== "Identifier") return undefined
+ if (callee.property.type !== "Identifier") return undefined
+ const object = callee.object.name
+ const method = callee.property.name
+ if (object === "Effect" && runners.has(method)) return `Effect.${method}`
+ if (object === "ManagedRuntime" && method === "make") return "ManagedRuntime.make"
+ return undefined
+}
+
+export default {
+ meta: { name: "effect-tests" },
+ rules: {
+ "no-manual-runtime": {
+ meta: {
+ type: "problem",
+ docs: {
+ description: "Run Effects in tests with it.effect or it.layer from @effect/vitest",
+ },
+ messages: {
+ manual: "{{name}} in a test: use it.effect or it.layer from @effect/vitest instead.",
+ },
+ },
+ create(context) {
+ return {
+ CallExpression(node) {
+ const name = manualRunner(node.callee)
+ if (name !== undefined) context.report({ node, messageId: "manual", data: { name } })
+ },
+ }
+ },
+ },
+ },
+}
diff --git a/templates/base/files/root/vite.config.ts b/templates/base/files/root/vite.config.ts
index b52881d..c440eaa 100644
--- a/templates/base/files/root/vite.config.ts
+++ b/templates/base/files/root/vite.config.ts
@@ -16,6 +16,7 @@ export default defineConfig({
categories: { correctness: "error", suspicious: "error", perf: "error" },
// an explicit list replaces oxlint's defaults, so keep oxc/typescript/unicorn
plugins: ["oxc", "typescript", "unicorn", "react", "import", "effecttsgo"],
+ jsPlugins: ["./lint/effect-tests.js"],
options: { typeAware: true, typeCheck: true },
rules: {
"typescript/no-explicit-any": "error",
@@ -30,8 +31,30 @@ export default defineConfig({
"react/react-in-jsx-scope": "off",
// exact pins make "unstable" Effect APIs safe; this flags it.effect itself
"effecttsgo/unstable-api-usage": "off",
+ // bindings reach code through effect-cf layers; cloudflare.ts is the one file that reads env
+ "no-restricted-imports": [
+ "error",
+ {
+ paths: [
+ {
+ name: "cloudflare:workers",
+ importNames: ["env"],
+ message:
+ "Read bindings through effect-cf layers; only server/cloudflare.ts reads env.",
+ },
+ ],
+ },
+ ],
},
overrides: [
+ {
+ files: ["**/*.test.ts", "**/*.test.tsx"],
+ rules: { "effect-tests/no-manual-runtime": "error" },
+ },
+ {
+ files: ["apps/web/src/server/cloudflare.ts"],
+ rules: { "no-restricted-imports": "off" },
+ },
{
// entry points are where layers get provided: the server runtime and one-off scripts
files: ["apps/web/src/server/runtime.ts", "packages/*/scripts/**"],
From 9b572d3797b572e42c6a96c41b2dc95b41ced9b6 Mon Sep 17 00:00:00 2001
From: Abdulrahman Magdy
Date: Tue, 20 Oct 2026 18:05:54 +0300
Subject: [PATCH 2/8] Lint deprecated APIs and misused promises in generated
projects
Take two rules from Ultracite's oxlint preset after measuring it on a
generated stack. Fix what they found in the templates: FormEvent becomes
SubmitEvent, and async React handlers are wrapped as () => void fn().
---
CHANGELOG.md | 2 ++
docs/decisions/0003-rat-stack-learnings.md | 1 +
.../ai/effect-ai-byok/files/routes/ai.tsx | 10 +++++-----
.../files/components/org-switcher.tsx | 2 +-
.../files/routes/accept-invite.$id.tsx | 2 +-
.../files/routes/app/settings/members.tsx | 18 +++++++++++-------
.../files/routes/onboarding.tsx | 6 +++---
.../files/shared/components/user-menu.tsx | 2 +-
.../files/shared/routes/sign-in.tsx | 6 +++---
.../files/shared/routes/sign-up.tsx | 6 +++---
templates/base/files/root/vite.config.ts | 2 ++
.../extras/realtime/files/realtime-demo.tsx | 4 ++--
12 files changed, 35 insertions(+), 26 deletions(-)
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 466c83d..36c2bfa 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,11 +5,13 @@
### Added
- Generated projects lint two rules that `AGENTS.md` only described before: `Effect.run*` and `ManagedRuntime.make` in test files (a local oxlint plugin, `lint/effect-tests.js`), and importing `env` from `cloudflare:workers` outside `server/cloudflare.ts`.
+- Generated projects lint `typescript/no-deprecated` and `typescript/no-misused-promises`.
- The generated `AGENTS.md` has a Tests section and asks for lifecycles as tagged states. See `docs/decisions/0003-rat-stack-learnings.md`.
### Changed
- The `effect-ai-byok` crypto test uses `it.effect` instead of `Effect.runPromise`.
+- Template forms and buttons use React's `SubmitEvent` instead of the deprecated `FormEvent`, and wrap async handlers as `() => void handler()`.
## 0.1.0 (2026-10-19)
diff --git a/docs/decisions/0003-rat-stack-learnings.md b/docs/decisions/0003-rat-stack-learnings.md
index f900d3e..68a010b 100644
--- a/docs/decisions/0003-rat-stack-learnings.md
+++ b/docs/decisions/0003-rat-stack-learnings.md
@@ -12,6 +12,7 @@ Adopted in the generated project:
- `lint/effect-tests.js`, a local oxlint JS plugin: `Effect.run*` and `ManagedRuntime.make` in `*.test.ts(x)` are errors; tests use `it.effect` and `it.layer`. Adapted from rat-stack's `scripts/oxlint-plugin-effect-tests.ts`. The `effect-ai-byok` crypto test was rewritten to comply.
- `no-restricted-imports` for `env` from `cloudflare:workers`, switched off for `apps/web/src/server/cloudflare.ts`. The "only cloudflare.ts reads env" rule was documentation; now lint enforces it.
+- Two rules from Ultracite's oxlint preset (rat-stack lints with Ultracite): `typescript/no-deprecated` and `typescript/no-misused-promises`. On the generated house stack they found 6 uses of React's deprecated `FormEvent` (now `SubmitEvent`) and 14 async event handlers passed where React expects a void return (now `() => void handler()`). The rest of Ultracite was not adopted: on that stack its `core`, `react` and `anti-slop` presets reported 895 issues in 90 files, nearly all style, several against Effect idiom (`func-names` flags every `Effect.gen(function* () {})`), and its oxfmt preset would replace the Vite+ format settings from 0001.
- `AGENTS.md`: a Tests section (test layers rather than module mocks, check workerd behaviour under `pnpm dev` where a fake can differ) and "model lifecycles as tagged states, not boolean flags".
Not adopted, for now:
diff --git a/templates/ai/effect-ai-byok/files/routes/ai.tsx b/templates/ai/effect-ai-byok/files/routes/ai.tsx
index bdcb10e..2af82e0 100644
--- a/templates/ai/effect-ai-byok/files/routes/ai.tsx
+++ b/templates/ai/effect-ai-byok/files/routes/ai.tsx
@@ -1,5 +1,5 @@
import { createFileRoute, useRouter } from "@tanstack/react-router"
-import { type FormEvent, useState } from "react"
+import { type SubmitEvent, useState } from "react"
import { toast } from "sonner"
import { Button } from "@/components/ui/button"
import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@/components/ui/card"
@@ -56,7 +56,7 @@ function AiSettings() {
const { canManage, configured, last4 } = settings
const needsUrl = provider === "ollama" || provider === "openai"
- async function save(event: FormEvent) {
+ async function save(event: SubmitEvent) {
event.preventDefault()
const form = event.currentTarget
const data = new FormData(form)
@@ -113,7 +113,7 @@ function AiSettings() {
)}
{canManage ? (
-