@classytic/arc 2.19.0 → 2.20.0

package/README.md

@@ -126,7 +126,7 @@ export default defineResource({
 });
 ```
 
-Auto-generates: `GET /products`, `GET /products/:id`, `POST /products`, `PATCH /products/:id`, `DELETE /products/:id` + softDelete adds `GET /products/deleted`, `POST /products/:id/restore` + slugLookup adds `GET /products/by-slug/:slug` + custom routes + `POST /products/:id/action`.
+Auto-generates: `GET /products`, `GET /products/:id`, `POST /products`, `PATCH /products/:id`, `DELETE /products/:id` + softDelete adds `GET /products/deleted`, `POST /products/:id/restore` + slugLookup adds `GET /products/slug/:slug` + custom routes + `POST /products/:id/action`.
 
 ### Resource shorthands
 

package/bin/arc.js

@@ -60,8 +60,30 @@ if (args.length === 0 || args.includes('--help') || args.includes('-h')) {
 
 const [command, subcommand, ...rest] = args;
 
+// Per-command usage — `arc <command> --help` prints this instead of falling
+// through to the command (where `--help` was mistaken for an argument).
+const COMMAND_ALIASES = { new: 'init', g: 'generate', i: 'introspect', desc: 'describe', d: 'docs' };
+const COMMAND_HELP = {
+  init: 'Usage: arc init [name] [--jwt|--better-auth] [--mongokit|--custom] [--api-key]\n            [--multi|--single] [--js] [--edge] [--docker|--no-docker] [--skip-install] [--force]\n  Scaffold a new arc project (prompts when run in a TTY without a name).',
+  generate: 'Usage: arc generate <resource|controller|model|repository|schemas|mcp> <name> [--mcp]\n  Aliases: g; types r/c/m/repo/s. Name must be kebab-case (letters, digits, hyphens).',
+  introspect: 'Usage: arc introspect <entry-file>\n  Print a human-readable summary of the resources an entry file exports.',
+  describe: 'Usage: arc describe <entry-file> [--json] [--pretty] [--entry <file>]\n  Describe resources; --json emits machine output for AI agents.',
+  docs: 'Usage: arc docs <entry-file> [output.json] [--entry <file>]\n  Export the generated OpenAPI document.',
+  doctor: 'Usage: arc doctor\n  Diagnose common arc setup issues (exit 1 on hard failures).',
+};
+
 async function main() {
   try {
+    // `arc <command> --help` / `-h` → command-specific usage, exit 0.
+    const canonicalCommand = COMMAND_ALIASES[command] ?? command;
+    if (
+      COMMAND_HELP[canonicalCommand] &&
+      [subcommand, ...rest].some((a) => a === '--help' || a === '-h')
+    ) {
+      console.log(COMMAND_HELP[canonicalCommand]);
+      return;
+    }
+
     switch (command) {
       case 'init':
       case 'new':
@@ -310,6 +332,21 @@ function parseInitOptions(rawArgs) {
       case '-f':
         opts.force = true;
         break;
+
+      case '--help':
+      case '-h':
+        // Handled by the per-command help short-circuit in main(); ignore here.
+        break;
+
+      default:
+        // Surface typos instead of silently scaffolding with defaults — a
+        // dropped `--jwt` / `--mongokit` would change the whole project. Warn
+        // (non-fatal, to stderr) rather than error, since a scaffolder should
+        // stay forgiving.
+        if (arg.startsWith('-')) {
+          console.error(`Warning: unknown flag "${arg}" (ignored). Run "arc init --help".`);
+        }
+        break;
     }
   }
 

package/dist/{BaseController-Dy6EQHjM.mjs → BaseController-D-MHZ27_.mjs}

@@ -1,11 +1,11 @@
-import { h as SYSTEM_FIELDS, o as DEFAULT_TENANT_FIELD } from "./constants-gaEeMlz-.mjs";
+import { h as SYSTEM_FIELDS, o as DEFAULT_TENANT_FIELD } from "./constants-DNre0wRg.mjs";
 import { arcLog } from "./logger/index.mjs";
 import { d as createDomainError, f as createError, i as NotFoundError, r as ForbiddenError } from "./errors-DkO8Nk6-.mjs";
 import { b as isElevated, c as getOrgId, n as PUBLIC_SCOPE, x as isMember } from "./types-bHblZ9YN.mjs";
-import { M as scheduleBackground, N as simpleEqualityMatcher, j as getUserId, k as ArcQueryParser } from "./utils-C6QQ9-hd.mjs";
-import { t as buildQueryKey } from "./keys-Cd316u_y.mjs";
-import { F as applyFieldWritePermissions, L as resolveEffectiveRoles } from "./permissions-BPB1xqGf.mjs";
+import { N as simpleEqualityMatcher, _ as ArcQueryParser, r as scheduleBackground, t as getUserId } from "./utils-ChjYQpjn.mjs";
+import { F as applyFieldWritePermissions, L as resolveEffectiveRoles } from "./permissions-CgbOLJZG.mjs";
 import { t as getUserRoles } from "./types-XTApa8b6.mjs";
+import { t as buildQueryKey } from "./keys-Cd316u_y.mjs";
 //#region src/core/AccessControl.ts
 const log = arcLog("access-control");
 var AccessControl = class {

package/dist/{ResourceRegistry-5fKZwhK_.mjs → ResourceRegistry-7RnrEWNP.mjs}

@@ -1,4 +1,4 @@
-import "./constants-gaEeMlz-.mjs";
+import "./constants-DNre0wRg.mjs";
 //#region src/registry/ResourceRegistry.ts
 /**
 * Resource Registry

package/dist/{actionPermissions-D7NGwcAR.mjs → actionPermissions-C9RMiIpc.mjs}

@@ -1,5 +1,5 @@
 import { b as isElevated, c as getOrgId, g as getUserId, n as PUBLIC_SCOPE, x as isMember } from "./types-bHblZ9YN.mjs";
-import { L as resolveEffectiveRoles, P as applyFieldReadPermissions } from "./permissions-BPB1xqGf.mjs";
+import { L as resolveEffectiveRoles, P as applyFieldReadPermissions } from "./permissions-CgbOLJZG.mjs";
 import { t as getUserRoles } from "./types-XTApa8b6.mjs";
 import { t as executePipeline } from "./pipe-BOLmGIxa.mjs";
 import { isPaginatedResult, toCanonicalList } from "@classytic/repo-core/pagination";

package/dist/audit/index.mjs

@@ -108,7 +108,7 @@ function extractUserId(user) {
 */
 function detectChanges(before, after) {
 	const changes = [];
-	const allKeys = new Set([...Object.keys(before), ...Object.keys(after)]);
+	const allKeys = /* @__PURE__ */ new Set([...Object.keys(before), ...Object.keys(after)]);
 	for (const key of allKeys) {
 		if (key.startsWith("_") || key === "updatedAt") continue;
 		if (JSON.stringify(before[key]) !== JSON.stringify(after[key])) changes.push(key);

package/dist/auth/index.d.mts

@@ -1,4 +1,4 @@
-import { Ht as AuthPluginOptions, Vt as AuthHelpers } from "../index-CUTG2Cuo.mjs";
+import { Ht as AuthPluginOptions, Vt as AuthHelpers } from "../index-_--GyzcO.mjs";
 import { c as PermissionCheck } from "../fields-C7ahdGYf.mjs";
 import { t as ExternalOpenApiPaths } from "../externalPaths-BE6wFpYv.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-BXG-HGwG.mjs";

package/dist/auth/index.mjs

@@ -1,5 +1,5 @@
 import { d as createDomainError, l as UnauthorizedError, p as isArcError, t as ArcError } from "../errors-DkO8Nk6-.mjs";
-import { _ as requireTeamMembership, m as requireOrgRole, p as requireOrgMembership } from "../permissions-BPB1xqGf.mjs";
+import { _ as requireTeamMembership, m as requireOrgRole, p as requireOrgMembership } from "../permissions-CgbOLJZG.mjs";
 import { n as normalizeRoles, t as getUserRoles } from "../types-XTApa8b6.mjs";
 import { a as toJsonSchema } from "../schemaConverter-U0MnO9vd.mjs";
 import { createHmac, randomUUID, timingSafeEqual } from "node:crypto";
@@ -1054,7 +1054,7 @@ var MemorySessionStore = class {
 		const userSessions = this.userIndex.get(userId);
 		if (!userSessions) return;
 		for (const sessionId of userSessions) if (sessionId !== currentSessionId) this.sessions.delete(sessionId);
-		if (userSessions.has(currentSessionId)) this.userIndex.set(userId, new Set([currentSessionId]));
+		if (userSessions.has(currentSessionId)) this.userIndex.set(userId, /* @__PURE__ */ new Set([currentSessionId]));
 		else this.userIndex.delete(userId);
 	}
 	/**
@@ -1160,9 +1160,10 @@ function createSessionManager(options) {
 			metadata
 		};
 		await store.set(sessionId, sessionData);
+		const signedId = signSessionId(sessionId, secret);
 		return {
 			sessionId,
-			cookie: buildSetCookieHeader(cookieName, signSessionId(sessionId, secret), maxAgeSeconds, cookieOptions)
+			cookie: buildSetCookieHeader(cookieName, signedId, maxAgeSeconds, cookieOptions)
 		};
 	}
 	/**
@@ -1257,7 +1258,8 @@ function createSessionManager(options) {
 			if (Date.now() - session.updatedAt > updateAgeMs) {
 				const updatedSession = await refreshSession(sessionId);
 				if (updatedSession) {
-					const newCookie = buildSetCookieHeader(cookieName, signSessionId(sessionId, secret), maxAgeSeconds, cookieOptions);
+					const signedId = signSessionId(sessionId, secret);
+					const newCookie = buildSetCookieHeader(cookieName, signedId, maxAgeSeconds, cookieOptions);
 					reply.header("Set-Cookie", newCookie);
 					request.session = {
 						...updatedSession,
@@ -1300,7 +1302,7 @@ function mirrorTrustedOriginsFromCors(options) {
 	const { corsOrigins, canonicalUrl } = options;
 	if (corsOrigins === true) return ["*"];
 	if (!corsOrigins) return [canonicalUrl];
-	return Array.from(new Set([canonicalUrl, ...corsOrigins]));
+	return Array.from(/* @__PURE__ */ new Set([canonicalUrl, ...corsOrigins]));
 }
 //#endregion
 export { MemorySessionStore, authPlugin_default as authPlugin, authPlugin as authPluginFn, createBetterAuthAdapter, createSessionManager, extractBetterAuthOpenApi, mirrorTrustedOriginsFromCors };

package/dist/{buildHandler-B0qvAguf.mjs → buildHandler-D_2ULWxZ.mjs}

@@ -1,4 +1,4 @@
-import { i as compileAggRequest, t as adapterSupportsAggregate } from "./validate-CRcaWzp2.mjs";
+import { i as compileAggRequest, t as adapterSupportsAggregate } from "./validate-C2mGgSXg.mjs";
 //#region src/core/aggregation/buildHandler.ts
 /**
 * Framework-agnostic aggregation execution. Runs safety guards,
@@ -193,7 +193,7 @@ const OPERATOR_SHORTHAND = {
 	size: "$size",
 	type: "$type"
 };
-const SHORTHAND_RANGE_OPS = new Set([
+const SHORTHAND_RANGE_OPS = /* @__PURE__ */ new Set([
 	"gt",
 	"gte",
 	"lt",
@@ -239,7 +239,7 @@ function expandShorthandOperators(value) {
 */
 function extractCallerFilter(query) {
 	const out = {};
-	const reserved = new Set([
+	const reserved = /* @__PURE__ */ new Set([
 		"page",
 		"limit",
 		"after",

package/dist/cache/index.mjs

@@ -1,6 +1,6 @@
-import { i as versionKey, n as hashParams, r as tagVersionKey, t as buildQueryKey } from "../keys-Cd316u_y.mjs";
 import { t as MemoryCacheStore } from "../memory-CLXA2VeJ.mjs";
-import { r as QueryCache, t as queryCachePlugin } from "../queryCachePlugin-emHb0CuX.mjs";
+import { i as versionKey, n as hashParams, r as tagVersionKey, t as buildQueryKey } from "../keys-Cd316u_y.mjs";
+import { r as QueryCache, t as queryCachePlugin } from "../queryCachePlugin-DzqLN904.mjs";
 //#region src/cache/redis.ts
 /**
 * Redis-backed cache store.

package/dist/cli/commands/describe.d.mts

@@ -1,4 +1,4 @@
-import { V as ResourceDefinition, ht as RouteSchemaOptions, it as RateLimitConfig } from "../../index-CUTG2Cuo.mjs";
+import { V as ResourceDefinition, ht as RouteSchemaOptions, it as RateLimitConfig } from "../../index-_--GyzcO.mjs";
 
 //#region src/cli/commands/describe.d.ts
 interface DescribedResource {

package/dist/cli/commands/describe.mjs

@@ -1,5 +1,5 @@
-import { t as CRUD_OPERATIONS } from "../../constants-gaEeMlz-.mjs";
-import { n as stringifyMeasureMap } from "../../ResourceRegistry-5fKZwhK_.mjs";
+import { t as CRUD_OPERATIONS } from "../../constants-DNre0wRg.mjs";
+import { n as stringifyMeasureMap } from "../../ResourceRegistry-7RnrEWNP.mjs";
 import { resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 //#region src/cli/commands/describe.ts

package/dist/cli/commands/docs.mjs

@@ -1,5 +1,5 @@
-import { t as buildOpenApiSpec } from "../../openapi-DZ-5a5Op.mjs";
-import { t as loadResourcesFromEntry } from "../../loadResourcesFromEntry-BTlFEx05.mjs";
+import { t as buildOpenApiSpec } from "../../openapi-Dq6RbEGK.mjs";
+import { t as loadResourcesFromEntry } from "../../loadResourcesFromEntry-OMCvIEE7.mjs";
 import { dirname, resolve } from "node:path";
 import { mkdirSync, writeFileSync } from "node:fs";
 //#region src/cli/commands/docs.ts

package/dist/cli/commands/generate.mjs

@@ -1,2 +1,2 @@
-import { t as generate } from "../../generate-Brans3fW.mjs";
+import { t as generate } from "../../generate-usRSdQmP.mjs";
 export { generate };

package/dist/cli/commands/init.mjs

@@ -1,2 +1,2 @@
-import { t as init } from "../../init-Bqpt1Hxf.mjs";
+import { t as init } from "../../init-YH_nslQR.mjs";
 export { init };

package/dist/cli/commands/introspect.mjs

@@ -1,4 +1,4 @@
-import { t as loadResourcesFromEntry } from "../../loadResourcesFromEntry-BTlFEx05.mjs";
+import { t as loadResourcesFromEntry } from "../../loadResourcesFromEntry-OMCvIEE7.mjs";
 //#region src/cli/commands/introspect.ts
 function describePermission(value) {
 	if (!value) return "none";
@@ -10,19 +10,10 @@ function describePermission(value) {
 async function introspect(args) {
 	console.log("Introspecting Arc resources...\n");
 	const entryPath = args[0];
-	if (!entryPath) {
-		console.log("Usage: arc introspect <entry-file>\n");
-		console.log("Where entry-file exports your defineResource() results.");
-		console.log("Example: arc introspect ./src/resources.js");
-		return;
-	}
+	if (!entryPath) throw new Error("Missing entry-file argument\nUsage: arc introspect <entry-file>\nWhere entry-file exports your defineResource() results.\nExample: arc introspect ./src/resources.js");
 	const { registry, registered } = await loadResourcesFromEntry(entryPath);
-	if (registered === 0) {
-		console.log("No resource definitions found in entry file.");
-		console.log("\nMake sure your file exports defineResource() results:");
-		console.log("  export const productResource = defineResource({ ... });");
-		return;
-	}
+	if (registered === 0) throw new Error(`No resource definitions found in "${entryPath}".\nMake sure the file exports defineResource() results:
+  export const productResource = defineResource({ ... });`);
 	const resources = registry.getAll();
 	console.log(`Found ${resources.length} resource(s):\n`);
 	resources.forEach((resource, index) => {

package/dist/cli/index.mjs

@@ -1,7 +1,7 @@
 import { describe } from "./commands/describe.mjs";
 import { exportDocs } from "./commands/docs.mjs";
 import { doctor } from "./commands/doctor.mjs";
-import { t as generate } from "../generate-Brans3fW.mjs";
-import { t as init } from "../init-Bqpt1Hxf.mjs";
+import { t as generate } from "../generate-usRSdQmP.mjs";
+import { t as init } from "../init-YH_nslQR.mjs";
 import { introspect } from "./commands/introspect.mjs";
 export { describe, doctor, exportDocs, generate, init, introspect };

package/dist/{constants-gaEeMlz-.mjs → constants-DNre0wRg.mjs}

@@ -73,7 +73,7 @@ const MAX_FILTER_DEPTH = 10;
 * filter. See `ArcQueryParser.parseFilters()` for the unwrap step that
 * merges `q.filter[*]` back into the top-level filter map.
 */
-const RESERVED_QUERY_PARAMS = Object.freeze(new Set([
+const RESERVED_QUERY_PARAMS = Object.freeze(/* @__PURE__ */ new Set([
 	"page",
 	"limit",
 	"sort",

package/dist/core/index.d.mts

@@ -1,3 +1,3 @@
-import { At as AggregationMaterializedResult, B as defineResource, Bn as BodySanitizerConfig, Ct as AggMeasureInput, Dt as AggregationDateRangeRequirement, Et as AggregationConfig, Fn as BaseControllerOptions, In as ControllerConfigurableOptions, Ln as ControllerConstructionOptions, Mt as AggregationsMap, Ot as AggregationIndexHint, Rn as ListResult, Tt as AggregationCacheConfig, V as ResourceDefinition, an as SlugExt, cn as BulkMixin, dn as QueryResolverConfig, en as BaseController, fn as AccessControl, in as TreeMixin, jt as AggregationRateLimit, kt as AggregationMaterializedContext, ln as BaseCrudController, nn as SoftDeleteMixin, on as SlugMixin, pn as AccessControlConfig, rn as TreeExt, sn as BulkExt, tn as SoftDeleteExt, un as QueryResolver, wt as AggMeasureShorthand, zn as BodySanitizer } from "../index-CUTG2Cuo.mjs";
-import { A as MAX_FILTER_DEPTH, C as DEFAULT_SORT, D as HOOK_PHASES, E as HOOK_OPERATIONS, F as RESERVED_QUERY_PARAMS, I as SYSTEM_FIELDS, M as MAX_SEARCH_LENGTH, N as MUTATION_OPERATIONS, O as HookOperation, P as MutationOperation, S as DEFAULT_MAX_LIMIT, T as DEFAULT_UPDATE_METHOD, _ as defineAggregation, a as createRequestContext, b as DEFAULT_ID_FIELD, c as sendControllerResponse, d as getEntityQuery, f as defineResourceVariants, g as createPermissionMiddleware, h as createCrudRouter, i as createFastifyHandler, j as MAX_REGEX_LENGTH, k as HookPhase, l as getEntityId, m as defineAction, n as isFieldReadable, o as getControllerContext, p as DefineActionConfig, r as createCrudHandlers, s as getControllerScope, t as collectReadBlockedFields, u as getEntityIdField, v as CRUD_OPERATIONS, w as DEFAULT_TENANT_FIELD, x as DEFAULT_LIMIT, y as CrudOperation } from "../index-CP6A1Ffj.mjs";
+import { At as AggregationMaterializedResult, B as defineResource, Bn as BodySanitizerConfig, Ct as AggMeasureInput, Dt as AggregationDateRangeRequirement, Et as AggregationConfig, Fn as BaseControllerOptions, In as ControllerConfigurableOptions, Ln as ControllerConstructionOptions, Mt as AggregationsMap, Ot as AggregationIndexHint, Rn as ListResult, Tt as AggregationCacheConfig, V as ResourceDefinition, an as SlugExt, cn as BulkMixin, dn as QueryResolverConfig, en as BaseController, fn as AccessControl, in as TreeMixin, jt as AggregationRateLimit, kt as AggregationMaterializedContext, ln as BaseCrudController, nn as SoftDeleteMixin, on as SlugMixin, pn as AccessControlConfig, rn as TreeExt, sn as BulkExt, tn as SoftDeleteExt, un as QueryResolver, wt as AggMeasureShorthand, zn as BodySanitizer } from "../index-_--GyzcO.mjs";
+import { A as MAX_FILTER_DEPTH, C as DEFAULT_SORT, D as HOOK_PHASES, E as HOOK_OPERATIONS, F as RESERVED_QUERY_PARAMS, I as SYSTEM_FIELDS, M as MAX_SEARCH_LENGTH, N as MUTATION_OPERATIONS, O as HookOperation, P as MutationOperation, S as DEFAULT_MAX_LIMIT, T as DEFAULT_UPDATE_METHOD, _ as defineAggregation, a as createRequestContext, b as DEFAULT_ID_FIELD, c as sendControllerResponse, d as getEntityQuery, f as defineResourceVariants, g as createPermissionMiddleware, h as createCrudRouter, i as createFastifyHandler, j as MAX_REGEX_LENGTH, k as HookPhase, l as getEntityId, m as defineAction, n as isFieldReadable, o as getControllerContext, p as DefineActionConfig, r as createCrudHandlers, s as getControllerScope, t as collectReadBlockedFields, u as getEntityIdField, v as CRUD_OPERATIONS, w as DEFAULT_TENANT_FIELD, x as DEFAULT_LIMIT, y as CrudOperation } from "../index-DUa8WHz3.mjs";
 export { AccessControl, type AccessControlConfig, type AggMeasureInput, type AggMeasureShorthand, type AggregationCacheConfig, type AggregationConfig, type AggregationDateRangeRequirement, type AggregationIndexHint, type AggregationMaterializedContext, type AggregationMaterializedResult, type AggregationRateLimit, type AggregationsMap, BaseController, type BaseControllerOptions, BaseCrudController, BodySanitizer, type BodySanitizerConfig, type BulkExt, BulkMixin, CRUD_OPERATIONS, type ControllerConfigurableOptions, type ControllerConstructionOptions, CrudOperation, DEFAULT_ID_FIELD, DEFAULT_LIMIT, DEFAULT_MAX_LIMIT, DEFAULT_SORT, DEFAULT_TENANT_FIELD, DEFAULT_UPDATE_METHOD, type DefineActionConfig, HOOK_OPERATIONS, HOOK_PHASES, HookOperation, HookPhase, type ListResult, MAX_FILTER_DEPTH, MAX_REGEX_LENGTH, MAX_SEARCH_LENGTH, MUTATION_OPERATIONS, MutationOperation, QueryResolver, type QueryResolverConfig, RESERVED_QUERY_PARAMS, ResourceDefinition, SYSTEM_FIELDS, type SlugExt, SlugMixin, type SoftDeleteExt, SoftDeleteMixin, type TreeExt, TreeMixin, collectReadBlockedFields, createCrudHandlers, createCrudRouter, createFastifyHandler, createPermissionMiddleware, createRequestContext, defineAction, defineAggregation, defineResource, defineResourceVariants, getControllerContext, getControllerScope, getEntityId, getEntityIdField, getEntityQuery, isFieldReadable, 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-gaEeMlz-.mjs";
-import { a as BulkMixin, c as collectReadBlockedFields, f as AccessControl, i as SlugMixin, l as isFieldReadable, n as TreeMixin, o as BaseCrudController, r as SoftDeleteMixin, s as QueryResolver, t as BaseController, u as BodySanitizer } from "../BaseController-Dy6EQHjM.mjs";
-import { a as defineResource, c as createCrudRouter, i as defineResourceVariants, l as createPermissionMiddleware, n as getEntityIdField, o as ResourceDefinition, r as getEntityQuery, s as defineAction, t as getEntityId, u as defineAggregation } from "../core-Ba-6Sue6.mjs";
-import { a as createCrudHandlers, c as getControllerContext, l as getControllerScope, o as createFastifyHandler, s as createRequestContext, u as sendControllerResponse } from "../actionPermissions-D7NGwcAR.mjs";
+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-DNre0wRg.mjs";
+import { a as BulkMixin, c as collectReadBlockedFields, f as AccessControl, i as SlugMixin, l as isFieldReadable, n as TreeMixin, o as BaseCrudController, r as SoftDeleteMixin, s as QueryResolver, t as BaseController, u as BodySanitizer } from "../BaseController-D-MHZ27_.mjs";
+import { a as defineResource, c as createCrudRouter, i as defineResourceVariants, l as createPermissionMiddleware, n as getEntityIdField, o as ResourceDefinition, r as getEntityQuery, s as defineAction, t as getEntityId, u as defineAggregation } from "../core-CWhyGkiM.mjs";
+import { a as createCrudHandlers, c as getControllerContext, l as getControllerScope, o as createFastifyHandler, s as createRequestContext, u as sendControllerResponse } from "../actionPermissions-C9RMiIpc.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, collectReadBlockedFields, createCrudHandlers, createCrudRouter, createFastifyHandler, createPermissionMiddleware, createRequestContext, defineAction, defineAggregation, defineResource, defineResourceVariants, getControllerContext, getControllerScope, getEntityId, getEntityIdField, getEntityQuery, isFieldReadable, sendControllerResponse };

package/dist/{core-Ba-6Sue6.mjs → core-CWhyGkiM.mjs}

@@ -1,18 +1,57 @@
-import { s as DEFAULT_UPDATE_METHOD, t as CRUD_OPERATIONS } from "./constants-gaEeMlz-.mjs";
+import { s as DEFAULT_UPDATE_METHOD, t as CRUD_OPERATIONS } from "./constants-DNre0wRg.mjs";
 import { arcLog } from "./logger/index.mjs";
 import { r as ForbiddenError } from "./errors-DkO8Nk6-.mjs";
 import { b as isElevated, n as PUBLIC_SCOPE, x as isMember } from "./types-bHblZ9YN.mjs";
-import { p as assertValidConfig, x as getDefaultCrudSchemas } from "./utils-C6QQ9-hd.mjs";
-import { d as DEFAULT_FIELD_WRITE_DENIAL_POLICY, t as BaseController } from "./BaseController-Dy6EQHjM.mjs";
-import { F as applyFieldWritePermissions, L as resolveEffectiveRoles } from "./permissions-BPB1xqGf.mjs";
+import { A as assertValidConfig, l as getDefaultCrudSchemas } from "./utils-ChjYQpjn.mjs";
+import { d as DEFAULT_FIELD_WRITE_DENIAL_POLICY, t as BaseController } from "./BaseController-D-MHZ27_.mjs";
+import { a as selectPluginMw, c as buildPreHandlerChain, f as buildArcDecorator, i as resolveRouterPluginMw, l as resolveRoutePreHandlers, n as buildRateLimitConfig, r as buildRouteConfig, s as buildCrudPermissionMw, t as tryRegisterRoute, u as buildAuthMiddleware } from "./registerRoute-DGSREwPw.mjs";
+import { F as applyFieldWritePermissions, L as resolveEffectiveRoles } from "./permissions-CgbOLJZG.mjs";
 import { t as getUserRoles } from "./types-XTApa8b6.mjs";
+import { t as applyPresets } from "./presets-DWsYQdbV.mjs";
 import { n as convertRouteSchema, t as convertOpenApiSchemas } from "./schemaConverter-U0MnO9vd.mjs";
 import { i as pipeUIMessageStreamToReply, r as isReadableStream } from "./streaming-BQcW6_Kq.mjs";
-import { a as createCrudHandlers, d as buildRequestScopeProjection, i as resolvePipelineSteps, o as createFastifyHandler, r as buildPipelineHandler, s as createRequestContext, t as resolveActionPermission } from "./actionPermissions-D7NGwcAR.mjs";
-import { a as selectPluginMw, c as buildPreHandlerChain, f as buildArcDecorator, i as resolveRouterPluginMw, l as resolveRoutePreHandlers, n as buildRateLimitConfig, r as buildRouteConfig, s as buildCrudPermissionMw, t as tryRegisterRoute, u as buildAuthMiddleware } from "./registerRoute-BdV8DDwU.mjs";
-import { t as applyPresets } from "./presets-BtyFwTO4.mjs";
 import { t as hasEvents } from "./typeGuards-C9KXUly6.mjs";
-import { t as pluralize } from "./pluralize-DccFV9R7.mjs";
+import { a as createCrudHandlers, d as buildRequestScopeProjection, i as resolvePipelineSteps, o as createFastifyHandler, r as buildPipelineHandler, s as createRequestContext, t as resolveActionPermission } from "./actionPermissions-C9RMiIpc.mjs";
+import { t as pluralize } from "./pluralize-BhrgwZb9.mjs";
+//#region src/core/middlewares/fieldWrite.ts
+/**
+* Build a preHandler that enforces field-write permissions on the request body.
+*
+* Auto-CRUD's create/update routes get this for free via `BodySanitizer.sanitize()`
+* inside `BaseController`. Custom routes (`config.routes`, presets, action endpoints)
+* never went through that path — so a host that declared
+* `fields: { role: fields.writableBy(['admin']) }` and a custom
+* `POST /users/promote` happily accepted `{ role: 'admin' }` from any caller.
+*
+* This preHandler closes that gap. It applies ONLY the `applyFieldWritePermissions`
+* step — no `SYSTEM_FIELDS` strip, no `fieldRules` strip — because custom-route
+* bodies don't necessarily mirror the resource's adapter shape, and we'd
+* generate surprising 403s by enforcing rules tied to that shape.
+*
+* Returns `null` when the resource has no field permissions configured — the
+* caller should then skip wiring it into the preHandler chain.
+*/
+function buildFieldWritePreHandler(fieldPermissions, policy = DEFAULT_FIELD_WRITE_DENIAL_POLICY) {
+	if (!fieldPermissions || Object.keys(fieldPermissions).length === 0) return null;
+	return async (request, _reply) => {
+		const body = request.body;
+		if (!body || typeof body !== "object" || Array.isArray(body)) return;
+		const scope = request.scope ?? PUBLIC_SCOPE;
+		if (isElevated(scope)) return;
+		const { body: filtered, deniedFields } = applyFieldWritePermissions(body, fieldPermissions, resolveEffectiveRoles(getUserRoles(request.user), isMember(scope) ? scope.orgRoles : []));
+		if (deniedFields.length > 0 && policy === "reject") throw new ForbiddenError(`Not permitted to write field${deniedFields.length === 1 ? "" : "s"}: ${deniedFields.join(", ")}`);
+		request.body = filtered;
+	};
+}
+/**
+* True for HTTP methods that carry a request body and should run the
+* field-write preHandler. GET/DELETE/HEAD/OPTIONS skip enforcement.
+*/
+function methodCarriesBody(method) {
+	const m = method.toUpperCase();
+	return m === "POST" || m === "PUT" || m === "PATCH";
+}
+//#endregion
 //#region src/core/aggregation/defineAggregation.ts
 /**
 * Declare a single resource aggregation. Exported configs flow into
@@ -59,45 +98,6 @@ function defineAggregation(config) {
 	return config;
 }
 //#endregion
-//#region src/core/middlewares/fieldWrite.ts
-/**
-* Build a preHandler that enforces field-write permissions on the request body.
-*
-* Auto-CRUD's create/update routes get this for free via `BodySanitizer.sanitize()`
-* inside `BaseController`. Custom routes (`config.routes`, presets, action endpoints)
-* never went through that path — so a host that declared
-* `fields: { role: fields.writableBy(['admin']) }` and a custom
-* `POST /users/promote` happily accepted `{ role: 'admin' }` from any caller.
-*
-* This preHandler closes that gap. It applies ONLY the `applyFieldWritePermissions`
-* step — no `SYSTEM_FIELDS` strip, no `fieldRules` strip — because custom-route
-* bodies don't necessarily mirror the resource's adapter shape, and we'd
-* generate surprising 403s by enforcing rules tied to that shape.
-*
-* Returns `null` when the resource has no field permissions configured — the
-* caller should then skip wiring it into the preHandler chain.
-*/
-function buildFieldWritePreHandler(fieldPermissions, policy = DEFAULT_FIELD_WRITE_DENIAL_POLICY) {
-	if (!fieldPermissions || Object.keys(fieldPermissions).length === 0) return null;
-	return async (request, _reply) => {
-		const body = request.body;
-		if (!body || typeof body !== "object" || Array.isArray(body)) return;
-		const scope = request.scope ?? PUBLIC_SCOPE;
-		if (isElevated(scope)) return;
-		const { body: filtered, deniedFields } = applyFieldWritePermissions(body, fieldPermissions, resolveEffectiveRoles(getUserRoles(request.user), isMember(scope) ? scope.orgRoles : []));
-		if (deniedFields.length > 0 && policy === "reject") throw new ForbiddenError(`Not permitted to write field${deniedFields.length === 1 ? "" : "s"}: ${deniedFields.join(", ")}`);
-		request.body = filtered;
-	};
-}
-/**
-* True for HTTP methods that carry a request body and should run the
-* field-write preHandler. GET/DELETE/HEAD/OPTIONS skip enforcement.
-*/
-function methodCarriesBody(method) {
-	const m = method.toUpperCase();
-	return m === "POST" || m === "PUT" || m === "PATCH";
-}
-//#endregion
 //#region src/core/createCrudRouter.ts
 /**
 * Mount custom routes (from presets or user-defined `routes`) on Fastify.
@@ -177,7 +177,7 @@ function createCustomRoutes(fastify, routes, controller, options) {
 				}
 				return result;
 			} : handler,
-			...buildRouteConfig(rateLimitConfig, extensions)
+			...buildRouteConfig(route.rateLimit !== void 0 ? buildRateLimitConfig(route.rateLimit) : rateLimitConfig, extensions)
 		}, {
 			resourceName,
 			op: opName
@@ -949,6 +949,42 @@ function computeHasCrudRoutes(config) {
 	const disabled = new Set(config.disabledRoutes ?? []);
 	return !config.disableDefaultRoutes && CRUD_OPERATIONS.some((op) => !disabled.has(op));
 }
+const WRITE_OPERATIONS = /* @__PURE__ */ new Set([
+	"create",
+	"update",
+	"delete"
+]);
+/**
+* Public-by-omission CRUD diagnostic (post-preset).
+*
+* An omitted CRUD permission mounts the route with NO permission
+* middleware at all — unlike custom routes and actions, which fail boot
+* without one. That asymmetry silently shipped unauthenticated writes
+* (`permissions: readOnly()` pre-2.20 being the canonical victim).
+*
+* Runs against `resolvedConfig` — never the raw user config — so
+* permissions injected by presets (ownedByUser, multiTenant policy
+* wiring, ...) count as gates and don't false-positive.
+*
+* Severity ladder:
+*   - `warn` when any enabled WRITE op (create/update/delete) is ungated —
+*     this is real exposure the host must acknowledge.
+*   - `info` when only reads are ungated — public catalogs
+*     (`referenceData: true`) are a legitimate shape, but the host should
+*     still state intent with `permissions.fullPublic()` / `allowPublic()`.
+*/
+function collectUngatedCrudDiagnostics(config) {
+	if (config.disableDefaultRoutes) return [];
+	const disabled = new Set(config.disabledRoutes ?? []);
+	const permissions = config.permissions ?? {};
+	const ungated = CRUD_OPERATIONS.filter((op) => !disabled.has(op) && typeof permissions[op] !== "function");
+	if (ungated.length === 0) return [];
+	return [{
+		severity: ungated.some((op) => WRITE_OPERATIONS.has(op)) ? "warn" : "info",
+		code: "crud-public-by-omission",
+		message: `[Arc] Resource '${config.name}' mounts ${ungated.length} CRUD route(s) with no permission gate: ${ungated.join(", ")}.\nAn omitted permission mounts the route WITHOUT auth. State intent explicitly:\n  permissions: permissions.fullPublic()     // intentionally public\n  permissions: permissions.authenticated()  // require auth on every op\n  permissions: { ${ungated[0]}: requireAuth(), ... }  // per-operation`
+	}];
+}
 //#endregion
 //#region src/registry/resolveTenantPurge.ts
 const DEFAULT_PRIORITY = 100;
@@ -1102,7 +1138,7 @@ function deepMergeSchemas(base, override) {
 	if (!override) return base;
 	if (!base) return override;
 	const result = { ...base };
-	for (const [key, value] of Object.entries(override)) if (Array.isArray(value) && Array.isArray(result[key])) result[key] = [...new Set([...result[key], ...value])];
+	for (const [key, value] of Object.entries(override)) if (Array.isArray(value) && Array.isArray(result[key])) result[key] = [.../* @__PURE__ */ new Set([...result[key], ...value])];
 	else if (value && typeof value === "object" && !Array.isArray(value)) result[key] = deepMergeSchemas(result[key], value);
 	else result[key] = value;
 	return result;
@@ -1247,7 +1283,7 @@ function buildResourcePlugin(resource) {
 				extensions: resource.extensions
 			});
 			if (resource.actions && Object.keys(resource.actions).length > 0) {
-				const { createActionRouter } = await import("./createActionRouter-B_WzBFyf.mjs").then((n) => n.n);
+				const { createActionRouter } = await import("./createActionRouter-HlQso0jO.mjs").then((n) => n.n);
 				createActionRouter(typedInstance, {
 					...normalizeActionsToRouterConfig(resource.actions, resource.actionPermissions, resource.tag, resource.permissions, resource.name, typedInstance.log),
 					resourceName: resource.name,
@@ -1262,7 +1298,7 @@ function buildResourcePlugin(resource) {
 				});
 			}
 			if (resource.aggregations && Object.keys(resource.aggregations).length > 0) {
-				const [{ createAggregationRouter }, { adapterSupportsAggregate, ArcAggregationConfigError }] = await Promise.all([import("./createAggregationRouter-B_G_nIjm.mjs"), import("./validate-CRcaWzp2.mjs").then((n) => n.r)]);
+				const [{ createAggregationRouter }, { adapterSupportsAggregate, ArcAggregationConfigError }] = await Promise.all([import("./createAggregationRouter-5LzPzgw1.mjs"), import("./validate-C2mGgSXg.mjs").then((n) => n.r)]);
 				const repoForAgg = resource.controller?.repository ?? resource.repository;
 				if (!adapterSupportsAggregate(repoForAgg)) {
 					const undispatchable = Object.entries(resource.aggregations).filter(([, cfg]) => !cfg.materialized).map(([name]) => name);
@@ -1718,7 +1754,7 @@ function mergeUserOpenApiOverrides(openApiSchemas, userOverrides) {
 * call) since the set is fixed and the cost of re-allocating is a
 * pointless boot tax for hosts with hundreds of resources.
 */
-const CRUD_OP_NAMES = new Set([
+const CRUD_OP_NAMES = /* @__PURE__ */ new Set([
 	"create",
 	"update",
 	"delete",
@@ -1738,7 +1774,42 @@ function validateDefineResourceConfig(config) {
 	validatePermissionsShape(config);
 	validateCustomRoutePermissions(config);
 	validateActionsShape(config);
-	return collectRedundantFieldRuleDiagnostics(config);
+	return [...collectRedundantFieldRuleDiagnostics(config), ...collectReservedFilterNameDiagnostics(config)];
+}
+/**
+* Query-string param names arc's `QueryParser` reserves for
+* pagination/projection (`q.after ?? q.cursor` is the keyset cursor). A
+* document field with one of these names can never be filtered via the query
+* string — the parser consumes the name before it reaches the filter map — and
+* the same reservation flows into the MCP list-tool schema. Silent pre-2.20;
+* now surfaced.
+*/
+const RESERVED_QUERY_PARAMS = /* @__PURE__ */ new Set([
+	"page",
+	"limit",
+	"cursor",
+	"after",
+	"sort",
+	"search",
+	"select",
+	"populate"
+]);
+/**
+* Warn when a declared filterable field's NAME collides with a reserved query
+* param. Verified empirically (tests/e2e/reserved-field-name-collision.test.ts):
+* a field named `cursor`/`page` is silently unfilterable. Boot diagnostic, not
+* a hard error — the resource still works, the field just isn't query-filterable.
+*/
+function collectReservedFilterNameDiagnostics(config) {
+	const filterable = config.schemaOptions?.filterableFields;
+	if (!filterable) return [];
+	const collisions = filterable.filter((f) => RESERVED_QUERY_PARAMS.has(f));
+	if (collisions.length === 0) return [];
+	return [{
+		severity: "warn",
+		code: "filter-field-reserved-name",
+		message: `[Arc] Resource '${config.name}': filterable field(s) [${collisions.join(", ")}] collide with reserved query params (page, limit, cursor, after, sort, search, select, populate). The query parser consumes these names for pagination/projection, so filtering by them via the query string — and via the MCP list tool — will NOT work. Rename the field(s), or drop them from \`filterableFields\` if the collision is intended.`
+	}];
 }
 /** Permissions must be `PermissionCheck` functions, not arbitrary values. */
 function validatePermissionsShape(config) {
@@ -1820,6 +1891,7 @@ function defineResource(config) {
 	const configWithId = resolveIdField(normalisedConfig, repository);
 	const resolvedConfig = applyPresetsAndAutoInject(configWithId);
 	const hasCrudRoutes = computeHasCrudRoutes(resolvedConfig);
+	if (!normalisedConfig.skipValidation) diagnostics = diagnostics.concat(collectUngatedCrudDiagnostics(resolvedConfig));
 	const narrowedConfig = resolvedConfig;
 	const narrowedAdapter = configWithId.adapter;
 	const controller = resolveOrAutoCreateController(narrowedConfig, narrowedAdapter, repository, hasCrudRoutes);

package/dist/{createActionRouter-B_WzBFyf.mjs → createActionRouter-HlQso0jO.mjs}

@@ -1,9 +1,9 @@
 import { t as __exportAll } from "./rolldown-runtime-8H4AJuhK.mjs";
-import "./constants-gaEeMlz-.mjs";
+import "./constants-DNre0wRg.mjs";
 import { f as createError } from "./errors-DkO8Nk6-.mjs";
-import { i as resolvePipelineSteps, n as buildActionPipelineHandler, u as sendControllerResponse } from "./actionPermissions-D7NGwcAR.mjs";
-import { a as selectPluginMw, c as buildPreHandlerChain, d as buildAuthMiddlewareForPermissions, f as buildArcDecorator, i as resolveRouterPluginMw, n as buildRateLimitConfig, o as buildActionPermissionMw, r as buildRouteConfig, t as tryRegisterRoute } from "./registerRoute-BdV8DDwU.mjs";
-import { n as schemaIRToJsonSchemaBranch, t as normalizeSchemaIR } from "./schemaIR-D1MJwqmp.mjs";
+import { a as selectPluginMw, c as buildPreHandlerChain, d as buildAuthMiddlewareForPermissions, f as buildArcDecorator, i as resolveRouterPluginMw, n as buildRateLimitConfig, o as buildActionPermissionMw, r as buildRouteConfig, t as tryRegisterRoute } from "./registerRoute-DGSREwPw.mjs";
+import { i as resolvePipelineSteps, n as buildActionPipelineHandler, u as sendControllerResponse } from "./actionPermissions-C9RMiIpc.mjs";
+import { n as schemaIRToJsonSchemaBranch, t as normalizeSchemaIR } from "./schemaIR-ajetw3Fv.mjs";
 //#region src/core/createActionRouter.ts
 var createActionRouter_exports = /* @__PURE__ */ __exportAll({
 	buildActionBodySchema: () => buildActionBodySchema,

package/dist/{createAggregationRouter-B_G_nIjm.mjs → createAggregationRouter-5LzPzgw1.mjs}

@@ -1,7 +1,7 @@
 import { f as createError, l as UnauthorizedError, r as ForbiddenError } from "./errors-DkO8Nk6-.mjs";
-import { a as selectPluginMw, c as buildPreHandlerChain, f as buildArcDecorator, i as resolveRouterPluginMw, n as buildRateLimitConfig, u as buildAuthMiddleware } from "./registerRoute-BdV8DDwU.mjs";
-import { n as validateAggregations } from "./validate-CRcaWzp2.mjs";
-import { t as buildAggregationHandler } from "./buildHandler-B0qvAguf.mjs";
+import { a as selectPluginMw, c as buildPreHandlerChain, f as buildArcDecorator, i as resolveRouterPluginMw, n as buildRateLimitConfig, u as buildAuthMiddleware } from "./registerRoute-DGSREwPw.mjs";
+import { n as validateAggregations } from "./validate-C2mGgSXg.mjs";
+import { t as buildAggregationHandler } from "./buildHandler-D_2ULWxZ.mjs";
 //#region src/core/aggregation/createAggregationRouter.ts
 /**
 * Register one Fastify route per aggregation. No-op when the map is
@@ -39,7 +39,8 @@ function registerOne(fastify, normalized, ctx) {
 	const authMw = buildAuthMiddleware(fastify, config.permissions);
 	const permissionFn = config.permissions;
 	const permissionMw = async (req, _reply) => {
-		const raw = await permissionFn(buildPermissionContextLite(req, normalized.name));
+		const ctx = buildPermissionContextLite(req, normalized.name);
+		const raw = await permissionFn(ctx);
 		if (!normalizePermissionGranted(raw)) {
 			const status = req.user ? 403 : 401;
 			const reason = normalizePermissionReason(raw);