rat-stack 🐀

_An Effect stack so pure (aspirational) Kit Langton will blush._

gh repo create <name> --template joelhooks/rat-stack

nvm use
pnpm install
pnpm vendor:agent-sources
pnpm turbo run check test build

pnpm cli stats README.md
pnpm cli stats README.md --json

node apps/cli/dist/cli.js stats README.md

pnpm cli openapi                 # OpenAPI 3.1 document for the REST projection
pnpm cli serve --port 3000       # POST /inspectFile, GET /openapi.json, GET /docs
pnpm cli mcp                     # MCP server over stdio, one tool per capability
pnpm cli mcp --code-mode         # MCP server with two tools: search and execute
pnpm cli catalog --types         # the tools declarations a code-mode program sees

• pnpm workspaces + Turborepo 2.11.9: cached typecheck / test / build across packages from day one.
• Effect 4.0.0: typed runtime, errors, filesystem service, and the three surfaces the capabilities project onto: effect/cli, effect/http-api (with OpenApi.fromApi), and effect/ai (Toolkit + McpServer).
• @effect/platform-node 4.0.0: Node-backed services; keep adapter and core pins matched.
• TypeScript 7.0.2: strict module and index-access checks.
• XState 6.0.0-alpha.70: real lifecycle states; do not replace those with boolean soup.
• @xstate/effect 1.0.0-alpha.9: the official XState v6 to Effect 4 bridge: createEffectActor runs a machine as a scoped Effect, createEffectLogic makes Effects into actors with typed failures and requirements. packages/core/src/inspect-machine.ts is the example.
• Alchemy 2.0.0-beta.83: Infrastructure as Effects: apps/infra/alchemy.run.ts is the Stack; pnpm infra:plan / infra:deploy / infra:destroy; auth via pnpm alchemy profile edit.
• Oxlint + Ultracite + Oxfmt: native lint and format.
• Vitest 5.0.5 + @effect/vitest 4.0.0: it.effect and it.layer for every Effect test; running Effects by hand in a test file is a lint error.
• @effect/tsgo 0.54.0: patches TypeScript 7 in prepare so Effect language-service diagnostics (leaked requirements, any/unknown in channels, global Date/fetch/console inside Effect, Node built-ins where Effect has a service) fail tsc.
• varlock 1.23.0: .env.schema declares every variable with @env-spec decorators; pnpm check runs varlock load, secrets stay in gitignored .env.local.
• Vendored agent sources: Effect, effect-solutions, XState, Alchemy, Better Auth, and Foldkit via ./scripts/vendor-agent-sources.sh, each at the ref its workspace pin names (not x-algorithm; that stays app-specific).
• Agent fence: lefthook pre-commit + Pi/Cursor/Claude hooks that block git … --no-verify. Cheating should be uncomfortable and obvious.

Commands

| Command | Purpose | | --- | --- | | pnpm typecheck | Check TypeScript without emitting files | | pnpm check | Typecheck, check formatting, and run type-aware linting | | pnpm fix | Apply Oxfmt and safe Oxlint fixes | | pnpm test | Run the Vitest suite once | | pnpm build | Compile package outputs | | pnpm cli -- ... | Build and run the CLI | | pnpm vendor:agent-sources | Clone core lib mirrors | | pnpm turbo run check test build | Cached verification pipeline |

Agentic surface

Every clone includes AGENTS.md for repo law and commands, CLAUDE.md as Claude Code's pointer to that law, and VISION.md for project intent. Source mirrors live under .agent_sources/ after you run the vendor script. Repo-local Pi extensions belong in .pi/extensions/.

Make it yours

Start with the template:

gh repo create <name> --template joelhooks/rat-stack

Clone the new repository, then install it:

pnpm install
pnpm sources:fetch

pnpm sources:fetch imports missing pinned source commits from the configured repository remotes once, including in template children. Generation reads only local Git objects and never fetches. Re-run the command when adding a new pin that is not present locally.

Rename the workspace package names before you build on the example. The current name fields are:

• package.json: rat-stack
• apps/cli/package.json: @rat-stack/cli
• apps/infra/package.json: @rat-stack/infra
• apps/site/package.json: @rat-stack/site
• packages/capability/package.json: @rat-stack/capability
• packages/core/package.json: @rat-stack/core

rg -n '@rat-stack/' --glob '.json' --glob '.ts' -l

A new scope changes line lengths, so run the formatter once after the rename:

pnpm fix

Replace inspectFile in packages/core with one useful capability. Add it to capabilities, then verify each surface you keep. Rewrite the Project law, Architecture, and Boundaries sections of AGENTS.md and the top of .pi/APPEND_SYSTEM.md; they describe rat-stack until you do. Keep expected failures typed and map them to deliberate exit codes.

apps/site is the public site and Worker. apps/infra is its Alchemy Stack. Delete both if you do not want a public site. If you keep them, change the Cloudflare Zone name and the DNS names and targets derived from it in apps/infra/alchemy.run.ts. Change the Worker domain and redirects in apps/site/src/worker.ts. Choose an Alchemy stage for each plan or deploy. The stage is a command-line choice, for example --stage . Configure credentials with:

pnpm alchemy profile edit --add Cloudflare

Run the acceptance gate before the first push:

pnpm turbo run check test build

What it promises and how to check

• One capability reaches every kept surface. Proof: packages/capability/test/to-command.test.ts, packages/capability/test/to-http-api.test.ts, packages/capability/test/to-toolkit.test.ts, packages/capability/test/to-code-mode.test.ts, and apps/cli/test/cli.e2e.test.ts.
• Schemas are the contract. Proof: packages/capability/test/catalog.test.ts, packages/capability/test/to-http-api.test.ts, and packages/capability/test/to-toolkit.test.ts check derived JSON Schema and typed failures.
• A fresh sandbox isolates model code. The Node sandbox has a 10-second wall-clock limit and a 1-second limit per synchronous evaluation. Both run inside the child. Scope close and interruption send SIGTERM, then SIGKILL after 250 milliseconds. Stdin EOF, a lost parent, or a failed protocol write ends the child. Child-process imports remain blocked. Proof: packages/capability/test/sandbox.test.ts checks isolation and VM budgets; sandbox-lifetime.test.ts and sandbox-orphan.test.ts check deadlines, parent death, and process-group cleanup.
• Rate limits fail closed. Proof: apps/site/test/worker.test.ts checks 429 responses before another execute worker starts and when the global limit denies.
• Markdown is the default machine representation. Proof: apps/site/test/worker.test.ts checks Markdown without Accept: text/html and HTML only when requested.

Keep or cut

The template is a working project. Delete what you will not use on day one; the fence will identify dependent code that must go too. After each cut, trim packages/capability/src/index.ts and run pnpm install, pnpm fix, then pnpm turbo run check test build. Update the package table in AGENTS.md.

| Want | Keep | Delete | | --- | --- | --- | | Only the CLI | packages/capability/src/contract.ts, packages/capability/src/implement.ts, packages/capability/src/to-command.ts, call-watch.ts, actor-watch.ts, every dependency imported by retained code, and their tests; all of packages/core; the toCommand composition in apps/cli/src/surfaces.ts | unused projections and their matching tests after tracing the retained imports; unused compositions in apps/cli/src/surfaces.ts; the catalog, openapi, serve, and mcp commands in apps/cli/src/command.ts; apps/cli/test/serve.test.ts and the MCP and catalog cases in apps/cli/test/cli.e2e.test.ts | | No code mode | | packages/capability/src/catalog.ts, packages/capability/src/code-mode.ts, packages/capability/src/sandbox-error.ts, packages/capability/src/sandbox-service.ts, packages/capability/src/sandbox-subprocess.ts, and packages/capability/src/to-code-mode.ts; packages/capability/test/catalog.test.ts, packages/capability/test/sandbox.test.ts, packages/capability/test/sandbox-lifetime.test.ts, packages/capability/test/sandbox-orphan.test.ts, packages/capability/scripts/sandbox-lifetime-proof.mjs, and packages/capability/test/to-code-mode.test.ts; the ./sandbox and ./code-mode exports in packages/capability/package.json; codeMode and mcpServer.codeMode in apps/cli/src/surfaces.ts; the catalog command and the --code-mode flag in apps/cli/src/command.ts; the code-mode and catalog cases in apps/cli/test/cli.e2e.test.ts | | No HTTP | | packages/capability/src/to-http-api.ts, packages/capability/src/http-api.ts, and their tests; the ./http-api export in packages/capability/package.json; http, routes, and webServer in apps/cli/src/surfaces.ts; the openapi and serve commands; apps/cli/test/serve.test.ts; the OpenAPI case in apps/cli/test/cli.e2e.test.ts | | No MCP | | packages/capability/src/to-toolkit.ts, packages/capability/src/toolkit.ts, their test, and packages/capability/test/mcp-harness.ts; the ./toolkit export in packages/capability/package.json; tools and mcpServer in apps/cli/src/surfaces.ts; the mcp command; the MCP cases in apps/cli/test/cli.e2e.test.ts. Code mode imports from packages/capability/src/to-toolkit.ts, so cutting MCP cuts code mode too | | Default flags only | Core's Flags port and declarations | Replace apps/site/src/flags.ts with core imports and export const flagsLayer = Flags.defaults(eventFlags); export const liveFlagsLayer = flagsLayer;; remove packages/flags and its dependency in apps/site/package.json. Readers use defaults; the CLI writer fails with a named read-only error | | No analytics | | packages/events; @rat-stack/events in apps/site/package.json; the Basin and basinFoundation calls, EVENTS_ENABLED, withEventCapture, inBackground, EVENTS_IDENTITY_MODE, and the events parameter in apps/site/src/worker.ts; EVENTS_ENABLED, EVENTS_SINK_TOKEN, and EVENTS_IDENTITY_MODE in apps/site/.env.schema and apps/site/src/config-fingerprint.ts; apps/site/test/worker-events.test.ts | | No XState (only after removing interest and every other lifecycle except file inspection) | Keep XState and its bridge while any retained lifecycle imports them | packages/core/src/inspect-machine.ts and its test (call FileInspector.inspect directly from packages/core/src/inspect-file.ts); xstate and @xstate/effect in packages/core/package.json and their minimumReleaseAgeExclude entries in pnpm-workspace.yaml; scripts/oxlint-plugin-xstate-effect.ts and its entry in oxlint.config.ts |

defineContract, implement, and toCommand are the minimum that keep stats working. The contract module has no dependency on the other projections.

License

MIT