@classytic/arc 2.11.3 → 2.11.4

package/README.md

@@ -1,21 +1,19 @@
 # @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)
+# Storage adapter — pick one
+npm install @classytic/mongokit mongoose          # MongoDB
 # OR @classytic/sqlitekit drizzle-orm better-sqlite3 (sqlite)
-# OR bring your own: implement RepositoryLike from @classytic/repo-core
+# OR implement RepositoryLike from @classytic/repo-core
 ```
 
 ---
@@ -40,12 +38,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,7 +72,7 @@ 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.
 
 ---
 
@@ -206,7 +211,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',

package/dist/EventTransport-BFQjw9pB.mjs

@@ -0,0 +1,133 @@
+//#region src/events/EventTransport.ts
+/**
+* In-memory event transport (default)
+* Events are delivered synchronously within the process.
+* Not suitable for multi-instance deployments.
+*/
+var MemoryEventTransport = class {
+	name = "memory";
+	handlers = /* @__PURE__ */ new Map();
+	logger;
+	constructor(options) {
+		this.logger = options?.logger ?? console;
+	}
+	async publish(event) {
+		const exactHandlers = this.handlers.get(event.type) ?? /* @__PURE__ */ new Set();
+		const wildcardHandlers = this.handlers.get("*") ?? /* @__PURE__ */ new Set();
+		const patternHandlers = /* @__PURE__ */ new Set();
+		for (const [pattern, handlers] of this.handlers.entries()) if (pattern.endsWith(".*")) {
+			const prefix = pattern.slice(0, -2);
+			if (event.type.startsWith(`${prefix}.`)) for (const h of handlers) patternHandlers.add(h);
+		}
+		const allHandlers = new Set([
+			...exactHandlers,
+			...wildcardHandlers,
+			...patternHandlers
+		]);
+		for (const handler of allHandlers) try {
+			await handler(event);
+		} catch (err) {
+			this.logger.error(`[EventTransport] Handler error for ${event.type}:`, err);
+		}
+	}
+	/**
+	* Reference `publishMany` implementation — delegates to `publish()` in order.
+	*
+	* Production transports (Kafka, Redis pipeline, SQS batch) should override
+	* this with a single batched network call. Memory transport has nothing to
+	* batch, so we just loop — the loop still returns a proper result map so
+	* `EventOutbox.relay` can exercise the batched code path in tests.
+	*/
+	async publishMany(events) {
+		const results = /* @__PURE__ */ new Map();
+		for (const event of events) try {
+			await this.publish(event);
+			results.set(event.meta.id, null);
+		} catch (err) {
+			results.set(event.meta.id, err instanceof Error ? err : new Error(String(err)));
+		}
+		return results;
+	}
+	async subscribe(pattern, handler) {
+		if (!this.handlers.has(pattern)) this.handlers.set(pattern, /* @__PURE__ */ new Set());
+		this.handlers.get(pattern)?.add(handler);
+		return () => {
+			const set = this.handlers.get(pattern);
+			if (set) {
+				set.delete(handler);
+				if (set.size === 0) this.handlers.delete(pattern);
+			}
+		};
+	}
+	async close() {
+		this.handlers.clear();
+	}
+};
+/**
+* Create a domain event with auto-generated metadata.
+*
+* `id` and `timestamp` are filled in; everything else is caller-controlled.
+* Set `schemaVersion` explicitly for any event type you plan to evolve.
+*/
+function createEvent(type, payload, meta) {
+	return {
+		type,
+		payload,
+		meta: {
+			id: crypto.randomUUID(),
+			timestamp: /* @__PURE__ */ new Date(),
+			...meta
+		}
+	};
+}
+/**
+* Create a child event that chains causation from a parent event.
+*
+* Rules:
+*  - `causationId` is set to the parent's `id` (direct cause)
+*  - `correlationId` is inherited from the parent if set, else falls back
+*    to the parent's `id` (root correlation)
+*  - `userId` / `organizationId` are inherited when not overridden so the
+*    whole chain stays scoped to the originating principal/tenant
+*
+* Caller-supplied `meta` wins over inherited fields — pass `{ userId: newActor }`
+* to override when a subsystem acts on behalf of a different principal.
+*
+* @example
+* ```typescript
+* const orderPlaced = createEvent('order.placed', { orderId: 'o1' }, {
+*   correlationId: req.id, userId: user.id,
+* });
+* await events.publish(orderPlaced);
+*
+* // Downstream handler emits a child event:
+* const reserved = createChildEvent(orderPlaced, 'inventory.reserved', {
+*   orderId: 'o1', skus: ['sku-1', 'sku-2'],
+* });
+* // reserved.meta.causationId   === orderPlaced.meta.id
+* // reserved.meta.correlationId === orderPlaced.meta.correlationId
+* // reserved.meta.userId        === user.id   (inherited)
+* ```
+*/
+function createChildEvent(parent, type, payload, meta) {
+	const inherited = {
+		correlationId: parent.meta.correlationId ?? parent.meta.id,
+		causationId: parent.meta.id
+	};
+	if (parent.meta.userId !== void 0) inherited.userId = parent.meta.userId;
+	if (parent.meta.organizationId !== void 0) inherited.organizationId = parent.meta.organizationId;
+	if (parent.meta.source !== void 0) inherited.source = parent.meta.source;
+	if (parent.meta.idempotencyKey !== void 0) inherited.idempotencyKey = parent.meta.idempotencyKey;
+	return {
+		type,
+		payload,
+		meta: {
+			id: crypto.randomUUID(),
+			timestamp: /* @__PURE__ */ new Date(),
+			...inherited,
+			...meta
+		}
+	};
+}
+//#endregion
+export { createChildEvent as n, createEvent as r, MemoryEventTransport as t };

package/dist/{QueryCache-DOBNHBE0.d.mts → QueryCache-D41bfdBB.d.mts}

@@ -1,4 +1,4 @@
-import { r as CacheStore } from "./interface-Da0r7Lna.mjs";
+import { r as CacheStore } from "./interface-beEtJyWM.mjs";
 
 //#region src/cache/QueryCache.d.ts
 /** Metadata wrapper stored in CacheStore */

package/dist/adapters/index.d.mts

@@ -1,3 +1,3 @@
-import { An as RelationMetadata, En as AdapterFactory, Mn as SchemaMetadata, Nn as ValidationResult, On as DataAdapter, jn as RepositoryLike, kn as FieldMetadata } from "../index-6u4_Gg6G.mjs";
-import { a as PrismaQueryParserOptions, c as MongooseAdapterOptions, d as DrizzleAdapterOptions, f as createDrizzleAdapter, i as PrismaQueryParser, l as createMongooseAdapter, n as PrismaAdapterOptions, o as createPrismaAdapter, r as PrismaQueryOptions, s as MongooseAdapter, t as PrismaAdapter, u as DrizzleAdapter } from "../index-BbMrcvGp.mjs";
-export { AdapterFactory, DataAdapter, DrizzleAdapter, DrizzleAdapterOptions, FieldMetadata, MongooseAdapter, MongooseAdapterOptions, PrismaAdapter, PrismaAdapterOptions, PrismaQueryOptions, PrismaQueryParser, PrismaQueryParserOptions, RelationMetadata, RepositoryLike, SchemaMetadata, ValidationResult, createDrizzleAdapter, createMongooseAdapter, createPrismaAdapter };
+import { An as FieldMetadata, Dn as AdapterRepositoryInput, En as AdapterFactory, Fn as asRepositoryLike, Mn as RepositoryLike, Nn as SchemaMetadata, Pn as ValidationResult, jn as RelationMetadata, kn as DataAdapter } from "../index-CXXRbnf8.mjs";
+import { a as PrismaQueryParserOptions, c as MongooseAdapterOptions, d as DrizzleAdapterOptions, f as createDrizzleAdapter, i as PrismaQueryParser, l as createMongooseAdapter, n as PrismaAdapterOptions, o as createPrismaAdapter, r as PrismaQueryOptions, s as MongooseAdapter, t as PrismaAdapter, u as DrizzleAdapter } from "../index-Rg8axYPz.mjs";
+export { AdapterFactory, AdapterRepositoryInput, DataAdapter, DrizzleAdapter, DrizzleAdapterOptions, FieldMetadata, MongooseAdapter, MongooseAdapterOptions, PrismaAdapter, PrismaAdapterOptions, PrismaQueryOptions, PrismaQueryParser, PrismaQueryParserOptions, RelationMetadata, RepositoryLike, SchemaMetadata, ValidationResult, asRepositoryLike, createDrizzleAdapter, createMongooseAdapter, createPrismaAdapter };

package/dist/adapters/index.mjs

@@ -1,2 +1,2 @@
-import { a as createMongooseAdapter, i as MongooseAdapter, n as PrismaQueryParser, o as DrizzleAdapter, r as createPrismaAdapter, s as createDrizzleAdapter, t as PrismaAdapter } from "../adapters-D0tT2Tyo.mjs";
-export { DrizzleAdapter, MongooseAdapter, PrismaAdapter, PrismaQueryParser, createDrizzleAdapter, createMongooseAdapter, createPrismaAdapter };
+import { a as createMongooseAdapter, c as createDrizzleAdapter, i as MongooseAdapter, n as PrismaQueryParser, o as asRepositoryLike, r as createPrismaAdapter, s as DrizzleAdapter, t as PrismaAdapter } from "../adapters-DUUiiimH.mjs";
+export { DrizzleAdapter, MongooseAdapter, PrismaAdapter, PrismaQueryParser, asRepositoryLike, createDrizzleAdapter, createMongooseAdapter, createPrismaAdapter };

package/dist/{adapters-D0tT2Tyo.mjs → adapters-DUUiiimH.mjs}

@@ -264,6 +264,21 @@ function createDrizzleAdapter(options) {
 	return new DrizzleAdapter(options);
 }
 //#endregion
+//#region src/adapters/interface.ts
+/**
+* Widen a permissive `AdapterRepositoryInput<TDoc>` to arc's strict
+* `RepositoryLike<TDoc>` view. Single-source escape hatch for the
+* filter-IR drift documented on `AdapterRepositoryInput`.
+*
+* Arc internals (audit / outbox / idempotency, BaseController) still see
+* the IR-aware `RepositoryLike`; only the call paths arc exercises are
+* shared between the two views, and those use the narrower
+* `Record<string, unknown>` filter shape both sides agree on.
+*/
+function asRepositoryLike(input) {
+	return input;
+}
+//#endregion
 //#region src/adapters/mongoose.ts
 /**
 * Mongoose data adapter with proper type safety
@@ -280,7 +295,7 @@ var MongooseAdapter = class {
 		if (!isMongooseModel(options.model)) throw new TypeError("MongooseAdapter: Invalid model. Expected Mongoose Model instance.\nUsage: createMongooseAdapter({ model: YourModel, repository: yourRepo })");
 		if (!isRepository(options.repository)) throw new TypeError("MongooseAdapter: Invalid repository. Expected StandardRepo instance.\nUsage: createMongooseAdapter({ model: YourModel, repository: yourRepo })");
 		this.model = options.model;
-		this.repository = options.repository;
+		this.repository = asRepositoryLike(options.repository);
 		this.schemaGenerator = options.schemaGenerator;
 		this.name = `MongooseAdapter<${options.model.modelName}>`;
 	}
@@ -946,4 +961,4 @@ function createPrismaAdapter(options) {
 	return new PrismaAdapter(options);
 }
 //#endregion
-export { createMongooseAdapter as a, MongooseAdapter as i, PrismaQueryParser as n, DrizzleAdapter as o, createPrismaAdapter as r, createDrizzleAdapter as s, PrismaAdapter as t };
+export { createMongooseAdapter as a, createDrizzleAdapter as c, MongooseAdapter as i, PrismaQueryParser as n, asRepositoryLike as o, createPrismaAdapter as r, DrizzleAdapter as s, PrismaAdapter as t };

package/dist/audit/index.d.mts

@@ -1,5 +1,5 @@
-import { jn as RepositoryLike } from "../index-6u4_Gg6G.mjs";
-import { d as UserBase } from "../fields-C8Y0XLAu.mjs";
+import { Mn as RepositoryLike } from "../index-CXXRbnf8.mjs";
+import { d as UserBase } from "../fields-BRjxOAFp.mjs";
 import { FastifyPluginAsync } from "fastify";
 
 //#region src/audit/stores/interface.d.ts

package/dist/auth/index.d.mts

@@ -1,7 +1,7 @@
-import { Ot as AuthHelpers, kt as AuthPluginOptions } from "../index-6u4_Gg6G.mjs";
-import { c as PermissionCheck } from "../fields-C8Y0XLAu.mjs";
-import { t as ExternalOpenApiPaths } from "../externalPaths-Bapitwvd.mjs";
-import { a as SessionManagerOptions, c as createSessionManager, i as SessionData, n as MemorySessionStoreOptions, o as SessionManagerResult, r as SessionCookieOptions, s as SessionStore, t as MemorySessionStore } from "../sessionManager-D-oNWHz3.mjs";
+import { Ot as AuthHelpers, kt as AuthPluginOptions } from "../index-CXXRbnf8.mjs";
+import { c as PermissionCheck } from "../fields-BRjxOAFp.mjs";
+import { t as ExternalOpenApiPaths } from "../externalPaths-BD5nw6St.mjs";
+import { a as SessionManagerOptions, c as createSessionManager, i as SessionData, n as MemorySessionStoreOptions, o as SessionManagerResult, r as SessionCookieOptions, s as SessionStore, t as MemorySessionStore } from "../sessionManager-C4Le_UB3.mjs";
 import { FastifyPluginAsync, FastifyReply as FastifyReply$1, FastifyRequest } from "fastify";
 
 //#region src/auth/authPlugin.d.ts

package/dist/auth/redis-session.d.mts

@@ -1,4 +1,4 @@
-import { i as SessionData, s as SessionStore } from "../sessionManager-D-oNWHz3.mjs";
+import { i as SessionData, s as SessionStore } from "../sessionManager-C4Le_UB3.mjs";
 
 //#region src/auth/redis-session.d.ts
 /** Minimal Redis client interface — compatible with ioredis */

package/dist/cache/index.d.mts

@@ -1,6 +1,6 @@
-import { n as CacheStats, r as CacheStore, t as CacheLogger } from "../interface-Da0r7Lna.mjs";
-import { a as QueryCacheConfig, i as QueryCache, n as CacheResult, r as CacheStatus, t as CacheEnvelope } from "../QueryCache-DOBNHBE0.mjs";
-import { i as queryCachePlugin, n as QueryCacheDefaults, r as QueryCachePluginOptions, t as CrossResourceRule } from "../queryCachePlugin-BUXBSm4F.mjs";
+import { n as CacheStats, r as CacheStore, t as CacheLogger } from "../interface-beEtJyWM.mjs";
+import { a as QueryCacheConfig, i as QueryCache, n as CacheResult, r as CacheStatus, t as CacheEnvelope } from "../QueryCache-D41bfdBB.mjs";
+import { i as queryCachePlugin, n as QueryCacheDefaults, r as QueryCachePluginOptions, t as CrossResourceRule } from "../queryCachePlugin-CqMdLI2-.mjs";
 
 //#region src/cache/keys.d.ts
 /**

package/dist/cli/commands/docs.mjs

@@ -1,5 +1,5 @@
 import { t as ResourceRegistry } from "../../ResourceRegistry-DkAeAuTX.mjs";
-import { t as buildOpenApiSpec } from "../../openapi-BGUn7Ki1.mjs";
+import { t as buildOpenApiSpec } from "../../openapi-D7G1V7ex.mjs";
 import { dirname, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 import { mkdirSync, writeFileSync } from "node:fs";

package/dist/cli/commands/generate.mjs

@@ -1,4 +1,4 @@
-import { t as pluralize } from "../../pluralize-BneOJkpi.mjs";
+import { t as pluralize } from "../../pluralize-CWP6MB39.mjs";
 import { join } from "node:path";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 //#region src/cli/commands/generate.ts

package/dist/cli/commands/init.mjs

@@ -87,42 +87,103 @@ function existsSync$1(filePath) {
 	}
 }
 /**
-* Install dependencies using the detected package manager
+* Single source of truth for scaffolded project dependencies.
+*
+* Versions are pinned to the floor each subsystem requires — peer-dep
+* minimums on Arc, kit minimums (mongokit ≥ 3.11, repo-core ≥ 0.2,
+* mongoose ≥ 9.4.1), and major-version stable for the rest. The carets
+* allow minor + patch upgrades without breaking arc's contract, while
+* preventing the silent breakage of `@latest` on a kit floor bump.
+*
+* Used by both `packageJsonTemplate` (declares the deps in the generated
+* `package.json` so `npm install` works without a pre-pass) and
+* `installDependencies` (runs the package manager's `install` against
+* the declared ranges). One source — no drift.
 */
-async function installDependencies(projectPath, config, pm) {
-	const deps = [
-		"@classytic/arc@latest",
-		"fastify@latest",
-		"@fastify/cors@latest",
-		"@fastify/helmet@latest",
-		"@fastify/rate-limit@latest",
-		"@fastify/sensible@latest",
-		"@fastify/under-pressure@latest",
-		"dotenv@latest"
-	];
-	if (config.auth === "better-auth") deps.push("better-auth@^1.6.0", "mongodb@latest");
-	else deps.push("@fastify/jwt@latest", "bcryptjs@latest");
-	if (config.adapter === "mongokit") deps.push("@classytic/mongokit@^3.11.0", "@classytic/repo-core@^0.2.0", "mongoose@^9.4.1");
-	const devDeps = ["vitest@latest", "pino-pretty@latest"];
-	if (config.typescript) devDeps.push("typescript@latest", "@types/node@latest", "tsx@latest");
-	const installCmd = getInstallCommand(pm, deps, false);
-	const installDevCmd = getInstallCommand(pm, devDeps, true);
+const SCAFFOLD_DEP_VERSIONS = {
+	core: {
+		"@classytic/arc": "^2.11.3",
+		"@fastify/cors": "^11.0.0",
+		"@fastify/helmet": "^13.0.0",
+		"@fastify/rate-limit": "^10.0.0",
+		"@fastify/sensible": "^6.0.0",
+		"@fastify/under-pressure": "^9.0.0",
+		dotenv: "^17.0.0",
+		fastify: "^5.8.0"
+	},
+	authJwt: {
+		"@fastify/jwt": "^10.0.0",
+		bcryptjs: "^3.0.0"
+	},
+	authBetterAuth: {
+		"better-auth": "^1.6.0",
+		mongodb: "^6.10.0"
+	},
+	adapterMongokit: {
+		"@classytic/mongokit": "^3.11.0",
+		"@classytic/repo-core": "^0.2.0",
+		mongoose: "^9.4.1"
+	},
+	devCommon: {
+		"pino-pretty": "^13.0.0",
+		vitest: "^4.0.0"
+	},
+	devTypescript: {
+		"@types/node": "^22.0.0",
+		tsx: "^4.21.0",
+		typescript: "^5.6.0"
+	},
+	typesJwt: { "@types/bcryptjs": "^3.0.0" }
+};
+/**
+* Resolve the dependency manifest for a scaffold configuration.
+*
+* Returns sorted records (alphabetical by package name) so the generated
+* `package.json` is deterministic — diffs across re-runs stay clean.
+*/
+function resolveScaffoldDependencies(config) {
+	const dependencies = { ...SCAFFOLD_DEP_VERSIONS.core };
+	const devDependencies = { ...SCAFFOLD_DEP_VERSIONS.devCommon };
+	if (config.auth === "better-auth") Object.assign(dependencies, SCAFFOLD_DEP_VERSIONS.authBetterAuth);
+	else {
+		Object.assign(dependencies, SCAFFOLD_DEP_VERSIONS.authJwt);
+		if (config.typescript) Object.assign(devDependencies, SCAFFOLD_DEP_VERSIONS.typesJwt);
+	}
+	if (config.adapter === "mongokit") Object.assign(dependencies, SCAFFOLD_DEP_VERSIONS.adapterMongokit);
+	if (config.typescript) Object.assign(devDependencies, SCAFFOLD_DEP_VERSIONS.devTypescript);
+	return {
+		dependencies: sortByKey(dependencies),
+		devDependencies: sortByKey(devDependencies)
+	};
+}
+/**
+* Sort a record alphabetically by key — package.json convention.
+*/
+function sortByKey(record) {
+	return Object.fromEntries(Object.entries(record).sort(([a], [b]) => a.localeCompare(b)));
+}
+/**
+* Install dependencies using the detected package manager.
+*
+* Dependencies are already declared in the generated `package.json` (see
+* `packageJsonTemplate`), so a single plain `install` resolves the full
+* tree. No two-pass `npm add` flow — the manifest is the source of truth.
+*/
+async function installDependencies(projectPath, _config, pm) {
 	console.log(`  Installing dependencies...`);
-	await runCommand(installCmd, projectPath);
-	console.log(`  Installing dev dependencies...`);
-	await runCommand(installDevCmd, projectPath);
+	await runCommand(getInstallCommand(pm), projectPath);
 	console.log(`\nDependencies installed successfully.`);
 }
 /**
-* Get the install command for a package manager
+* Get the plain `install` command for a package manager. Reads the declared
+* dependencies from the project's `package.json`.
 */
-function getInstallCommand(pm, packages, isDev) {
-	const pkgList = packages.join(" ");
+function getInstallCommand(pm) {
 	switch (pm) {
-		case "pnpm": return `pnpm add ${isDev ? "-D" : ""} ${pkgList}`;
-		case "yarn": return `yarn add ${isDev ? "-D" : ""} ${pkgList}`;
-		case "bun": return `bun add ${isDev ? "-d" : ""} ${pkgList}`;
-		default: return `npm install ${isDev ? "--save-dev" : ""} ${pkgList}`;
+		case "pnpm": return "pnpm install";
+		case "yarn": return "yarn install";
+		case "bun": return "bun install";
+		default: return "npm install";
 	}
 }
 /**
@@ -267,6 +328,7 @@ async function createProjectStructure(projectPath, config) {
 	}
 }
 function packageJsonTemplate(config) {
+	const { dependencies, devDependencies } = resolveScaffoldDependencies(config);
 	const scripts = config.typescript ? config.edge ? {
 		dev: "tsx watch src/index.ts",
 		build: "tsc",
@@ -309,6 +371,8 @@ function packageJsonTemplate(config) {
 			"#utils/*": "./src/utils/*"
 		},
 		scripts,
+		dependencies,
+		devDependencies,
 		engines: { node: ">=22" }
 	}, null, 2);
 }
@@ -1808,8 +1872,10 @@ describe('Example Resource', () => {
       authMode: 'jwt',
 ${config.adapter === "mongokit" ? "      connectMongoose: true,\n" : ""}    });
 
+    // Arc's permission engine reads singular user.role — string,
+    // comma-separated string, or array all normalise via getUserRoles().
     ctx.auth${ts ? "!" : ""}.register('admin', {
-      user: { id: '1', roles: ['admin'] },
+      user: { id: '1', role: 'admin' },
       orgId: 'org-1',
     });
   });
@@ -1913,13 +1979,19 @@ userSchema.methods.removeOrganization = function(organizationId${ts ? ": Types.O
 userSchema.index({ 'organizations.organizationId': 1 });
 ` : "";
 	const userType = ts ? `
-type PlatformRole = 'user' | 'admin' | 'superadmin';
+const PLATFORM_ROLES = ['user', 'admin', 'superadmin'] as const;
+type PlatformRole = typeof PLATFORM_ROLES[number];
 
+/**
+ * Comma-separated list of platform roles (Better Auth admin-plugin convention).
+ * Single role: 'admin'. Multiple: 'admin,trainer'. Arc's permission engine
+ * normalises both forms via getUserRoles() — see @classytic/arc/scope.
+ */
 type User = {
   name: string;
   email: string;
   password: string;
-  roles: PlatformRole[];${config.tenant === "multi" ? `
+  role: string;${config.tenant === "multi" ? `
   organizations: UserOrganization[];` : ""}
   resetPasswordToken?: string;
   resetPasswordExpires?: Date;
@@ -1958,11 +2030,21 @@ const userSchema = new Schema${ts ? "<User, UserModel, UserMethods>" : ""}(
     },
     password: { type: String, required: true },
 
-    // Platform roles
-    roles: {
-      type: [String],
-      enum: ['user', 'admin', 'superadmin'],
-      default: ['user'],
+    // Platform role — singular field, matches Arc's permission engine
+    // (req.user.role) and Better Auth's admin-plugin convention.
+    // Comma-separated for multi-role users (e.g. 'admin,trainer');
+    // getUserRoles() in @classytic/arc/scope normalises both forms.
+    role: {
+      type: String,
+      required: true,
+      default: 'user',
+      index: true,
+      validate: {
+        validator: (v${ts ? ": string" : ""}) =>
+          /^(user|admin|superadmin)(,(user|admin|superadmin))*$/.test(v),
+        message: (props${ts ? ": { value: string }" : ""}) =>
+          \`Invalid role "\${props.value}" — expected one or more of user|admin|superadmin\`,
+      },
     },
 ${orgSchema}
     // Password reset
@@ -2381,7 +2463,7 @@ export async function register(request${ts ? ": FastifyRequest" : ""}, reply${ts
     }
 
     // Create user
-    await userRepository.create({ name, email, password, roles: ['user'] });
+    await userRepository.create({ name, email, password, role: 'user' });
 
     return reply.code(201).send({ success: true, message: 'User registered successfully' });
   } catch (error) {
@@ -2506,10 +2588,10 @@ export async function updateUserProfile(request${ts ? ": FastifyRequest" : ""},
     const userId = (request${ts ? " as any" : ""}).user?._id || (request${ts ? " as any" : ""}).user?.id;
     const updates = { ...request.body${ts ? " as any" : ""} };
 
-    // Prevent updating protected fields
-    if ('password' in updates) delete updates.password;
-    if ('roles' in updates) delete updates.roles;
-    if ('organizations' in updates) delete updates.organizations;
+    // Prevent updating protected fields — auth-managed only
+    delete updates.password;
+    delete updates.role;
+    delete updates.organizations;
 
     const user = await userRepository.Model.findByIdAndUpdate(userId, updates, { new: true });
     return reply.send({ success: true, data: user });
@@ -2598,7 +2680,7 @@ export const loginResponse = {
         id: { type: 'string' },
         name: { type: 'string' },
         email: { type: 'string' },
-        roles: { type: 'array', items: { type: 'string' } },
+        role: { type: 'string' },
       },
     },
     accessToken: { type: 'string' },

package/dist/core/index.d.mts

@@ -1,3 +1,3 @@
-import { B as ResourceDefinition, Gt as TreeMixin, Ht as SoftDeleteExt, Jt as BulkExt, Kt as SlugExt, Ut as SoftDeleteMixin, V as defineResource, Vt as BaseController, Wt as TreeExt, Yt as BulkMixin, an as QueryResolverConfig, cn as AccessControl, in as QueryResolver, ln as AccessControlConfig, nn as BaseCrudController, on as BodySanitizer, qt as SlugMixin, rn as ListResult, sn as BodySanitizerConfig, tn as BaseControllerOptions } from "../index-6u4_Gg6G.mjs";
-import { C as MAX_REGEX_LENGTH, D as RESERVED_QUERY_PARAMS, E as MutationOperation, O as SYSTEM_FIELDS, S as MAX_FILTER_DEPTH, T as MUTATION_OPERATIONS, _ as DEFAULT_UPDATE_METHOD, a as getControllerScope, b as HookOperation, c as createCrudRouter, d as CrudOperation, f as DEFAULT_ID_FIELD, g as DEFAULT_TENANT_FIELD, h as DEFAULT_SORT, i as getControllerContext, l as createPermissionMiddleware, m as DEFAULT_MAX_LIMIT, n as createFastifyHandler, o as sendControllerResponse, p as DEFAULT_LIMIT, r as createRequestContext, s as defineResourceVariants, t as createCrudHandlers, u as CRUD_OPERATIONS, v as HOOK_OPERATIONS, w as MAX_SEARCH_LENGTH, x as HookPhase, y as HOOK_PHASES } from "../index-BdXnTPRj.mjs";
+import { B as ResourceDefinition, Gt as TreeMixin, Ht as SoftDeleteExt, Jt as BulkExt, Kt as SlugExt, Ut as SoftDeleteMixin, V as defineResource, Vt as BaseController, Wt as TreeExt, Yt as BulkMixin, an as QueryResolverConfig, cn as AccessControl, in as QueryResolver, ln as AccessControlConfig, nn as BaseCrudController, on as BodySanitizer, qt as SlugMixin, rn as ListResult, sn as BodySanitizerConfig, tn as BaseControllerOptions } from "../index-CXXRbnf8.mjs";
+import { C as MAX_REGEX_LENGTH, D as RESERVED_QUERY_PARAMS, E as MutationOperation, O as SYSTEM_FIELDS, S as MAX_FILTER_DEPTH, T as MUTATION_OPERATIONS, _ as DEFAULT_UPDATE_METHOD, a as getControllerScope, b as HookOperation, c as createCrudRouter, d as CrudOperation, f as DEFAULT_ID_FIELD, g as DEFAULT_TENANT_FIELD, h as DEFAULT_SORT, i as getControllerContext, l as createPermissionMiddleware, m as DEFAULT_MAX_LIMIT, n as createFastifyHandler, o as sendControllerResponse, p as DEFAULT_LIMIT, r as createRequestContext, s as defineResourceVariants, t as createCrudHandlers, u as CRUD_OPERATIONS, v as HOOK_OPERATIONS, w as MAX_SEARCH_LENGTH, x as HookPhase, y as HOOK_PHASES } from "../index-m8mOOlFW.mjs";
 export { AccessControl, AccessControlConfig, BaseController, BaseControllerOptions, BaseCrudController, BodySanitizer, BodySanitizerConfig, BulkExt, BulkMixin, CRUD_OPERATIONS, CrudOperation, DEFAULT_ID_FIELD, DEFAULT_LIMIT, DEFAULT_MAX_LIMIT, DEFAULT_SORT, DEFAULT_TENANT_FIELD, DEFAULT_UPDATE_METHOD, HOOK_OPERATIONS, HOOK_PHASES, HookOperation, HookPhase, ListResult, MAX_FILTER_DEPTH, MAX_REGEX_LENGTH, MAX_SEARCH_LENGTH, MUTATION_OPERATIONS, MutationOperation, QueryResolver, QueryResolverConfig, RESERVED_QUERY_PARAMS, ResourceDefinition, SYSTEM_FIELDS, SlugExt, SlugMixin, SoftDeleteExt, SoftDeleteMixin, TreeExt, TreeMixin, createCrudHandlers, createCrudRouter, createFastifyHandler, createPermissionMiddleware, createRequestContext, defineResource, defineResourceVariants, getControllerContext, getControllerScope, sendControllerResponse };

package/dist/core/index.mjs

@@ -1,5 +1,5 @@
 import { a as DEFAULT_SORT, c as HOOK_OPERATIONS, d as MAX_REGEX_LENGTH, f as MAX_SEARCH_LENGTH, h as SYSTEM_FIELDS, i as DEFAULT_MAX_LIMIT, l as HOOK_PHASES, m as RESERVED_QUERY_PARAMS, n as DEFAULT_ID_FIELD, o as DEFAULT_TENANT_FIELD, p as MUTATION_OPERATIONS, r as DEFAULT_LIMIT, s as DEFAULT_UPDATE_METHOD, t as CRUD_OPERATIONS, u as MAX_FILTER_DEPTH } from "../constants-BhY1OHoH.mjs";
 import { a as BulkMixin, c as BodySanitizer, i as SlugMixin, l as AccessControl, n as TreeMixin, o as BaseCrudController, r as SoftDeleteMixin, s as QueryResolver, t as BaseController } from "../BaseController-swXruJ2_.mjs";
 import { _ as getControllerContext, g as createRequestContext, h as createFastifyHandler, m as createCrudHandlers, v as getControllerScope, y as sendControllerResponse } from "../routerShared-BqLRb5l7.mjs";
-import { a as createPermissionMiddleware, i as createCrudRouter, n as ResourceDefinition, r as defineResource, t as defineResourceVariants } from "../core-DnUsRpuX.mjs";
+import { a as createPermissionMiddleware, i as createCrudRouter, n as ResourceDefinition, r as defineResource, t as defineResourceVariants } from "../core-CbcQRIch.mjs";
 export { AccessControl, BaseController, BaseCrudController, BodySanitizer, BulkMixin, CRUD_OPERATIONS, DEFAULT_ID_FIELD, DEFAULT_LIMIT, DEFAULT_MAX_LIMIT, DEFAULT_SORT, DEFAULT_TENANT_FIELD, DEFAULT_UPDATE_METHOD, HOOK_OPERATIONS, HOOK_PHASES, MAX_FILTER_DEPTH, MAX_REGEX_LENGTH, MAX_SEARCH_LENGTH, MUTATION_OPERATIONS, QueryResolver, RESERVED_QUERY_PARAMS, ResourceDefinition, SYSTEM_FIELDS, SlugMixin, SoftDeleteMixin, TreeMixin, createCrudHandlers, createCrudRouter, createFastifyHandler, createPermissionMiddleware, createRequestContext, defineResource, defineResourceVariants, getControllerContext, getControllerScope, sendControllerResponse };

package/dist/{core-DnUsRpuX.mjs → core-CbcQRIch.mjs}

@@ -470,15 +470,20 @@ function resolveOrAutoCreateController(resolvedConfig, adapter, repository, hasC
 		else arcLog("defineResource").warn(`Resource "${resolvedConfig.name}" declares a custom \`queryParser\` but its controller does not expose \`setQueryParser(qp)\`. The parser will NOT be threaded into the controller's query resolution — operator filters (\`[contains]\`, \`[like]\`, etc.) may fall back to the controller's internal default. Extend \`BaseController\` / \`BaseCrudController\` (both implement \`setQueryParser\`) OR add the method to your custom controller to honor the resource-level parser.`);
 	}
 	if (controller) {
-		const droppedOptions = [];
-		if (resolvedConfig.tenantField !== void 0) droppedOptions.push("tenantField");
-		if (resolvedConfig.schemaOptions !== void 0 && Object.keys(resolvedConfig.schemaOptions).length > 0) droppedOptions.push("schemaOptions");
-		if (resolvedConfig.idField !== void 0) droppedOptions.push("idField");
-		if (resolvedConfig.defaultSort !== void 0) droppedOptions.push("defaultSort");
-		if (resolvedConfig.cache !== void 0) droppedOptions.push("cache");
-		if (resolvedConfig.onFieldWriteDenied !== void 0) droppedOptions.push("onFieldWriteDenied");
-		if (resolvedConfig._controllerOptions !== void 0) droppedOptions.push("preset-injected fields (slug/softDelete/parent)");
-		if (droppedOptions.length > 0) arcLog("defineResource").warn(`Resource "${resolvedConfig.name}" declares a custom controller AND resource-level option(s) [${droppedOptions.join(", ")}]. Arc only threads these when it auto-builds the controller — when you pass your own, they are dropped silently and the controller falls back to its own defaults (e.g. tenantField → 'organizationId'). Forward them to your controller's \`super(repo, { ... })\` call. Same root cause as the \`queryParser\` warn above.`);
+		const authorOptions = [];
+		if (resolvedConfig.tenantField !== void 0) authorOptions.push("tenantField");
+		if (resolvedConfig.schemaOptions !== void 0 && Object.keys(resolvedConfig.schemaOptions).length > 0) authorOptions.push("schemaOptions");
+		if (resolvedConfig.idField !== void 0) authorOptions.push("idField");
+		if (resolvedConfig.defaultSort !== void 0) authorOptions.push("defaultSort");
+		if (resolvedConfig.cache !== void 0) authorOptions.push("cache");
+		if (resolvedConfig.onFieldWriteDenied !== void 0) authorOptions.push("onFieldWriteDenied");
+		if (authorOptions.length > 0) arcLog("defineResource").warn(`Resource "${resolvedConfig.name}" declares a custom controller AND resource-level option(s) [${authorOptions.join(", ")}]. Arc only threads these when it auto-builds the controller — when you pass your own, they are dropped silently and the controller falls back to its own defaults (e.g. tenantField → 'organizationId'). Forward them to your controller's \`super(repo, { ... })\` call. Same root cause as the \`queryParser\` warn above.`);
+		if (resolvedConfig._controllerOptions !== void 0) {
+			const presetFields = [];
+			if (resolvedConfig._controllerOptions.slugField) presetFields.push("slugField");
+			if (resolvedConfig._controllerOptions.parentField) presetFields.push("parentField");
+			arcLog("defineResource").warn(`Resource "${resolvedConfig.name}" applies a preset that injects controller field(s) [${presetFields.join(", ") || "preset metadata"}] (e.g. slugLookup / softDelete / parent), but the resource also declares a custom controller. Preset metadata only reaches arc's auto-built BaseController — your custom controller will not see \`slugField\`/\`parentField\`/etc. Either (a) drop the preset on this resource (\`presets: [...]\` without it), or (b) extend \`BaseController\` / \`BaseCrudController\` so arc auto-builds the controller and threads the preset fields automatically.`);
+		}
 		return controller;
 	}
 	if (!hasCrudRoutes || !repository) return controller;
@@ -881,7 +886,7 @@ var ResourceDefinition = class {
 					fields: self.fields
 				});
 				if (self.actions && Object.keys(self.actions).length > 0) {
-					const { createActionRouter } = await import("./createActionRouter-u3ql2EDo.mjs").then((n) => n.n);
+					const { createActionRouter } = await import("./createActionRouter-CIKOcNA7.mjs").then((n) => n.n);
 					createActionRouter(typedInstance, {
 						...normalizeActionsToRouterConfig(self.actions, self.actionPermissions, self.tag, self.permissions, self.name, typedInstance.log),
 						resourceName: self.name,

package/dist/{createActionRouter-u3ql2EDo.mjs → createActionRouter-CIKOcNA7.mjs}

@@ -1,6 +1,6 @@
 import { t as __exportAll } from "./chunk-BpYLSNr0.mjs";
 import { a as buildAuthMiddlewareForPermissions, c as buildPreHandlerChain, f as resolveRouterPluginMw, l as buildRateLimitConfig, n as buildActionPipelineHandler, p as selectPluginMw, r as buildArcDecorator, t as buildActionPermissionMw, u as resolvePipelineSteps, y as sendControllerResponse } from "./routerShared-BqLRb5l7.mjs";
-import { n as schemaIRToJsonSchemaBranch, t as normalizeSchemaIR } from "./schemaIR-BlG9bY7v.mjs";
+import { n as schemaIRToJsonSchemaBranch, t as normalizeSchemaIR } from "./schemaIR-Dy2p4MxS.mjs";
 //#region src/core/createActionRouter.ts
 var createActionRouter_exports = /* @__PURE__ */ __exportAll({
 	buildActionBodySchema: () => buildActionBodySchema,