@classytic/arc 2.4.2 → 2.6.1

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.0
 license: MIT
 metadata:
   author: Classytic
-  version: "2.4.1"
+  version: "2.6.0"
 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';
 
@@ -360,7 +404,7 @@ GET /products?lookup[cat][from]=categories&...&lookup[cat][select]=name,slug
 
 Operators: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`, `like`, `regex`, `exists`
 
-**Custom query parser (e.g., MongoKit for $lookup support):**
+**Custom query parser (e.g., MongoKit >=3.4.5 for $lookup, whitelists, MCP auto-derive):**
 
 ```typescript
 import { QueryParser } from '@classytic/mongokit';
@@ -368,11 +412,16 @@ import { QueryParser } from '@classytic/mongokit';
 defineResource({
   name: 'product',
   adapter: createMongooseAdapter({ model: ProductModel, repository: productRepo }),
-  queryParser: new QueryParser(),  // enables lookup, advanced populate, keyset pagination
+  queryParser: new QueryParser({
+    allowedFilterFields: ['status', 'category', 'orgId'],  // whitelist filter fields
+    allowedSortFields: ['createdAt', 'price'],              // whitelist sort fields
+    allowedOperators: ['eq', 'gte', 'lte', 'in'],          // whitelist operators
+  }),
+  // MCP auto-derives filterableFields from queryParser — no duplication needed
   schemaOptions: {
     query: {
-      allowedPopulate: ['category', 'brand'],     // whitelist populate paths
-      allowedLookups: ['categories', 'brands'],   // whitelist lookup collections
+      allowedPopulate: ['category', 'brand'],
+      allowedLookups: ['categories', 'brands'],
     },
   },
 });
@@ -381,10 +430,14 @@ 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.
+
 ## Compensating Transaction
 
 In-process rollback for multi-step operations. Not a distributed saga — use Temporal/Streamline for that.
@@ -474,6 +527,60 @@ src/resources/order/
 
 Generate: `arc generate resource order --mcp` | Wire: `extraTools: [fulfillOrderTool]`
 
+**Auto-load resources** (v2.6.0) — no barrel files, no manual `toPlugin()`:
+
+```typescript
+import { createApp, loadResources } from '@classytic/arc/factory';
+
+const app = await createApp({
+  resources: await loadResources('./src/resources'),  // discovers *.resource.ts
+  auth: { type: 'jwt', jwt: { secret: process.env.JWT_SECRET } },
+});
+// loadResources options: exclude, include, suffix, recursive
+```
+
+**Import compatibility:** `loadResources()` uses runtime `import()`. Works with relative imports (`./foo.js`) and Node.js `#` subpath imports (`#shared/utils.js` via `package.json` `imports` — both `.js` and `.ts` extensions). Does **NOT** work with tsconfig path aliases (`@/*`, `~/`) — those are compile-time only, Node.js ignores them. Projects using tsconfig aliases should use explicit `resources: [r1, r2]` instead.
+
+**Unified role check** (v2.6.0) — 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** (v2.4.4):
+
+```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 |