add game config configuration

.env.example

@@ -23,3 +23,36 @@ RECFLARE_DOMAIN=rec.example.com
 # Kept out of the committed wrangler.jsonc (which uses a "local" placeholder) and
 # spliced in at deploy time. Required to deploy any worker.
 # RECFLARE_SECRETS_STORE=00000000-0000-0000-0000-000000000000
+
+# --- Server tuning (all optional; the shown value is the built-in default) ---
+# Everything below is passed to the workers as a variable, named without the RECFLARE_
+# prefix: RECFLARE_STARTING_TOKENS becomes STARTING_TOKENS. Every worker gets every knob —
+# the ones that don't read a knob just ignore it — so nothing here has to be routed to a
+# particular service, and two services reading the same knob agree on it for free. (The five
+# settings above are the exception: they configure the deploy itself, not the workers.)
+#
+# The same values are used by `just deploy` and by `just dev`, so a knob is set in exactly
+# one place. Change one and re-deploy the worker that reads it (e.g. `just deploy -F auth`)
+# for it to take effect. Leave a line commented out and the worker uses its built-in
+# default — and deleting a line you'd set really does restore that default on the next
+# deploy.
+#
+# Don't set these in the Cloudflare dashboard — a deploy replaces a worker's variables
+# wholesale, so a dashboard-set value is wiped by your next `just deploy`. This file is the
+# durable place. (Actual secrets don't go here either: they live in the Cloudflare Secrets
+# Store, like the shared JWT signing key above.)
+
+# How many accounts one signup source may create (`auth`). Enforced on signup only,
+# never on login: an existing account always stays reachable. Set either to 0 to turn
+# that cap off entirely.
+#   ...PER_PLATFORM_ID counts accounts per Steam-verified identity — unspoofable.
+#   ...PER_IP counts accounts per signup IP — coarse, since a household, NAT or campus
+#   network shares one address. This is the one to raise (or zero out) if real players
+#   report being locked out.
+# RECFLARE_MAX_ACCOUNTS_PER_PLATFORM_ID=3
+# RECFLARE_MAX_ACCOUNTS_PER_IP=3
+
+# RecCenterTokens a new player is granted, the first time their balance is read (`econ`).
+# 0 means players start broke. Applies only to players who haven't been granted yet —
+# raising it later does NOT top up existing players.
+# RECFLARE_STARTING_TOKENS=10000

DEPLOYING.md

@@ -157,6 +157,48 @@ just deploy # Deploy code
 
 Optionally if you know there was only a change to a single service, you can use `just [migrate|deploy] -F econ` for example to only deploy the `econ` microservice.
 
+## Tuning your server
+
+A few gameplay/policy values are knobs rather than hardcoded constants, and they live in
+the same `.env` you already created. `.env.example` carries each one commented out, set to
+its built-in default: copy the lines you want to change into your `.env`, uncomment them,
+edit the value, then re-deploy the worker that reads them.
+
+| `.env` variable                         | Read by | Default | What it does                                                   |
+| --------------------------------------- | ------- | ------- | -------------------------------------------------------------- |
+| `RECFLARE_MAX_ACCOUNTS_PER_PLATFORM_ID` | `auth`  | `3`     | Accounts one Steam-verified identity may create. `0` disables. |
+| `RECFLARE_MAX_ACCOUNTS_PER_IP`          | `auth`  | `3`     | Accounts one signup IP may create. `0` disables.               |
+| `RECFLARE_STARTING_TOKENS`              | `econ`  | `10000` | RecCenterTokens a new player is granted.                       |
+
+Then deploy just the worker that reads it:
+
+```bash
+just deploy -F auth
+```
+
+A line you leave out of `.env` keeps its default, so only copy over what you actually want
+to change — and deleting a line you'd set restores the default on the next deploy. The same
+`.env` feeds `just dev`, so a knob is configured once and behaves the same locally as it
+does deployed.
+
+Adding a knob of your own takes no changes to the deploy tooling. Every `RECFLARE_*` in
+`.env` is handed to the workers as a variable under its unprefixed name — `RECFLARE_STARTING_TOKENS`
+arrives as `STARTING_TOKENS` — so a new one only needs declaring in that worker's
+`src/context.ts` and reading in its code. Every worker receives every knob and ignores the
+ones it doesn't read, which is also how two services can share a value. (The domain and the
+resource ids above are the exception: those configure the deploy itself and are never
+passed to a worker.)
+
+Both account caps are enforced on signup only, never on login — an existing account always
+stays reachable no matter how many its owner has accumulated. The per-IP cap is the coarse
+one: households, NAT and shared campus/mobile networks put many legitimate players behind a
+single address, so raise it (or set it to `0`) if real players report being locked out.
+
+> **Don't set these as Worker variables in the Cloudflare dashboard.** A deploy replaces a
+> worker's variables wholesale, so a dashboard-set value is wiped by your next
+> `just deploy`. `.env` is the durable place. Real secrets don't belong there either — they
+> go in the Cloudflare Secrets Store, like the shared `JWT_SECRET` above.
+
 ## Repository Structure
 
 - `apps/` - The service workers, one deployable Worker per subdirectory. Each has

apps/auth/src/auth.app.ts

@@ -15,7 +15,7 @@ import {
 	setPasswordHash,
 	setPresence,
 } from '@repo/domain'
-import { logger, withNotFound, withOnError } from '@repo/hono-helpers'
+import { intVar, logger, withNotFound, withOnError } from '@repo/hono-helpers'
 import { generateToken, TOKEN_TTL_SECONDS, validateAndGetAccountId } from '@repo/jwt'
 
 import { hashPassword, verifyPassword } from './password'
@@ -57,9 +57,15 @@ const PLATFORM_TYPES: Record<number, string> = {
  *    legitimate players behind one address, so this WILL be the arm that produces false
  *    positives. It counts `signupIp` (immutable), so an abuser can't reset their own
  *    count by hopping networks.
+ *
+ * These are the defaults. An operator overrides either arm with the matching worker var
+ * (`MAX_ACCOUNTS_PER_PLATFORM_ID` / `MAX_ACCOUNTS_PER_IP` in wrangler.jsonc `vars`), and
+ * setting one to 0 disables that arm entirely — which a small private server that trusts
+ * everyone it invites will want, and which the IP arm in particular is worth reaching for
+ * if a shared network is being locked out.
  */
-const MAX_ACCOUNTS_PER_PLATFORM_ID = 3
+const DEFAULT_MAX_ACCOUNTS_PER_PLATFORM_ID = 3
-const MAX_ACCOUNTS_PER_IP = 3
+const DEFAULT_MAX_ACCOUNTS_PER_IP = 3
 
 /** New players start in the Orientation room (RoomId 13) — the new-user flow. */
 const ORIENTATION_ROOM_ID = 13
@@ -301,12 +307,19 @@ const app = new Hono<App>()
 		let accountId: string
 		if (grantType === 'create_account') {
 			// Signup caps. Checked before minting anything, so a rejected signup leaves no
-			// account behind. Each arm is skipped when its identity is unknown (no verified
+			// account behind. Each arm is skipped when it's disabled (var <= 0) or when its
-			// platform id / no client IP) — an unattributable signup can't be counted against
+			// identity is unknown (no verified platform id / no client IP) — an unattributable
-			// anyone, and lumping them together would lock out real players.
+			// signup can't be counted against anyone, and lumping them together would lock out
+			// real players. The disabled check comes first so a disabled arm costs no D1 read.
+			const maxPerPlatformId = intVar(
+				c.env.MAX_ACCOUNTS_PER_PLATFORM_ID,
+				DEFAULT_MAX_ACCOUNTS_PER_PLATFORM_ID
+			)
+			const maxPerIp = intVar(c.env.MAX_ACCOUNTS_PER_IP, DEFAULT_MAX_ACCOUNTS_PER_IP)
 			if (
+				maxPerPlatformId > 0 &&
 				verifiedSteamId !== null &&
-				(await countAccountsByPlatformId(c.env.DB, verifiedSteamId)) >= MAX_ACCOUNTS_PER_PLATFORM_ID
+				(await countAccountsByPlatformId(c.env.DB, verifiedSteamId)) >= maxPerPlatformId
 			) {
 				logger.info('signup rejected: platform account limit', { platformId: verifiedSteamId })
 				return c.json(
@@ -318,8 +331,9 @@ const app = new Hono<App>()
 				)
 			}
 			if (
+				maxPerIp > 0 &&
 				clientIp !== '' &&
-				(await countAccountsBySignupIp(c.env.DB, clientIp)) >= MAX_ACCOUNTS_PER_IP
+				(await countAccountsBySignupIp(c.env.DB, clientIp)) >= maxPerIp
 			) {
 				logger.info('signup rejected: per-IP account limit', { ip: clientIp })
 				return c.json(

apps/auth/src/context.ts

@@ -12,6 +12,13 @@ export type Env = SharedHonoEnv & {
 	// signed here verify in all of them. Provisioned via `wrangler secrets-store`;
 	// the store id is spliced into wrangler.jsonc at deploy time (RECFLARE_SECRETS_STORE).
 	JWT_SECRET: SecretsStoreSecret
+	// Signup caps, both optional (see auth.app.ts for what each arm counts and why).
+	// Unset falls back to the DEFAULT_MAX_ACCOUNTS_* constants there; 0 disables that arm.
+	// Typed `string | number` because a var declared in wrangler.jsonc `vars` arrives as a
+	// number while the same var set from the dashboard or `--var` arrives as a string —
+	// read them through `intVar`, never as a bare number.
+	MAX_ACCOUNTS_PER_PLATFORM_ID?: string | number
+	MAX_ACCOUNTS_PER_IP?: string | number
 }
 
 /** Variables can be extended */

apps/auth/src/test/integration/api.test.ts

@@ -419,10 +419,36 @@ describe('auth worker routes', () => {
 		expect(capped.json.error_description).toMatch(/network/)
 
 		// A different IP is unaffected, and the capped IP can still LOG IN to what it has.
-		const other = await postToken('grant_type=create_account&platform_id=steam-cap4', '198.51.100.23')
+		const other = await postToken(
+			'grant_type=create_account&platform_id=steam-cap4',
+			'198.51.100.23'
+		)
 		expect(other.status).toBe(200)
 	})
 
+	test('the signup caps come from vars, and 0 disables an arm', async () => {
+		// The cap an operator actually runs is the `MAX_ACCOUNTS_PER_IP` var; the constant in
+		// auth.app.ts is only the fallback. `env` is shared by every test in this file, so the
+		// override is restored in `finally` rather than leaking a cap of 0 into the tests above.
+		const original = env.MAX_ACCOUNTS_PER_IP
+		try {
+			env.MAX_ACCOUNTS_PER_IP = 1
+			const ip = '198.51.100.30'
+			const first = await postToken('grant_type=create_account&platform_id=steam-var0', ip)
+			expect(first.status).toBe(200)
+			const capped = await postToken('grant_type=create_account&platform_id=steam-var1', ip)
+			expect(capped.status).toBe(400)
+			expect(capped.json.error_description).toMatch(/network/)
+
+			// 0 disables the arm entirely: the IP that was just capped can sign up again.
+			env.MAX_ACCOUNTS_PER_IP = 0
+			const uncapped = await postToken('grant_type=create_account&platform_id=steam-var2', ip)
+			expect(uncapped.status).toBe(200)
+		} finally {
+			env.MAX_ACCOUNTS_PER_IP = original
+		}
+	})
+
 	test('POST /connect/token does not cap logins, only signups', async () => {
 		// Account 42's owner may be over the signup cap; that must never lock them out of
 		// an account they already have.

apps/auth/wrangler.jsonc

@@ -36,6 +36,11 @@
 			"head_sampling_rate": 1 // 100%
 		}
 	},
+	// The signup caps (MAX_ACCOUNTS_PER_PLATFORM_ID, MAX_ACCOUNTS_PER_IP) are deliberately
+	// NOT set here. They're injected at deploy time from the gitignored .env
+	// (RECFLARE_MAX_ACCOUNTS_*, see .env.example), so tuning them never means editing a
+	// versioned file. Unset — the default — falls back to the DEFAULT_MAX_ACCOUNTS_*
+	// constants in src/auth.app.ts.
 	"vars": {
 		"ENVIRONMENT": "development", // overridden during deployment
 		"SENTRY_RELEASE": "unknown" // overridden during deployment

apps/econ/src/balance-db.ts

@@ -68,16 +68,26 @@ const SPENDABLE: readonly number[] = [
 export const isSpendable = (currencyType: number): boolean => SPENDABLE.includes(currencyType)
 
 /**
- * What a player starts with, granted lazily the first time their balances are read
+ * The signup grant, in RecCenterTokens, when the `STARTING_TOKENS` var is unset.
+ * An operator overrides it in wrangler.jsonc `vars`; 0 is a valid setting and means
+ * players start broke.
+ */
+export const DEFAULT_STARTING_TOKENS = 10_000
+
+/**
+ * What a player starts with, granted lazily the first time their balances are touched
  * (see `ensureStartingBalances`). Currencies absent here start at 0.
  *
- * This is the whole signup grant — change the number here and it applies to every
+ * This is the whole signup grant. It is NOT re-granted: a player who spends down to 0
- * player who hasn't been granted yet. It is NOT re-granted: a player who spends down
+ * keeps a 0 row, and the grant is skipped because the row exists. That also means
- * to 0 keeps a 0 row, and the grant is skipped because the row exists.
+ * raising `STARTING_TOKENS` later only affects players who haven't been granted yet —
+ * existing players keep the amount they were granted under the old setting.
  */
-export const STARTING_BALANCES: ReadonlyArray<{ currencyType: number; amount: number }> = [
+export function startingBalances(
-	{ currencyType: CurrencyType.RecCenterTokens, amount: 10_000 },
+	startingTokens: number
-]
+): ReadonlyArray<{ currencyType: number; amount: number }> {
+	return [{ currencyType: CurrencyType.RecCenterTokens, amount: startingTokens }]
+}
 
 /**
  * `Platform` in the client's balance DTO. -2 is "all platforms" — we don't track
@@ -108,19 +118,32 @@ export interface Balance {
  *
  * Called on read rather than at account creation so accounts that predate this table
  * (every existing player) get their grant too.
+ *
+ * `startingTokens` is passed in rather than read from a module constant because it's
+ * operator configuration (`STARTING_TOKENS`), and every path that can trigger the grant
+ * has to agree on it — a caller that skipped it would quietly grant the built-in default
+ * to whichever player happened to touch that path first.
  */
-export async function ensureStartingBalances(db: D1Database, accountId: number): Promise<void> {
+export async function ensureStartingBalances(
+	db: D1Database,
+	accountId: number,
+	startingTokens: number
+): Promise<void> {
 	const stmt = db.prepare(
 		'INSERT OR IGNORE INTO balance (account_id, currency_type, amount) VALUES (?1, ?2, ?3)'
 	)
 	await db.batch(
-		STARTING_BALANCES.map((b) => stmt.bind(accountId, b.currencyType, b.amount))
+		startingBalances(startingTokens).map((b) => stmt.bind(accountId, b.currencyType, b.amount))
 	)
 }
 
 /** Every balance an account holds (after its starting grant is applied). */
-export async function getBalances(db: D1Database, accountId: number): Promise<Balance[]> {
+export async function getBalances(
-	await ensureStartingBalances(db, accountId)
+	db: D1Database,
+	accountId: number,
+	startingTokens: number
+): Promise<Balance[]> {
+	await ensureStartingBalances(db, accountId, startingTokens)
 	const { results } = await db
 		.prepare(
 			'SELECT currency_type, amount FROM balance WHERE account_id = ?1 ORDER BY currency_type'
@@ -134,9 +157,10 @@ export async function getBalances(db: D1Database, accountId: number): Promise<Ba
 export async function getBalance(
 	db: D1Database,
 	accountId: number,
-	currencyType: number
+	currencyType: number,
+	startingTokens: number
 ): Promise<number> {
-	await ensureStartingBalances(db, accountId)
+	await ensureStartingBalances(db, accountId, startingTokens)
 	const row = await db
 		.prepare('SELECT amount FROM balance WHERE account_id = ?1 AND currency_type = ?2')
 		.bind(accountId, currencyType)
@@ -155,7 +179,8 @@ export async function creditCurrency(
 	db: D1Database,
 	accountId: number,
 	currencyType: number,
-	amount: number
+	amount: number,
+	startingTokens: number
 ): Promise<number> {
 	if (!Number.isInteger(amount) || amount <= 0) {
 		throw new Error(`creditCurrency: amount must be a positive integer, got ${amount}`)
@@ -167,7 +192,7 @@ export async function creditCurrency(
 		)
 		.bind(accountId, currencyType, amount)
 		.run()
-	return getBalance(db, accountId, currencyType)
+	return getBalance(db, accountId, currencyType, startingTokens)
 }
 
 /**
@@ -182,12 +207,13 @@ export async function spendCurrency(
 	db: D1Database,
 	accountId: number,
 	currencyType: number,
-	amount: number
+	amount: number,
+	startingTokens: number
 ): Promise<boolean> {
 	if (!Number.isInteger(amount) || amount <= 0) {
 		throw new Error(`spendCurrency: amount must be a positive integer, got ${amount}`)
 	}
-	await ensureStartingBalances(db, accountId)
+	await ensureStartingBalances(db, accountId, startingTokens)
 	const { meta } = await db
 		.prepare(
 			`UPDATE balance SET amount = amount - ?3

apps/econ/src/context.ts

@@ -10,6 +10,15 @@ export type Env = SharedHonoEnv & {
 	DB: D1Database
 	/** Static storefront catalogs (`static/storefronts/sf*.json`), fetched by path. */
 	ASSETS: Fetcher
+	/**
+	 * The RecCenterTokens a new player is granted (see balance-db.ts). Optional — unset
+	 * falls back to DEFAULT_STARTING_TOKENS, and 0 means players start broke.
+	 *
+	 * Typed `string | number` because a var declared in wrangler.jsonc `vars` arrives as a
+	 * number while the same var set from the dashboard or `--var` arrives as a string —
+	 * read it through `intVar`, never as a bare number.
+	 */
+	STARTING_TOKENS?: string | number
 }
 
 /** Variables can be extended */

apps/econ/src/econ.app.ts

@@ -1,7 +1,7 @@
 import { Hono } from 'hono'
 import { useWorkersLogger } from 'workers-tagged-logger'
 
-import { withNotFound, withOnError } from '@repo/hono-helpers'
+import { intVar, withNotFound, withOnError } from '@repo/hono-helpers'
 import { validateAndGetAccountId } from '@repo/jwt'
 
 import defaultAvatarItems from '../static/default-avatar-items.json'
@@ -9,7 +9,7 @@ import defaultAvatar from '../static/default-avatar.json'
 import myProgress from '../static/my-progress.json'
 import weeklyChallenge from '../static/weekly-challenge.json'
 import { getAvatar, setAvatar } from './avatar-db'
-import { ALL_PLATFORMS, getBalance, isSpendable } from './balance-db'
+import { ALL_PLATFORMS, DEFAULT_STARTING_TOKENS, getBalance, isSpendable } from './balance-db'
 import { getOutfits, setOutfit } from './outfit-db'
 
 import type { Context } from 'hono'
@@ -220,7 +220,14 @@ const app = new Hono<App>()
 		if (id === null) return unauthorized(c)
 		const currencyType = Number.parseInt(c.req.param('currencyType'), 10)
 		if (Number.isNaN(currencyType)) return c.body(null, 400)
-		const amount = isSpendable(currencyType) ? await getBalance(c.env.DB, id, currencyType) : 0
+		const amount = isSpendable(currencyType)
+			? await getBalance(
+					c.env.DB,
+					id,
+					currencyType,
+					intVar(c.env.STARTING_TOKENS, DEFAULT_STARTING_TOKENS)
+				)
+			: 0
 		return c.json([{ CurrencyType: currencyType, Platform: ALL_PLATFORMS, Balance: amount }])
 	})
 

apps/econ/src/test/integration/api.test.ts

@@ -8,6 +8,7 @@ import { SCHEMA_DDL } from '../../avatar-db'
 import {
 	BALANCE_SCHEMA_DDL,
 	CurrencyType,
+	DEFAULT_STARTING_TOKENS,
 	getBalance,
 	spendCurrency,
 } from '../../balance-db'
@@ -423,7 +424,9 @@ describe('econ endpoints', () => {
 
 	test('GET /api/storefronts/v4/balance/2 reflects what the player has spent', async () => {
 		// Spend from account 7 (a fresh account: the read below grants it first).
-		expect(await spendCurrency(env.DB, 7, CurrencyType.RecCenterTokens, 2500)).toBe(true)
+		expect(
+			await spendCurrency(env.DB, 7, CurrencyType.RecCenterTokens, 2500, DEFAULT_STARTING_TOKENS)
+		).toBe(true)
 		const res = await exports.default.fetch(`${ORIGIN}/api/storefronts/v4/balance/2`, {
 			headers: await bearer('7'),
 		})
@@ -431,15 +434,47 @@ describe('econ endpoints', () => {
 	})
 
 	test('a spend the player cannot afford changes nothing', async () => {
-		const before = await getBalance(env.DB, 8, CurrencyType.RecCenterTokens)
+		const before = await getBalance(
-		expect(await spendCurrency(env.DB, 8, CurrencyType.RecCenterTokens, before + 1)).toBe(false)
+			env.DB,
-		expect(await getBalance(env.DB, 8, CurrencyType.RecCenterTokens)).toBe(before)
+			8,
+			CurrencyType.RecCenterTokens,
+			DEFAULT_STARTING_TOKENS
+		)
+		expect(
+			await spendCurrency(
+				env.DB,
+				8,
+				CurrencyType.RecCenterTokens,
+				before + 1,
+				DEFAULT_STARTING_TOKENS
+			)
+		).toBe(false)
+		expect(await getBalance(env.DB, 8, CurrencyType.RecCenterTokens, DEFAULT_STARTING_TOKENS)).toBe(
+			before
+		)
+	})
+
+	test('the starting grant comes from the STARTING_TOKENS var', async () => {
+		// The grant an operator actually runs is the var; DEFAULT_STARTING_TOKENS is only the
+		// fallback. `env` is shared by every test in this file, so restore it in `finally`.
+		const original = env.STARTING_TOKENS
+		try {
+			env.STARTING_TOKENS = 250
+			const res = await exports.default.fetch(`${ORIGIN}/api/storefronts/v4/balance/2`, {
+				headers: await bearer('11'),
+			})
+			expect(await res.json()).toEqual([{ CurrencyType: 2, Platform: -2, Balance: 250 }])
+		} finally {
+			env.STARTING_TOKENS = original
+		}
 	})
 
 	test('the starting grant is not re-granted after spending down to zero', async () => {
 		// The grant is INSERT OR IGNORE against the row, not a top-up: a player who spends
 		// everything stays at 0 rather than being refilled by their next balance read.
-		expect(await spendCurrency(env.DB, 9, CurrencyType.RecCenterTokens, 10_000)).toBe(true)
+		expect(
+			await spendCurrency(env.DB, 9, CurrencyType.RecCenterTokens, 10_000, DEFAULT_STARTING_TOKENS)
+		).toBe(true)
 		const res = await exports.default.fetch(`${ORIGIN}/api/storefronts/v4/balance/2`, {
 			headers: await bearer('9'),
 		})

apps/econ/wrangler.jsonc

@@ -44,6 +44,10 @@
 			"head_sampling_rate": 1 // 100%
 		}
 	},
+	// The signup token grant (STARTING_TOKENS) is deliberately NOT set here. It's injected
+	// at deploy time from the gitignored .env (RECFLARE_STARTING_TOKENS, see .env.example),
+	// so tuning it never means editing a versioned file. Unset — the default — falls back
+	// to DEFAULT_STARTING_TOKENS in src/balance-db.ts.
 	"vars": {
 		"ENVIRONMENT": "development", // overridden during deployment
 		"SENTRY_RELEASE": "unknown" // overridden during deployment

packages/hono-helpers/src/helpers/env.ts

@@ -0,0 +1,19 @@
+/**
+ * Read an integer worker var, falling back to `fallback` when it is unset or unusable.
+ *
+ * A var arrives as a number when it's declared in wrangler.jsonc `vars`, but as a string
+ * when it's set anywhere else (the dashboard, `wrangler deploy --var`, `.dev.vars`), so
+ * both have to be accepted — the same var is a different type depending on where the
+ * operator set it.
+ *
+ * Anything that isn't a finite integer (an empty string, a typo, `3.5`) is treated as
+ * unset rather than coerced: `Number.parseInt` would read `"3abc"` as 3 and `"3.9"` as 3,
+ * which turns a typo into a silently wrong limit. Falling back to the documented default
+ * is the safe failure here.
+ */
+export function intVar(value: unknown, fallback: number): number {
+	if (typeof value === 'number') return Number.isInteger(value) ? value : fallback
+	if (typeof value !== 'string' || value.trim() === '') return fallback
+	const parsed = Number(value)
+	return Number.isInteger(parsed) ? parsed : fallback
+}

packages/hono-helpers/src/index.ts

@@ -1,4 +1,5 @@
 export type { HonoApp, SharedHonoEnv, SharedHonoVariables, SharedAppContext } from './types'
+export * from './helpers/env'
 export { logger } from './helpers/logger'
 export { getRequestLogData, type LogDataRequest } from './helpers/request'
 export * from './helpers/errors'

packages/tools/bin/run-wrangler-deploy

@@ -1,28 +1,22 @@
 #!/bin/sh
 set -eu
 
+. "$(git rev-parse --show-toplevel)/packages/tools/src/sh/env.sh"
+
 # Extract name and version from package.json using jq
 NAME=$(jq -r '.name' package.json)
 VERSION=$(get-version)
 
+# Everything an operator supplies — domain, resource ids, tuning knobs — comes from the
+# single gitignored .env at the repo root (in CI, from exported secrets, which win over the
+# file). See .env.example.
+recflare_load_env
+
 # Resolve the base domain (and this worker's subdomain), then deploy onto the
 # custom domain via `--domain`. This keeps the real domain out of versioned files
 # — committed wrangler.jsonc has no routes, and the base domain is passed as the
-# DOMAIN var at runtime.
+# DOMAIN var at runtime. Per-app subdomain overrides come from RECFLARE_SUBDOMAINS
-#
+# (a JSON object, e.g. {"playersettings":"settings"}).
-# The domain comes from the RECFLARE_DOMAIN env var. For local dev that's set in a
-# gitignored .env at the repo root; in CI it's an exported secret. An already-set
-# RECFLARE_DOMAIN wins and skips the file. Per-app subdomain overrides come from
-# RECFLARE_SUBDOMAINS (a JSON object, e.g. {"playersettings":"settings"}).
-if [ -z "${RECFLARE_DOMAIN:-}" ]; then
-	ENV_FILE="$(git rev-parse --show-toplevel)/.env"
-	if [ -f "$ENV_FILE" ]; then
-		set -a
-		. "$ENV_FILE"
-		set +a
-	fi
-fi
-
 if [ -z "${RECFLARE_DOMAIN:-}" ]; then
 	echo "error: RECFLARE_DOMAIN is not set — export it or add it to .env (see .env.example)" >&2
 	exit 1
@@ -129,6 +123,12 @@ if [ "$CONFIG" = "wrangler.jsonc" ] && { [ -n "$NEEDS_D1" ] || [ -n "$NEEDS_KV"
 	fi
 fi
 
+# The operator's tuning knobs, injected the same way as the resource ids above: each lives
+# in the .env as RECFLARE_<VAR> and rides along as a `--var`. See recflare_vars in
+# packages/tools/src/sh/env.sh. run-wrangler-dev passes the same flags, so one .env tunes
+# both a deploy and a local dev server.
+EXTRA_VARS=$(recflare_vars)
+
 # Vite-built configs set no_bundle (vite already bundled and minified), which is
 # incompatible with --minify. Only pass --minify when wrangler does the bundling.
 MINIFY="--minify"
@@ -136,11 +136,14 @@ MINIFY="--minify"
 
 # Deploy with wrangler using the extracted values as binding variables
 echo "Deploying worker $NAME version $VERSION to $HOST"
+# $EXTRA_VARS is intentionally unquoted — it's a flag list to word-split, and every
+# value in it is an integer, so there's nothing to split on inside a value.
 wrangler deploy \
 	--config "$CONFIG" \
 	--var NAME:"$NAME" \
 	--var SENTRY_RELEASE:"$VERSION" \
 	--var DOMAIN:"$DOMAIN" \
+	$EXTRA_VARS \
 	--domain "$HOST" \
 	$MINIFY \
 	"$@"

packages/tools/bin/run-wrangler-dev

@@ -1,8 +1,19 @@
 #!/bin/sh
 set -eu
 
+. "$(git rev-parse --show-toplevel)/packages/tools/src/sh/env.sh"
+
 NAME=$(jq -r '.name' package.json)
 
+# Tuning knobs come from the same gitignored root .env a deploy reads (RECFLARE_<VAR>, see
+# .env.example), so a knob is configured in exactly one place whether you're running locally
+# or shipping. Unset knobs fall back to the worker's own default constants, same as a deploy.
+#
+# Passed as `--var` rather than left to wrangler's own .env loading: wrangler only reads a
+# .env sitting next to the worker's wrangler.jsonc, which would mean a second file per app.
+recflare_load_env
+EXTRA_VARS=$(recflare_vars)
+
 # Give each worker a stable, unique dev port so `turbo dev` can run them all in
 # parallel without colliding on wrangler's default 8787 (and its 9229 inspector
 # port). The offset is the worker's alphabetical position among its siblings, so
@@ -16,8 +27,10 @@ OFFSET=$(
 PORT=$((8787 + OFFSET - 1))
 INSPECTOR_PORT=$((9229 + OFFSET - 1))
 
+# $EXTRA_VARS is intentionally unquoted — it's a flag list to word-split on.
 exec wrangler dev \
 	--var NAME:"$NAME" \
+	$EXTRA_VARS \
 	--port "$PORT" \
 	--inspector-port "$INSPECTOR_PORT" \
 	"$@"

packages/tools/bin/run-wrangler-migrate

@@ -1,6 +1,8 @@
 #!/bin/sh
 set -eu
 
+. "$(git rev-parse --show-toplevel)/packages/tools/src/sh/env.sh"
+
 # Apply this worker's D1 migrations. Run from a worker directory (e.g. via
 # `bun turbo -F rooms migrate`). Defaults to --remote; pass --local to target the
 # dev SQLite db. Extra args pass through to `wrangler d1 migrations apply`.
@@ -41,16 +43,8 @@ if [ "$LOCAL" -eq 1 ]; then
 	exec wrangler d1 migrations apply "$DB_NAME" "$@"
 fi
 
-# Load RECFLARE_D1 from the gitignored root .env if not already set (mirrors
+# RECFLARE_D1 comes from the gitignored root .env, or from CI secrets, which win over it.
-# run-wrangler-deploy's handling of RECFLARE_DOMAIN). An already-set value wins.
+recflare_load_env
-if [ -z "${RECFLARE_D1:-}" ]; then
-	ENV_FILE="$(git rev-parse --show-toplevel)/.env"
-	if [ -f "$ENV_FILE" ]; then
-		set -a
-		. "$ENV_FILE"
-		set +a
-	fi
-fi
 
 DB_ID=${RECFLARE_D1:-}
 if [ -z "$DB_ID" ]; then

packages/tools/src/sh/env.sh

@@ -0,0 +1,73 @@
+#!/bin/sh
+# Shared by the run-wrangler-* scripts. Source it, don't run it:
+#
+#   . "$(git rev-parse --show-toplevel)/packages/tools/src/sh/env.sh"
+#
+# It lives outside bin/ on purpose — package.json sets directories.bin to bin/, so anything
+# in there becomes a runnable command in node_modules/.bin.
+#
+# RecFlare keeps a single gitignored .env at the repo root (see .env.example) holding
+# everything an operator has to supply: their domain, the ids of the storage resources they
+# created, and any tuning knobs they want to change. That one file feeds both `just deploy`
+# and `just dev`, so a value is never configured twice.
+
+# Names the deploy scripts consume themselves — the domain and the ids of the operator's
+# Cloudflare resources. Everything else in .env is worker config; see recflare_vars.
+RECFLARE_RESERVED="DOMAIN SUBDOMAINS D1 KV SECRETS_STORE ENV_LOADED"
+
+# Load the root .env, letting anything already in the environment win. The file is a local
+# convenience; CI exports the same names as secrets and must not be clobbered by a stray
+# .env in a checkout. Safe to call more than once.
+recflare_load_env() {
+	[ -z "${RECFLARE_ENV_LOADED:-}" ] || return 0
+	RECFLARE_ENV_LOADED=1
+
+	_env_file="$(git rev-parse --show-toplevel)/.env"
+	[ -f "$_env_file" ] || return 0
+
+	# `export -p` re-emits the already-exported values as quoted assignments, so we can put
+	# them back after the file has had its say.
+	_preset=$(export -p | grep -E '(^|[[:space:]])RECFLARE_[A-Za-z0-9_]+=' || true)
+	set -a
+	. "$_env_file"
+	set +a
+	eval "$_preset"
+
+	unset _env_file _preset
+}
+
+# Echo the `--var` flags carrying the operator's tuning knobs, e.g.
+# " --var MAX_ACCOUNTS_PER_IP:10 --var STARTING_TOKENS:250".
+#
+# This is a convention, not a list kept here: every RECFLARE_<VAR> in the environment that
+# isn't one of the RECFLARE_RESERVED deploy inputs above is handed to the worker as
+# `--var <VAR>:<value>`. So RECFLARE_MAX_ACCOUNTS_PER_IP=10 gives every worker
+# MAX_ACCOUNTS_PER_IP=10 — the workers that don't read it simply ignore it, and two workers
+# that read the same knob agree on it for free. Adding a knob means declaring it in the
+# worker's context.ts, reading it there, and documenting it in .env.example; these scripts
+# never need to change and stay free of any knowledge of specific app names.
+#
+# Every knob is optional: unset means no `--var` at all, so the worker falls back to the
+# default constant in its own source, and deleting a line from .env really does restore that
+# default on the next deploy. (Vars are replaced wholesale by a deploy — which is exactly
+# why a value set in the Cloudflare dashboard doesn't survive one.)
+#
+# Values must not contain whitespace: the result is a flag list the caller word-splits.
+# Knobs are numbers and short enums, and real secrets belong in the Secrets Store (which is
+# bound in wrangler.jsonc, not passed through here), so this hasn't been worth the ceremony
+# of an array. Vars also arrive in the Worker as strings (`--var X:3` is "3", not 3), which
+# is why the workers parse them through `intVar` rather than reading them as numbers.
+recflare_vars() {
+	# The sed only ever yields [A-Z0-9_] names, so the eval below can't expand anything else.
+	for _name in $(env | sed -n 's/^RECFLARE_\([A-Z0-9_][A-Z0-9_]*\)=.*/\1/p'); do
+		case " $RECFLARE_RESERVED " in
+		*" $_name "*) continue ;;
+		esac
+
+		eval "_value=\${RECFLARE_${_name}}"
+		[ -n "$_value" ] || continue
+		printf ' --var %s:%s' "$_name" "$_value"
+	done
+
+	unset _name _value
+}