@nextsparkjs/core 0.1.0-beta.184 → 0.1.0-beta.185

package/scripts/build/registry/generators/scope-registry.mjs

@@ -3,112 +3,82 @@
  *
  * Generates scope-registry.ts
  *
+ * IMPORTANT: unlike most registry generators, the role→scope computation does
+ * NOT happen here at generation time. It happens at IMPORT TIME inside the
+ * emitted TypeScript, by statically importing the sibling generated
+ * `entity-registry.ts` (for which entities are API-exposed, via
+ * `access.api`) and `permissions-registry.ts` (for which team roles can
+ * perform which action on each entity, via `PERMISSIONS_BY_ROLE`).
+ *
+ * Why: this generator previously computed scopes from the raw `entities`
+ * discovery array (filesystem-scan metadata only — `{name, exportName,
+ * configPath, ...}`), which never carried `.api`/`.features`/`.fields`
+ * properties. Those properties don't exist on that shape, nor on the real
+ * `EntityConfig` type, so the computation silently produced `base: []` and a
+ * hardcoded, wrong `roles` object every time. Reading the REAL entity config
+ * (`access.api`, `slug`, `fields`) and the REAL per-role permission matrix
+ * requires resolving imports, which can only happen once the generated files
+ * are imported by app code — not synchronously inside this generation
+ * script. Doing the computation at import time also guarantees scope
+ * minting and scope enforcement can never diverge again: both read the same
+ * `PERMISSIONS_BY_ROLE` source of truth `checkPermission()` uses at request
+ * time.
+ *
  * @module core/scripts/build/registry/generators/scope-registry
  */
 
+// Flag-based scopes and restriction rules are orthogonal to team roles/entity
+// permissions (they're driven by user flags like `beta_tester`/`vip`, not by
+// what a role can do to which entity) — kept as static literals, unrelated to
+// the role/entity computation this generator used to get wrong.
+const FLAG_SCOPES = {
+  'beta_tester': ['beta:features'],
+  'vip': ['vip:features', 'advanced:export'],
+  'early_adopter': ['early:features'],
+  'power_user': ['advanced:features', 'bulk:operations']
+}
+
+const SCOPE_RESTRICTIONS = {
+  'restricted': {
+    remove: ['delete', 'admin']
+  },
+  'limited_access': {
+    allow_only: ['read', 'tasks:write']
+  }
+}
+
 /**
  * Generate the scope registry file
  *
- * @param {Array} entities - Discovered entities
+ * @param {Array} entities - Discovered entities (unused for scope computation
+ *   today — kept in the signature for call-site consistency with the other
+ *   generators; the real per-entity data used below comes from the generated
+ *   `entity-registry.ts` this file imports, not from this parameter)
  * @param {object} config - Configuration object from getConfig()
  * @returns {string} Generated TypeScript content
  */
 export function generateScopeRegistry(entities, config) {
-  // Generate base scopes from entities
-  const baseScopes = []
-  const entityPaths = []
-
-  for (const entity of entities) {
-    if (entity.api && entity.features?.enabled) {
-      const entityName = entity.name
-      baseScopes.push(`${entityName}:read`)
-
-      // Add write scope if entity supports creation
-      if (entity.api.endpoints && entity.api.endpoints.create) {
-        baseScopes.push(`${entityName}:write`)
-      }
-
-      // Add delete scope for entities that support deletion
-      if (entity.api.endpoints && entity.api.endpoints.delete) {
-        baseScopes.push(`${entityName}:delete`)
-      }
-
-      // Collect entity paths for routing
-      if (entity.api.apiPath) {
-        entityPaths.push(entity.api.apiPath)
-      }
-    }
-  }
-
-  // Define role-based scopes
-  const roleScopes = {
-    'superadmin': ['admin:users', 'tasks:delete', 'products:write', 'products:delete', ...baseScopes.filter(s => s.includes(':delete'))],
-    'admin': ['admin:users', 'tasks:delete', 'products:write', 'products:delete', ...baseScopes.filter(s => s.includes(':delete'))],
-    'manager': baseScopes.filter(s => s.includes(':write') || s.includes(':read')),
-    'member': baseScopes.filter(s => s.includes(':read') || s === 'tasks:write')
-  }
-
-  // Define flag-based scopes
-  const flagScopes = {
-    'beta_tester': ['beta:features'],
-    'vip': ['vip:features', 'advanced:export'],
-    'early_adopter': ['early:features'],
-    'power_user': ['advanced:features', 'bulk:operations']
-  }
-
-  // Define allowed filters based on entities
-  const allowedFilters = ['status', 'role', 'completed', 'userId']
-
-  // Add entity-specific filters
-  for (const entity of entities) {
-    if (entity.api && entity.features?.enabled) {
-      allowedFilters.push(`${entity.name}Id`)
-
-      // Add common entity filters
-      if (entity.fields) {
-        const fields = Object.keys(entity.fields)
-        if (fields.includes('status')) allowedFilters.push(`${entity.name}Status`)
-        if (fields.includes('type')) allowedFilters.push(`${entity.name}Type`)
-        if (fields.includes('category')) allowedFilters.push(`${entity.name}Category`)
-      }
-    }
-  }
-
-  const scopeConfig = {
-    base: [...new Set(baseScopes)],
-    roles: roleScopes,
-    flags: flagScopes,
-    restrictions: {
-      'restricted': {
-        remove: ['delete', 'admin']
-      },
-      'limited_access': {
-        allow_only: ['read', 'tasks:write']
-      }
-    }
-  }
-
-  const apiConfig = {
-    filters: {
-      allowed: [...new Set(allowedFilters)]
-    },
-    entityPaths: [...new Set(entityPaths)]
-  }
-
   return `/**
  * Auto-generated API Scope Registry
  *
  * Generated at: ${new Date().toISOString()}
- * Base scopes: ${scopeConfig.base.length}
- * Role configurations: ${Object.keys(scopeConfig.roles).length}
- * Flag configurations: ${Object.keys(scopeConfig.flags).length}
- * Allowed filters: ${apiConfig.filters.allowed.length}
+ *
+ * Role→scope mapping is computed below at import time from
+ * \`entity-registry.ts\` (which entities are API-exposed) and
+ * \`permissions-registry.ts\` (which team roles can do what to each entity),
+ * so scope MINTING (this file) and scope ENFORCEMENT
+ * (\`checkPermission\`/\`hasRequiredScope\`) can never drift apart.
  *
  * This file replaces hardcoded scope configurations in helpers.ts
  *
  * DO NOT EDIT - This file is auto-generated by scripts/build-registry.mjs
  */
 
+import { ENTITY_REGISTRY } from './entity-registry'
+import { AVAILABLE_ROLES, PERMISSIONS_BY_ROLE } from './permissions-registry'
+import type { Permission } from '@/core/lib/permissions/types'
+import type { EntityConfig } from '@/core/lib/entities/types'
+
 export interface ScopeConfig {
   base: string[]
   roles: Record<string, string[]>
@@ -123,9 +93,84 @@ export interface ApiConfig {
   entityPaths: string[]
 }
 
-export const SCOPE_CONFIG: ScopeConfig = ${JSON.stringify(scopeConfig, null, 2)}
+interface ScopeApiEntity {
+  slug: string
+  apiPath: string
+  fieldNames: string[]
+}
 
-export const API_CONFIG: ApiConfig = ${JSON.stringify(apiConfig, null, 2)}
+// Entities exposed via the external API (access.api === true). ENTITY_REGISTRY
+// entries can be a full EntityConfig or a ChildEntityDefinition (which has no
+// \`access\`/\`slug\` at all) — guard defensively rather than assume every
+// registry entry is a root entity.
+const SCOPE_API_ENTITIES: ScopeApiEntity[] = Object.values(ENTITY_REGISTRY)
+  .map((entry) => {
+    const cfg = entry.config as Partial<EntityConfig>
+    if (!cfg?.access?.api || !cfg.slug) return null
+    return {
+      slug: cfg.slug,
+      apiPath: cfg.access.basePath || \`/api/v1/\${cfg.slug}\`,
+      fieldNames: Array.isArray(cfg.fields) ? cfg.fields.map((field) => field.name) : []
+    }
+  })
+  .filter((entity): entity is ScopeApiEntity => entity !== null)
+
+// For each API-exposed entity, grant \`<slug>:read/write/delete\` to any team
+// role whose PERMISSIONS_BY_ROLE set includes the corresponding
+// \`<slug>.<action>\` permission — the SAME set checkAuthPermission() consults
+// at request time. Superadmin is a GLOBAL role (never in AVAILABLE_ROLES) and
+// is intentionally NOT represented here; it's handled as an explicit bypass
+// in validateScopesForUser().
+function computeRoleScopes(): Record<string, string[]> {
+  const roleScopes: Record<string, string[]> = {}
+  for (const role of AVAILABLE_ROLES) {
+    const perms = PERMISSIONS_BY_ROLE[role]
+    const scopes: string[] = []
+    for (const { slug } of SCOPE_API_ENTITIES) {
+      if (perms?.has(\`\${slug}.list\` as Permission) || perms?.has(\`\${slug}.read\` as Permission)) {
+        scopes.push(\`\${slug}:read\`)
+      }
+      if (perms?.has(\`\${slug}.create\` as Permission) || perms?.has(\`\${slug}.update\` as Permission)) {
+        scopes.push(\`\${slug}:write\`)
+      }
+      if (perms?.has(\`\${slug}.delete\` as Permission)) {
+        scopes.push(\`\${slug}:delete\`)
+      }
+    }
+    roleScopes[role] = [...new Set(scopes)]
+  }
+  return roleScopes
+}
+
+function computeAllowedFilters(): string[] {
+  const allowedFilters = new Set<string>(['status', 'role', 'completed', 'userId'])
+  for (const { slug, fieldNames } of SCOPE_API_ENTITIES) {
+    allowedFilters.add(\`\${slug}Id\`)
+    if (fieldNames.includes('status')) allowedFilters.add(\`\${slug}Status\`)
+    if (fieldNames.includes('type')) allowedFilters.add(\`\${slug}Type\`)
+    if (fieldNames.includes('category')) allowedFilters.add(\`\${slug}Category\`)
+  }
+  return [...allowedFilters]
+}
+
+export const SCOPE_CONFIG: ScopeConfig = {
+  // Nothing is granted irrespective of role — every entity scope flows
+  // through computeRoleScopes() above, sourced from the real permission
+  // matrix. Kept as an empty array (rather than removed) so a future,
+  // deliberate "these scopes belong to every authenticated key" need has a
+  // place to live without re-deriving this decision.
+  base: [],
+  roles: computeRoleScopes(),
+  flags: ${JSON.stringify(FLAG_SCOPES, null, 2).split('\n').join('\n  ')},
+  restrictions: ${JSON.stringify(SCOPE_RESTRICTIONS, null, 2).split('\n').join('\n  ')}
+}
+
+export const API_CONFIG: ApiConfig = {
+  filters: {
+    allowed: computeAllowedFilters()
+  },
+  entityPaths: SCOPE_API_ENTITIES.map((entity) => entity.apiPath)
+}
 
 // ==================== Service Layer ====================
 // Query functions have been moved to: @nextsparkjs/core/lib/services/scope.service

package/scripts/build/registry.mjs

@@ -55,6 +55,7 @@ import { discoverEmails } from './registry/discovery/emails.mjs'
 import { discoverBlocks } from './registry/discovery/blocks.mjs'
 import { discoverCoreRoutes } from './registry/discovery/core-routes.mjs'
 import { discoverApiPresets } from './registry/discovery/api-presets.mjs'
+import { discoverMcpOverrides } from './registry/discovery/mcp-overrides.mjs'
 import { validateEntityConfigurations } from './registry/validation/entity-validator.mjs'
 import { generatePluginRegistry, generatePluginRegistryClient } from './registry/generators/plugin-registry.mjs'
 import { generateEntityRegistry, generateEntityRegistryClient } from './registry/generators/entity-registry.mjs'
@@ -76,6 +77,7 @@ import { generatePermissionsRegistry } from './registry/generators/permissions-r
 import { generateScheduledActionsRegistry } from './registry/generators/scheduled-actions-registry.mjs'
 import { generateDocsRegistry } from './registry/generators/docs-registry.mjs'
 import { generateApiPresetsRegistry, generateApiDocsRegistry } from './registry/generators/api-presets-registry.mjs'
+import { generateMcpRegistry } from './registry/generators/mcp-registry.mjs'
 import {
   generateMissingPages,
   displayTreeStructure,
@@ -89,7 +91,7 @@ import { syncAppGlobalsCss } from './theme.mjs'
 
 // ==================== Registry File Generation ====================
 
-async function generateRegistryFiles(CONFIG, plugins, entities, themes, templates, middlewares, blocks, permissionsConfig, coreRoutes, apiPresetsData, emails) {
+async function generateRegistryFiles(CONFIG, plugins, entities, themes, templates, middlewares, blocks, permissionsConfig, coreRoutes, apiPresetsData, emails, mcpOverridesData) {
   log('Generating registry files...', 'build')
 
   try {
@@ -122,6 +124,7 @@ async function generateRegistryFiles(CONFIG, plugins, entities, themes, template
       { name: 'docs-registry.ts', content: generateDocsRegistry() },
       { name: 'api-presets-registry.ts', content: generateApiPresetsRegistry(apiPresetsData, CONFIG) },
       { name: 'api-docs-registry.ts', content: generateApiDocsRegistry(apiPresetsData, CONFIG) },
+      { name: 'mcp-registry.ts', content: generateMcpRegistry(mcpOverridesData, CONFIG) },
       { name: 'index.ts', content: generateUnifiedRegistry(plugins, entities, themes, templates, middlewares, CONFIG) }
     ]
 
@@ -191,7 +194,7 @@ export async function buildRegistries(projectRoot = null) {
     await discoverParentChildRelations(CONFIG)
 
     // Discover all content types in parallel (pass CONFIG to each)
-    const [plugins, coreEntities, themes, templates, middlewares, blocks, permissionsConfig, coreRoutes, apiPresetsData, emails] = await Promise.all([
+    const [plugins, coreEntities, themes, templates, middlewares, blocks, permissionsConfig, coreRoutes, apiPresetsData, emails, mcpOverridesData] = await Promise.all([
       discoverPlugins(CONFIG),
       discoverCoreEntities(CONFIG),
       discoverThemes(CONFIG),
@@ -201,7 +204,8 @@ export async function buildRegistries(projectRoot = null) {
       discoverPermissionsConfig(CONFIG),
       discoverCoreRoutes(CONFIG),
       discoverApiPresets(CONFIG),
-      discoverEmails(CONFIG)
+      discoverEmails(CONFIG),
+      discoverMcpOverrides(CONFIG)
     ])
 
     // Aggregate all entities with proper priority: plugin < core < theme
@@ -260,7 +264,7 @@ export async function buildRegistries(projectRoot = null) {
 
     // Hoist plugin dependencies to root workspace for proper resolution
     // Generate all registry files (use aggregated entities for entity registry + blocks)
-    await generateRegistryFiles(CONFIG, plugins, allEntities, themes, templates, middlewares, blocks, permissionsConfig, coreRoutes, apiPresetsData, emails)
+    await generateRegistryFiles(CONFIG, plugins, allEntities, themes, templates, middlewares, blocks, permissionsConfig, coreRoutes, apiPresetsData, emails, mcpOverridesData)
 
     // Generate missing pages for templates that don't have core app pages
     await generateMissingPages(templates, CONFIG)

package/templates/app/api/mcp/route.ts

@@ -0,0 +1,173 @@
+/**
+ * MCP endpoint — POST /api/mcp (Streamable HTTP, stateless JSON mode).
+ *
+ * Auth: API key ONLY (Authorization: Bearer sk_... or x-api-key). Session
+ * cookies are rejected — this endpoint is for MCP clients, not browsers.
+ * authenticateRequest runs ONCE here; the resolved identity, team context and
+ * api_key id travel to every tool via ToolExecutionContext.
+ *
+ * Tools and overrides are entirely registry-driven: every access.api-enabled
+ * entity in ENTITY_REGISTRY becomes a set of tools automatically, and any
+ * `entities/<slug>/mcp.ts` a theme defines is picked up via the generated
+ * MCP_OVERRIDES registry — no per-app hand-wiring required.
+ *
+ * Security posture:
+ * - kill-switch: MCP_ENABLED (dev: on unless 'false'; production: OFF unless 'true')
+ * - Origin validated when present (DNS-rebinding protection); no CORS reflection
+ * - rate limit: tier 'api' — with the in-process executor this is the ONLY
+ *   rate limit on the whole MCP surface (deploy prerequisite: Redis)
+ * - team-role permissions + scopes + ownership/field guards come from the
+ *   real generic entity handlers the executor calls in-process (#94/#95)
+ * - every tool call is audited to api_audit_log
+ */
+
+import { NextRequest, NextResponse } from 'next/server'
+import {
+  authenticateRequest,
+  resolveTeamContext,
+} from '@nextsparkjs/core/lib/api/auth/dual-auth'
+import { validateApiKey } from '@nextsparkjs/core/lib/api/auth'
+import { withRateLimitTier } from '@nextsparkjs/core/lib/api/rate-limit'
+import { setEntityRegistry } from '@nextsparkjs/core/lib/entities/queries'
+import { createMcpEngine } from '@nextsparkjs/core/lib/mcp'
+import type { ToolExecutionContext } from '@nextsparkjs/core/lib/mcp'
+import type { EntityConfig } from '@nextsparkjs/core/lib/entities/types'
+// Import registries directly - webpack resolves @nextsparkjs/registries alias at compile time
+import { ENTITY_REGISTRY, ENTITY_METADATA } from '@nextsparkjs/registries/entity-registry'
+import { MCP_OVERRIDES } from '@nextsparkjs/registries/mcp-registry'
+import { API_PRESETS_REGISTRY } from '@nextsparkjs/registries/api-presets-registry'
+
+// Initialize registry at module load time (before any handler runs)
+setEntityRegistry(ENTITY_REGISTRY, ENTITY_METADATA)
+
+// Registry entries are wrappers ({ name, config, tableName, ... }) — the
+// engine consumes the EntityConfig map.
+const entityConfigs = Object.fromEntries(
+  Object.entries(ENTITY_REGISTRY as Record<string, { config: EntityConfig }>).map(
+    ([slug, entry]) => [slug, entry.config]
+  )
+)
+
+// Tool descriptions are seeded from api/presets.ts (summary → entity
+// description, presets → few-shot examples) — the same registry the API
+// Explorer already uses, keyed by endpoint instead of slug here.
+const presetsBySlug = Object.fromEntries(
+  Object.entries(API_PRESETS_REGISTRY.endpoints ?? {}).map(([endpoint, data]) => [
+    endpoint.replace(/^\/api\/v1\//, ''),
+    { summary: data.summary, presets: data.presets },
+  ])
+)
+
+const toolPrefix = (process.env.MCP_TOOL_PREFIX || process.env.NEXT_PUBLIC_ACTIVE_THEME || 'app')
+  .toLowerCase()
+  .replace(/[^a-z0-9]+/g, '_')
+  .replace(/^_+|_+$/g, '')
+
+const engine = createMcpEngine(entityConfigs, {
+  toolPrefix,
+  overrides: MCP_OVERRIDES,
+  presets: presetsBySlug,
+})
+
+const API_KEY_HELP =
+  'This endpoint requires an API key: generate one in Settings → API Keys and configure it in your MCP client as the header "Authorization: Bearer sk_...".'
+
+function isMcpEnabled(): boolean {
+  const flag = process.env.MCP_ENABLED
+  if (process.env.NODE_ENV === 'production') return flag === 'true'
+  return flag !== 'false'
+}
+
+function isOriginAllowed(request: NextRequest): boolean {
+  const origin = request.headers.get('origin')
+  if (!origin) return true // non-browser MCP clients don't send Origin
+  const allowed = new Set(
+    [request.nextUrl.origin, process.env.NEXT_PUBLIC_APP_URL, process.env.BETTER_AUTH_URL].filter(
+      Boolean
+    )
+  )
+  return allowed.has(origin)
+}
+
+function jsonRpcError(
+  status: number,
+  code: number,
+  message: string,
+  id: string | number | null = null
+): NextResponse {
+  return NextResponse.json({ jsonrpc: '2.0', error: { code, message }, id }, { status })
+}
+
+async function handleMcpPost(request: NextRequest): Promise<NextResponse> {
+  if (!isMcpEnabled()) {
+    return NextResponse.json({ error: 'Not found' }, { status: 404 })
+  }
+  if (!isOriginAllowed(request)) {
+    return jsonRpcError(403, -32000, 'Origin not allowed')
+  }
+
+  const authResult = await authenticateRequest(request)
+  if (!authResult.success || authResult.type !== 'api-key' || !authResult.user) {
+    return jsonRpcError(401, -32001, API_KEY_HELP)
+  }
+
+  // Same cached lookup the auth already did — needed for the audit trail.
+  const apiKeyAuth = await validateApiKey(request)
+
+  const teamResult = await resolveTeamContext(request, authResult)
+  if (teamResult instanceof Response) {
+    const status = teamResult.status
+    return jsonRpcError(
+      status,
+      -32002,
+      status === 403
+        ? 'The API key user is not a member of the team specified in x-team-id.'
+        : 'Could not resolve the user team. Send the x-team-id header or assign a default team.'
+    )
+  }
+
+  let body: unknown
+  try {
+    body = await request.json()
+  } catch {
+    return jsonRpcError(400, -32700, 'Parse error: body must be JSON-RPC')
+  }
+
+  const ctx: ToolExecutionContext = {
+    userId: authResult.user.id,
+    userRole: authResult.user.role,
+    teamId: teamResult,
+    authHeader:
+      request.headers.get('authorization') ?? `Bearer ${request.headers.get('x-api-key') ?? ''}`,
+    apiKeyId: apiKeyAuth?.keyId ?? null,
+    scopes: authResult.scopes ?? [],
+  }
+
+  try {
+    const result = await engine.handleJsonRpc(body, ctx)
+    if (result === null) {
+      // Notification(s) only — accepted, nothing to return.
+      return new NextResponse(null, { status: 202 })
+    }
+    return NextResponse.json(result, { status: 200 })
+  } catch (error) {
+    console.error('[mcp] request failed:', error)
+    return jsonRpcError(500, -32603, 'Internal error processing MCP request')
+  }
+}
+
+export const POST = withRateLimitTier(handleMcpPost, 'api')
+
+export async function GET(): Promise<NextResponse> {
+  return NextResponse.json(
+    { error: 'Method not allowed. MCP requests must be POST (stateless JSON mode, no SSE).' },
+    { status: 405, headers: { Allow: 'POST' } }
+  )
+}
+
+export async function DELETE(): Promise<NextResponse> {
+  return NextResponse.json(
+    { error: 'Method not allowed. This server is stateless: there is no session to delete.' },
+    { status: 405, headers: { Allow: 'POST' } }
+  )
+}

package/templates/app/api/v1/api-keys/route.ts

@@ -7,7 +7,7 @@ import {
   handleCorsPreflightRequest,
   addCorsHeaders
 } from '@nextsparkjs/core/lib/api/helpers';
-import { authenticateRequest, hasRequiredScope } from '@nextsparkjs/core/lib/api/auth/dual-auth';
+import { authenticateRequest, hasRequiredScope, resolveTeamContext } from '@nextsparkjs/core/lib/api/auth/dual-auth';
 import { ApiKeyManager, API_SCOPES, API_KEY_LIMITS } from '@nextsparkjs/core/lib/api/keys';
 import { validateScopesForUser } from '@nextsparkjs/core/lib/api/auth';
 import { withRateLimitTier } from '@nextsparkjs/core/lib/api/rate-limit';
@@ -177,8 +177,20 @@ export const POST = withRateLimitTier(withApiLogging(async (req: NextRequest): P
       return addCorsHeaders(response);
     }
 
-    // Validar que el usuario pueda crear API keys con estos scopes
-    const userScopeValidation = await validateScopesForUser(authResult.user!.id, validatedData.scopes);
+    // Validar que el usuario pueda crear API keys con estos scopes.
+    // Scope minting is TEAM-role based (see validateScopesForUser) — resolve
+    // the team this key is being minted for, unless the caller is a global
+    // superadmin, which validateScopesForUser bypasses regardless of team.
+    let teamId: string | null = null;
+    if (authResult.user!.role !== 'superadmin') {
+      const teamResult = await resolveTeamContext(req, authResult);
+      if (teamResult instanceof NextResponse) {
+        return teamResult;
+      }
+      teamId = teamResult;
+    }
+
+    const userScopeValidation = await validateScopesForUser(authResult.user!.id, teamId, validatedData.scopes);
     if (!userScopeValidation.valid) {
       const response = createApiError(
         'You do not have permission to create API keys with these scopes', 

package/templates/app/layout.tsx

@@ -5,6 +5,7 @@
  */
 
 import type { Metadata } from "next"
+import { Suspense } from "react"
 import { Geist, Geist_Mono } from "next/font/google"
 import { NextIntlClientProvider } from 'next-intl'
 import { getMessages } from 'next-intl/server'
@@ -13,6 +14,7 @@ import "./globals.css"
 import { getBillingResourceHints } from "@nextsparkjs/core/lib/billing/gateways/factory"
 import { ThemeProvider as NextThemeProvider } from "@nextsparkjs/core/providers/theme-provider"
 import { ThemeProvider as CustomThemeProvider } from "@nextsparkjs/core/lib/theme/ThemeProvider"
+import { Toaster } from "@nextsparkjs/core/components/ui/sonner"
 import { getUserLocale } from '@nextsparkjs/core/lib/locale'
 import { TranslationContextManager } from "@nextsparkjs/core/providers/TranslationContextManager"
 import { PluginService } from '@nextsparkjs/core/lib/services'
@@ -85,6 +87,7 @@ export default async function RootLayout({
             <CustomThemeProvider>
               <TranslationContextManager />
               <main>{children}</main>
+              <Suspense><Toaster position="bottom-left" /></Suspense>
             </CustomThemeProvider>
           </NextThemeProvider>
         </NextIntlClientProvider>

package/tests/jest/__mocks__/@nextsparkjs/registries/scope-registry.ts

@@ -1,15 +1,65 @@
 /**
  * Mock Scope Registry for Jest tests
+ *
+ * Shape MUST match the real generated `scope-registry.ts`
+ * (`ScopeConfig`/`ApiConfig`, see
+ * packages/core/scripts/build/registry/generators/scope-registry.mjs) — the
+ * previous version of this mock only exported an empty `SCOPE_REGISTRY` with
+ * unrelated `{name, description}`/`{basePath, version}` interfaces, which
+ * meant `scope.service.test.ts` failed on every assertion the moment it was
+ * force-run and had to be excluded from the suite.
+ *
+ * The role names below (superadmin/admin/manager/member) are an arbitrary
+ * fixture for exercising ScopeService's lookup/immutability/edge-case
+ * behavior — they are NOT meant to represent real `AVAILABLE_ROLES` (which
+ * are `owner/admin/member/viewer` + theme customs). ScopeService itself is
+ * agnostic to what role names exist; it's a pure Record lookup.
  */
 
-export const SCOPE_REGISTRY: Record<string, any> = {}
-
 export interface ScopeConfig {
-  name: string
-  description: string
+  base: string[]
+  roles: Record<string, string[]>
+  flags: Record<string, string[]>
+  restrictions: Record<string, { remove?: string[]; allow_only?: string[] }>
 }
 
 export interface ApiConfig {
-  basePath: string
-  version: string
+  filters: {
+    allowed: string[]
+  }
+  entityPaths: string[]
+}
+
+export const SCOPE_CONFIG: ScopeConfig = {
+  base: ['tasks:read'],
+  roles: {
+    superadmin: ['admin:users', 'admin:api-keys', 'tasks:delete'],
+    admin: ['admin:users', 'tasks:read', 'tasks:write', 'tasks:delete'],
+    manager: ['tasks:read', 'tasks:write'],
+    member: ['tasks:read'],
+  },
+  flags: {
+    beta_tester: ['beta:features'],
+    vip: ['vip:features', 'advanced:export'],
+    early_adopter: ['early:features'],
+    power_user: ['advanced:features', 'bulk:operations'],
+  },
+  restrictions: {
+    restricted: {
+      remove: ['delete', 'admin'],
+    },
+    limited_access: {
+      allow_only: ['read', 'tasks:write'],
+    },
+  },
 }
+
+export const API_CONFIG: ApiConfig = {
+  filters: {
+    allowed: ['status', 'role', 'completed', 'userId'],
+  },
+  entityPaths: ['/api/v1/tasks'],
+}
+
+// Kept for any legacy import still expecting SCOPE_REGISTRY to exist.
+export const SCOPE_REGISTRY: Record<string, unknown> = {}