@nextsparkjs/core 0.1.0-beta.8 → 0.1.0-beta.82

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

@@ -0,0 +1,410 @@
+/**
+ * API Presets Registry Generator
+ *
+ * Generates:
+ * - api-presets-registry.ts - Presets organized by endpoint
+ * - api-docs-registry.ts - Documentation paths by endpoint
+ *
+ * @module core/scripts/build/registry/generators/api-presets-registry
+ */
+
+import { join } from 'path'
+import { convertCorePath } from '../config.mjs'
+
+/**
+ * Normalize path separators to forward slashes (for cross-platform compatibility)
+ * @param {string} path - Path to normalize
+ * @returns {string} Path with forward slashes
+ */
+function normalizePath(path) {
+  if (typeof path !== 'string') return path
+  return path.replace(/\\/g, '/')
+}
+
+/**
+ * Escape string for use in TypeScript string literal
+ * @param {string} str - String to escape
+ * @returns {string} Escaped string
+ */
+function escapeString(str) {
+  if (typeof str !== 'string') return str
+  return str
+    .replace(/\\/g, '\\\\')
+    .replace(/'/g, "\\'")
+    .replace(/"/g, '\\"')
+    .replace(/\n/g, '\\n')
+    .replace(/\r/g, '\\r')
+}
+
+/**
+ * Generate TypeScript representation of a preset object
+ * @param {Object} preset - Preset object
+ * @param {string} indent - Indentation string
+ * @returns {string} TypeScript code
+ */
+function generatePresetCode(preset, indent = '      ') {
+  const lines = [`${indent}{`]
+
+  // Required fields
+  lines.push(`${indent}  id: '${escapeString(preset.id)}',`)
+  lines.push(`${indent}  title: '${escapeString(preset.title)}',`)
+  lines.push(`${indent}  method: '${preset.method}',`)
+
+  // Optional description
+  if (preset.description) {
+    lines.push(`${indent}  description: '${escapeString(preset.description)}',`)
+  }
+
+  // Optional pathParams
+  if (preset.pathParams && Object.keys(preset.pathParams).length > 0) {
+    lines.push(`${indent}  pathParams: ${JSON.stringify(preset.pathParams)},`)
+  }
+
+  // Optional params
+  if (preset.params && Object.keys(preset.params).length > 0) {
+    lines.push(`${indent}  params: ${JSON.stringify(preset.params)},`)
+  }
+
+  // Optional headers
+  if (preset.headers && Object.keys(preset.headers).length > 0) {
+    lines.push(`${indent}  headers: ${JSON.stringify(preset.headers)},`)
+  }
+
+  // Optional payload
+  if (preset.payload && Object.keys(preset.payload).length > 0) {
+    const payloadStr = JSON.stringify(preset.payload, null, 2)
+      .split('\n')
+      .map((line, i) => i === 0 ? line : `${indent}  ${line}`)
+      .join('\n')
+    lines.push(`${indent}  payload: ${payloadStr},`)
+  }
+
+  // Optional sessionConfig
+  if (preset.sessionConfig && Object.keys(preset.sessionConfig).length > 0) {
+    lines.push(`${indent}  sessionConfig: ${JSON.stringify(preset.sessionConfig)},`)
+  }
+
+  // Optional tags
+  if (preset.tags && preset.tags.length > 0) {
+    lines.push(`${indent}  tags: [${preset.tags.map(t => `'${escapeString(t)}'`).join(', ')}],`)
+  }
+
+  lines.push(`${indent}}`)
+  return lines.join('\n')
+}
+
+/**
+ * Generate the API presets registry file
+ *
+ * @param {{presets: Array, docs: Array}} data - Discovery data
+ * @param {object} config - Configuration object
+ * @returns {string} Generated TypeScript content
+ */
+export function generateApiPresetsRegistry(data, config) {
+  const { presets } = data
+  const outputFilePath = join(config.outputDir, 'api-presets-registry.ts')
+  const themeName = config.activeTheme || 'unknown'
+
+  // Calculate totals
+  const totalPresets = presets.reduce((sum, p) => sum + (p.presets?.length || 0), 0)
+
+  // Type import path
+  const typesImportPath = convertCorePath('@/core/types/api-presets', outputFilePath, config)
+
+  if (presets.length === 0) {
+    return `/**
+ * Auto-generated API Presets Registry
+ *
+ * Generated at: ${new Date().toISOString()}
+ * Theme: ${themeName}
+ * Total endpoints: 0
+ * Total presets: 0
+ *
+ * To add presets, create files in:
+ * contents/themes/${themeName}/devtools/api/*.presets.ts
+ *
+ * DO NOT EDIT - This file is auto-generated
+ */
+
+import type { ApiPresetsRegistryStructure, ApiEndpointPresets, ApiPreset } from '${typesImportPath}'
+
+// Re-export types
+export type { ApiPresetsRegistryStructure, ApiEndpointPresets, ApiPreset }
+
+export const API_PRESETS_REGISTRY: ApiPresetsRegistryStructure = {
+  endpoints: {},
+  meta: {
+    totalEndpoints: 0,
+    totalPresets: 0,
+    generatedAt: '${new Date().toISOString()}',
+    themeName: '${themeName}'
+  }
+}
+
+/**
+ * Get presets for a specific endpoint
+ */
+export function getPresetsForEndpoint(endpoint: string): ApiEndpointPresets | undefined {
+  return API_PRESETS_REGISTRY.endpoints[endpoint]
+}
+
+/**
+ * Get presets filtered by endpoint and method
+ */
+export function getPresetsByMethod(endpoint: string, method: string): ApiPreset[] {
+  const config = API_PRESETS_REGISTRY.endpoints[endpoint]
+  if (!config) return []
+  return config.presets.filter(p => p.method === method)
+}
+
+/**
+ * Get all endpoint presets
+ */
+export function getAllPresets(): ApiEndpointPresets[] {
+  return Object.values(API_PRESETS_REGISTRY.endpoints)
+}
+
+/**
+ * Check if endpoint has presets
+ */
+export function hasPresets(endpoint: string): boolean {
+  return !!API_PRESETS_REGISTRY.endpoints[endpoint]
+}
+`
+  }
+
+  // Build endpoints code
+  const endpointsCode = presets.map(endpointConfig => {
+    const presetsCode = (endpointConfig.presets || [])
+      .map(preset => generatePresetCode(preset))
+      .join(',\n')
+
+    const source = endpointConfig.source || 'unknown'
+    const normalizedEndpoint = normalizePath(endpointConfig.endpoint)
+    const normalizedSourcePath = normalizePath(endpointConfig.sourcePath)
+    return `  '${normalizedEndpoint}': {
+    endpoint: '${normalizedEndpoint}',
+    summary: '${escapeString(endpointConfig.summary || '')}',
+    sourcePath: '${normalizedSourcePath}',
+    source: '${source}',
+    presets: [
+${presetsCode}
+    ]
+  }`
+  }).join(',\n')
+
+  return `/**
+ * Auto-generated API Presets Registry
+ *
+ * Generated at: ${new Date().toISOString()}
+ * Theme: ${themeName}
+ * Total endpoints: ${presets.length}
+ * Total presets: ${totalPresets}
+ *
+ * DO NOT EDIT - This file is auto-generated
+ */
+
+import type { ApiPresetsRegistryStructure, ApiEndpointPresets, ApiPreset } from '${typesImportPath}'
+
+// Re-export types
+export type { ApiPresetsRegistryStructure, ApiEndpointPresets, ApiPreset }
+
+export const API_PRESETS_REGISTRY: ApiPresetsRegistryStructure = {
+  endpoints: {
+${endpointsCode}
+  },
+  meta: {
+    totalEndpoints: ${presets.length},
+    totalPresets: ${totalPresets},
+    generatedAt: '${new Date().toISOString()}',
+    themeName: '${themeName}'
+  }
+}
+
+/**
+ * Get presets for a specific endpoint
+ * Supports exact match and glob pattern matching
+ */
+export function getPresetsForEndpoint(endpoint: string): ApiEndpointPresets | undefined {
+  // Try exact match first
+  if (API_PRESETS_REGISTRY.endpoints[endpoint]) {
+    return API_PRESETS_REGISTRY.endpoints[endpoint]
+  }
+
+  // Try glob pattern matching
+  for (const [pattern, config] of Object.entries(API_PRESETS_REGISTRY.endpoints)) {
+    if (pattern.includes('*')) {
+      const regex = new RegExp('^' + pattern.replace(/\\*/g, '.*') + '$')
+      if (regex.test(endpoint)) {
+        return config
+      }
+    }
+  }
+
+  return undefined
+}
+
+/**
+ * Get presets filtered by endpoint and method
+ */
+export function getPresetsByMethod(endpoint: string, method: string): ApiPreset[] {
+  const config = getPresetsForEndpoint(endpoint)
+  if (!config) return []
+  return config.presets.filter(p => p.method === method)
+}
+
+/**
+ * Get all endpoint presets
+ */
+export function getAllPresets(): ApiEndpointPresets[] {
+  return Object.values(API_PRESETS_REGISTRY.endpoints)
+}
+
+/**
+ * Check if endpoint has presets
+ */
+export function hasPresets(endpoint: string): boolean {
+  return !!getPresetsForEndpoint(endpoint)
+}
+`
+}
+
+/**
+ * Generate the API docs registry file
+ *
+ * @param {{presets: Array, docs: Array}} data - Discovery data
+ * @param {object} config - Configuration object
+ * @returns {string} Generated TypeScript content
+ */
+export function generateApiDocsRegistry(data, config) {
+  const { docs } = data
+  const outputFilePath = join(config.outputDir, 'api-docs-registry.ts')
+  const themeName = config.activeTheme || 'unknown'
+
+  // Type import path
+  const typesImportPath = convertCorePath('@/core/types/api-presets', outputFilePath, config)
+
+  if (docs.length === 0) {
+    return `/**
+ * Auto-generated API Docs Registry
+ *
+ * Generated at: ${new Date().toISOString()}
+ * Theme: ${themeName}
+ * Total docs: 0
+ *
+ * To add documentation, create files in:
+ * contents/themes/${themeName}/devtools/api/*.md
+ *
+ * DO NOT EDIT - This file is auto-generated
+ */
+
+import type { ApiDocsRegistryStructure, ApiDocEntry } from '${typesImportPath}'
+
+// Re-export types
+export type { ApiDocsRegistryStructure, ApiDocEntry }
+
+export const API_DOCS_REGISTRY: ApiDocsRegistryStructure = {
+  docs: {},
+  meta: {
+    totalDocs: 0,
+    generatedAt: '${new Date().toISOString()}',
+    themeName: '${themeName}'
+  }
+}
+
+/**
+ * Get doc entry for a specific endpoint
+ */
+export function getDocForEndpoint(endpoint: string): ApiDocEntry | undefined {
+  return API_DOCS_REGISTRY.docs[endpoint]
+}
+
+/**
+ * Check if endpoint has documentation
+ */
+export function hasDoc(endpoint: string): boolean {
+  return !!API_DOCS_REGISTRY.docs[endpoint]
+}
+
+/**
+ * Get all documented endpoints
+ */
+export function getAllDocEndpoints(): string[] {
+  return Object.keys(API_DOCS_REGISTRY.docs)
+}
+`
+  }
+
+  // Build docs code - use endpoint from discovery
+  const docsCode = docs.map(doc => {
+    const endpoint = normalizePath(doc.endpoint)
+    const filePath = normalizePath(doc.filePath)
+    const source = doc.source || 'unknown'
+    return `  '${endpoint}': {
+    path: '${filePath}',
+    title: '${escapeString(doc.title)}',
+    endpoint: '${endpoint}',
+    source: '${source}'
+  }`
+  }).join(',\n')
+
+  return `/**
+ * Auto-generated API Docs Registry
+ *
+ * Generated at: ${new Date().toISOString()}
+ * Theme: ${themeName}
+ * Total docs: ${docs.length}
+ *
+ * DO NOT EDIT - This file is auto-generated
+ */
+
+import type { ApiDocsRegistryStructure, ApiDocEntry } from '${typesImportPath}'
+
+// Re-export types
+export type { ApiDocsRegistryStructure, ApiDocEntry }
+
+export const API_DOCS_REGISTRY: ApiDocsRegistryStructure = {
+  docs: {
+${docsCode}
+  },
+  meta: {
+    totalDocs: ${docs.length},
+    generatedAt: '${new Date().toISOString()}',
+    themeName: '${themeName}'
+  }
+}
+
+/**
+ * Get doc entry for a specific endpoint
+ * Also tries to match base endpoint for paths with parameters
+ */
+export function getDocForEndpoint(endpoint: string): ApiDocEntry | undefined {
+  // Try exact match first
+  if (API_DOCS_REGISTRY.docs[endpoint]) {
+    return API_DOCS_REGISTRY.docs[endpoint]
+  }
+
+  // Try matching base endpoint (e.g., /api/v1/customers/123 -> /api/v1/customers)
+  const baseEndpoint = endpoint.replace(/\\/[^/]+$/, '')
+  if (API_DOCS_REGISTRY.docs[baseEndpoint]) {
+    return API_DOCS_REGISTRY.docs[baseEndpoint]
+  }
+
+  return undefined
+}
+
+/**
+ * Check if endpoint has documentation
+ */
+export function hasDoc(endpoint: string): boolean {
+  return !!getDocForEndpoint(endpoint)
+}
+
+/**
+ * Get all documented endpoints
+ */
+export function getAllDocEndpoints(): string[] {
+  return Object.keys(API_DOCS_REGISTRY.docs)
+}
+`
+}

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

@@ -18,6 +18,8 @@ import { convertCorePath } from '../config.mjs'
 export function generateBlockRegistry(blocks, config) {
   const outputFilePath = join(config.outputDir, 'block-registry.ts')
   if (blocks.length === 0) {
+    // When no blocks, use inline type definition to avoid import issues in npm mode
+    // (DTS generation is disabled in core package for performance reasons)
     return `/**
  * Auto-generated Block Registry
  *
@@ -28,13 +30,22 @@ export function generateBlockRegistry(blocks, config) {
  */
 
 import React from 'react'
-import type { BlockConfig } from '${convertCorePath('@/core/types/blocks', outputFilePath, config)}'
+
+// Inline type definition for empty registry (avoids import issues in npm mode)
+type BlockConfig = {
+  slug: string
+  name: string
+  description?: string
+  category: string
+  icon?: string
+  fields?: unknown[]
+}
 
 export const BLOCK_REGISTRY: Record<string, BlockConfig> = {}
 
 export const BLOCK_CATEGORIES: string[] = []
 
-export const BLOCK_COMPONENTS: Record<string, React.LazyExoticComponent<React.ComponentType<any>>> = {}
+export const BLOCK_COMPONENTS: Record<string, React.LazyExoticComponent<React.ComponentType<unknown>>> = {}
 
 export const BLOCK_METADATA = {
   totalBlocks: 0,
@@ -69,6 +80,9 @@ export const BLOCK_METADATA = {
       ? `[${block.scope.map(s => `'${s}'`).join(', ')}]`
       : 'undefined'
     const examplesValue = block.hasExamples ? `${slugVar}_examples` : '[]'
+    const allowInPatternsValue = block.allowInPatterns !== undefined
+      ? block.allowInPatterns.toString()
+      : 'undefined'
 
     return `  '${block.slug}': {
     slug: '${block.slug}',
@@ -83,6 +97,7 @@ export const BLOCK_METADATA = {
     fieldDefinitions: ${slugVar}_fields,
     examples: ${examplesValue},
     scope: ${scopeValue},
+    allowInPatterns: ${allowInPatternsValue},
     isCore: false,
     source: 'theme' as const,
     sourceId: '${block.themeName}'
@@ -105,7 +120,7 @@ export const BLOCK_METADATA = {
  */
 
 import React from 'react'
-import type { BlockConfig, BlockCategory } from '${convertCorePath('@/core/types/blocks', outputFilePath, config)}'
+import type { BlockConfig, BlockCategory } from '${convertCorePath('@/core/types', outputFilePath, config)}'
 
 ${fieldImports}
 

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

@@ -0,0 +1,241 @@
+/**
+ * Docs Registry Generator
+ *
+ * Generates docs-registry.ts with actual documentation content.
+ * Scans themes/{THEME}/docs/public/ and docs/superadmin/ directories.
+ *
+ * @module core/scripts/build/registry/generators/docs-registry
+ */
+
+import fs from 'fs'
+import path from 'path'
+import { existsSync } from 'fs'
+import { CONFIG } from '../config.mjs'
+
+// Get config values - use themesDir which correctly handles monorepo mode
+const projectRoot = CONFIG.projectRoot
+const monorepoRoot = CONFIG.monorepoRoot
+const isNpmMode = CONFIG.isNpmMode
+const isMonorepoMode = CONFIG.isMonorepoMode
+
+// Themes directory - use CONFIG.themesDir for correct monorepo/npm mode handling
+const THEMES_DIR = CONFIG.themesDir
+
+/**
+ * Extract order number from filename (01-example -> 1)
+ */
+function extractOrder(name) {
+  const match = name.match(/^(\d+)-/)
+  return match ? parseInt(match[1], 10) : 999
+}
+
+/**
+ * Clean filename (01-example.md -> example)
+ */
+function cleanName(name) {
+  return name.replace(/^\d+-/, '').replace(/\.md$/, '')
+}
+
+/**
+ * Convert slug to title (getting-started -> Getting Started)
+ */
+function slugToTitle(slug) {
+  return slug
+    .split('-')
+    .map(word => word.charAt(0).toUpperCase() + word.slice(1))
+    .join(' ')
+}
+
+/**
+ * Scan a documentation directory and build registry metadata
+ *
+ * @param {string} docsPath - Absolute path to docs directory
+ * @param {'public' | 'superadmin'} source - Source type
+ * @returns {Array} Array of section metadata
+ */
+function scanDocsDirectory(docsPath, source) {
+  if (!existsSync(docsPath)) {
+    return []
+  }
+
+  const sections = []
+  const items = fs.readdirSync(docsPath, { withFileTypes: true })
+
+  for (const item of items) {
+    if (!item.isDirectory()) continue
+
+    const sectionPath = path.join(docsPath, item.name)
+    const order = extractOrder(item.name)
+    const slug = cleanName(item.name)
+    const title = slugToTitle(slug)
+
+    const pages = []
+    const files = fs.readdirSync(sectionPath)
+
+    for (const file of files) {
+      if (!file.endsWith('.md')) continue
+
+      const filePath = path.join(sectionPath, file)
+      const fileOrder = extractOrder(file)
+      const pageSlug = cleanName(file)
+      const pageTitle = slugToTitle(pageSlug)
+
+      // Get relative path from consuming app directory
+      // In monorepo mode: calculate relative from projectRoot (apps/dev) to file in themes/
+      // In npm mode: calculate relative from projectRoot to file in contents/themes/
+      let relativePath
+      if (isMonorepoMode && monorepoRoot) {
+        // In monorepo, themes are at monorepoRoot/themes/
+        // projectRoot is apps/dev, so we need ../../themes/...
+        const themeRelativePath = filePath.replace(monorepoRoot, '')
+        relativePath = '../..' + themeRelativePath
+      } else {
+        // In npm mode, themes are at projectRoot/contents/themes/
+        relativePath = filePath.replace(projectRoot, '')
+      }
+
+      pages.push({
+        slug: pageSlug,
+        title: pageTitle,
+        order: fileOrder,
+        path: relativePath,
+        source
+      })
+    }
+
+    // Sort pages by order
+    pages.sort((a, b) => a.order - b.order)
+
+    sections.push({
+      title,
+      slug,
+      order,
+      pages,
+      source
+    })
+  }
+
+  // Sort sections by order
+  return sections.sort((a, b) => a.order - b.order)
+}
+
+/**
+ * Generate the docs registry file with actual content
+ *
+ * @returns {string} Generated TypeScript content
+ */
+export function generateDocsRegistry() {
+  const theme = CONFIG.activeTheme || 'default'
+  const themeDocsDir = path.join(THEMES_DIR, theme, 'docs')
+
+  // Scan public docs (user-facing → /docs)
+  const publicDocs = scanDocsDirectory(
+    path.join(themeDocsDir, 'public'),
+    'public'
+  )
+
+  // Scan superadmin docs (admin-facing → /superadmin/docs)
+  const superadminDocs = scanDocsDirectory(
+    path.join(themeDocsDir, 'superadmin'),
+    'superadmin'
+  )
+
+  // Create registry
+  const registry = {
+    public: publicDocs,
+    superadmin: superadminDocs,
+    all: [...publicDocs, ...superadminDocs].sort((a, b) => a.order - b.order)
+  }
+
+  // Total pages count
+  const publicPages = publicDocs.reduce((sum, section) => sum + section.pages.length, 0)
+  const superadminPages = superadminDocs.reduce((sum, section) => sum + section.pages.length, 0)
+  const totalPages = publicPages + superadminPages
+
+  return `/**
+ * Auto-generated Documentation Registry
+ *
+ * Generated at: ${new Date().toISOString()}
+ * Theme: ${theme}
+ * Public sections: ${publicDocs.length}
+ * Superadmin sections: ${superadminDocs.length}
+ * Total pages: ${totalPages}
+ *
+ * Structure:
+ * - public: User-facing documentation → /docs
+ * - superadmin: Admin documentation → /superadmin/docs
+ *
+ * DO NOT EDIT - This file is auto-generated
+ */
+
+// Inline type definitions for npm mode (avoids import issues since DTS is disabled)
+export interface DocPageMeta {
+  slug: string
+  title: string
+  order: number
+  path: string
+  source: 'public' | 'superadmin'
+}
+
+export interface DocSectionMeta {
+  slug: string
+  title: string
+  order: number
+  pages: DocPageMeta[]
+  source: 'public' | 'superadmin'
+}
+
+export interface DocsRegistryStructure {
+  public: DocSectionMeta[]
+  superadmin: DocSectionMeta[]
+  all: DocSectionMeta[]
+}
+
+export const DOCS_REGISTRY: DocsRegistryStructure = ${JSON.stringify(registry, null, 2)} as const
+
+export type DocsRegistry = typeof DOCS_REGISTRY
+
+/**
+ * Get all documentation sections (public + superadmin)
+ */
+export function getAllDocSections(): DocSectionMeta[] {
+  return DOCS_REGISTRY.all
+}
+
+/**
+ * Get public documentation sections only (for /docs)
+ */
+export function getPublicDocSections(): DocSectionMeta[] {
+  return DOCS_REGISTRY.public
+}
+
+/**
+ * Get superadmin documentation sections only (for /superadmin/docs)
+ */
+export function getSuperadminDocSections(): DocSectionMeta[] {
+  return DOCS_REGISTRY.superadmin
+}
+
+/**
+ * Find a section by slug
+ */
+export function findDocSection(slug: string): DocSectionMeta | undefined {
+  return DOCS_REGISTRY.all.find(section => section.slug === slug)
+}
+
+/**
+ * Find a section by slug in a specific category
+ */
+export function findDocSectionInCategory(slug: string, category: 'public' | 'superadmin'): DocSectionMeta | undefined {
+  return DOCS_REGISTRY[category].find(section => section.slug === slug)
+}
+
+/**
+ * Find a page within a section
+ */
+export function findDocPage(sectionSlug: string, pageSlug: string): DocPageMeta | undefined {
+  const section = findDocSection(sectionSlug)
+  return section?.pages.find(page => page.slug === pageSlug)
+}
+`
+}