@classytic/arc 2.10.8 → 2.11.0

package/dist/{tracing-xqXzWeaf.d.mts → tracing-DokiEsuz.d.mts}

@@ -1,4 +1,5 @@
 import { FastifyInstance, FastifyRequest } from "fastify";
+import { Span, Tracer } from "@opentelemetry/api";
 
 //#region src/plugins/tracing.d.ts
 interface TracingOptions {
@@ -28,8 +29,8 @@ interface TracingOptions {
   sampleRate?: number;
 }
 interface TracerContext {
-  tracer: any;
-  currentSpan: any;
+  tracer: Tracer;
+  currentSpan: Span;
 }
 declare module "fastify" {
   interface FastifyRequest {
@@ -53,7 +54,7 @@ declare function tracingPlugin(fastify: FastifyInstance, options?: TracingOption
  *   });
  * }
  */
-declare function createSpan<T>(request: FastifyRequest, name: string, fn: (span: any) => Promise<T>, attributes?: Record<string, any>): Promise<T>;
+declare function createSpan<T>(request: FastifyRequest, name: string, fn: (span: Span | null) => Promise<T>, attributes?: Record<string, string | number | boolean>): Promise<T>;
 /**
  * Decorator to automatically trace repository methods
  *
@@ -65,7 +66,11 @@ declare function createSpan<T>(request: FastifyRequest, name: string, fn: (span:
  *   }
  * }
  */
-declare function traced(spanName?: string): (target: any, propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor;
+declare function traced(spanName?: string): (target: {
+  constructor: {
+    name: string;
+  };
+}, propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor;
 /**
  * Check if OpenTelemetry is available
  */

package/dist/types/index.d.mts

@@ -1,5 +1,5 @@
-import { $t as ObjectId, A as RequestIdOptions, At as FastifyHandler, C as RequestContext, Ct as ResourcePermissions, D as HealthCheck, Dt as RouteSchemaOptions, E as GracefulShutdownOptions, Et as RouteMethod, F as FastifyWithDecorators, Gt as Authenticator, I as MiddlewareHandler, Jt as TokenPair, Kt as AuthenticatorContext, L as RequestWithExtras, M as EventsDecorator, Mt as IControllerResponse, N as FastifyRequestExtras, Nt as IRequestContext, O as HealthOptions, Ot as ControllerHandler, P as FastifyWithAuth, Pt as RouteHandler, Qt as JWTPayload, S as QueryParserInterface, St as ResourceHooks, T as CrudRouterOptions, Tt as RouteMcpConfig, Ut as AuthHelpers, Wt as AuthPluginOptions, Xt as ApiResponse, Yt as AnyRecord, Zt as ArcRequest, _ as ControllerQueryOptions, _t as PresetResult, a as InferAdapterDoc, an as BaseControllerOptions, at as ActionEntry, b as ParsedQuery, bt as ResourceConfig, c as TypedController, ct as CrudController, d as PaginationResult, dt as EventDefinition, en as UserLike, f as IntrospectionData, ft as FieldRule, g as ArcInternalMetadata, gt as PresetHook, h as ResourceMetadata, ht as PresetFunction, i as ValidationResult, it as ActionDefinition, j as ArcDecorator, jt as IController, k as IntrospectionPluginOptions, kt as ControllerLike, l as TypedRepository, lt as CrudRouteKey, m as RegistryStats, mt as OpenApiSchemas, n as ConfigError, nn as envelope, o as InferDocType, ot as ActionHandlerFn, p as RegistryEntry, pt as MiddlewareConfig, qt as JwtContext, r as ValidateOptions, rn as getUserId, s as InferResourceDoc, st as ActionsMap, t as RouteHandlerMethod, tn as UserOrganization, u as TypedResourceConfig, ut as CrudSchemas, v as LookupOption, vt as RateLimitConfig, w as ServiceContext, wt as RouteDefinition, x as PopulateOption, xt as ResourceHookContext, y as OwnershipCheck, yt as ResourceCacheConfig } from "../index-BGbpGVyM.mjs";
-import { _ as isAuthenticated, c as getOrgRoles, g as hasOrgAccess, n as PUBLIC_SCOPE, p as getTeamId, r as RequestScope, s as getOrgId, t as AUTHENTICATED_SCOPE, v as isElevated, y as isMember } from "../types-tgR4Pt8F.mjs";
+import { $ as OpenApiSchemas, A as RequestIdOptions, At as Authenticator, Bt as UserOrganization, C as RequestContext, D as HealthCheck, E as GracefulShutdownOptions, F as FastifyWithDecorators, Ft as ApiResponse, G as ActionsMap, H as ActionDefinition, I as MiddlewareHandler, It as ArcRequest, J as CrudRouteKey, K as ArcFieldRule, L as RequestWithExtras, Lt as JWTPayload, M as EventsDecorator, Mt as JwtContext, N as FastifyRequestExtras, Nt as TokenPair, O as HealthOptions, Ot as AuthHelpers, P as FastifyWithAuth, Pt as AnyRecord, Q as MiddlewareConfig, Rt as ObjectId, S as QueryParserInterface, T as CrudRouterOptions, U as ActionEntry, W as ActionHandlerFn, X as EventDefinition, Y as CrudSchemas, Z as FieldRule, _ as ControllerQueryOptions, _t as IControllerResponse, a as InferAdapterDoc, at as ResourceConfig, b as ParsedQuery, c as TypedController, ct as ResourcePermissions, d as PaginationResult, dt as RouteMethod, et as PresetFunction, f as IntrospectionData, ft as RouteSchemaOptions, g as ArcInternalMetadata, gt as IController, h as ResourceMetadata, ht as FastifyHandler, i as ValidationResult, it as ResourceCacheConfig, j as ArcDecorator, jt as AuthenticatorContext, k as IntrospectionPluginOptions, kt as AuthPluginOptions, l as TypedRepository, lt as RouteDefinition, m as RegistryStats, mt as ControllerLike, n as ConfigError, nt as PresetResult, o as InferDocType, ot as ResourceHookContext, p as RegistryEntry, pt as ControllerHandler, q as CrudController, r as ValidateOptions, rt as RateLimitConfig, s as InferResourceDoc, st as ResourceHooks, t as RouteHandlerMethod, tn as BaseControllerOptions, tt as PresetHook, u as TypedResourceConfig, ut as RouteMcpConfig, v as LookupOption, vt as IRequestContext, w as ServiceContext, x as PopulateOption, y as OwnershipCheck, yt as RouteHandler, zt as UserLike } from "../index-Cm0vUrr_.mjs";
+import { r as RequestScope } from "../types-tgR4Pt8F.mjs";
 import { c as PermissionCheck, d as UserBase, l as PermissionContext, u as PermissionResult } from "../fields-C8Y0XLAu.mjs";
 import { n as ElevationOptions, t as ElevationEvent } from "../elevation-s5ykdNHr.mjs";
-export { AUTHENTICATED_SCOPE, ActionDefinition, ActionEntry, ActionHandlerFn, ActionsMap, AnyRecord, ApiResponse, ArcDecorator, ArcInternalMetadata, ArcRequest, AuthHelpers, AuthPluginOptions, Authenticator, AuthenticatorContext, BaseControllerOptions, ConfigError, ControllerHandler, ControllerLike, ControllerQueryOptions, CrudController, CrudRouteKey, CrudRouterOptions, CrudSchemas, ElevationEvent, ElevationOptions, EventDefinition, EventsDecorator, FastifyHandler, FastifyRequestExtras, FastifyWithAuth, FastifyWithDecorators, FieldRule, GracefulShutdownOptions, HealthCheck, HealthOptions, IController, IControllerResponse, IRequestContext, InferAdapterDoc, InferDocType, InferResourceDoc, IntrospectionData, IntrospectionPluginOptions, JWTPayload, JwtContext, LookupOption, MiddlewareConfig, MiddlewareHandler, ObjectId, OpenApiSchemas, OwnershipCheck, PUBLIC_SCOPE, PaginationResult, ParsedQuery, PermissionCheck, PermissionContext, PermissionResult, PopulateOption, PresetFunction, PresetHook, PresetResult, QueryParserInterface, RateLimitConfig, RegistryEntry, RegistryStats, RequestContext, RequestIdOptions, RequestScope, RequestWithExtras, ResourceCacheConfig, ResourceConfig, ResourceHookContext, ResourceHooks, ResourceMetadata, ResourcePermissions, RouteDefinition, RouteHandler, RouteHandlerMethod, RouteMcpConfig, RouteMethod, RouteSchemaOptions, ServiceContext, TokenPair, TypedController, TypedRepository, TypedResourceConfig, UserBase, UserLike, UserOrganization, ValidateOptions, ValidationResult, envelope, getOrgId, getOrgRoles, getTeamId, getUserId, hasOrgAccess, isAuthenticated, isElevated, isMember };
+export { ActionDefinition, ActionEntry, ActionHandlerFn, ActionsMap, AnyRecord, ApiResponse, ArcDecorator, ArcFieldRule, ArcInternalMetadata, ArcRequest, AuthHelpers, AuthPluginOptions, Authenticator, AuthenticatorContext, BaseControllerOptions, ConfigError, ControllerHandler, ControllerLike, ControllerQueryOptions, CrudController, CrudRouteKey, CrudRouterOptions, CrudSchemas, ElevationEvent, ElevationOptions, EventDefinition, EventsDecorator, FastifyHandler, FastifyRequestExtras, FastifyWithAuth, FastifyWithDecorators, FieldRule, GracefulShutdownOptions, HealthCheck, HealthOptions, IController, IControllerResponse, IRequestContext, InferAdapterDoc, InferDocType, InferResourceDoc, IntrospectionData, IntrospectionPluginOptions, JWTPayload, JwtContext, LookupOption, MiddlewareConfig, MiddlewareHandler, ObjectId, OpenApiSchemas, OwnershipCheck, PaginationResult, ParsedQuery, PermissionCheck, PermissionContext, PermissionResult, PopulateOption, PresetFunction, PresetHook, PresetResult, QueryParserInterface, RateLimitConfig, RegistryEntry, RegistryStats, RequestContext, RequestIdOptions, RequestScope, RequestWithExtras, ResourceCacheConfig, ResourceConfig, ResourceHookContext, ResourceHooks, ResourceMetadata, ResourcePermissions, RouteDefinition, RouteHandler, RouteHandlerMethod, RouteMcpConfig, RouteMethod, RouteSchemaOptions, ServiceContext, TokenPair, TypedController, TypedRepository, TypedResourceConfig, UserBase, UserLike, UserOrganization, ValidateOptions, ValidationResult };

package/dist/types/index.mjs

@@ -1,3 +1 @@
-import { _ as isElevated, f as getTeamId, g as isAuthenticated, h as hasOrgAccess, n as PUBLIC_SCOPE, o as getOrgId, s as getOrgRoles, t as AUTHENTICATED_SCOPE, v as isMember } from "../types-AOD8fxIw.mjs";
-import { n as getUserId, t as envelope } from "../types-CDnTEpga.mjs";
-export { AUTHENTICATED_SCOPE, PUBLIC_SCOPE, envelope, getOrgId, getOrgRoles, getTeamId, getUserId, hasOrgAccess, isAuthenticated, isElevated, isMember };
+export {};

package/dist/{types-CVdgPXBW.d.mts → types-CgikqKAj.d.mts}

@@ -1,13 +1,13 @@
-import { Gt as Authenticator } from "./index-BGbpGVyM.mjs";
+import { At as Authenticator } from "./index-Cm0vUrr_.mjs";
+import { r as CacheStore } from "./interface-Da0r7Lna.mjs";
 import { n as ElevationOptions } from "./elevation-s5ykdNHr.mjs";
 import { o as EventTransport } from "./EventTransport-CfVEGaEl.mjs";
 import { t as ExternalOpenApiPaths } from "./externalPaths-Bapitwvd.mjs";
-import { r as CacheStore } from "./interface-yhyb_pLY.mjs";
-import { r as QueryCachePluginOptions } from "./queryCachePlugin-Dumka73q.mjs";
-import { t as EventPluginOptions } from "./eventPlugin-D1ThQ1Pp.mjs";
-import { f as CachingOptions, l as SSEOptions, o as MetricsOptions, t as VersioningOptions } from "./versioning-CeUXHfjw.mjs";
-import { t as ErrorHandlerOptions } from "./errorHandler-2ii4RIYr.mjs";
-import { r as IdempotencyStore } from "./interface-B-pe8fhj.mjs";
+import { r as QueryCachePluginOptions } from "./queryCachePlugin-BUXBSm4F.mjs";
+import { t as EventPluginOptions } from "./eventPlugin-CUNjYYRY.mjs";
+import { f as CachingOptions, l as SSEOptions, o as MetricsOptions, t as VersioningOptions } from "./versioning-M9lNLhO8.mjs";
+import { t as ErrorHandlerOptions } from "./errorHandler-Co3lnVmJ.mjs";
+import { r as IdempotencyStore } from "./interface-CkkWm5uR.mjs";
 import { FastifyInstance, FastifyPluginAsync, FastifyReply, FastifyRequest, FastifyServerOptions } from "fastify";
 
 //#region src/factory/loadResources.d.ts
@@ -653,18 +653,70 @@ interface CreateAppOptions {
    */
   serializeBigInt?: boolean;
   /**
-   * Resources to register automatically.
-   * Each resource's `.toPlugin()` is called and registered for you.
+   * Resources to register automatically. Accepts two shapes:
    *
-   * @example
+   *   1. **Array** — each resource's `.toPlugin()` is called and registered.
+   *      Defined at module-import time, so the resource's adapter must be
+   *      constructible without any async state.
+   *
+   *   2. **Factory function** (sync or async) — called AFTER `bootstrap[]`
+   *      but BEFORE routes are wired. Use this when a resource's adapter
+   *      depends on an engine / singleton that boots asynchronously
+   *      (e.g. `await ensureCatalogEngine()` / `await createFlowEngine()`).
+   *      The factory receives the Fastify instance for symmetry with
+   *      `plugins` and `bootstrap`.
+   *
+   * Arc's lifecycle contract:
+   * ```
+   * 1. Arc core (security, auth, events)
+   * 2. plugins()            ← infra (DB, SSE, docs)
+   * 3. bootstrap[]          ← domain init (engines, singletons)
+   * 4. resources resolution ← (factory form: call it here)
+   * 5. resources registered ← plugins mounted on Fastify
+   * 6. afterResources()     ← post-registration wiring
+   * ```
+   *
+   * The factory form is the canonical answer to "my repository lives in an
+   * engine that boots asynchronously." Before this shape existed, hosts had
+   * to write per-resource lazy-bridge adapters that awaited the engine on
+   * every CRUD call — pure boilerplate. With a factory, `defineResource(...)`
+   * runs with the engine already live, so `createMongooseAdapter(engine.models.X, engine.repositories.X)`
+   * works directly.
+   *
+   * @example Static array (most resources)
    * ```ts
    * const app = await createApp({
    *   resources: [productResource, orderResource, userResource],
    *   auth: { type: 'jwt', jwt: { secret: 'xxx' } },
    * });
    * ```
+   *
+   * @example Factory with async-booted engine
+   * ```ts
+   * const app = await createApp({
+   *   bootstrap: [async () => { await ensureCatalogEngine(); }],
+   *   resources: async () => {
+   *     const cat = await ensureCatalogEngine();
+   *     return [
+   *       defineResource({
+   *         name: 'product',
+   *         adapter: createMongooseAdapter(cat.models.Product, cat.repositories.product),
+   *         // ...
+   *       }),
+   *     ];
+   *   },
+   * });
+   * ```
+   *
+   * @example Factory delegating to auto-discovery
+   * ```ts
+   * const app = await createApp({
+   *   bootstrap: [async () => { await ensureCatalogEngine(); }],
+   *   resources: async () => loadResources(import.meta.url),
+   * });
+   * ```
    */
-  resources?: Array<ResourceLike>;
+  resources?: ReadonlyArray<ResourceLike> | ((fastify: FastifyInstance) => ReadonlyArray<ResourceLike> | Promise<ReadonlyArray<ResourceLike>>);
   /**
    * URL prefix for all auto-registered resources.
    * Applied only to resources in the `resources` array — not to `plugins()`.
@@ -681,25 +733,72 @@ interface CreateAppOptions {
   resourcePrefix?: string;
   /**
    * Auto-discover resources from a directory instead of passing an explicit
-   * `resources` array. Resolves relative to `process.cwd()`.
+   * `resources` array.
    *
-   * This replaces the common pattern:
-   * ```ts
-   * resources: await loadResources(import.meta.url)
-   * ```
+   * Accepts either a filesystem path OR `import.meta.url` (a `file://` URL).
+   * **Prefer the URL form in production** — bare strings resolve relative to
+   * `process.cwd()`, which diverges from `dist/` at runtime and was the root
+   * cause of a reported "deployed app serves 404 on every route" incident.
    *
-   * When both `resourceDir` and `resources` are provided, `resources` wins
-   * (explicit always beats convention).
+   * When both `resourceDir` and `resources` are provided, `resources` wins —
+   * explicit always beats convention, **including an explicit empty array**.
+   * `resources: []` disables resource registration entirely even with
+   * `resourceDir` set, which is the common case for shared base configs
+   * that turn resource loading off in test / CLI / health-check subprocesses.
+   * Auto-discovery from `resourceDir` fires only when `resources` is
+   * `undefined` (absent).
    *
    * @example
    * ```ts
+   * // Recommended (v2.10.9+): URL form works in both src/ and dist/
    * const app = await createApp({
-   *   resourceDir: 'src/resources',
+   *   resourceDir: import.meta.url,
    *   resourcePrefix: '/api/v1',
    * });
+   *
+   * // String form — resolves against process.cwd(), mind the dist/ gap
+   * const app = await createApp({
+   *   resourceDir: 'src/resources',
+   * });
    * ```
    */
   resourceDir?: string;
+  /**
+   * Throw instead of silently booting with zero resources when `resourceDir`
+   * yields an empty result. Off by default to preserve back-compat — turning
+   * it on in production catches the "typoed path / stale dist/ layout"
+   * failure mode before the app accepts traffic.
+   *
+   * Only takes effect when `resourceDir` is set.
+   *
+   * @example
+   * ```ts
+   * await createApp({
+   *   resourceDir: import.meta.url,
+   *   strictResourceDir: process.env.NODE_ENV === 'production',
+   * });
+   * ```
+   *
+   * @default false
+   */
+  strictResourceDir?: boolean;
+  /**
+   * Throw instead of warn when two resources share the same `name`. Off by
+   * default to preserve back-compat; turn on in production to catch stale
+   * `dist/` files (a common source of `Mongoose model already exists`
+   * collisions downstream of arc's own registry).
+   *
+   * @example
+   * ```ts
+   * await createApp({
+   *   resources: await loadResources(import.meta.url),
+   *   strictResources: process.env.NODE_ENV === 'production',
+   * });
+   * ```
+   *
+   * @default false
+   */
+  strictResources?: boolean;
   /**
    * Custom plugin registration — runs after Arc core (security, auth, events)
    * but before `bootstrap` and `resources`.

package/dist/{types-CVKBssX5.d.mts → types-D9NqiYIw.d.mts}

@@ -1,4 +1,4 @@
-import { B as ResourceDefinition } from "./index-BGbpGVyM.mjs";
+import { B as ResourceDefinition } from "./index-Cm0vUrr_.mjs";
 import { z } from "zod";
 
 //#region src/integrations/mcp/types.d.ts