docs: split CLAUDE.md by scope, and say what this repo is

CLAUDE.md was 1,324 lines and all of it was about the TypeScript half, written before there was another half. Every line of it loaded on every turn regardless of what was being worked on, which is a real cost paid constantly for context that is usually irrelevant. Split by where it applies, so each guide loads when you are in the directory it describes: packages/core/CLAUDE.md 694 domain modules, fn(), actor, errors, auth apps/api/CLAUDE.md 284 routes, registration, error flow docs/alchemy.md 345 stages, bindings, secrets, the CLI CLAUDE.md 72 the repo, both toolchains, two hard rules Nothing was rewritten or dropped — the three files are the original text, verified identical after the split. What the root file now carries is only what is true repo-wide: the layout, the commands, where the detail lives, and the two rules that are not style preferences. One of those is that nothing closed may enter this repo, which is here because it has already been caught once. The README described a streaming platform in four bullets and did not mention that half the repository is Rust that runs inside a virtual machine. It now says what each component does, why a micro-VM rather than a container, what is deliberately absent, and what decides whether a thing is open — data is, capacity is not. It also says plainly that this is mid-rewrite and the docs are behind. Someone arriving at a repo whose documentation does not match its tree should be told that by the README rather than discover it. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-09-19 09:15:19 +03:00 · 2026-08-26 18:23:42 +03:00
parent 6164e0c636
commit 77d4782c86
5 changed files with 1455 additions and 1310 deletions
--- a/docs/alchemy.md
+++ b/docs/alchemy.md
@@ -0,0 +1,345 @@
+# Alchemy — infrastructure as code
+
+This project uses [Alchemy](https://alchemy.run) (v0.93.12) for infrastructure-as-code — the equivalent of SST, but targeting Cloudflare Workers instead of AWS Lambda.
+
+## Project structure
+
+```
+web/
+  alchemy.run.ts          # Entry point — creates scope, imports infra
+  infra/
+    stage.ts              # Stage detection (Scope.getCurrentScope().stage)
+    secret.ts             # Encrypted secrets via alchemy.secret()
+    auth.ts               # Auth Worker resource
+    api.ts                # API Worker resource
+```
+
+## `alchemy.run.ts` — entry point
+
+```ts
+import alchemy from 'alchemy';
+
+const app = await alchemy('nestri', {
+	password: process.env.ALCHEMY_PASSWORD // required for secrets
+});
+
+// Import infra modules in dependency order (SST-style)
+await import('./infra/stage.ts');
+await import('./infra/secret.ts');
+await import('./infra/auth.ts');
+await import('./infra/api.ts');
+
+await app.finalize();
+```
+
+Key rules:
+
+- `alchemy(appName, opts)` creates a **scope** — resources register into this scope automatically
+- `app.finalize()` must be called at the end to persist state
+- Import order matters — resources that depend on others must be imported after
+- `--dev` flag runs locally via Miniflare; omit it to deploy to Cloudflare
+
+## Infra resources
+
+Each resource is imported from `alchemy/cloudflare` and called with an ID + props:
+
+```ts
+import { Worker, KVNamespace, D1Database } from 'alchemy/cloudflare';
+
+export const kv = await KVNamespace('my-kv');
+export const db = await D1Database('my-db');
+
+export const worker = await Worker('my-worker', {
+	entrypoint: 'apps/some-app/src/index.ts',
+	compatibility: 'node', // enables nodejs_compat flag
+	url: true, // assign workers.dev URL
+	bindings: {
+		KV: kv, // resource binding → KVNamespace at runtime
+		DB: db, // → D1Database
+		PLAIN_VAR: 'hello' // → plain_text binding
+	}
+});
+```
+
+### Supported resources (subset)
+
+| Resource      | Import               | Purpose                                         |
+| ------------- | -------------------- | ----------------------------------------------- |
+| `Worker`      | `alchemy/cloudflare` | Cloudflare Worker (entrypoint or inline script) |
+| `KVNamespace` | `alchemy/cloudflare` | KV storage                                      |
+| `D1Database`  | `alchemy/cloudflare` | D1 SQL database                                 |
+| `R2Bucket`    | `alchemy/cloudflare` | R2 object storage                               |
+| `Queue`       | `alchemy/cloudflare` | Queue/pub-sub                                   |
+
+### Compatibility flag
+
+Always add `compatibility: 'node'` to Workers that use Node.js built-ins (`node:async_hooks`, `crypto`, `node:stream`, etc.):
+
+```ts
+Worker('api', {
+	entrypoint: 'apps/api/app/index.ts',
+	compatibility: 'node' // enables nodejs_compat
+});
+```
+
+## Stage detection
+
+```ts
+// infra/stage.ts
+import { Scope } from 'alchemy';
+const scope = Scope.getCurrentScope();
+export const stage = scope?.stage ?? 'dev';
+export const isPermanent = ['production', 'dev'].includes(stage);
+```
+
+Use stage for conditional infrastructure:
+
+```ts
+const api = await Worker('api', {
+	...(isPermanent && {
+		observability: { enabled: true },
+		logpush: true
+	})
+});
+```
+
+Pass `--stage` flag at runtime: `bun alchemy.run.ts --stage production`
+
+## Secrets and environment variables
+
+Three levels of env management, from most-secure to least:
+
+### 1. `alchemy.secret.env.X` (preferred)
+
+```ts
+// infra/secret.ts
+import alchemy from 'alchemy';
+
+export const secret = {
+	steamApiKey: alchemy.secret.env.STEAM_API_KEY // reads process.env at deploy time
+	// Equivalent to:
+	// steamApiKey: alchemy.secret(process.env.STEAM_API_KEY),
+};
+```
+
+- Reads from `process.env` at deploy time
+- Throws a descriptive error if the env var is missing
+- Encrypted in Alchemy state files (`.alchemy/`)
+- Deployed as `secret_text` binding (hidden from Cloudflare API)
+
+### 2. `alchemy.env()` (non-secret config)
+
+```ts
+export const frontendUrl = alchemy.env('FRONTEND_URL', 'http://localhost:5173');
+```
+
+- Optional default value
+- Plain text — not encrypted
+- Deployed as `plain_text` binding
+
+### 3. Plain strings in `bindings` (inline)
+
+```ts
+bindings: {
+	MY_VAR: 'hello';
+}
+```
+
+- Hard-coded, visible in state files
+- Deployed as `plain_text` binding
+
+### How bindings map to runtime types
+
+| Alchemy binding type | Deployed as    | Runtime type               |
+| -------------------- | -------------- | -------------------------- |
+| `Worker`             | `service`      | `Service` (has `.fetch()`) |
+| `KVNamespace`        | `kv_namespace` | `KVNamespace`              |
+| `D1Database`         | `d1`           | `D1Database`               |
+| `alchemy.secret()`   | `secret_text`  | `string`                   |
+| plain `string`       | `plain_text`   | `string`                   |
+| `Json(...)`          | `json`         | `typeof json`              |
+
+## Service bindings (Worker → Worker)
+
+Pass one Worker as a binding to another:
+
+```ts
+// infra/auth.ts
+export const auth = await Worker('auth', {
+  entrypoint: 'apps/auth/src/index.ts',
+  compatibility: 'node',
+  bindings: { ... },
+});
+
+// infra/api.ts
+import { auth } from './auth.ts';
+export const api = await Worker('api', {
+  entrypoint: 'apps/api/app/index.ts',
+  bindings: { AUTH: auth },
+});
+```
+
+At runtime, `env.AUTH` is a `Service` — call it directly:
+
+```ts
+const response = await env.AUTH.fetch(request);
+```
+
+### OpenAuth client + service binding
+
+The `@openauthjs/openauth/client` only accepts a URL string for `issuer`, so use a custom `fetch` to route through the service binding:
+
+```ts
+function getClient(env: Record<string, unknown>) {
+	return createClient({
+		issuer: 'https://auth.internal', // dummy — used for path construction
+		clientID: 'api',
+		fetch: (input, init) => {
+			const url = new URL(typeof input === 'string' ? input : input.url);
+			const request = new Request(url.pathname + url.search, init);
+			return (env.AUTH as { fetch: typeof fetch }).fetch(request);
+		}
+	});
+}
+```
+
+## Env propagation to Workers
+
+CF Workers receive env vars as the second argument to the `fetch` handler (`env`), NOT via `process.env`. Bridge the gap with a lazy + overridable schema:
+
+```ts
+// packages/core/src/env.ts
+import { memo } from '../utils/memo.ts';
+
+let _overrides: Record<string, unknown> = {};
+
+export namespace Env {
+	export const Info = z.object({
+		FRONTEND_URL: z.string().optional(),
+		STEAM_API_KEY: z.string().optional(),
+		AUTH_ISSUER_URL: z.string().optional()
+	});
+	export type Info = z.infer<typeof Info>;
+
+	const _get = memo(() => Info.parse({ ...process.env, ..._overrides }));
+
+	export function get(): Info {
+		return _get();
+	}
+
+	export function init(bindings: Record<string, unknown>) {
+		_overrides = bindings;
+		_get.reset();
+	}
+}
+```
+
+Wire in the Hono entrypoint:
+
+```ts
+export default {
+	fetch(request, env, ctx) {
+		Env.init(env); // merge CF bindings into Env
+		return app.fetch(request, env, ctx);
+	}
+};
+```
+
+Now any module that imports `Env.get()` gets the correct values — on Bun dev `process.env` provides them, on CF Workers the bindings override.
+
+## CLI usage
+
+```sh
+# Local dev (Miniflare)
+bun alchemy.run.ts --dev
+
+# Deploy to Cloudflare
+bun alchemy.run.ts --stage production
+
+# Destroy all resources
+bun alchemy.run.ts --destroy
+
+# With custom stage
+bun alchemy.run.ts --stage wanjohiryan
+
+# Password (for encrypting secrets)
+export ALCHEMY_PASSWORD="some-passphrase"
+```
+
+When deploying, set `CLOUDFLARE_API_TOKEN` or configure `alchemy login`.
+
+## Common patterns
+
+### Conditional infra per-stage
+
+```ts
+Worker('api', {
+	...(isPermanent && { logpush: true }),
+	...(stage === 'production' && { scaling: { min: 3, max: 10 } })
+});
+```
+
+### Across-app resource references
+
+Alchemy uses top-level await in infra files — resources resolve at import time within the active scope. The scope propagates via `AsyncLocalStorage`, so any `await import()` after `alchemy(appName)` picks it up.
+
+### .alchemy/ directory
+
+Created automatically — contains Miniflare state, build output, and encrypted state files. Add to `.gitignore`.
+
+```gitignore
+.alchemy/
+```
+
+---
+
+### Index Rule: Null-Safe Exclusions (`IS DISTINCT FROM`)
+
+When writing indices to track data drift, synchronization deltas, or pending background worker states where values might be nullable, **always build a partial index utilizing Postgres-native `IS DISTINCT FROM`**.
+
+Standard inequality operators (`!=` or `<>`) evaluate to `NULL` if either column is `NULL`, causing them to bypass standard `WHERE` index filters. Using `is distinct from` allows Postgres to treat `NULL` as a real value for state comparison:
+
+- Excludes perfectly synchronized records completely from the index footprint.
+- Optimizes heavy background worker poll queries directly into small, lightning-fast index scans.
+
+2. Add to the Pattern: index.ts (Domain Namespace) section
+
+Replace the existing create block and add the upsert block inside SomeModule:
+
+```ts
+// ── create ───────────────────────────────────────────────────────────
+// Use Info.pick({…}) for the schema — keeps fields in sync with Info.
+// Always use .returning() to get the updated row context in one database trip.
+export const create = fn(Info.pick({ id: true, name: true, email: true }), async (input) => {
+	return Database.use(async (tx) => {
+		const [row] = await tx
+			.insert(SomeTable)
+			.values({
+				id: input.id,
+				name: input.name,
+				email: input.email ?? null
+			})
+			.returning();
+		return row;
+	});
+});
+
+// ── upsert ───────────────────────────────────────────────────────────
+// Simple copies use the input values directly. For coalesce-style set
+// expressions, reference the excluded pseudo-table with unqualified
+// identifiers: sql`excluded.${sql.identifier(SomeTable.name.name)}` —
+// interpolating a column object (or its .name string) is invalid.
+export const upsert = fn(Info.pick({ id: true, name: true }), async (input) => {
+	return Database.use(async (tx) => {
+		const [row] = await tx
+			.insert(SomeTable)
+			.values({ id: input.id, name: input.name })
+			.onConflictDoUpdate({
+				target: SomeTable.id,
+				set: { name: input.name }
+			})
+			.returning();
+		return row;
+	});
+});
+```