@classytic/arc 2.15.4 → 2.16.0

package/dist/buildHandler-BZX6zzDM.mjs

@@ -0,0 +1,300 @@
+import { n as compileAggRequest, t as adapterSupportsAggregate } from "./validate-By96rH0r.mjs";
+//#region src/core/aggregation/buildHandler.ts
+/**
+* Framework-agnostic aggregation execution. Runs safety guards,
+* compiles the AggRequest, dispatches to the materialized hook or
+* `repo.aggregate()`, and applies the post-execution `maxGroups` cap.
+*
+* Returns an envelope describing the response — Fastify wrappers
+* apply it to a reply, MCP wrappers convert it to a tool-call result.
+*
+* **Does NOT run the per-aggregation permission check.** Auth runs
+* upstream (Fastify preHandler chain or MCP `evaluatePermission`)
+* because the permission shape differs by surface (FastifyRequest vs
+* MCP session). Both surfaces fail-closed BEFORE reaching this
+* function; this is purely the runtime executor.
+*/
+async function executeAggregation(normalized, deps, ctx) {
+	const { repo } = deps;
+	const config = normalized.base;
+	const aggregationName = normalized.name;
+	const { query, tenantOptions } = ctx;
+	const guardError = checkRequestGuards(query, config);
+	if (guardError) return {
+		status: 400,
+		body: guardError
+	};
+	const aggReq = compileAggRequest(normalized, extractCallerFilter(query), tenantOptions);
+	if (config.materialized) {
+		const matCtx = {
+			filter: aggReq.filter,
+			orgId: pickString(tenantOptions.organizationId),
+			userId: pickString(tenantOptions.userId),
+			requestId: pickString(tenantOptions.requestId),
+			query
+		};
+		return {
+			status: 200,
+			headers: { "x-aggregation-source": "materialized" },
+			body: { rows: (await config.materialized(matCtx)).rows }
+		};
+	}
+	if (!adapterSupportsAggregate(repo)) return {
+		status: 501,
+		body: {
+			code: "arc.adapter.capability_required",
+			message: `Aggregation "${aggregationName}" is not supported: the resource's storage adapter does not implement repo.aggregate(). Use a kit that ships StandardRepo.aggregate (mongokit / sqlitekit), or remove the aggregations entry.`,
+			status: 501,
+			meta: {
+				capability: "aggregate",
+				aggregation: aggregationName
+			}
+		}
+	};
+	let result;
+	try {
+		result = await repo.aggregate(aggReq, tenantOptions);
+	} catch (err) {
+		return mapAggregateError(err, aggregationName);
+	}
+	if (config.maxGroups !== void 0 && result.rows.length > config.maxGroups) return {
+		status: 422,
+		body: {
+			code: "arc.aggregation.max_groups_exceeded",
+			message: `Aggregation "${aggregationName}" produced ${result.rows.length} groups, exceeding maxGroups (${config.maxGroups}). Narrow the filter or raise the cap.`,
+			status: 422,
+			meta: {
+				aggregation: aggregationName,
+				produced: result.rows.length,
+				maxGroups: config.maxGroups
+			}
+		}
+	};
+	return {
+		status: 200,
+		body: { rows: result.rows }
+	};
+}
+/**
+* Build the Fastify handler for a single aggregation.
+*
+* The returned function calls the repo (or materialized hook), shapes
+* the response envelope, and writes status/headers via Fastify's
+* `reply` API. Errors throw — the router's error handler converts to
+* the standard arc response shape.
+*/
+/**
+* Build the Fastify handler for a single aggregation.
+*
+* Caching lives in the kit's repo-core `cachePlugin` — when the host
+* declares `cache:` on the aggregation, `compileAggRequest` translates
+* to `aggReq.cache: CacheOptions` and the kit handles SWR + tag
+* invalidation + version-bump on writes. Arc passes the request
+* through; no duplicate cache layer at the HTTP handler.
+*/
+function buildAggregationHandler(normalized, deps) {
+	const { buildOptions } = deps;
+	return async (request, reply) => {
+		const result = await executeAggregation(normalized, deps, {
+			query: request.query ?? {},
+			tenantOptions: buildOptions(request)
+		});
+		reply.status(result.status);
+		if (result.headers) for (const [k, v] of Object.entries(result.headers)) reply.header(k, v);
+		return result.body;
+	};
+}
+function pickString(value) {
+	return typeof value === "string" ? value : void 0;
+}
+function checkRequestGuards(query, config) {
+	if (config.requireFilters) {
+		for (const field of config.requireFilters) if (!hasFilterOnField(query, field)) return {
+			code: "arc.aggregation.required_filter_missing",
+			message: `Aggregation requires filter on "${field}" — supply ?${field}=... or ?${field}[op]=... in the query string.`,
+			status: 400,
+			meta: { field }
+		};
+	}
+	if (config.requireDateRange) {
+		const { field, maxRangeDays } = config.requireDateRange;
+		const range = parseDateRange(query, field);
+		if (!range) return {
+			code: "arc.aggregation.required_date_range_missing",
+			message: `Aggregation requires a bounded date range on "${field}" — supply ?${field}[gte]=... and ?${field}[lt]=... (or ?${field}[lte]=...).`,
+			status: 400,
+			meta: { field }
+		};
+		if (maxRangeDays !== void 0) {
+			const days = (range.upper.getTime() - range.lower.getTime()) / 864e5;
+			if (days > maxRangeDays) return {
+				code: "arc.aggregation.date_range_exceeded",
+				message: `Aggregation date range on "${field}" exceeds the cap (${maxRangeDays} days). Requested range: ${days.toFixed(1)} days. Narrow the range and retry.`,
+				status: 400,
+				meta: {
+					field,
+					maxRangeDays,
+					requestedDays: days
+				}
+			};
+		}
+	}
+	return null;
+}
+function hasFilterOnField(query, field) {
+	const direct = query[field];
+	if (direct !== void 0 && direct !== "") return true;
+	for (const key of Object.keys(query)) if (key.startsWith(`${field}[`)) return true;
+	return false;
+}
+function parseDateRange(query, field) {
+	let gte;
+	let lte;
+	const nested = query[field];
+	if (nested && typeof nested === "object" && !Array.isArray(nested)) {
+		const ops = nested;
+		gte = pickString(ops.gte) ?? pickString(ops.gt);
+		lte = pickString(ops.lte) ?? pickString(ops.lt);
+	}
+	if (!gte) gte = pickString(query[`${field}[gte]`]) ?? pickString(query[`${field}[gt]`]);
+	if (!lte) lte = pickString(query[`${field}[lte]`]) ?? pickString(query[`${field}[lt]`]);
+	if (!gte || !lte) return null;
+	const lower = new Date(gte);
+	const upper = new Date(lte);
+	if (Number.isNaN(lower.getTime()) || Number.isNaN(upper.getTime())) return null;
+	if (upper <= lower) return null;
+	return {
+		lower,
+		upper
+	};
+}
+/**
+* Bracket-syntax operator shorthand → canonical Mongo operator. Mirrors
+* the `operators` map in `ArcQueryParser` so the aggregation route emits
+* the same shape the CRUD list route produces. Aggregations don't run
+* through the resource-level QueryParser (they have their own URL→IR
+* compile path), so this translation has to happen in arc itself —
+* downstream kits' filter compilers expect canonical `$gte/$lte/$in/...`
+* keys, not bare `gte/lte/in/...` shorthand.
+*/
+const OPERATOR_SHORTHAND = {
+	eq: "$eq",
+	ne: "$ne",
+	gt: "$gt",
+	gte: "$gte",
+	lt: "$lt",
+	lte: "$lte",
+	in: "$in",
+	nin: "$nin",
+	like: "$regex",
+	contains: "$regex",
+	regex: "$regex",
+	exists: "$exists",
+	size: "$size",
+	type: "$type"
+};
+const SHORTHAND_RANGE_OPS = new Set([
+	"gt",
+	"gte",
+	"lt",
+	"lte"
+]);
+const ISO_DATE_RE = /^\d{4}-\d{2}-\d{2}(?:T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:?\d{2})?)?$/;
+function tryCoerceDate(v) {
+	if (typeof v !== "string" || !ISO_DATE_RE.test(v)) return v;
+	const d = new Date(v);
+	return Number.isNaN(d.getTime()) ? v : d;
+}
+/**
+* Translate a qs-parsed nested-operator object (`{ field: { gte, lte } }`)
+* into Mongo-shape (`{ field: { $gte: Date, $lte: Date } }`). Only fires
+* when EVERY key is a known shorthand operator — leaves user-data
+* objects untouched so callers can still equality-match on a stored
+* sub-document.
+*/
+function expandShorthandOperators(value) {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return value;
+	const nested = value;
+	const keys = Object.keys(nested);
+	if (keys.length === 0) return value;
+	if (!keys.every((k) => !k.startsWith("$") && OPERATOR_SHORTHAND[k] !== void 0)) return value;
+	const expanded = {};
+	for (const [op, opVal] of Object.entries(nested)) {
+		const mongoOp = OPERATOR_SHORTHAND[op];
+		if (!mongoOp) continue;
+		expanded[mongoOp] = SHORTHAND_RANGE_OPS.has(op) ? tryCoerceDate(opVal) : opVal;
+	}
+	return expanded;
+}
+/**
+* Strip control params (page/limit/sort/select/...) and the resource-
+* dispatch verbs from the query, leaving only filter predicates the
+* caller used to narrow the aggregation. Bracket-syntax operator
+* shorthand (`createdAt[gte]=...`) gets translated to canonical Mongo-
+* shape here so kits don't have to reimplement the URL grammar — same
+* contract `ArcQueryParser` enforces for the CRUD list route.
+*
+* The resulting record is shallow-merged into the AggRequest filter
+* via `compileAggRequest`.
+*/
+function extractCallerFilter(query) {
+	const out = {};
+	const reserved = new Set([
+		"page",
+		"limit",
+		"after",
+		"sort",
+		"select",
+		"populate",
+		"search",
+		"_count",
+		"_distinct",
+		"_exists"
+	]);
+	for (const [key, value] of Object.entries(query)) {
+		if (reserved.has(key)) continue;
+		if (value === void 0 || value === "") continue;
+		out[key] = expandShorthandOperators(value);
+	}
+	return out;
+}
+/**
+* Map a kit-thrown error to the framework-agnostic execute response.
+* Detects two well-known signals:
+*   - "unsupported" / "not implemented" → 501 with upgrade hint
+*   - timeout markers → 504
+*   - everything else → 500
+*/
+function mapAggregateError(err, aggregationName) {
+	const message = err instanceof Error ? err.message : String(err);
+	const lower = message.toLowerCase();
+	if (lower.includes("unsupported") || lower.includes("not implemented")) return {
+		status: 501,
+		body: {
+			code: "arc.adapter.capability_required",
+			message: `Aggregation "${aggregationName}" failed: ${message}. The kit may not yet support this feature (e.g. lookups in aggregate). Upgrade the kit or remove the unsupported field.`,
+			status: 501,
+			meta: { aggregation: aggregationName }
+		}
+	};
+	if (lower.includes("maxtimems") || lower.includes("timeout") || lower.includes("timed out")) return {
+		status: 504,
+		body: {
+			code: "arc.gateway_timeout",
+			message: `Aggregation "${aggregationName}" timed out: ${message}. Narrow the filter or raise the timeout.`,
+			status: 504,
+			meta: { aggregation: aggregationName }
+		}
+	};
+	return {
+		status: 500,
+		body: {
+			code: "arc.internal_error",
+			message: `Aggregation "${aggregationName}" failed: ${message}`,
+			status: 500,
+			meta: { aggregation: aggregationName }
+		}
+	};
+}
+//#endregion
+export { executeAggregation as n, buildAggregationHandler as t };

package/dist/cache/index.d.mts

@@ -1,6 +1,6 @@
-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";
+import { n as CacheStats, r as CacheStore, t as CacheLogger } from "../interface-CH0OQudo.mjs";
+import { a as QueryCacheConfig, i as QueryCache, n as CacheResult, r as CacheStatus, t as CacheEnvelope } from "../QueryCache-SvmT_9ti.mjs";
+import { i as queryCachePlugin, n as QueryCacheDefaults, r as QueryCachePluginOptions, t as CrossResourceRule } from "../queryCachePlugin-Biqzfbi5.mjs";
 
 //#region src/cache/keys.d.ts
 /**

package/dist/cache/index.mjs

@@ -1,6 +1,6 @@
-import { t as MemoryCacheStore } from "../memory-UBydS5ku.mjs";
-import { i as versionKey, n as hashParams, r as tagVersionKey, t as buildQueryKey } from "../keys-CGcCbNyu.mjs";
-import { r as QueryCache, t as queryCachePlugin } from "../queryCachePlugin-m1XsgAIJ.mjs";
+import { t as MemoryCacheStore } from "../memory-QOLe11D5.mjs";
+import { i as versionKey, n as hashParams, r as tagVersionKey, t as buildQueryKey } from "../keys-DopsCuyQ.mjs";
+import { r as QueryCache, t as queryCachePlugin } from "../queryCachePlugin-B4XMSSe7.mjs";
 //#region src/cache/redis.ts
 /**
 * Redis-backed cache store.

package/dist/{caching-SM8gghN6.mjs → caching-TeHE8G-v.mjs}

@@ -21,7 +21,7 @@ const cachingPlugin = async (fastify, opts = {}) => {
 	const methodSet = new Set(methods.map((m) => m.toUpperCase()));
 	/** Find the first matching rule for a URL path */
 	function findRule(url) {
-		const path = url.split("?")[0];
+		const path = url.split("?")[0] ?? url;
 		return rules.find((r) => path.startsWith(r.match));
 	}
 	/** Build Cache-Control header value */

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

@@ -1,4 +1,4 @@
-import { V as ResourceDefinition, ft as RouteSchemaOptions, rt as RateLimitConfig } from "../../index-BswOSJCE.mjs";
+import { V as ResourceDefinition, it as RateLimitConfig, mt as RouteSchemaOptions } from "../../index-CkW0flkU.mjs";
 
 //#region src/cli/commands/describe.d.ts
 interface DescribedResource {
@@ -32,12 +32,46 @@ interface DescribedResource {
   schemaOptions?: RouteSchemaOptions;
   rateLimit?: RateLimitConfig | false;
   middlewares: string[];
+  /**
+   * 2.15.5+: multi-tenant + cascade metadata. Surfaced so audit scripts
+   * answering "what cascades on org-delete?" or "what scopes by org?"
+   * read from one source instead of grepping resource files. Mirrors
+   * the registry projection — same shape consumed by
+   * `getCascadingResources()` and `assertNoTenantData()`.
+   */
+  tenancy: {
+    tenantField: string | false | undefined;
+    /**
+     * Resolved purge strategy — what `cascadeDeleteForOrganization`
+     * actually runs (`hard` / `soft` / `anonymize` / `skip`) plus where
+     * the rule came from (`declared` / `inferred-soft` / `inferred-hard`
+     * / `disabled`).
+     */
+    purgeStrategy?: {
+      type: string;
+      source: string;
+    };
+  };
+  /**
+   * 2.16: configured primary-key field. Defaults to `_id`; hosts pin it
+   * to a domain handle (`slug`, `reportId`, `sku`) for non-Mongo schemas
+   * — the CLI surfaces it so generated code / tooling can compose
+   * `findOne` filters via the right key.
+   */
+  idField: string;
 }
 interface ActionDescription {
   name: string;
   description?: string;
   hasSchema: boolean;
   permission: PermissionDescription;
+  /**
+   * 2.15.5: mount preference — `true` (default) for `POST /<prefix>/:id/action`,
+   * `false` for `POST /<prefix>/action` (resource-root, no `:id`).
+   */
+  requiresId: boolean;
+  /** Mount-point URL suffix derived from `requiresId`. */
+  mount: "/:id/action" | "/action";
 }
 interface AggregationDescription {
   name: string;

package/dist/cli/commands/describe.mjs

@@ -1,5 +1,5 @@
-import { t as CRUD_OPERATIONS } from "../../constants-Cxde4rpC.mjs";
-import { n as stringifyMeasureMap } from "../../ResourceRegistry-CTERg_2x.mjs";
+import { t as CRUD_OPERATIONS } from "../../constants-TrJVIJl0.mjs";
+import { n as stringifyMeasureMap } from "../../ResourceRegistry-f48hFk3m.mjs";
 import { resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 //#region src/cli/commands/describe.ts
@@ -129,13 +129,40 @@ function describeRoutes(resource) {
 			routes.push(route);
 		}
 	}
-	for (const ar of resource.routes ?? []) routes.push({
-		method: ar.method,
-		path: `${resource.prefix}${ar.path}`,
-		operation: typeof ar.handler === "string" ? ar.handler : "custom",
-		summary: ar.summary,
-		description: ar.description,
-		permission: describePermission(ar.permissions)
+	for (const ar of resource.routes ?? []) {
+		const arWithRef = ar;
+		let operation;
+		if (typeof ar.handler === "string") operation = ar.handler;
+		else if (typeof arWithRef.controllerMethod === "function") operation = ar.operation ?? arWithRef.controllerMethod.name ?? "controllerMethod";
+		else operation = ar.operation ?? "custom";
+		routes.push({
+			method: ar.method,
+			path: `${resource.prefix}${ar.path}`,
+			operation,
+			summary: ar.summary,
+			description: ar.description,
+			permission: describePermission(ar.permissions)
+		});
+	}
+	if (resource.actions && Object.keys(resource.actions).length > 0) {
+		const entries = Object.entries(resource.actions);
+		const hasIdBound = entries.some(([, e]) => typeof e === "function" || e.id !== false);
+		const hasIdLess = entries.some(([, e]) => typeof e !== "function" && e.id === false);
+		if (hasIdBound) routes.push({
+			method: "POST",
+			path: `${resource.prefix}/:id/action`,
+			operation: "action"
+		});
+		if (hasIdLess) routes.push({
+			method: "POST",
+			path: `${resource.prefix}/action`,
+			operation: "action"
+		});
+	}
+	if (resource.aggregations) for (const name of Object.keys(resource.aggregations)) routes.push({
+		method: "GET",
+		path: `${resource.prefix}/aggregations/${name}`,
+		operation: `aggregation:${name}`
 	});
 	return routes;
 }
@@ -160,13 +187,18 @@ function describeActions(actions, fallback) {
 		if (typeof entry === "function") return {
 			name,
 			hasSchema: false,
-			permission: describePermission(fallback)
+			permission: describePermission(fallback),
+			requiresId: true,
+			mount: "/:id/action"
 		};
+		const requiresId = entry.id !== false;
 		return {
 			name,
 			description: entry.description,
 			hasSchema: !!entry.schema,
-			permission: describePermission(entry.permissions ?? fallback)
+			permission: describePermission(entry.permissions ?? fallback),
+			requiresId,
+			mount: requiresId ? "/:id/action" : "/action"
 		};
 	});
 }
@@ -224,7 +256,15 @@ function describeResource(resource, module) {
 		aggregations: describeAggregations(resource.aggregations),
 		schemaOptions: Object.keys(resource.schemaOptions ?? {}).length > 0 ? resource.schemaOptions : void 0,
 		rateLimit: resource.rateLimit,
-		middlewares: describeMiddlewares(resource.middlewares)
+		middlewares: describeMiddlewares(resource.middlewares),
+		tenancy: {
+			tenantField: resource.tenantField,
+			...resource.resolvedTenantPurge ? { purgeStrategy: {
+				type: resource.resolvedTenantPurge.strategy.type,
+				source: resource.resolvedTenantPurge.source
+			} } : {}
+		},
+		idField: resource.idField ?? "_id"
 	};
 }
 async function describe(args) {

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

@@ -6,8 +6,5 @@
  * Requires an entry file that exports defineResource() results.
  */
 declare function exportDocs(args: string[]): Promise<void>;
-declare const _default: {
-  exportDocs: typeof exportDocs;
-};
 //#endregion
-export { _default as default, exportDocs };
+export { exportDocs };

package/dist/cli/commands/docs.mjs

@@ -1,7 +1,6 @@
-import { t as ResourceRegistry } from "../../ResourceRegistry-CTERg_2x.mjs";
-import { t as buildOpenApiSpec } from "../../openapi-BHXhoX8O.mjs";
+import { t as buildOpenApiSpec } from "../../openapi-34T9yNwd.mjs";
+import { t as loadResourcesFromEntry } from "../../loadResourcesFromEntry-BLMEI2Xa.mjs";
 import { dirname, resolve } from "node:path";
-import { pathToFileURL } from "node:url";
 import { mkdirSync, writeFileSync } from "node:fs";
 //#region src/cli/commands/docs.ts
 /**
@@ -21,17 +20,7 @@ async function exportDocs(args) {
 	const { entryPath, outputPath } = parseDocsArgs(args);
 	console.log("Exporting OpenAPI specification...\n");
 	if (!entryPath) throw new Error("Missing entry file.\n\nUsage: arc docs <entry-file> [output.json]\nExample: arc docs ./src/resources.js ./openapi.json");
-	const entryModule = await import(pathToFileURL(resolve(process.cwd(), entryPath)).href);
-	const registry = new ResourceRegistry();
-	let registered = 0;
-	function tryRegister(value) {
-		if (value && typeof value === "object" && "name" in value && "_registryMeta" in value && "toPlugin" in value) {
-			registry.register(value, value._registryMeta ?? {});
-			registered++;
-		}
-	}
-	for (const exported of Object.values(entryModule)) if (Array.isArray(exported)) exported.forEach(tryRegister);
-	else tryRegister(exported);
+	const { registry, registered } = await loadResourcesFromEntry(entryPath);
 	if (registered === 0) throw new Error("No resource definitions found in entry file.\nMake sure your file exports defineResource() results:\n  export const productResource = defineResource({ ... });");
 	const resources = registry.getAll();
 	const spec = buildOpenApiSpec(resources, {
@@ -46,6 +35,5 @@ async function exportDocs(args) {
 	console.log(`\nResources included: ${resources.length}`);
 	console.log(`Total endpoints: ${Object.keys(spec.paths).length}`);
 }
-var docs_default = { exportDocs };
 //#endregion
-export { docs_default as default, exportDocs };
+export { exportDocs };

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

@@ -1,20 +1,2 @@
-//#region src/cli/commands/generate.d.ts
-/**
- * Arc CLI - Generate Command
- *
- * Scaffolds resources with consistent naming:
- * - src/resources/product/product.model.ts
- * - src/resources/product/product.repository.ts
- * - src/resources/product/product.resource.ts
- *
- * Handles kebab-case names: `arc g r org-profile` generates:
- * - Class names: OrgProfile, OrgProfileRepository
- * - Variable names: orgProfileSchema, orgProfileRepository
- * - File names: org-profile.model.ts, org-profile.repository.ts
- */
-/**
- * Generate command handler
- */
-declare function generate(type: string | undefined, args: string[]): Promise<void>;
-//#endregion
-export { generate };
+import { n as generate, t as ArcProjectConfig } from "../../generate-BWFwgcCM.mjs";
+export { ArcProjectConfig, generate };