Configurable Monorepo: User-zone config, route hooks, and config validation

[thinkdj]

• User-zone file separation: ottabase.config.ts, wrangler.jsonc, and ottabase/ are now gitignored with tracked .example/.template counterparts, so framework updates never overwrite user customizations
• Route registration hook: Custom/premium packages can register API routes via ottabase/config.routes.ts without editing framework-owned router.ts — mirrors the existing config.migrations.ts pattern for tables
• Config validation at startup: defineOttabaseConfig() now throws on missing required fields (appId, appName) and warns on unrecognized keys at all nesting levels (catches typos like packges or features.authBehaviour that previously fell silently to defaults)
• Config pipeline fixes: Email from/sesRegion and auth behavior flags (sessionMaxAge, requireEmailVerified, disableCredentials, verbose) moved from env vars to ottabase.config.ts with env var override kept for backward compat
• Package route guards: Built-in package routes (ottablog, shortlinks, referrals, brandEngine) return 404 with PACKAGE_DISABLED code when toggled off in config

Key files

File	Change
ottabase.template/config.routes.ts	New — user-zone route registration scaffold
worker/routes/types.ts	New — shared ApiRouteContext type (avoids circular imports)
worker/routes/router.ts	Wires custom routes as last fallback in resolveApiRoute()
packages/config/src/createAppConfig.ts	Adds validateOttabaseConfig() with 3-level-deep key checking
ottabase.config.example.ts	Replaces ottabase.config.ts as tracked template
wrangler.example.jsonc	Replaces wrangler.jsonc as tracked template
.gitignore	Ignores user working copies

Test plan

• 34 config tests pass (12 new validation tests)
• pnpm dev:worker starts without config validation errors
• Typo in ottabase.config.ts (e.g. packges) produces [ottabase] Unknown key warning
• Missing appId throws clear error at startup
• Custom route in ottabase/config.routes.ts responds correctly
• Disabled package routes return 404 PACKAGE_DISABLED

[Copilot]

Pull request overview

This pull request introduces a configurable monorepo architecture with user-zone file separation, custom route registration, and config validation. The key innovation is gitignoring ottabase.config.ts, wrangler.jsonc, and the ottabase/ directory (which contain user customizations) while providing tracked .example and .template counterparts, ensuring framework updates never overwrite user code.

Changes:

• User-zone file separation: Three user-owned areas (ottabase.config.ts, wrangler.jsonc, ottabase/) are now gitignored with tracked templates, preventing framework updates from overwriting customizations
• Config validation: defineOttabaseConfig() validates required fields and warns on typos via recursive key checking (3 levels deep)
• Route registration hook: Custom packages can register API routes via ottabase/config.routes.ts using the new ApiRouteContext type, called as final fallback in the router
• Template scaffolding: Queue handlers, Todo model, migration system, and helper utilities provided in ottabase.template/ as starting point
• CI/CD updates: Workflows updated to use wrangler.example.jsonc (tracked) instead of wrangler.jsonc (gitignored)

Reviewed changes

Copilot reviewed 15 out of 26 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
packages/config/src/createAppConfig.ts	Adds validateOttabaseConfig() with 3-level recursive key validation; warns on typos, throws on missing required fields
packages/config/src/__tests__/config.test.ts	12 new validation tests covering required fields, typos, and nested key warnings
packages/config/src/index.ts	Exports validateOttabaseConfig for external use
worker/routes/types.ts	New file defining shared ApiRouteContext interface to avoid circular imports
worker/routes/router.ts	Imports custom routes handler and calls it as final fallback after built-in routes
ottabase.template/config.routes.ts	User-zone scaffold for custom route registration with documentation
ottabase.template/config.migrations.ts	Updated comments referencing route registration in config.routes.ts
ottabase.template/queue/index.ts	Queue handler registry with DLQ support, stats tracking, and KV persistence
ottabase.template/queue/handlers.ts	Email, order processing, report generation, and sync job handlers
ottabase.template/models/Todo.ts	Example app-specific fat model with helper methods
ottabase.template/models/Todo.schema.ts	Drizzle schema for todos table
ottabase.template/migrations/index.ts	Migration registry combining core, app, and package migrations
ottabase.template/migrations/README.md	Comprehensive migration system documentation (337 lines)
ottabase.template/helpers/referral-attribution.ts	Server-side referral attribution helper with context capture
ottabase.template/helpers/__tests__/referral-attribution.test.ts	Test coverage for referral attribution edge cases
ottabase.template/db/schemas-helper.ts	Collects schemas from core, app, and package sources for autoInit
ottabase.template/db/schema.ts	Re-exports all table schemas for drizzle-kit
ottabase.config.example.ts	Updated template with validation documentation and route registration instructions
wrangler.example.jsonc	Updated header comments explaining CI usage and local workflow
cloudflare-config.json	Changed wranglerConfig to point to wrangler.example.jsonc
.gitignore	Adds gitignore entries for ottabase.config.ts, wrangler.jsonc, and ottabase/ directory
README.md	Major updates: first-time setup section, file ownership table, custom routes documentation, directory structure
.github/workflows/pr-preview.yml	Updates wrangler config references from wrangler.jsonc to wrangler.example.jsonc
.github/workflows/deploy.yml	Updates wrangler config references and comments
.github/README.md	Documentation updates for new wrangler config pattern

[Copilot]

The console.warn spy is created and restored within individual test cases, but if a test fails or throws an error before reaching warnSpy.mockRestore(), the spy will leak into subsequent tests. According to the stored memory about this codebase, "Global vitest setup does not call vi.restoreAllMocks()/vi.resetAllMocks() between tests; individual tests must restore spies/mocks they create."

Consider using afterEach to ensure cleanup happens even when tests fail:

describe('defineOttabaseConfig – validation integration', () => {
    let warnSpy: ReturnType<typeof vi.spyOn>;

    beforeEach(() => {
        warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
    });

    afterEach(() => {
        warnSpy?.mockRestore();
    });

    // tests...
});

This follows the same pattern needed elsewhere in the codebase due to the global setup not handling mock restoration.