@nextsparkjs/core 0.1.0-beta.190 → 0.1.0-beta.192

package/scripts/build/registry/contracts/render.mjs

@@ -0,0 +1,341 @@
+/**
+ * Render the portable contracts module (#203 stage 7b): the DTO types and zod schemas of the
+ * project's entities and the API response envelopes, as TypeScript sources.
+ *
+ * The output imports `zod` and nothing else - no Node built-ins, no server code, no registries -
+ * so a React Native app can import it. It is a pure function of its input, byte for byte:
+ * no timestamps, entities in slug order, fields in config order.
+ *
+ * ```
+ * src/index.ts               export * from the envelope, the shared field schemas and the entities
+ * src/envelope.ts            ApiSuccessResponse / ApiListResponse / ApiErrorResponse (+ zod schemas)
+ * src/fields.ts              the schemas several field types share (address, uploaded file, media reference)
+ * src/schema/*.ts            core's portable schema sources, copied verbatim (lib/entities/portable/)
+ * src/entities/index.ts      export * of every entity module
+ * src/entities/<slug>.ts     the entity descriptor, <Entity>, Create<Entity>Input, Update<Entity>Input, their schemas,
+ *                            one enum per option field
+ * ```
+ *
+ * Request schemas ARE the server's: each entity module calls `generateEntitySchemas` from the copied
+ * `src/schema/schema-generator.ts` on a literal descriptor of the entity, so what a client validates is what
+ * the server enforces. Response DTOs are rendered from the columns the handlers select (`entityResponseSystemColumns`,
+ * `taxonomyResponseFields`, evaluated from the same response-shape.ts the handlers import) and, for numbers, from
+ * what the `pg` driver delivers for the column's SQL type (`pgWireKind`).
+ *
+ * @module core/scripts/build/registry/contracts/render
+ */
+
+import { wireKind } from './read-entities.mjs'
+import { PORTABLE_FILES } from './portable.mjs'
+
+export const CONTRACTS_HEADER = '// Generated by NextSpark (nextspark prepare). Do not edit: regenerated on every prepare.'
+
+const quote = value => `'${String(value).replace(/\\/g, '\\\\').replace(/'/g, "\\'").replace(/\n/g, '\\n')}'`
+
+/** `in-progress` -> `InProgress`, `visitDays` -> `VisitDays`. */
+export function pascal(text) {
+  const words = String(text).replace(/([a-z0-9])([A-Z])/g, '$1 $2').split(/[^A-Za-z0-9]+/).filter(Boolean)
+  const joined = words.map(word => word[0].toUpperCase() + word.slice(1)).join('')
+  return /^[A-Za-z]/.test(joined) ? joined : `Entity${joined}`
+}
+
+const camel = text => {
+  const value = pascal(text)
+  return value[0].toLowerCase() + value.slice(1)
+}
+
+/** The singular form of a plural slug, for entities that do not name themselves (`categories` -> `category`). */
+export function singularize(slug) {
+  if (/ies$/.test(slug)) return slug.replace(/ies$/, 'y')
+  if (/(?:ss|us|is)$/.test(slug)) return slug
+  if (/(?:ches|shes|xes|sses|zes)$/.test(slug)) return slug.replace(/es$/, '')
+  return slug.replace(/s$/, '')
+}
+
+/** The names an entity module exports, from the entity's contract. */
+export function entityNames(contract) {
+  const singular = contract.singular && /[A-Za-z]/.test(contract.singular) ? contract.singular : singularize(contract.slug)
+  const base = pascal(singular)
+  return {
+    base,
+    schema: `${camel(base)}Schema`,
+    create: `Create${base}Input`,
+    createSchema: `create${base}InputSchema`,
+    update: `Update${base}Input`,
+    updateSchema: `update${base}InputSchema`,
+    apiPath: `${camel(contract.slug)}ApiPath`,
+    entity: `${camel(base)}Entity`,
+    createShape: `${camel(base)}CreateShape`,
+    updateShape: `${camel(base)}UpdateShape`,
+    schemas: `${camel(base)}Schemas`,
+  }
+}
+
+const enumNames = (names, field, multi) => {
+  const stem = `${names.base}${pascal(field.name)}${multi ? 'Option' : ''}`
+  return { type: stem, schema: `${camel(stem)}Schema` }
+}
+
+const literalExpression = value => (typeof value === 'number' ? `z.literal(${value})` : `z.literal(${quote(value)})`)
+
+function enumExpression(values) {
+  if (values.every(value => typeof value === 'string')) return `z.enum([${values.map(quote).join(', ')}])`
+  return values.length === 1 ? literalExpression(values[0]) : `z.union([${values.map(literalExpression).join(', ')}])`
+}
+
+/**
+ * The zod expression of a field's value. `side` is `response` (what the handler returns: numbers follow the SQL column,
+ * `shape.pgWireKind`) or `request` (what a client should send, for the input types only: the server's own schema
+ * validates, and accepts a number or a numeric string).
+ */
+function valueExpression(field, names, { side, contract, shape, inlineEnums = false }) {
+  const wire = wireKind(field)
+  switch (wire.kind) {
+    case 'string':
+      return 'z.string()'
+    case 'number': {
+      if (side === 'request') return 'z.union([z.number(), z.string()])'
+      const column = contract.columnTypes?.[field.name]
+      const delivered = column ? shape.pgWireKind(column) : null
+      if (delivered === 'string') return 'z.string()'
+      if (delivered === 'number') return 'z.number()'
+      return 'z.union([z.number(), z.string()])'
+    }
+    case 'address':
+      return 'addressSchema'
+    case 'media':
+      return 'mediaRefSchema'
+    case 'image':
+      return 'z.union([z.string(), z.array(fileObjectSchema)])'
+    case 'files':
+      return 'z.array(fileObjectSchema)'
+    case 'id-list':
+      return side === 'request' ? 'z.array(z.string())' : 'z.union([z.array(z.string()), z.string()])'
+    case 'boolean':
+      return 'z.boolean()'
+    case 'tuple':
+      return 'z.tuple([z.number(), z.number()])'
+    case 'string-array':
+      return 'z.array(z.string())'
+    case 'enum':
+      return inlineEnums ? enumExpression(wire.values) : enumNames(names, field, false).schema
+    case 'enum-array':
+      return `z.array(${inlineEnums ? enumExpression(wire.values) : enumNames(names, field, true).schema})`
+    default:
+      return 'z.unknown()'
+  }
+}
+
+/** Every name the entity module declares, to catch two entities that would export the same one. */
+export function exportedNames(contract) {
+  const names = entityNames(contract)
+  const exported = [names.base, names.schema, names.create, names.createSchema, names.update, names.updateSchema, names.apiPath, names.entity]
+  for (const field of contract.fields) {
+    const wire = wireKind(field)
+    if (wire.kind === 'enum') exported.push(enumNames(names, field, false).type, enumNames(names, field, false).schema)
+    if (wire.kind === 'enum-array') exported.push(enumNames(names, field, true).type, enumNames(names, field, true).schema)
+  }
+  return exported
+}
+
+const SHARED_FIELD_SCHEMAS = ['addressSchema', 'fileObjectSchema', 'mediaRefSchema']
+
+const usesSharedSchema = (field, name) => {
+  const kind = wireKind(field).kind
+  return (name === 'addressSchema' && kind === 'address') || (name === 'mediaRefSchema' && kind === 'media') || (name === 'fileObjectSchema' && (kind === 'image' || kind === 'files'))
+}
+
+/** Every name the envelope and the shared field schemas export: no entity may export one too. */
+export const SHARED_EXPORTS = [
+  'apiInfoSchema', 'ApiInfo', 'paginationInfoSchema', 'PaginationInfo', 'ApiSuccessResponse', 'ApiListResponse', 'ApiErrorResponse', 'ApiResponse',
+  'apiSuccessResponseSchema', 'apiListResponseSchema', 'apiErrorResponseSchema',
+  'addressSchema', 'Address', 'fileObjectSchema', 'FileObject', 'mediaRefSchema', 'MediaRef',
+]
+
+const propertyLiteral = value => (typeof value === 'string' ? quote(value) : String(value))
+
+const identifierKey = name => (/^[A-Za-z_$][\w$]*$/.test(name) ? name : quote(name))
+
+/** One field of a descriptor as a literal (`api` is the top-level fields' only: child fields have none). */
+function fieldLiteral(field, { api }) {
+  const parts = [`name: ${quote(field.name)}`, `type: ${quote(field.type)}`, `required: ${field.required}`]
+  if (field.defaultValue) parts.push(`defaultValue: ${propertyLiteral(field.defaultValue.value)}`)
+  for (const key of ['min', 'max', 'maxLength']) if (field[key] !== undefined) parts.push(`${key}: ${field[key]}`)
+  if (field.optionDescriptors) parts.push(`options: [${field.optionDescriptors.map(option => `{ value: ${propertyLiteral(option.value)}${option.label ? `, label: ${quote(option.label)}` : ''} }`).join(', ')}]`)
+  parts.push(`display: { label: ${quote(field.label)} }`)
+  if (api) parts.push(`api: { readOnly: ${field.readOnly} }`)
+  return `{ ${parts.join(', ')} }`
+}
+
+/** The literal descriptor of the entity `generateEntitySchemas` is run on. */
+function descriptorLiteral(contract, names) {
+  const singular = contract.singular && /[A-Za-z]/.test(contract.singular) ? contract.singular : singularize(contract.slug)
+  const lines = [`export const ${names.entity} = {`, `  slug: ${quote(contract.slug)},`, `  names: { singular: ${quote(singular)} },`, '  fields: [', ...contract.fields.map(field => `    ${fieldLiteral(field, { api: true })},`), '  ],']
+  if (contract.builder) lines.push('  builder: { enabled: true },')
+  if (contract.softDelete) lines.push('  table: { softDelete: true },')
+  if (contract.taxonomies.length > 0) lines.push(`  taxonomies: { enabled: true, types: [${contract.taxonomies.map(type => `{ type: ${quote(type.type)}, field: ${quote(type.field)} }`).join(', ')}] },`)
+  if (contract.childEntities) {
+    lines.push('  childEntities: {')
+    for (const [name, child] of Object.entries(contract.childEntities)) lines.push(`    ${identifierKey(name)}: {`, `      table: ${quote(child.table)},`, '      fields: [', ...child.fields.map(field => `        ${fieldLiteral(field, { api: false })},`), '      ],', '    },')
+    lines.push('  },')
+  }
+  lines.push('} satisfies EntityConfig')
+  return lines
+}
+
+/** The module of one entity. `shape` is the evaluated response-shape.ts of the core the contracts are generated with. */
+export function renderEntity(contract, { source, shape } = {}) {
+  const names = entityNames(contract)
+  const isSystem = name => ['id', 'createdAt', 'updatedAt', 'userId', 'teamId'].includes(name)
+  const own = new Set(contract.fields.map(field => field.name))
+  const writable = contract.fields.filter(field => !field.readOnly && !isSystem(field.name))
+  const systemColumns = shape.entityResponseSystemColumns({ builder: { enabled: contract.builder }, table: { softDelete: contract.softDelete } }, { includeSoftDelete: true })
+  const taxonomyFields = shape.taxonomyResponseFields({ taxonomies: { enabled: contract.taxonomies.length > 0, types: contract.taxonomies } })
+  // The shared schemas any field needs, a child row's fields included (their input types use them too)
+  const everyField = [...contract.fields, ...Object.values(contract.childEntities ?? {}).flatMap(child => child.fields)]
+  const shared = SHARED_FIELD_SCHEMAS.filter(name => everyField.some(field => usesSharedSchema(field, name)))
+  const fromShape = ['builderBlockSchema', 'taxonomyTermSchema', 'metasResponseSchema', 'childrenResponseSchema']
+  const usedFromShape = ['metasResponseSchema', 'childrenResponseSchema', ...(contract.builder ? ['builderBlockSchema'] : []), ...(taxonomyFields.length > 0 ? ['taxonomyTermSchema'] : [])]
+    .filter((name, index, all) => fromShape.includes(name) && all.indexOf(name) === index).sort()
+
+  const lines = [CONTRACTS_HEADER]
+  if (source) lines.push(`// Source: ${source}`)
+  for (const warning of contract.warnings) lines.push(`// Warning: ${warning}`)
+  lines.push('', "import { z } from 'zod'", "import type { EntityConfig } from '../schema/types'", "import { generateEntitySchemas } from '../schema/schema-generator'", `import { ${usedFromShape.join(', ')} } from '../schema/response-shape'`)
+  if (shared.length > 0) lines.push(`import { ${shared.join(', ')} } from '../fields'`)
+  lines.push('', `export const ${names.apiPath} = ${quote(`/api/v1/${contract.slug}`)}`, '')
+
+  lines.push('/** The entity as the server sees it: the request schemas below are generated from it by the server\'s own generator. */', ...descriptorLiteral(contract, names), '', `const ${names.schemas} = generateEntitySchemas(${names.entity})`, '')
+
+  for (const field of contract.fields) {
+    const wire = wireKind(field)
+    if (wire.kind !== 'enum' && wire.kind !== 'enum-array') continue
+    const declared = enumNames(names, field, wire.kind === 'enum-array')
+    lines.push(`export const ${declared.schema} = ${enumExpression(wire.values)}`, `export type ${declared.type} = z.infer<typeof ${declared.schema}>`, '')
+  }
+
+  // Response: the columns the handlers select, in their order, then the configured fields, the taxonomy expansions and the optional expansions
+  const response = []
+  const systemType = { blocks: 'z.array(builderBlockSchema).nullish()', deletedAt: 'z.string().nullish()', deletedBy: 'z.string().nullish()' }
+  for (const column of systemColumns) if (!own.has(column) || column === 'id') response.push(`  ${column}: ${systemType[column] ?? 'z.string()'},`)
+  for (const field of contract.fields.filter(field => field.name !== 'id')) {
+    const present = field.required || field.hasDefault
+    response.push(`  ${field.name}: ${valueExpression(field, names, { side: 'response', contract, shape })}${present ? '' : '.nullish()'},`)
+  }
+  for (const field of taxonomyFields) if (!own.has(field)) response.push(`  ${field}: z.array(taxonomyTermSchema),`)
+  response.push('  metas: metasResponseSchema.optional(),', '  children: childrenResponseSchema.optional(),')
+  lines.push(`export const ${names.schema} = z.object({`, ...response, '})', `export type ${names.base} = z.infer<typeof ${names.schema}>`, '')
+
+  // Requests: the server's schemas, typed by what a client should send
+  // A child row is typed from the child's own fields, with the parent's semantics (required unless it has a default,
+  // enum options, numbers as a number or a numeric string) and an optional `id` (an existing row); the server's schema
+  // rejects the rows these types reject
+  const childRow = child => `z.object({ id: z.string().optional(), ${child.fields.map(field => `${identifierKey(field.name)}: ${valueExpression(field, names, { side: 'request', contract, shape, inlineEnums: true })}${field.required && !field.hasDefault ? '' : '.nullish()'}`).join(', ')} })`
+  const childKeys = contract.childEntities ? [`  children: z.object({ ${Object.entries(contract.childEntities).map(([name, child]) => `${identifierKey(name)}: z.array(${childRow(child)}).optional()`).join(', ')} }).optional(),`] : []
+  const builderKeys = [...(contract.builder ? ['  blocks: z.unknown().optional(),', '  settings: z.unknown().optional(),'] : []), ...childKeys]
+  const create = writable.map(field => `  ${field.name}: ${valueExpression(field, names, { side: 'request', contract, shape })}${field.required && !field.hasDefault ? '' : '.nullish()'},`)
+  const update = writable.map(field => `  ${field.name}: ${valueExpression(field, names, { side: 'request', contract, shape })}${field.required ? '.optional()' : '.nullish()'},`)
+  lines.push('// Types only: what a client should send. The schemas exported below are the server\'s, which also accept what it normalizes', `// (numeric strings, empty values) and, on update, the read-only columns of a row fetched earlier.`)
+  lines.push(`const ${names.createShape} = z.object({`, ...create, ...builderKeys, '})', `const ${names.updateShape} = z.object({`, ...update, ...builderKeys, '})', '')
+  lines.push(`export type ${names.create} = z.input<typeof ${names.createShape}>`, `export const ${names.createSchema} = ${names.schemas}.create as unknown as z.ZodType<${names.create}>`, '')
+  lines.push(`export type ${names.update} = z.input<typeof ${names.updateShape}>`, `export const ${names.updateSchema} = ${names.schemas}.update as unknown as z.ZodType<${names.update}>`, '')
+  return lines.join('\n')
+}
+
+/** The API response envelopes, exactly what `createApiResponse` / `createApiError` put on the wire. */
+export function renderEnvelope() {
+  return `${CONTRACTS_HEADER}
+
+import { z } from 'zod'
+
+/** \`info\` of every response: the timestamp, plus whatever the endpoint adds (pagination, \`created\`). */
+export const apiInfoSchema = z.looseObject({ timestamp: z.string() })
+export type ApiInfo = z.infer<typeof apiInfoSchema>
+
+/** What a list endpoint adds to \`info\`. */
+export const paginationInfoSchema = z.object({
+  page: z.number(),
+  limit: z.number(),
+  total: z.number(),
+  totalPages: z.number(),
+  hasNextPage: z.boolean(),
+  hasPrevPage: z.boolean(),
+})
+export type PaginationInfo = z.infer<typeof paginationInfoSchema>
+
+export interface ApiSuccessResponse<T> {
+  success: true
+  data: T
+  info: ApiInfo
+}
+
+export interface ApiListResponse<T> {
+  success: true
+  data: T[]
+  info: ApiInfo & PaginationInfo
+}
+
+export interface ApiErrorResponse {
+  success: false
+  error: string
+  code: string
+  details?: unknown
+  info?: ApiInfo
+}
+
+export type ApiResponse<T> = ApiSuccessResponse<T> | ApiErrorResponse
+
+export function apiSuccessResponseSchema<T extends z.ZodType>(data: T) {
+  return z.object({ success: z.literal(true), data, info: apiInfoSchema })
+}
+
+export function apiListResponseSchema<T extends z.ZodType>(item: T) {
+  return z.object({ success: z.literal(true), data: z.array(item), info: apiInfoSchema.extend(paginationInfoSchema.shape) })
+}
+
+export const apiErrorResponseSchema = z.object({
+  success: z.literal(false),
+  error: z.string(),
+  code: z.string(),
+  details: z.unknown().optional(),
+  info: apiInfoSchema.optional(),
+})
+`
+}
+
+/** The schemas several entities' field types share: the server's own (schema/schema-generator.ts, schema/media-ref.ts). */
+export function renderFields() {
+  return `${CONTRACTS_HEADER}
+
+import { z } from 'zod'
+import { addressSchema, fileObjectSchema } from './schema/schema-generator'
+import { mediaRefSchema } from './schema/media-ref'
+
+export { addressSchema, fileObjectSchema, mediaRefSchema }
+
+/** \`address\` fields. */
+export type Address = z.infer<typeof addressSchema>
+
+/** One uploaded file: the items of \`file\`, \`video\`, \`audio\` and multi-\`image\` fields. */
+export type FileObject = z.infer<typeof fileObjectSchema>
+
+/** \`media-library\` fields: a plain URL (legacy) or the media id with its url. */
+export type MediaRef = z.infer<typeof mediaRefSchema>
+`
+}
+
+/**
+ * Every file of the contracts module for these entity contracts (`{ contract, source }` in slug order) and the
+ * portable sources (`{ path, content }` from `readPortableSources`), as `{ path, content }` relative to the module
+ * root, sorted by path.
+ */
+export function renderContracts(entities, { portable = [], shape } = {}) {
+  const files = [...portable, { path: 'src/envelope.ts', content: renderEnvelope() }, { path: 'src/fields.ts', content: renderFields() }]
+  for (const { contract, source } of entities) files.push({ path: `src/entities/${contract.slug}.ts`, content: renderEntity(contract, { source, shape }) })
+  const entityExports = entities.map(({ contract }) => `export * from './${contract.slug}'`)
+  files.push({ path: 'src/entities/index.ts', content: `${CONTRACTS_HEADER}\n\n${entityExports.length > 0 ? `${entityExports.join('\n')}\n` : 'export {}\n'}` })
+  files.push({ path: 'src/index.ts', content: `${CONTRACTS_HEADER}\n\nexport * from './envelope'\nexport * from './fields'\nexport * from './entities'\n` })
+  return files.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0))
+}
+
+export { PORTABLE_FILES }

package/scripts/build/registry/discovery/all-entities.mjs

@@ -0,0 +1,57 @@
+/**
+ * Every entity the project serves: the enabled plugins', core's and the project's, merged with the
+ * priority the registry build applies (plugins < core < project; a later entity replaces an earlier one
+ * of the same name).
+ *
+ * The registry build (registry.mjs) merges the discoveries it already ran; `nextspark prepare` needs the
+ * same list to write the per-entity routes of the generated host (host/entity-routes.mjs), so both share
+ * `mergeEntities` and the host calls `discoverAllEntities`.
+ *
+ * @module core/scripts/build/registry/discovery/all-entities
+ */
+
+import { discoverCoreEntities } from './core-entities.mjs'
+import { discoverPlugins } from './plugins.mjs'
+import { assertNoPluginCollisions } from './plugin-capabilities.mjs'
+import { discoverThemes } from './themes.mjs'
+
+/**
+ * Merge the discovered plugin, core and project entities.
+ *
+ * @param {object} input
+ * @param {object[]} input.plugins - `discoverPlugins()`
+ * @param {object[]} input.coreEntities - `discoverCoreEntities()`
+ * @param {object[]} input.themes - `discoverThemes()` (the project's contribution)
+ * @param {(entity: object, replaced: object) => void} [input.onOverride] - called when an entity replaces one of the same name
+ * @returns {object[]}
+ */
+export function mergeEntities({ plugins, coreEntities, themes, onOverride }) {
+  // Core and the project may replace a plugin's entity; two plugins providing one is a collision, whatever their order.
+  assertNoPluginCollisions(plugins)
+  const merged = [
+    ...plugins.flatMap(plugin => plugin.entities ?? []), // lowest priority
+    ...coreEntities, // core framework entities
+    ...themes.flatMap(theme => theme.entities ?? []), // highest priority (can override core)
+  ]
+  const byName = new Map()
+  for (const entity of merged) {
+    const replaced = byName.get(entity.name)
+    if (replaced) {
+      onOverride?.(entity, replaced)
+      // A project config of a core entity's name is that entity, customized (the host must not take its name for a new entity's)
+      if (replaced.isCore || replaced.overridesCore) entity.overridesCore = true
+    }
+    byName.set(entity.name, entity)
+  }
+  return Array.from(byName.values())
+}
+
+/**
+ * Discover and merge every entity of the project described by `config` (`getConfig()`).
+ * `includeCore: false` leaves core's own entities out (the host serves those with core's own routes).
+ */
+export async function discoverAllEntities(config, { includeCore = true } = {}) {
+  const [plugins, coreEntities, themes] = await Promise.all([discoverPlugins(config), discoverCoreEntities(config), discoverThemes(config)])
+  const merged = mergeEntities({ plugins, coreEntities, themes })
+  return includeCore ? merged : merged.filter(entity => !entity.isCore)
+}

package/scripts/build/registry/discovery/api-presets.mjs

@@ -4,9 +4,10 @@
  * Discovers API preset and documentation files from multiple sources:
  *
  * Priority (highest to lowest):
- * 1. Theme custom routes: {theme}/app/api/**\/docs.md and presets.ts
- * 2. Entity folders: {theme}/entities/*\/api/docs.md and presets.ts
- * 3. Core routes: packages/core/templates/app/api/**\/docs.md and presets.ts
+ * 1. Project custom routes: api/**\/docs.md and presets.ts
+ * 2. Entity folders: entities/*\/api/docs.md and presets.ts
+ * 3. Core routes: next to core's route modules, packages/core/src/routes/api/**\/docs.md and presets.ts
+ *    (dist/routes/api in the published package)
  *
  * @module core/scripts/build/registry/discovery/api-presets
  */
@@ -291,16 +292,7 @@ function deriveEndpointFromRoute(routePath) {
  * @returns {string} Path to store in registry (with forward slashes)
  */
 function getStoragePath(absolutePath, config) {
-  let result
-  if (config.isMonorepoMode) {
-    // In monorepo, use path relative to monorepo root
-    result = relative(config.monorepoRoot, absolutePath)
-  } else {
-    // In npm mode, use path relative to project root with contents/ prefix
-    result = relative(config.projectRoot, absolutePath)
-  }
-  // Always normalize to forward slashes (Windows uses backslashes)
-  return normalizePath(result)
+  return normalizePath(relative(config.projectRoot, absolutePath))
 }
 
 /**
@@ -349,8 +341,8 @@ async function findFilesRecursive(dir, filename) {
  * @param {Set} processedEndpoints - Set of already processed endpoints
  */
 async function discoverEntityFolders(config, results, processedEndpoints) {
-  const themeName = config.activeTheme
-  const entitiesDir = join(config.themesDir, themeName, 'entities')
+  const themeName = config.projectName
+  const entitiesDir = join(config.projectSourceDir, 'entities')
 
   if (!existsSync(entitiesDir)) {
     verbose(`No entities directory found for theme "${themeName}"`)
@@ -432,13 +424,13 @@ async function discoverEntityFolders(config, results, processedEndpoints) {
 }
 
 /**
- * Discover docs and presets from theme custom routes
+ * Discover docs and presets from project custom routes
  * @param {object} config - Configuration object
  * @param {object} results - Results accumulator
  * @param {Set} processedEndpoints - Set of already processed endpoints
  */
 async function discoverThemeRoutes(config, results, processedEndpoints) {
-  const themeName = config.activeTheme
+  const themeName = config.projectName
 
   // Process every docs.md / presets.ts under `baseDir`, mapping each route
   // directory to an endpoint via `endpointForDir(routeDir)`.
@@ -514,18 +506,11 @@ async function discoverThemeRoutes(config, results, processedEndpoints) {
     }
   }
 
-  // Legacy tree: {theme}/app/api/** — the docs path mirrors the full request URL
-  // under `app/` (e.g. app/api/v1/theme/{theme}/foo -> /api/v1/theme/{theme}/foo).
-  const appDir = join(config.themesDir, themeName, 'app')
-  await processTree(join(appDir, 'api'), (routeDir) =>
-    '/' + normalizePath(relative(appDir, routeDir))
-  )
-
-  // Colocated tree: {theme}/api/** — docs/presets live next to the route handler,
-  // mapped the same way the handlers are (api/foo -> /api/v1/theme/{theme}/foo).
-  const apiDir = join(config.themesDir, themeName, 'api')
+  // Root-first route source: api/** — docs/presets live next to the route handler and follow it to
+  // its URL: the project's api/ is served at /api/<path> (api/ai/usage -> /api/ai/usage).
+  const apiDir = join(config.projectSourceDir, 'api')
   await processTree(apiDir, (routeDir) =>
-    '/api/v1/theme/' + themeName + '/' + normalizePath(relative(apiDir, routeDir))
+    '/api/' + normalizePath(relative(apiDir, routeDir))
   )
 }
 
@@ -536,9 +521,12 @@ async function discoverThemeRoutes(config, results, processedEndpoints) {
  * @param {Set} processedEndpoints - Set of already processed endpoints
  */
 async function discoverCoreRoutes(config, results, processedEndpoints) {
-  const coreApiDir = join(config.coreDir, 'templates', 'app', 'api')
+  // Core's docs and presets sit next to its route modules: src/routes in a source checkout, dist/routes in
+  // the published package. The route path under them is the URL (routes/api/v1/billing -> /api/v1/billing).
+  const routesDir = ['src/routes', 'dist/routes'].map(dir => join(config.coreDir, dir)).find(dir => existsSync(join(dir, 'api')))
+  const coreApiDir = routesDir ? join(routesDir, 'api') : join(config.coreDir, 'src', 'routes', 'api')
 
-  if (!existsSync(coreApiDir)) {
+  if (!routesDir) {
     verbose('No core API routes found')
     return
   }
@@ -551,7 +539,7 @@ async function discoverCoreRoutes(config, results, processedEndpoints) {
   for (const docsPath of docFiles) {
     try {
       const routeDir = dirname(docsPath)
-      const relativeDir = relative(join(config.coreDir, 'templates', 'app'), routeDir)
+      const relativeDir = relative(routesDir, routeDir)
       const endpoint = '/' + normalizePath(relativeDir)
 
       // Skip if already processed by theme or entity
@@ -583,7 +571,7 @@ async function discoverCoreRoutes(config, results, processedEndpoints) {
   for (const presetsPath of presetFiles) {
     try {
       const routeDir = dirname(presetsPath)
-      const relativeDir = relative(join(config.coreDir, 'templates', 'app'), routeDir)
+      const relativeDir = relative(routesDir, routeDir)
       const endpoint = '/' + normalizePath(relativeDir)
 
       // Skip if already processed by theme or entity
@@ -620,7 +608,7 @@ async function discoverCoreRoutes(config, results, processedEndpoints) {
  * Discover all API presets and docs from multiple sources
  *
  * Priority (highest to lowest):
- * 1. Theme custom routes
+ * 1. Project custom routes
  * 2. Entity folders
  * 3. Core routes
  *
@@ -633,19 +621,8 @@ export async function discoverApiPresets(config = DEFAULT_CONFIG) {
   const results = { presets: [], docs: [] }
   const processedEndpoints = new Set()
 
-  if (!config.activeTheme) {
-    verbose('Warning: NEXT_PUBLIC_ACTIVE_THEME not set, skipping theme-based discovery')
-    // Still discover core routes
-    await discoverCoreRoutes(config, results, processedEndpoints)
-
-    if (results.presets.length > 0 || results.docs.length > 0) {
-      log(`Found ${results.presets.length} preset files and ${results.docs.length} doc files (core only)`, 'success')
-    }
-    return results
-  }
-
-  // 1. Theme custom routes (highest priority)
-  verbose('Checking theme custom routes...')
+  // 1. Project custom routes (highest priority)
+  verbose('Checking project custom routes...')
   await discoverThemeRoutes(config, results, processedEndpoints)
 
   // 2. Entity folders (second priority)

package/scripts/build/registry/discovery/auth.mjs

@@ -1,7 +1,7 @@
 /**
  * Auth Discovery
  *
- * Discovers authentication configuration files from contents/auth
+ * Discovers authentication configuration files from the project auth directory
  *
  * @module core/scripts/build/registry/discovery/auth
  */
@@ -10,7 +10,6 @@ import { readFile } from 'fs/promises'
 import { join } from 'path'
 import { existsSync } from 'fs'
 
-import { CONFIG } from '../config.mjs'
 import { verbose } from '../../../utils/index.mjs'
 
 /**
@@ -18,8 +17,8 @@ import { verbose } from '../../../utils/index.mjs'
  * Looks for roles.json in the auth directory
  * @returns {Promise<Array<{type: string, path: string, data: object, relativePath: string}>>}
  */
-export async function discoverAuthConfig() {
-  const authDir = join(CONFIG.contentsDir, 'auth')
+export async function discoverAuthConfig(config) {
+  const authDir = join(config.projectSourceDir, 'auth')
   const authConfig = []
 
   try {