@classytic/arc 2.4.3 → 2.6.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classytic/arc",
-  "version": "2.4.3",
+  "version": "2.6.2",
   "description": "Resource-oriented backend framework for Fastify — clean, minimal, powerful, tree-shakable",
   "type": "module",
   "exports": {
@@ -220,7 +220,7 @@
     "node": ">=22"
   },
   "peerDependencies": {
-    "@classytic/mongokit": ">=3.4.5",
+    "@classytic/mongokit": ">=3.5.0",
     "@classytic/streamline": ">=2.0.0",
     "@fastify/cors": "^11.0.0",
     "@fastify/helmet": "^13.0.0",
@@ -244,7 +244,7 @@
     "fastify-raw-body": "^5.0.0",
     "ioredis": "^5.0.0",
     "mongodb": "^6.0.0 || ^7.0.0",
-    "mongoose": "^8.0.0 || ^9.0.0",
+    "mongoose": ">=9.0.0",
     "pino-pretty": "^13.0.0",
     "zod": "^4.0.0"
   },
@@ -333,11 +333,12 @@
   },
   "dependencies": {
     "fastify-plugin": "^5.0.1",
-    "qs": "^6.14.1"
+    "qs": "^6.14.1",
+    "secure-json-parse": "^4.1.0"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.10",
-    "@classytic/mongokit": "^3.4.5",
+    "@classytic/mongokit": "^3.5.2",
     "@fastify/jwt": "^10.0.0",
     "@fastify/multipart": "^9.0.0",
     "@fastify/type-provider-typebox": "^6.0.0",

package/skills/arc/SKILL.md

@@ -8,11 +8,11 @@ description: |
   Triggers: arc, fastify resource, defineResource, createApp, BaseController, arc preset,
   arc auth, arc events, arc jobs, arc websocket, arc mcp, arc plugin, arc testing, arc cli,
   arc permissions, arc hooks, arc pipeline, arc factory, arc cache, arc QueryCache.
-version: 2.4.2
+version: 2.6.2
 license: MIT
 metadata:
   author: Classytic
-  version: "2.4.1"
+  version: "2.6.2"
 tags:
   - fastify
   - rest-api
@@ -196,6 +196,30 @@ presets: ['softDelete', { name: 'multiTenant', tenantField: 'organizationId' }]
 // Bulk: presets: ['bulk'] or bulkPreset({ operations: ['createMany', 'updateMany'] })
 ```
 
+### tenantField — When to Use and When to Disable
+
+Arc defaults `tenantField` to `'organizationId'` on BaseController. This silently adds `{ organizationId: scope.organizationId }` to every query when the user has an org context. Correct for per-org resources, wrong for company-wide resources.
+
+```typescript
+// Per-org resource (default) — each org sees only its own data
+defineResource({ name: 'invoice', ... });
+// → queries auto-scoped: { organizationId: 'org-123' }
+
+// Company-wide resource — ALL orgs share the same data
+defineResource({ name: 'account-type', tenantField: false, ... });
+// → no org filter applied, all users see all records
+
+// Custom tenant field — your schema uses a different name
+defineResource({ name: 'workspace-item', tenantField: 'workspaceId', ... });
+// → queries scoped by workspaceId instead of organizationId
+```
+
+When to use `tenantField: false`:
+- Lookup tables (account types, categories, currencies)
+- Platform-wide settings or config
+- Cross-org reports or analytics
+- Single-tenant apps where org scoping isn't needed
+
 ## QueryCache
 
 TanStack Query-inspired server cache with stale-while-revalidate and auto-invalidation on mutations.
@@ -314,6 +338,26 @@ const app = await createApp({
 
 ## Hooks
 
+**Inline on resource (recommended):**
+
+```typescript
+defineResource({
+  name: 'chat',
+  hooks: {
+    beforeCreate: async (ctx) => { ctx.data.slug = slugify(ctx.data.name); },
+    afterCreate: async (ctx) => { analytics.track('created', { id: ctx.data._id, user: ctx.user?.id }); },
+    beforeUpdate: async (ctx) => { console.log('Updating', ctx.meta?.id, 'existing:', ctx.meta?.existing); },
+    afterUpdate: async (ctx) => { await invalidateCache(ctx.data._id); },
+    beforeDelete: async (ctx) => { if (ctx.data.isProtected) throw new Error('Cannot delete'); },
+    afterDelete: async (ctx) => { await cleanupFiles(ctx.meta?.id); },
+  },
+});
+```
+
+`ResourceHookContext`: `{ data, user?, meta? }` — `data` is the document, `meta` has `id` and `existing` (for update/delete).
+
+**App-level (cross-resource):**
+
 ```typescript
 import { createHookSystem, beforeCreate, afterUpdate } from '@classytic/arc/hooks';
 
@@ -386,8 +430,10 @@ defineResource({
 ## Error Classes
 
 ```typescript
-import { ArcError, NotFoundError, ValidationError, UnauthorizedError, ForbiddenError } from '@classytic/arc';
-throw new NotFoundError('Product not found');  // 404
+import { ArcError, NotFoundError, ValidationError, createDomainError } from '@classytic/arc';
+throw new NotFoundError('Product not found');                      // 404
+throw createDomainError('MEMBER_NOT_FOUND', 'Not found', 404);    // domain error with code
+throw createDomainError('SELF_REFERRAL', 'Cannot self-refer', 422, { field: 'referralCode' });
 ```
 
 Error handler catches: `ArcError` → `.statusCode` (Fastify) → `.status` (MongoKit, http-errors) → `errorMap` → Mongoose/MongoDB → fallback 500. DB-agnostic — any error with `.status` or `.statusCode` gets the correct HTTP response.
@@ -481,6 +527,107 @@ src/resources/order/
 
 Generate: `arc generate resource order --mcp` | Wire: `extraTools: [fulfillOrderTool]`
 
+**Auto-load resources** — no barrel files, no manual `toPlugin()`:
+
+```typescript
+import { createApp, loadResources } from '@classytic/arc/factory';
+
+const app = await createApp({
+  resourcePrefix: '/api/v1',                            // optional URL prefix
+  resources: await loadResources(import.meta.url),      // discovers *.resource.ts
+  auth: { type: 'jwt', jwt: { secret: process.env.JWT_SECRET } },
+});
+```
+
+`loadResources()` discovers files matching `*.resource.{ts,js,mts,mjs}`, recursively. Pass `import.meta.url` for dev/prod parity (resolves to `src/` in dev, `dist/` in prod automatically). Discovers `default` export, `export const resource`, OR any named export with `toPlugin()` (e.g., `export const userResource`).
+
+Options: `exclude`, `include`, `suffix`, `recursive`, `silent`.
+
+**Per-resource opt-out of `resourcePrefix`** — for webhooks, admin routes:
+```typescript
+defineResource({ name: 'webhook', prefix: '/hooks', skipGlobalPrefix: true })
+// Registers at /hooks even with createApp({ resourcePrefix: '/api/v1' })
+```
+
+**Boot sequence:**
+```typescript
+const app = await createApp({
+  resourcePrefix: '/api/v1',
+  plugins: async (f) => { await connectDB(); },     // 1. infra (DB, docs)
+  bootstrap: [inventoryInit, accountingInit],        // 2. domain init (engines)
+  resources: await loadResources(import.meta.url),   // 3. routes
+  afterResources: async (f) => { subscribeEvents(f); }, // 4. post-wiring
+  onReady: async (f) => { logger.info('ready'); },   // 5. lifecycle
+});
+```
+
+**Audit per-resource opt-in** — no growing exclude lists:
+```typescript
+// Register audit plugin with perResource mode
+await fastify.register(auditPlugin, { autoAudit: { perResource: true } });
+
+// Opt-in at the resource level
+defineResource({ name: 'order', audit: true });
+defineResource({ name: 'payment', audit: { operations: ['delete'] } });
+defineResource({ name: 'product' }); // not audited
+
+// Manual custom() for MCP/additionalRoutes/read auditing
+app.post('/orders/:id/refund', async (req) => {
+  await app.audit.custom('order', req.params.id, 'refund', { reason }, { user });
+});
+```
+
+**Import compatibility:** `loadResources()` uses runtime `import()`. Works with relative imports (`./foo.js`) and Node.js `#` subpath imports (`#shared/utils.js` via `package.json` `imports`). Does **NOT** work with tsconfig path aliases (`@/*`, `~/`) — those are compile-time only.
+
+**Vitest workaround** (rare): if resources need engine bootstrap or transitive `node_modules` imports that don't compose with dynamic import:
+```typescript
+import { preloadResources } from '@classytic/arc/testing';
+
+export const preloadedResources = preloadResources(
+  import.meta.glob('../../src/resources/**/*.resource.ts', { eager: true, import: 'default' }),
+);
+```
+
+**Unified role check** — checks both platform AND org roles:
+
+```typescript
+import { roles } from '@classytic/arc/permissions';
+permissions: {
+  create: roles('admin', 'editor'),  // works with BA org roles + platform roles
+  delete: roles('admin'),
+}
+// Also: requireRoles(['admin'], { includeOrgRoles: true }) for backward compat
+```
+
+**DX helpers:**
+
+```typescript
+// Typed request for wrapHandler: false routes — no more (req as any).user
+import type { ArcRequest } from '@classytic/arc';
+handler: async (req: ArcRequest, reply) => { req.user?.id; req.scope; req.signal; }
+
+// Response envelope — no manual { success, data } wrapping
+import { envelope } from '@classytic/arc';
+reply.send(envelope(data, { total: 100 }));
+
+// Canonical org extraction — replaces 19 duplicated patterns
+import { getOrgContext } from '@classytic/arc/scope';
+const { userId, organizationId, roles, orgRoles } = getOrgContext(request);
+
+// Domain errors with auto HTTP status mapping
+import { createDomainError } from '@classytic/arc';
+throw createDomainError('SELF_REFERRAL', 'Cannot refer yourself', 422);
+
+// Resource lifecycle hook — wire singletons during registration
+defineResource({ name: 'notification', onRegister: (f) => setSseManager(f.sseManager) });
+
+// SSE auth — preAuth runs BEFORE auth middleware (EventSource can't set headers)
+additionalRoutes: [{ preAuth: [(req) => { req.headers.authorization = `Bearer ${req.query.token}`; }] }]
+
+// SSE streaming — auto headers + bypasses response wrapper
+additionalRoutes: [{ streamResponse: true, handler: async (req, reply) => reply.send(stream) }]
+```
+
 ## Subpath Imports
 
 ```typescript

package/skills/arc/references/mcp.md

@@ -12,11 +12,34 @@ npm install @modelcontextprotocol/sdk zod
 
 ```typescript
 import { mcpPlugin } from '@classytic/arc/mcp';
+import { createApp, loadResources } from '@classytic/arc/factory';
 
-await app.register(mcpPlugin, {
+// Option A: Explicit resources
+const app = await createApp({
   resources: [productResource, taskResource],
   auth: false,
-  exclude: ['credential'],
+  plugins: async (f) => {
+    await f.register(mcpPlugin, { resources: [productResource, taskResource], auth: false });
+  },
+});
+
+// Option B: Auto-discover from directory
+const resources = await loadResources('./src/resources');
+const app = await createApp({
+  resources,
+  plugins: async (f) => {
+    await f.register(mcpPlugin, { resources, auth: false });
+  },
+});
+```
+
+Per-resource overrides:
+
+```typescript
+await app.register(mcpPlugin, {
+  resources,
+  auth: false,
+  include: ['product', 'order'],          // only these get MCP tools
   overrides: { product: { operations: ['list', 'get'] } },
 });
 ```
@@ -429,3 +452,138 @@ await app.register(mcpPlugin, {
 - `DELETE /mcp` — terminates session
 
 Sessions: lazily created, TTL-cached, LRU-evicted at max capacity, auto-cleaned on shutdown.
+
+## Health Endpoint
+
+`GET /mcp/health` — no MCP protocol needed, plain JSON:
+
+```json
+{
+  "status": "ok",
+  "mode": "stateless",
+  "tools": 11,
+  "resources": 2,
+  "toolNames": ["list_products", "get_product", ...],
+  "sessions": null
+}
+```
+
+Use to verify the MCP server is alive before configuring Claude CLI.
+
+## DX Helpers (v2.4.4)
+
+### ArcRequest — Typed Fastify Request
+
+For `wrapHandler: false` routes, use `ArcRequest` instead of `(req as any).user`:
+
+```typescript
+import type { ArcRequest } from '@classytic/arc';
+
+handler: async (req: ArcRequest, reply) => {
+  req.user?.id;                    // typed
+  req.scope.organizationId;        // typed (when member)
+  req.signal;                      // AbortSignal (Fastify 5 built-in)
+}
+```
+
+### envelope() — Response Helper
+
+```typescript
+import { envelope } from '@classytic/arc';
+
+handler: async (req, reply) => {
+  const data = await service.getResults();
+  return reply.send(envelope(data));
+  // → { success: true, data }
+  return reply.send(envelope(data, { total: 100, page: 1 }));
+  // → { success: true, data, total: 100, page: 1 }
+}
+```
+
+### getOrgContext() — Canonical Org Extraction
+
+Eliminates duplicated `req.user.organizationId || req.headers['x-organization-id']` patterns:
+
+```typescript
+import { getOrgContext } from '@classytic/arc/scope';
+
+handler: async (req, reply) => {
+  const { userId, organizationId, roles, orgRoles } = getOrgContext(req);
+  // Works regardless of auth type (JWT, Better Auth, custom)
+}
+```
+
+### createDomainError() — Error Factory
+
+Eliminates manual `if (err.code) return status` mapping:
+
+```typescript
+import { createDomainError } from '@classytic/arc';
+
+throw createDomainError('MEMBER_NOT_FOUND', 'Member does not exist', 404);
+throw createDomainError('SELF_REFERRAL', 'Cannot refer yourself', 422);
+throw createDomainError('INSUFFICIENT_BALANCE', 'Not enough credits', 402, { balance: 0 });
+// Arc's error handler auto-maps statusCode to HTTP response
+```
+
+### onRegister — Resource Lifecycle Hook
+
+Called during plugin registration with the scoped Fastify instance:
+
+```typescript
+defineResource({
+  name: 'notification',
+  onRegister: (fastify) => {
+    setSseManager(fastify.sseManager);
+  },
+})
+```
+
+### preAuth — Pre-Auth Handlers for SSE/WebSocket
+
+Run before auth middleware. Use for promoting `?token=` to `Authorization` header (EventSource can't set headers):
+
+```typescript
+additionalRoutes: [{
+  method: 'GET',
+  path: '/stream',
+  wrapHandler: false,
+  permissions: requireAuth(),
+  preAuth: [(req) => {
+    const token = req.query?.token;
+    if (token) req.headers.authorization = `Bearer ${token}`;
+  }],
+  handler: sseHandler,
+}]
+```
+
+### streamResponse — SSE Route Flag
+
+Auto-sets SSE headers and bypasses Arc's response wrapper:
+
+```typescript
+additionalRoutes: [{
+  method: 'POST',
+  path: '/stream',
+  streamResponse: true,        // SSE headers + no { success, data } wrapper
+  permissions: requireAuth(),
+  handler: async (request, reply) => {
+    const { stream } = await generateStream({ abortSignal: request.signal });
+    return reply.send(stream);
+  },
+}]
+```
+
+## Test Coverage
+
+165 test files, 2439 tests. MCP-specific:
+
+| Test File | Tests | Covers |
+|-----------|-------|--------|
+| `mcp-auth-e2e.test.ts` | 16 | All auth modes, multi-tenancy, permission filters, async permissions |
+| `mcp-dx-features.test.ts` | 14 | include, names, prefix, disableDefaultRoutes, mcpHandler, guards, CRUD lifecycle |
+| `resourceToTools.test.ts` | 12 | Tool generation, annotations, field hiding, soft delete |
+| `createMcpServer.test.ts` | 10 | Server creation, tool registration, InMemoryTransport |
+| `guards.test.ts` | 8 | requireAuth, requireOrg, requireRole, customGuard, composition |
+| `dx-features.test.ts` | 17 | envelope, getOrgContext, createDomainError, onRegister, preAuth, streamResponse |
+| Others | 32 | fieldRulesToZod, defineTool, definePrompt, buildRequestContext, sessionCache, authCache |