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 ? ( -
+ void save(event)} className="space-y-4">
- @@ -132,7 +132,7 @@ function Members() { - + void invite(event)} className="flex items-end gap-2">
@@ -159,7 +159,7 @@ function Members() { value={link} onFocus={(e) => e.target.select()} /> -
@@ -178,11 +178,15 @@ function Members() { - diff --git a/templates/auth/better-auth-orgs/files/routes/onboarding.tsx b/templates/auth/better-auth-orgs/files/routes/onboarding.tsx index e89331f..fddfeeb 100644 --- a/templates/auth/better-auth-orgs/files/routes/onboarding.tsx +++ b/templates/auth/better-auth-orgs/files/routes/onboarding.tsx @@ -1,5 +1,5 @@ import { createFileRoute, redirect } from "@tanstack/react-router" -import { type FormEvent, useState } from "react" +import { type SubmitEvent, useState } from "react" import { AuthCard } from "@/components/auth-card" import { Button } from "@/components/ui/button" import { Input } from "@/components/ui/input" @@ -28,7 +28,7 @@ function Onboarding() { const [error, setError] = useState(null) const [pending, setPending] = useState(false) - async function onSubmit(event: FormEvent) { + async function onSubmit(event: SubmitEvent) { event.preventDefault() const name = formField(new FormData(event.currentTarget), "name").trim() setPending(true) @@ -47,7 +47,7 @@ function Onboarding() { title="Create your organization" description="Organizations hold your members and your data. You can create more later." > - + void onSubmit(event)} className="space-y-4">
diff --git a/templates/auth/better-auth/files/shared/components/user-menu.tsx b/templates/auth/better-auth/files/shared/components/user-menu.tsx index 9a5f40c..de8851b 100644 --- a/templates/auth/better-auth/files/shared/components/user-menu.tsx +++ b/templates/auth/better-auth/files/shared/components/user-menu.tsx @@ -37,7 +37,7 @@ export function UserMenu({ name, email }: { name: string; email: string }) {
{email}
- Sign out + void signOut()}>Sign out ) diff --git a/templates/auth/better-auth/files/shared/routes/sign-in.tsx b/templates/auth/better-auth/files/shared/routes/sign-in.tsx index 0501039..2af196f 100644 --- a/templates/auth/better-auth/files/shared/routes/sign-in.tsx +++ b/templates/auth/better-auth/files/shared/routes/sign-in.tsx @@ -1,5 +1,5 @@ import { createFileRoute, Link, redirect } from "@tanstack/react-router" -import { type FormEvent, useState } from "react" +import { type SubmitEvent, useState } from "react" import { AuthCard } from "@/components/auth-card" import { Button } from "@/components/ui/button" import { Input } from "@/components/ui/input" @@ -22,7 +22,7 @@ function SignIn() { const [error, setError] = useState(null) const [pending, setPending] = useState(false) - async function onSubmit(event: FormEvent) { + async function onSubmit(event: SubmitEvent) { event.preventDefault() const form = new FormData(event.currentTarget) setPending(true) @@ -56,7 +56,7 @@ function SignIn() { } > - + void onSubmit(event)} className="space-y-4">
diff --git a/templates/auth/better-auth/files/shared/routes/sign-up.tsx b/templates/auth/better-auth/files/shared/routes/sign-up.tsx index 42e47bd..8aa0986 100644 --- a/templates/auth/better-auth/files/shared/routes/sign-up.tsx +++ b/templates/auth/better-auth/files/shared/routes/sign-up.tsx @@ -1,5 +1,5 @@ import { createFileRoute, Link, redirect } from "@tanstack/react-router" -import { type FormEvent, useState } from "react" +import { type SubmitEvent, useState } from "react" import { AuthCard } from "@/components/auth-card" import { Button } from "@/components/ui/button" import { Input } from "@/components/ui/input" @@ -22,7 +22,7 @@ function SignUp() { const [error, setError] = useState(null) const [pending, setPending] = useState(false) - async function onSubmit(event: FormEvent) { + async function onSubmit(event: SubmitEvent) { event.preventDefault() const form = new FormData(event.currentTarget) setPending(true) @@ -57,7 +57,7 @@ function SignUp() { } > - + void onSubmit(event)} className="space-y-4">
diff --git a/templates/base/files/root/vite.config.ts b/templates/base/files/root/vite.config.ts index c440eaa..e601e4a 100644 --- a/templates/base/files/root/vite.config.ts +++ b/templates/base/files/root/vite.config.ts @@ -21,6 +21,8 @@ export default defineConfig({ rules: { "typescript/no-explicit-any": "error", "typescript/no-floating-promises": "error", + "typescript/no-misused-promises": "error", + "typescript/no-deprecated": "error", "no-unused-vars": "error", "react/exhaustive-deps": "error", "no-console": ["error", { allow: ["warn", "error"] }], diff --git a/templates/extras/realtime/files/realtime-demo.tsx b/templates/extras/realtime/files/realtime-demo.tsx index 0f92ab0..9e4971e 100644 --- a/templates/extras/realtime/files/realtime-demo.tsx +++ b/templates/extras/realtime/files/realtime-demo.tsx @@ -1,4 +1,4 @@ -import { type FormEvent, useState } from "react" +import { type SubmitEvent, useState } from "react" import { Button } from "@/components/ui/button" import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@/components/ui/card" import { Input } from "@/components/ui/input" @@ -9,7 +9,7 @@ export function RealtimeDemo() { const { messages, status, send } = useRoom("demo") const [text, setText] = useState("") - const submit = (event: FormEvent) => { + const submit = (event: SubmitEvent) => { event.preventDefault() if (text.trim() === "") return send(text) From 75404e40305456bd1bc27fbc905953f6d4c80c49 Mon Sep 17 00:00:00 2001 From: Abdulrahman Magdy Date: Thu, 22 Oct 2026 13:28:45 +0300 Subject: [PATCH 3/8] Polish the CLI: fail fast, explain errors, stack-aware next steps From a hands-on QA pass of create and add: - Prompts without a terminal (CI, pipes, npm eating flags) fail with the exact flag to pass instead of hanging. - Ctrl-C exits 130; stopping during setup says what is left to run. - pnpm is checked before any prompt; a failed install lists the steps that remain. Unsupported Node versions get a warning; missing git skips git. - The name prompt rejects an occupied directory and asks again. A directory holding only .git counts as empty, and `.` scaffolds in place. - Incompatible flags say why (auth needs a database, ...); unknown values say unknown. --json reports errors as JSON. Duplicate extras are dropped. - The install shows its latest output line and every step its duration; in CI or a pipe, steps print one line each without spinner frames. - create ends with next steps for the stack (docker, db:migrate, Alchemy). - add gets the same chrome: a change summary (+ new, ~ edited), warnings for removed files, replaced scripts and a dirty tree, the new env vars, and ids that are case-insensitive with a did-you-mean. - add explains which ids to add together (database + ORM + auth). - New `efforge list` shows every add-on and marks what a project has. - Help shows examples. --- src/cli.ts | 24 +++- src/commands/add.ts | 238 +++++++++++++++++++++++++++---- src/commands/create.ts | 299 +++++++++++++++++++++++++++++---------- src/commands/list.ts | 112 +++++++++++++++ src/exec.ts | 31 +++- src/prompts/flow.ts | 23 ++- src/prompts/navigable.ts | 195 +++++++++++++++++++------ src/rules.ts | 9 +- src/slots.ts | 20 +++ src/write.ts | 5 +- test/add.test.ts | 4 + test/create.test.ts | 31 ++-- test/polish.test.ts | 197 ++++++++++++++++++++++++++ 13 files changed, 1009 insertions(+), 179 deletions(-) create mode 100644 src/commands/list.ts create mode 100644 test/polish.test.ts diff --git a/src/cli.ts b/src/cli.ts index 52e955d..23dd14c 100644 --- a/src/cli.ts +++ b/src/cli.ts @@ -1,14 +1,34 @@ import { Command } from "effect/cli" import { addCommand } from "./commands/add.ts" import { createCommand, createConfig, createHandler } from "./commands/create.ts" +import { listCommand } from "./commands/list.ts" import { efforgeVersion } from "./versions.ts" -/** Root behaves as `create`; `efforge create` is an explicit alias, `efforge add` is separate. */ +/** Root behaves as `create`; `efforge create` is an explicit alias, `add` and `list` are separate. */ export const root = Command.make("create-efforge", createConfig, createHandler).pipe( Command.withDescription( "Scaffold an Effect + TanStack Start app on Cloudflare with database, auth and services already wired together", ), - Command.withSubcommands([createCommand, addCommand]), + Command.withSubcommands([createCommand, addCommand, listCommand]), + Command.withExamples([ + { + command: "npm create efforge my-app", + description: "Answer a few questions, then create ./my-app", + }, + { + command: "npm create efforge my-app -- --yes --database=d1 --orm=effect-sql", + description: "No questions: flags, defaults for the rest", + }, + { + command: "npm create efforge . -- --yes", + description: "Create in the current (empty) directory", + }, + { command: "npx create-efforge list", description: "See every add-on" }, + { + command: "npx create-efforge add email storage", + description: "Add add-ons to an existing project", + }, + ]), ) export const main = Command.run(root, { version: efforgeVersion }) diff --git a/src/commands/add.ts b/src/commands/add.ts index 0729bba..1aba549 100644 --- a/src/commands/add.ts +++ b/src/commands/add.ts @@ -21,7 +21,8 @@ import { type TransformAnchorMissing, type UnknownTransform, } from "../transforms/index.ts" -import { versions } from "../versions.ts" +import { PromptIO } from "../prompts/navigable.ts" +import { efforgeVersion, versions } from "../versions.ts" import { TemplatesDir } from "./create.ts" export class NotAnEfforgeProject extends Schema.TaggedError()( @@ -45,12 +46,24 @@ export interface AddOptions { export interface AddResult { /** Overlay files created or replaced, plus package.json, workspace, env and manifest updates. */ readonly written: string[] + /** The subset of `written` that didn't exist before. */ + readonly created: string[] /** Existing seam files edited by transforms. */ readonly transformed: string[] /** Ids already in the stack, and overlays that already match. */ readonly skipped: string[] /** Generated files the add-on replaces (e.g. wrangler.jsonc for infra/alchemy). */ readonly removed: string[] + /** Add-ons this run added, for the summary and next steps. */ + readonly added: ReadonlyArray<{ + readonly id: string + readonly title: string + readonly docs?: string + }> + /** Env vars this run added to `.env.example`. */ + readonly envVars: ReadonlyArray<{ readonly name: string; readonly description: string }> + /** `: