@nextsparkjs/core 0.1.0-beta.7 → 0.1.0-beta.70

package/scripts/build/docs-registry.mjs

@@ -3,9 +3,15 @@
 /**
  * Documentation Registry Builder
  *
- * Scans core/docs/, contents/themes/{THEME}/docs/, and plugin docs directories
+ * Scans contents/themes/{THEME}/docs/public/ and docs/superadmin/ directories
  * Generates static registry at .nextspark/registries/docs-registry.ts
  *
+ * Structure:
+ * - public: User-facing documentation → /docs
+ * - superadmin: Admin documentation → /superadmin/docs
+ *
+ * NOTE: Plugin docs are NOT included - they are for developer reference only (IDE/LLM).
+ *
  * ZERO RUNTIME I/O - Build-time only
  * Part of the registry system
  */
@@ -19,24 +25,39 @@ const __filename = fileURLToPath(import.meta.url)
 const __dirname = path.dirname(__filename)
 
 /**
- * Detect project root by searching for package.json with workspaces
+ * Detect project root by searching for nextspark.config.ts or apps/dev
+ * Excludes node_modules paths to avoid finding pnpm internal workspaces
  */
 function detectProjectRoot() {
+  // Check for explicit project root from CLI
+  if (process.env.NEXTSPARK_PROJECT_ROOT) {
+    return process.env.NEXTSPARK_PROJECT_ROOT
+  }
+
   let dir = process.cwd()
   const maxDepth = 10
   let depth = 0
 
+  // Search upward for nextspark.config.ts (NPM mode) or apps/dev (monorepo)
   while (dir !== '/' && depth < maxDepth) {
-    const pkgPath = path.join(dir, 'package.json')
-    if (existsSync(pkgPath)) {
-      try {
-        const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'))
-        if (pkg.workspaces || existsSync(path.join(dir, 'pnpm-workspace.yaml'))) {
-          return dir
-        }
-      } catch (error) {
-        // Continue searching
-      }
+    // Skip if we're inside node_modules
+    if (dir.includes('node_modules')) {
+      dir = path.dirname(dir)
+      depth++
+      continue
+    }
+
+    // Primary: nextspark.config.ts (NPM mode projects)
+    if (existsSync(path.join(dir, 'nextspark.config.ts'))) {
+      return dir
+    }
+    // Secondary: monorepo with apps/dev (development mode)
+    if (existsSync(path.join(dir, 'apps/dev'))) {
+      return path.join(dir, 'apps/dev')
+    }
+    // Tertiary: pnpm-workspace.yaml at root (monorepo without apps/dev)
+    if (existsSync(path.join(dir, 'pnpm-workspace.yaml'))) {
+      return dir
     }
     dir = path.dirname(dir)
     depth++
@@ -61,23 +82,28 @@ console.log(`📚 Building docs registry...`)
 console.log(`   Project root: ${PROJECT_ROOT}`)
 console.log(`   Mode: ${IS_NPM_MODE ? 'NPM' : 'Monorepo'}`)
 
-// Paths based on mode
-const CORE_DIR = IS_NPM_MODE
-  ? path.join(PROJECT_ROOT, 'node_modules/@nextsparkjs/core')
-  : path.join(PROJECT_ROOT, 'packages/core')
-
-const CONTENTS_DIR = path.join(PROJECT_ROOT, 'contents')
+// Paths - themes directory
+// In NPM mode: contents/themes
+// In Monorepo mode: themes/ (directly in root)
+const THEMES_DIR = IS_NPM_MODE
+  ? path.join(PROJECT_ROOT, 'contents/themes')
+  : path.join(PROJECT_ROOT, 'themes')
 
 const OUTPUT_DIR = path.join(PROJECT_ROOT, '.nextspark/registries')
 
 // For backward compatibility, ROOT_DIR is the project root
 const ROOT_DIR = PROJECT_ROOT
 
+// Path prefix for registry entries
+// In monorepo mode, registry is consumed from apps/dev, so paths need ../../ prefix
+// In NPM mode, registry is consumed from project root, so paths start with /
+const PATH_PREFIX = IS_NPM_MODE ? '' : '../..'
+
 /**
  * Scan a documentation directory and build registry metadata
  *
  * @param {string} docsPath - Absolute path to docs directory
- * @param {'core' | 'theme' | 'plugin'} source - Source type
+ * @param {'public' | 'superadmin'} source - Source type
  * @returns {Array} Array of section metadata
  */
 function scanDocsDirectory(docsPath, source) {
@@ -108,8 +134,10 @@ function scanDocsDirectory(docsPath, source) {
       const pageSlug = cleanName(file)
       const pageTitle = slugToTitle(pageSlug)
 
-      // Get relative path from project root
-      const relativePath = filePath.replace(ROOT_DIR, '')
+      // Get relative path from consuming app directory
+      // In monorepo: apps/dev needs ../../themes/... to reach themes/
+      // In NPM: project root uses /contents/themes/... directly
+      const relativePath = PATH_PREFIX + filePath.replace(ROOT_DIR, '')
 
       pages.push({
         slug: pageSlug,
@@ -161,75 +189,6 @@ function slugToTitle(slug) {
     .join(' ')
 }
 
-/**
- * Get active plugins from theme configuration
- */
-function getActiveThemePlugins(activeTheme) {
-  const themeConfigPath = path.join(CONTENTS_DIR, 'themes', activeTheme, 'theme.config.ts')
-
-  try {
-    const configContent = fs.readFileSync(themeConfigPath, 'utf8')
-
-    // Extract plugin dependencies from theme config
-    const pluginsMatch = configContent.match(/plugins:\s*\[([^\]]+)\]/)
-    const plugins = pluginsMatch
-      ? pluginsMatch[1].split(',').map(p => p.trim().replace(/['"]/g, '')).filter(Boolean)
-      : []
-
-    return plugins
-  } catch (error) {
-    console.log(`   Warning: Could not read theme config: ${error.message}`)
-    return []
-  }
-}
-
-/**
- * Read app config to check if plugin docs should be shown in production
- */
-function shouldShowPluginDocsInProd(activeTheme) {
-  const appConfigPath = path.join(CONTENTS_DIR, 'themes', activeTheme, 'app.config.ts')
-
-  try {
-    const configContent = fs.readFileSync(appConfigPath, 'utf8')
-
-    // Look for showPluginsDocsInProd setting
-    const match = configContent.match(/showPluginsDocsInProd:\s*(true|false)/)
-    if (match) {
-      return match[1] === 'true'
-    }
-
-    // Default to false if not found
-    return false
-  } catch (error) {
-    console.log(`   Warning: Could not read app config: ${error.message}`)
-    return false
-  }
-}
-
-/**
- * Scan plugin docs directories for all active plugins
- */
-function scanPluginDocs(activePlugins) {
-  const allPluginDocs = []
-
-  for (const pluginName of activePlugins) {
-    const pluginDocsPath = path.join(CONTENTS_DIR, 'plugins', pluginName, 'docs')
-
-    if (!fs.existsSync(pluginDocsPath)) {
-      continue
-    }
-
-    const sections = scanDocsDirectory(pluginDocsPath, 'plugin')
-
-    // Add plugin context to each section
-    for (const section of sections) {
-      section.pluginName = pluginName
-      allPluginDocs.push(section)
-    }
-  }
-
-  return allPluginDocs
-}
 
 /**
  * Build the documentation registry
@@ -238,49 +197,35 @@ async function buildDocsRegistry() {
   const activeTheme = process.env.NEXT_PUBLIC_ACTIVE_THEME || 'default'
   console.log(`   Active theme: ${activeTheme}`)
 
-  // Scan core docs
-  const coreDocsPath = path.join(CORE_DIR, 'docs')
-  const coreDocs = scanDocsDirectory(coreDocsPath, 'core')
-  console.log(`   Core sections: ${coreDocs.length}`)
+  const themeDocsDir = path.join(THEMES_DIR, activeTheme, 'docs')
 
-  // Scan theme docs
-  const themeDocs = scanDocsDirectory(
-    path.join(CONTENTS_DIR, `themes/${activeTheme}/docs`),
-    'theme'
+  // Scan public docs (user-facing → /docs)
+  const publicDocs = scanDocsDirectory(
+    path.join(themeDocsDir, 'public'),
+    'public'
   )
-  console.log(`   Theme sections: ${themeDocs.length}`)
-
-  // Scan plugin docs (conditionally based on environment and config)
-  const isProd = process.env.NODE_ENV === 'production'
-  const showPluginDocsInProd = shouldShowPluginDocsInProd(activeTheme)
-  const shouldIncludePluginDocs = !isProd || showPluginDocsInProd
+  console.log(`   Public sections: ${publicDocs.length}`)
 
-  let pluginDocs = []
-  if (shouldIncludePluginDocs) {
-    const activePlugins = getActiveThemePlugins(activeTheme)
-    console.log(`   Active plugins: [${activePlugins.join(', ')}]`)
-
-    pluginDocs = scanPluginDocs(activePlugins)
-    console.log(`   Plugin sections: ${pluginDocs.length}`)
-
-    if (pluginDocs.length > 0) {
-      const pluginPages = pluginDocs.reduce((sum, section) => sum + section.pages.length, 0)
-      console.log(`   Plugin pages: ${pluginPages}`)
-    }
-  } else {
-    console.log(`   Plugin docs: EXCLUDED (production + showPluginsDocsInProd: false)`)
-  }
+  // Scan superadmin docs (admin-facing → /superadmin/docs)
+  const superadminDocs = scanDocsDirectory(
+    path.join(themeDocsDir, 'superadmin'),
+    'superadmin'
+  )
+  console.log(`   Superadmin sections: ${superadminDocs.length}`)
 
-  // Merge and create registry
+  // Create registry (public + superadmin, no plugins)
   const registry = {
-    core: coreDocs,
-    theme: themeDocs,
-    plugins: pluginDocs,
-    all: [...coreDocs, ...themeDocs, ...pluginDocs].sort((a, b) => a.order - b.order)
+    public: publicDocs,
+    superadmin: superadminDocs,
+    all: [...publicDocs, ...superadminDocs].sort((a, b) => a.order - b.order)
   }
 
   // Total pages count
-  const totalPages = registry.all.reduce((sum, section) => sum + section.pages.length, 0)
+  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
+  console.log(`   Public pages: ${publicPages}`)
+  console.log(`   Superadmin pages: ${superadminPages}`)
   console.log(`   Total pages: ${totalPages}`)
 
   // Generate TypeScript registry file
@@ -288,60 +233,61 @@ async function buildDocsRegistry() {
  * Auto-generated Documentation Registry
  *
  * Generated at: ${new Date().toISOString()}
- * Core sections: ${coreDocs.length}
- * Theme sections: ${themeDocs.length}
- * Plugin sections: ${pluginDocs.length}
+ * Public sections: ${publicDocs.length}
+ * Superadmin sections: ${superadminDocs.length}
  * Total pages: ${totalPages}
  *
+ * Structure:
+ * - public: User-facing documentation → /docs
+ * - superadmin: Admin documentation → /superadmin/docs
+ *
+ * NOTE: Plugin docs are NOT included - they are for developer reference only (IDE/LLM).
+ *
  * DO NOT EDIT - This file is auto-generated by scripts/build/docs-registry.mjs
  */
 
 import type { DocPageMeta, DocSectionMeta, DocsRegistryStructure } from '@nextsparkjs/core/types/docs'
 
+// Re-export types for external use
+export type { DocPageMeta, DocSectionMeta, DocsRegistryStructure }
+
 export const DOCS_REGISTRY: DocsRegistryStructure = ${JSON.stringify(registry, null, 2)} as const
 
 export type DocsRegistry = typeof DOCS_REGISTRY
 
 /**
- * Get all documentation sections (core + theme + plugins)
+ * Get all documentation sections (public + superadmin)
  */
 export function getAllDocSections(): DocSectionMeta[] {
   return DOCS_REGISTRY.all
 }
 
 /**
- * Get core documentation sections only
+ * Get public documentation sections only (for /docs)
  */
-export function getCoreDocSections(): DocSectionMeta[] {
-  return DOCS_REGISTRY.core
+export function getPublicDocSections(): DocSectionMeta[] {
+  return DOCS_REGISTRY.public
 }
 
 /**
- * Get theme documentation sections only
+ * Get superadmin documentation sections only (for /superadmin/docs)
  */
-export function getThemeDocSections(): DocSectionMeta[] {
-  return DOCS_REGISTRY.theme
+export function getSuperadminDocSections(): DocSectionMeta[] {
+  return DOCS_REGISTRY.superadmin
 }
 
 /**
- * Get plugin documentation sections only
- */
-export function getPluginDocSections(): DocSectionMeta[] {
-  return DOCS_REGISTRY.plugins
-}
-
-/**
- * Get documentation sections for a specific plugin
+ * Find a section by slug
  */
-export function getPluginDocSectionsByName(pluginName: string): DocSectionMeta[] {
-  return DOCS_REGISTRY.plugins.filter(section => section.pluginName === pluginName)
+export function findDocSection(slug: string): DocSectionMeta | undefined {
+  return DOCS_REGISTRY.all.find(section => section.slug === slug)
 }
 
 /**
- * Find a section by slug
+ * Find a section by slug in a specific category
  */
-export function findDocSection(slug: string): DocSectionMeta | undefined {
-  return DOCS_REGISTRY.all.find(section => section.slug === slug)
+export function findDocSectionInCategory(slug: string, category: 'public' | 'superadmin'): DocSectionMeta | undefined {
+  return DOCS_REGISTRY[category].find(section => section.slug === slug)
 }
 
 /**

package/scripts/build/registry/config.mjs

@@ -14,14 +14,17 @@
 
 import { join, dirname } from 'path'
 import { fileURLToPath } from 'url'
-import { existsSync } from 'fs'
+import { existsSync, lstatSync, readlinkSync } from 'fs'
 import dotenv from 'dotenv'
 import { loadNextSparkConfigSync } from '../config-loader.mjs'
 
-// Load .env BEFORE accessing process.env
-// This must happen before CONFIG is defined since ES modules
-// execute imports before the importing module's code runs
-dotenv.config()
+// Load .env from the correct project root
+// Priority: NEXTSPARK_PROJECT_ROOT env var > cwd
+// This is critical for npm mode where cwd might be node_modules/@nextsparkjs/core
+const envPath = process.env.NEXTSPARK_PROJECT_ROOT
+  ? join(process.env.NEXTSPARK_PROJECT_ROOT, '.env')
+  : undefined
+dotenv.config({ path: envPath, override: true })
 
 const __filename = fileURLToPath(import.meta.url)
 const __dirname = dirname(__filename)
@@ -83,12 +86,46 @@ export function detectProjectRoot() {
 }
 
 /**
- * Check if NextSpark is installed as a package
+ * Check if NextSpark is installed as a package (from npm registry)
+ *
+ * This handles both traditional npm/yarn AND pnpm:
+ * - npm/yarn: packages are copied to node_modules (not symlinks)
+ * - pnpm: ALL packages are symlinks, but npm packages point to .pnpm/ store
+ * - pnpm workspace: local packages symlink to the actual package path
+ *
  * @param {string} root - Project root path
- * @returns {boolean} True if installed as npm package
+ * @returns {boolean} True if installed from npm registry
  */
 export function isInstalledAsPackage(root) {
-  return existsSync(join(root, 'node_modules/@nextsparkjs/core'))
+  const corePath = join(root, 'node_modules/@nextsparkjs/core')
+  if (!existsSync(corePath)) {
+    return false
+  }
+
+  try {
+    const stat = lstatSync(corePath)
+
+    // If not a symlink, it's a traditional npm/yarn install
+    if (!stat.isSymbolicLink()) {
+      return true
+    }
+
+    // For symlinks (pnpm), check WHERE it points to:
+    // - npm install: points to .pnpm/@nextsparkjs+core@version.../node_modules/@nextsparkjs/core
+    // - workspace: points to ../../packages/core or similar
+    const linkTarget = readlinkSync(corePath)
+
+    // If symlink points to .pnpm/ directory, it's a real npm installation via pnpm
+    // The .pnpm directory is pnpm's content-addressable store
+    if (linkTarget.includes('.pnpm/') || linkTarget.includes('.pnpm\\')) {
+      return true
+    }
+
+    // Otherwise it's a workspace symlink (monorepo development)
+    return false
+  } catch {
+    return false
+  }
 }
 
 /**
@@ -108,9 +145,11 @@ export function getConfig(projectRoot = null) {
   const isMonorepoMode = !isNpmMode && monorepoRoot !== null
 
   // Determine paths based on mode
+  // In monorepo mode, core is at monorepoRoot/packages/core
+  // In npm mode, core is at projectRoot/node_modules/@nextsparkjs/core
   const coreDir = isNpmMode
     ? join(root, 'node_modules/@nextsparkjs/core')
-    : join(root, 'packages/core')
+    : join(isMonorepoMode ? monorepoRoot : root, 'packages/core')
 
   // ALWAYS generate in .nextspark/registries/ of the project
   // This unifies npm mode and monorepo mode to use the same location