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

package/scripts/build/registry/__tests__/scope-registry.test.mjs

@@ -0,0 +1,106 @@
+/**
+ * Tests for the scope-registry generator.
+ *
+ * The role→scope computation no longer happens at generation time (see the
+ * rationale comment at the top of `generators/scope-registry.mjs`) — it's
+ * emitted as TypeScript that computes `SCOPE_CONFIG.roles` at IMPORT time,
+ * from the sibling generated `entity-registry.ts`/`permissions-registry.ts`.
+ * So this generator-level test can only assert on the EMITTED source: the
+ * correct static imports, the defensive entity-registry guard, the
+ * role/permission-derived scope logic, and the untouched flag/restriction
+ * literals. The actual `SCOPE_CONFIG.roles` VALUES for a real role are
+ * covered by `packages/core/tests/jest/services/scope.service.test.ts`
+ * (against a realistic mock) and by manual inspection of the real generated
+ * output after `node packages/core/scripts/build/registry.mjs`.
+ *
+ * Run: node --test packages/core/scripts/build/registry/__tests__/scope-registry.test.mjs
+ */
+
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { generateScopeRegistry } from '../generators/scope-registry.mjs'
+
+test('imports ENTITY_REGISTRY and AVAILABLE_ROLES/PERMISSIONS_BY_ROLE from sibling generated registries', () => {
+  const out = generateScopeRegistry([], {})
+  assert.match(out, /import \{ ENTITY_REGISTRY \} from '\.\/entity-registry'/)
+  assert.match(out, /import \{ AVAILABLE_ROLES, PERMISSIONS_BY_ROLE \} from '\.\/permissions-registry'/)
+})
+
+test('does not reintroduce the old generation-time entities/config computation', () => {
+  const out = generateScopeRegistry([{ name: 'ignored', api: { endpoints: { create: true } } }], { some: 'config' })
+  // The old bug read entity.api.endpoints/entity.features/entity.fields directly —
+  // none of those property paths should appear in the emitted output at all,
+  // since the real computation now reads ENTITY_REGISTRY's real EntityConfig.
+  assert.doesNotMatch(out, /entity\.api\.endpoints/)
+  assert.doesNotMatch(out, /entity\.features/)
+})
+
+test('base scopes are empty — nothing granted irrespective of role', () => {
+  const out = generateScopeRegistry([], {})
+  assert.match(out, /base:\s*\[\]/)
+})
+
+test('role scopes are computed from PERMISSIONS_BY_ROLE per AVAILABLE_ROLES, not hardcoded role names', () => {
+  const out = generateScopeRegistry([], {})
+  assert.match(out, /for \(const role of AVAILABLE_ROLES\)/)
+  assert.match(out, /const perms = PERMISSIONS_BY_ROLE\[role\]/)
+  // The old hardcoded roleScopes literal (superadmin/admin/manager/member keys,
+  // referencing a nonexistent "products" entity) must be gone.
+  assert.doesNotMatch(out, /'manager'/)
+  assert.doesNotMatch(out, /products:write/)
+  assert.doesNotMatch(out, /products:delete/)
+})
+
+test('read/write/delete scopes are derived from list|read / create|update / delete permissions', () => {
+  const out = generateScopeRegistry([], {})
+  assert.match(out, /\$\{slug\}\.list.*Permission.*\|\|.*perms\?\.has\(`\$\{slug\}\.read`/)
+  assert.match(out, /\$\{slug\}\.create.*Permission.*\|\|.*perms\?\.has\(`\$\{slug\}\.update`/)
+  assert.match(out, /\$\{slug\}\.delete.*Permission/)
+  assert.match(out, /scopes\.push\(`\$\{slug\}:read`\)/)
+  assert.match(out, /scopes\.push\(`\$\{slug\}:write`\)/)
+  assert.match(out, /scopes\.push\(`\$\{slug\}:delete`\)/)
+})
+
+test('guards against ChildEntityDefinition entries (no access/slug) in ENTITY_REGISTRY', () => {
+  const out = generateScopeRegistry([], {})
+  assert.match(out, /if \(!cfg\?\.access\?\.api \|\| !cfg\.slug\) return null/)
+})
+
+test('flag scopes and restrictions are preserved unchanged', () => {
+  const out = generateScopeRegistry([], {})
+  assert.match(out, /beta_tester/)
+  assert.match(out, /vip:features/)
+  assert.match(out, /"remove": \[\s*"delete",\s*"admin"\s*\]/)
+  assert.match(out, /"allow_only": \[\s*"read",\s*"tasks:write"\s*\]/)
+})
+
+test('superadmin is not hardcoded into SCOPE_CONFIG.roles — handled as a global-role bypass elsewhere', () => {
+  const out = generateScopeRegistry([], {})
+  assert.doesNotMatch(out, /'superadmin':\s*\[/)
+  assert.match(out, /Superadmin is a GLOBAL role/)
+})
+
+test('is a pure function of its output shape — always emits both SCOPE_CONFIG and API_CONFIG exports', () => {
+  const out = generateScopeRegistry([], {})
+  assert.match(out, /export const SCOPE_CONFIG: ScopeConfig = \{/)
+  assert.match(out, /export const API_CONFIG: ApiConfig = \{/)
+})
+
+// Regression for the npm-mode bug: this generator hardcoded the two `@/core/*`
+// type-only imports instead of routing them through convertCorePath() like
+// every sibling generator does, so a scaffolded (non-monorepo) app's tsconfig
+// — which maps `@/*` to its own `./*`, not to core — failed `tsc --noEmit`
+// with TS2307 on both. See https://github.com/NextSpark-js/nextspark/issues/133
+test('monorepo mode (isNpmMode: false or unset): @/core/* type imports are left as-is', () => {
+  const out = generateScopeRegistry([], { isNpmMode: false })
+  assert.match(out, /import type \{ Permission \} from '@\/core\/lib\/permissions\/types'/)
+  assert.match(out, /import type \{ EntityConfig \} from '@\/core\/lib\/entities\/types'/)
+})
+
+test('npm mode: @/core/* type imports are converted to @nextsparkjs/core/*, like every sibling generator', () => {
+  const out = generateScopeRegistry([], { isNpmMode: true, outputDir: '/project/.nextspark/registries' })
+  assert.match(out, /import type \{ Permission \} from '@nextsparkjs\/core\/lib\/permissions\/types'/)
+  assert.match(out, /import type \{ EntityConfig \} from '@nextsparkjs\/core\/lib\/entities\/types'/)
+  assert.doesNotMatch(out, /from '@\/core\//)
+})

package/scripts/build/registry/discovery/mcp-overrides.mjs

@@ -0,0 +1,72 @@
+/**
+ * MCP Override Discovery
+ *
+ * Discovers `entities/<slug>/mcp.ts` files for the active theme — the
+ * extension point a theme uses to customize how one entity is exposed by the
+ * MCP engine (@nextsparkjs/core/lib/mcp): exclude it, exclude specific
+ * operations, relax required fields, transform input/output, or add extra
+ * (non-CRUD) tools.
+ *
+ * Mirrors discoverApiPresets's discoverEntityFolders (same
+ * `{theme}/entities/<slug>/` scan, same theme-only scope) with one
+ * difference: `mcp.ts` sits at the entity folder root (a sibling of `api/`,
+ * `migrations/`, `messages/`), not nested under `api/` like `presets.ts`.
+ *
+ * Unlike the presets discovery, this module does NOT parse file contents —
+ * an McpEntityOverride exports real functions (transformInput, extraTools),
+ * which can't be recovered by regex/brace-counting. The generator instead
+ * emits a literal `import` statement per discovered file (same approach as
+ * entity-registry.mjs), and the override object itself is resolved by the
+ * TypeScript compiler/bundler at build time, not by this script.
+ *
+ * @module core/scripts/build/registry/discovery/mcp-overrides
+ */
+
+import { readdir } from 'fs/promises'
+import { join } from 'path'
+import { existsSync } from 'fs'
+
+import { log, verbose } from '../../../utils/index.mjs'
+
+/**
+ * Discover MCP entity overrides for the active theme.
+ * @param {object} config - Configuration object from getConfig()
+ * @returns {Promise<Array<{slug: string, importPath: string, themeName: string}>>}
+ */
+export async function discoverMcpOverrides(config) {
+  const overrides = []
+  const themeName = config.activeTheme
+
+  if (!themeName) {
+    verbose('[mcp-overrides] No active theme configured — skipping MCP override discovery')
+    return overrides
+  }
+
+  const entitiesDir = join(config.themesDir, themeName, 'entities')
+  if (!existsSync(entitiesDir)) {
+    verbose(`[mcp-overrides] No entities directory found for theme "${themeName}"`)
+    return overrides
+  }
+
+  try {
+    const entries = await readdir(entitiesDir, { withFileTypes: true })
+    const entityDirs = entries.filter((entry) => entry.isDirectory())
+
+    for (const dir of entityDirs) {
+      const entityName = dir.name
+      const mcpPath = join(entitiesDir, entityName, 'mcp.ts')
+      if (!existsSync(mcpPath)) continue
+
+      overrides.push({
+        slug: entityName,
+        importPath: `@/contents/themes/${themeName}/entities/${entityName}/mcp`,
+        themeName,
+      })
+      verbose(`[mcp-overrides] MCP override discovered: ${entityName} -> ${mcpPath}`)
+    }
+  } catch (error) {
+    log(`[mcp-overrides] Error discovering MCP overrides: ${error.message}`, 'error')
+  }
+
+  return overrides
+}

package/scripts/build/registry/discovery/mcp-overrides.test.mjs

@@ -0,0 +1,86 @@
+/**
+ * Tests for discoverMcpOverrides.
+ *
+ * Run: node --test packages/core/scripts/build/registry/discovery/mcp-overrides.test.mjs
+ */
+
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { mkdtemp, mkdir, writeFile, rm } from 'fs/promises'
+import { tmpdir } from 'os'
+import { join } from 'path'
+
+import { discoverMcpOverrides } from './mcp-overrides.mjs'
+
+async function makeThemeFixture(entities) {
+  const root = await mkdtemp(join(tmpdir(), 'mcp-overrides-test-'))
+  const themesDir = join(root, 'themes')
+  const themeName = 'testtheme'
+  const entitiesDir = join(themesDir, themeName, 'entities')
+
+  for (const [slug, files] of Object.entries(entities)) {
+    const entityDir = join(entitiesDir, slug)
+    await mkdir(entityDir, { recursive: true })
+    for (const file of files) {
+      await writeFile(join(entityDir, file), '// fixture\n')
+    }
+  }
+
+  return { root, themesDir, themeName }
+}
+
+test('returns an empty array when there is no active theme', async () => {
+  const result = await discoverMcpOverrides({ activeTheme: undefined, themesDir: '/nonexistent' })
+  assert.deepEqual(result, [])
+})
+
+test('returns an empty array when the theme has no entities directory', async () => {
+  const root = await mkdtemp(join(tmpdir(), 'mcp-overrides-test-'))
+  const result = await discoverMcpOverrides({ activeTheme: 'ghost', themesDir: join(root, 'themes') })
+  assert.deepEqual(result, [])
+  await rm(root, { recursive: true, force: true })
+})
+
+test('finds mcp.ts at the entity folder root, not nested under api/', async () => {
+  const { root, themesDir, themeName } = await makeThemeFixture({
+    customers: ['customers.config.ts', 'mcp.ts'],
+  })
+  const result = await discoverMcpOverrides({ activeTheme: themeName, themesDir })
+  assert.equal(result.length, 1)
+  assert.equal(result[0].slug, 'customers')
+  assert.equal(result[0].importPath, `@/contents/themes/${themeName}/entities/customers/mcp`)
+  await rm(root, { recursive: true, force: true })
+})
+
+test('skips entities that have no mcp.ts', async () => {
+  const { root, themesDir, themeName } = await makeThemeFixture({
+    customers: ['customers.config.ts', 'mcp.ts'],
+    tasks: ['tasks.config.ts'],
+  })
+  const result = await discoverMcpOverrides({ activeTheme: themeName, themesDir })
+  assert.deepEqual(result.map((r) => r.slug), ['customers'])
+  await rm(root, { recursive: true, force: true })
+})
+
+test('does NOT match a preset-style entities/<slug>/api/mcp.ts (wrong location)', async () => {
+  const root = await mkdtemp(join(tmpdir(), 'mcp-overrides-test-'))
+  const themesDir = join(root, 'themes')
+  const themeName = 'testtheme'
+  await mkdir(join(themesDir, themeName, 'entities', 'customers', 'api'), { recursive: true })
+  await writeFile(join(themesDir, themeName, 'entities', 'customers', 'api', 'mcp.ts'), '// wrong spot\n')
+
+  const result = await discoverMcpOverrides({ activeTheme: themeName, themesDir })
+  assert.deepEqual(result, [])
+  await rm(root, { recursive: true, force: true })
+})
+
+test('discovers multiple entity overrides in the same theme', async () => {
+  const { root, themesDir, themeName } = await makeThemeFixture({
+    customers: ['mcp.ts'],
+    tasks: ['mcp.ts'],
+    posts: [],
+  })
+  const result = await discoverMcpOverrides({ activeTheme: themeName, themesDir })
+  assert.deepEqual(result.map((r) => r.slug).sort(), ['customers', 'tasks'])
+  await rm(root, { recursive: true, force: true })
+})

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

@@ -0,0 +1,61 @@
+/**
+ * MCP Override Registry Generator
+ *
+ * Generates mcp-registry.ts: a literal-import map of discovered
+ * `entities/<slug>/mcp.ts` files (see discovery/mcp-overrides.mjs), consumed
+ * by the default `/api/mcp` route template to build the `overrides` option
+ * passed to `createMcpEngine`. Follows entity-registry.mjs's literal-import
+ * pattern (not the regex-parsing approach used for api-presets.ts) because
+ * an McpEntityOverride exports real functions — transformInput, extraTools —
+ * that can't be recovered from source text.
+ *
+ * @module core/scripts/build/registry/generators/mcp-registry
+ */
+
+import { join } from 'path'
+import { convertCorePath } from '../config.mjs'
+
+/**
+ * Generate the MCP override registry file.
+ * @param {Array<{slug: string, importPath: string, themeName: string}>} mcpOverrides - Discovered overrides
+ * @param {object} config - Configuration object from getConfig()
+ * @returns {string} Generated TypeScript content
+ */
+export function generateMcpRegistry(mcpOverrides, config) {
+  const outputFilePath = join(config.outputDir, 'mcp-registry.ts')
+
+  const importName = (slug) => `${toPascalCase(slug)}McpOverride`
+
+  const imports = mcpOverrides
+    .map((entry) => `import ${importName(entry.slug)} from '${entry.importPath}'`)
+    .join('\n')
+
+  const entries = mcpOverrides
+    .map((entry) => `  '${entry.slug}': ${importName(entry.slug)},`)
+    .join('\n')
+
+  return `/**
+ * Auto-generated MCP Override Registry
+ *
+ * Generated at: ${new Date().toISOString()}
+ * MCP overrides discovered: ${mcpOverrides.length}
+ *
+ * DO NOT EDIT - This file is auto-generated by scripts/build/registry.mjs
+ */
+
+${imports}
+import type { McpEntityOverride } from '${convertCorePath('@/core/lib/mcp', outputFilePath, config)}'
+
+export const MCP_OVERRIDES: Record<string, McpEntityOverride> = {
+${entries}
+}
+`
+}
+
+function toPascalCase(slug) {
+  return slug
+    .split(/[-_/]+/)
+    .filter(Boolean)
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join('')
+}

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

@@ -2,113 +2,90 @@
  * Scope Registry Generator
  *
  * Generates scope-registry.ts
+ */
+
+import { join } from 'path'
+import { convertCorePath } from '../config.mjs'
+
+/**
+ *
+ * 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)]
-  }
-
+  const outputFilePath = config.outputDir ? join(config.outputDir, 'scope-registry.ts') : 'scope-registry.ts'
   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 '${convertCorePath('@/core/lib/permissions/types', outputFilePath, config)}'
+import type { EntityConfig } from '${convertCorePath('@/core/lib/entities/types', outputFilePath, config)}'
+
 export interface ScopeConfig {
   base: string[]
   roles: Record<string, string[]>
@@ -123,9 +100,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/(auth)/signup/page.tsx

@@ -4,6 +4,7 @@ import { redirect } from 'next/navigation'
 import { SignupForm } from '@nextsparkjs/core/components/auth/forms/SignupForm'
 import { getTemplateOrDefault, getMetadataOrDefault } from '@nextsparkjs/core/lib/template-resolver'
 import { AUTH_CONFIG } from '@nextsparkjs/core/lib/config'
+import { resolveAuthMethods } from '@nextsparkjs/core/lib/auth/auth-methods'
 import { TeamService } from '@nextsparkjs/core/lib/services'
 
 // This page reads DB state (TeamService.hasGlobal) and redirect()s during render,
@@ -23,6 +24,13 @@ export const metadata: Metadata = getMetadataOrDefault(
 async function SignupPageContent() {
   const registrationMode = AUTH_CONFIG?.registration?.mode ?? 'open'
 
+  // Passwordless preset (no 'email-password' in auth.methods): the account is
+  // created by the first one-time-code sign-in, so there is no password signup
+  // form to show — send people to /login instead.
+  if (!resolveAuthMethods(AUTH_CONFIG).includes('email-password')) {
+    redirect('/login')
+  }
+
   // In invitation-only mode, allow the first user to register
   // (when no global team exists yet). Subsequent users need invitations.
   if (registrationMode === 'invitation-only') {