@classytic/arc 2.11.3 → 2.13.1

package/README.md

@@ -1,21 +1,20 @@
 # @classytic/arc
 
-Database-agnostic resource framework for Fastify. One `defineResource()` call → REST + auth + permissions + events + caching + OpenAPI + MCP tools — without boilerplate.
+Database-agnostic resource framework for Fastify. One `defineResource()` call -> REST + auth + permissions + events + caching + OpenAPI + MCP tools.
 
-**v2.11** · Fastify 5+ · Node.js 22+ · ESM only
+Fastify 5+ | Node.js 22+ | ESM only
 
 ```bash
-# Core
 npm install @classytic/arc fastify
 
-# Security defaults that createApp() enables out of the box
+# Security defaults createApp() loads (each opt-out via `cors: false` etc.)
 npm install @fastify/cors @fastify/helmet @fastify/rate-limit @fastify/under-pressure @fastify/sensible
-# (each is opt-out via `cors: false` / `helmet: false` / etc.)
 
-# Pick a storage adapter
-npm install @classytic/mongokit mongoose          # MongoDB (most common)
-# OR @classytic/sqlitekit drizzle-orm better-sqlite3 (sqlite)
-# OR bring your own: implement RepositoryLike from @classytic/repo-core
+# Storage adapter — pick one (kits ship their own adapters under `/adapter`)
+npm install @classytic/mongokit mongoose             # MongoDB → @classytic/mongokit/adapter
+# OR @classytic/sqlitekit drizzle-orm better-sqlite3 # → @classytic/sqlitekit/adapter
+# OR @classytic/prismakit @prisma/client             # → @classytic/prismakit/adapter
+# OR implement DataAdapter / RepositoryLike from @classytic/repo-core/adapter
 ```
 
 ---
@@ -25,7 +24,7 @@ npm install @classytic/mongokit mongoose          # MongoDB (most common)
 | | |
 |---|---|
 | **One call, full REST** | `defineResource({ name, adapter, presets, permissions })` → `GET /`, `GET /:id`, `POST /`, `PATCH /:id`, `DELETE /:id` + custom routes + actions |
-| **DB-agnostic** | Mongoose, Drizzle/sqlitekit, or any `RepositoryLike` impl — swap backends without rewriting routes. (Prisma adapter is experimental: implemented, no integration tests yet.) |
+| **DB-agnostic** | Mongoose (`@classytic/mongokit/adapter`), Drizzle/SQLite (`@classytic/sqlitekit/adapter`), Prisma (`@classytic/prismakit/adapter`), or any `RepositoryLike` impl — swap backends without rewriting routes. Adapter contract lives in `@classytic/repo-core/adapter`; arc 2.12 ships zero kit-specific adapters. |
 | **Multi-tenant by default** | Tenant-field auto-injected, scope-aware queries, per-org cache keys, elevation events. |
 | **Tree-shakable subpaths** | `@classytic/arc/auth`, `/events`, `/cache`, `/mcp`, `/integrations/jobs` — pay only for what you import. |
 | **MCP tools, free** | Resources auto-generate Model Context Protocol tools for AI agents. Same permissions, same field rules. |
@@ -40,12 +39,19 @@ import { createApp, loadResources } from '@classytic/arc/factory';
 
 await mongoose.connect(process.env.DB_URI);
 
+// Fail fast on missing CORS env — silent `undefined` here drops to surprising
+// browser defaults. Browser apps: declare an explicit allowlist (below).
+// Server-to-server / API-key services: `cors: { origin: '*', credentials: false }`
+// or `cors: false` to disable entirely (CORS is a browser-only concern).
+const ALLOWED_ORIGINS = process.env.ALLOWED_ORIGINS;
+if (!ALLOWED_ORIGINS) throw new Error('ALLOWED_ORIGINS env is required');
+
 const app = await createApp({
   preset: 'production',
   resourcePrefix: '/api/v1',
   resources: await loadResources(import.meta.url),  // auto-discover *.resource.ts
   auth: { type: 'jwt', jwt: { secret: process.env.JWT_SECRET } },
-  cors: { origin: process.env.ALLOWED_ORIGINS?.split(',') },
+  cors: { origin: ALLOWED_ORIGINS.split(','), credentials: true },
 });
 
 await app.listen({ port: 8040, host: '0.0.0.0' });
@@ -67,15 +73,16 @@ resources: async () => {
 },
 ```
 
-`loadResources({ context })` (2.11.1+) threads engine handles into resources whose default export is `(ctx) => defineResource(...)`. No parallel factory files, no `exclude: [...]` bookkeeping.
+`loadResources({ context })` threads engine handles into resources whose default export is `(ctx) => defineResource(...)`. No parallel factory files, no `exclude: [...]` bookkeeping.
 
 ---
 
 ## Define a resource
 
 ```typescript
-import { defineResource, createMongooseAdapter } from '@classytic/arc';
+import { defineResource } from '@classytic/arc';
 import { allowPublic, requireRoles, requireAuth } from '@classytic/arc/permissions';
+import { createMongooseAdapter } from '@classytic/mongokit/adapter';
 import { buildCrudSchemasFromModel } from '@classytic/mongokit';
 import ProductModel from './product.model.js';
 import productRepository from './product.repository.js';
@@ -167,7 +174,7 @@ auth: { type: 'custom', plugin: myAuthPlugin }
 auth: false
 ```
 
-Better Auth + Mongoose `populate()`: import `registerBetterAuthMongooseModels` from `@classytic/arc/auth/mongoose` to register `strict: false` stub models for BA collections. Subpath gate keeps Mongoose out of Prisma/Drizzle bundles.
+Better Auth + arc resources over BA tables: the kit owns the bridge. `@classytic/mongokit/better-auth` ships `createBetterAuthOverlay()` (per-collection `DataAdapter` for `defineResource`) and `registerBetterAuthStubs()` (bulk stub models for `populate()`). Sqlitekit users hand-roll the Drizzle table — see [auth.md](skills/arc/references/auth.md).
 
 ---
 
@@ -177,14 +184,16 @@ Tree-shake by importing only the subpath you need:
 
 | Subpath | Purpose |
 |---|---|
-| `@classytic/arc` | `defineResource`, `BaseController`, `createMongooseAdapter`, error classes |
+| `@classytic/arc` | `defineResource`, `BaseController`, error classes |
+| `@classytic/repo-core/adapter` | Adapter contract types: `DataAdapter`, `RepositoryLike`, `AdapterRepositoryInput`, `asRepositoryLike`, `isRepository`. **Imported from repo-core directly** — arc deliberately does not re-export the contract to keep one source of truth. |
 | `@classytic/arc/factory` | `createApp`, `loadResources`, presets |
 | `@classytic/arc/auth` | JWT + Better Auth adapters |
-| `@classytic/arc/auth/mongoose` | Better Auth Mongoose stub models (opt-in) |
+| `@classytic/mongokit/better-auth` | BA overlay for Mongoose: `createBetterAuthOverlay`, `registerBetterAuthStubs` (kit-owned) |
+| `@classytic/repo-core/better-auth` | BA collection registry shared by every kit's overlay |
 | `@classytic/arc/permissions` | All permission helpers |
 | `@classytic/arc/scope` | `RequestScope` accessors (`isMember`, `isElevated`, `getOrgId`, …) |
 | `@classytic/arc/cache` | `QueryCache`, transports, plugin |
-| `@classytic/arc/events` | Event plugin, transports, outbox |
+| `@classytic/arc/events` | Event plugin, `MemoryEventTransport`, outbox (event types live in `@classytic/primitives/events`) |
 | `@classytic/arc/events/redis` · `/redis-stream` | Redis Pub/Sub + Streams transports (opt-in) |
 | `@classytic/arc/plugins` | Health, request-id, versioning, tracing, response-cache |
 | `@classytic/arc/integrations/jobs` | BullMQ job dispatcher |
@@ -206,7 +215,7 @@ const ctx = await createTestApp({
   authMode: 'jwt',
   connectMongoose: true,           // in-memory Mongo + Mongoose connect
 });
-ctx.auth.register('admin', { user: { id: '1', roles: ['admin'] }, orgId: 'org-1' });
+ctx.auth.register('admin', { user: { id: '1', role: 'admin' }, orgId: 'org-1' });
 
 const res = await ctx.app.inject({
   method: 'POST',