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

package/scripts/build/registry/post-build/route-cleanup.mjs

@@ -12,6 +12,7 @@ import { join, dirname } from 'path'
 import { fileURLToPath } from 'url'
 
 import { log, verbose } from '../../../utils/index.mjs'
+import { isUnsafeWrite, projectFiles } from '../../safe-fs.mjs'
 
 const __filename = fileURLToPath(import.meta.url)
 const __dirname = dirname(__filename)
@@ -39,9 +40,7 @@ export async function cleanupOldRouteFiles(CONFIG) {
             const content = await readFile(routeFile, 'utf8')
             if (content.includes('Auto-generated Plugin Route Proxy')) {
               // Remove the entire plugin route directory
-              await import('fs/promises').then(fs =>
-                fs.rm(pluginDir, { recursive: true, force: true })
-              )
+              await projectFiles(rootDir).rm(pluginDir, { recursive: true, force: true })
               verbose(`Cleaned up old route: ${pluginDir}`)
             }
           }
@@ -49,6 +48,8 @@ export async function cleanupOldRouteFiles(CONFIG) {
       }
     }
   } catch (error) {
+    // An UNSAFE_WRITE refusal propagates and stops the build; every other error here is a non-fatal cleanup failure
+    if (isUnsafeWrite(error)) throw error
     verbose(`Error during route cleanup: ${error.message}`)
   }
 }
@@ -80,7 +81,6 @@ export async function cleanupOrphanedTemplates(activeTemplates, CONFIG) {
 
   async function scanAndCleanDirectory(dir, relativePath = '') {
     try {
-      const { readdir, stat, unlink } = await import('fs/promises')
       const entries = await readdir(dir, { withFileTypes: true })
 
       for (const entry of entries) {
@@ -103,13 +103,14 @@ export async function cleanupOrphanedTemplates(activeTemplates, CONFIG) {
 
           // Check if this generated file has a corresponding active template
           if (!activeTemplatePaths.has(fullPath)) {
-            await unlink(fullPath)
+            await projectFiles(rootDir).unlink(fullPath)
             log(`Cleaned orphaned file: ${fullPath.replace(rootDir, '')}`, 'info')
             cleaned++
           }
         }
       }
     } catch (error) {
+      if (isUnsafeWrite(error)) throw error
       verbose(`Error scanning directory ${dir}: ${error.message}`)
     }
   }
@@ -118,12 +119,12 @@ export async function cleanupOrphanedTemplates(activeTemplates, CONFIG) {
 
   // Clean up empty directories (in reverse order to handle nested structures)
   if (dirsToCleanup.length > 0) {
-    const { rmdir } = await import('fs/promises')
     for (const dir of dirsToCleanup.reverse()) {
       try {
-        await rmdir(dir)
+        await projectFiles(rootDir).rmdir(dir)
         log(`Removed empty directory: ${dir.replace(rootDir, '')}`, 'info')
-      } catch {
+      } catch (error) {
+        if (isUnsafeWrite(error)) throw error
         // Directory might not be empty anymore, ignore
       }
     }
@@ -166,10 +167,10 @@ export async function cleanupDeletedTemplate(templateFilePath, CONFIG) {
   }
 
   try {
-    const { unlink, rmdir } = await import('fs/promises')
+    const files = projectFiles(rootDir)
 
     // Remove the generated template file
-    await unlink(appTemplatePath)
+    await files.unlink(appTemplatePath)
     log(`Removed generated template: ${appTemplatePath.replace(rootDir, '')}`, 'info')
 
     // Try to remove empty parent directories (but don't fail if they're not empty)
@@ -178,19 +179,21 @@ export async function cleanupDeletedTemplate(templateFilePath, CONFIG) {
 
     while (parentDir !== templatesDir && parentDir !== rootDir) {
       try {
-        const entries = await import('fs/promises').then(fs => fs.readdir(parentDir))
+        const entries = await readdir(parentDir)
         if (entries.length === 0) {
-          await rmdir(parentDir)
+          await files.rmdir(parentDir)
           log(`Removed empty directory: ${parentDir.replace(rootDir, '')}`, 'info')
           parentDir = dirname(parentDir)
         } else {
           break // Directory is not empty, stop cleanup
         }
-      } catch {
+      } catch (error) {
+        if (isUnsafeWrite(error)) throw error
         break // Error reading directory or removing, stop cleanup
       }
     }
   } catch (error) {
+    if (isUnsafeWrite(error)) throw error
     verbose(`Failed to cleanup template file ${appTemplatePath}: ${error.message}`)
   }
 }

package/scripts/build/registry/post-build/test-fixtures.mjs

@@ -7,18 +7,36 @@
  */
 
 import { existsSync } from 'fs'
-import { readFile, writeFile } from 'fs/promises'
+import { readFile } from 'fs/promises'
 import { join, dirname } from 'path'
 import { fileURLToPath } from 'url'
 
 import { log, verbose } from '../../../utils/index.mjs'
-import { CONFIG } from '../config.mjs'
+import { CONFIG as DEFAULT_CONFIG } from '../config.mjs'
+import { projectFiles } from '../../safe-fs.mjs'
 
 const __filename = fileURLToPath(import.meta.url)
 const __dirname = dirname(__filename)
 // Path from packages/core/scripts/build/registry/post-build/ to project root (6 levels up)
 const rootDir = join(__dirname, '../../../../../..')
 
+/**
+ * The directory of the active theme's Cypress fixtures, which the build writes
+ * entities.json and blocks.json into when it exists, and the root those writes
+ * may land under: the project's, or the monorepo's, where the themes of the
+ * monorepo are.
+ *
+ * @param {object} config - Configuration object from getConfig()
+ * @returns {{ fixturesDir: string, root: string } | null} Null when no theme is active
+ */
+export function testFixturesPlace(config) {
+  if (!config.activeTheme) return null
+  return {
+    fixturesDir: join(config.themesDir, config.activeTheme, 'tests', 'cypress', 'fixtures'),
+    root: config.isMonorepoMode ? config.monorepoRoot : config.projectRoot,
+  }
+}
+
 /**
  * Extract test-relevant data from an entity config file using regex
  * @param {string} configPath - Path to the entity config file
@@ -88,7 +106,7 @@ export async function extractEntityTestData(configPath, entityDir) {
  * @param {Array} entities - All discovered entities
  * @param {Array} themes - All discovered themes
  */
-export async function generateTestEntitiesJson(entities, themes) {
+export async function generateTestEntitiesJson(entities, themes, CONFIG = DEFAULT_CONFIG) {
   const activeTheme = CONFIG.activeTheme
   if (!activeTheme) {
     verbose('No active theme set, skipping test fixtures generation')
@@ -103,7 +121,7 @@ export async function generateTestEntitiesJson(entities, themes) {
   }
 
   // Check if tests directory exists
-  const fixturesDir = join(CONFIG.themesDir, activeTheme, 'tests', 'cypress', 'fixtures')
+  const { fixturesDir, root } = testFixturesPlace(CONFIG)
   if (!existsSync(fixturesDir)) {
     verbose(`Test fixtures directory not found for theme "${activeTheme}", skipping`)
     return
@@ -178,7 +196,7 @@ export async function generateTestEntitiesJson(entities, themes) {
 
   // Write the file
   const outputPath = join(fixturesDir, 'entities.json')
-  await writeFile(outputPath, JSON.stringify(jsonContent, null, 2), 'utf8')
+  await projectFiles(root).writeFile(outputPath, JSON.stringify(jsonContent, null, 2), 'utf8')
   log(`entities.json generated for theme "${activeTheme}"`, 'success')
 }
 
@@ -187,7 +205,7 @@ export async function generateTestEntitiesJson(entities, themes) {
  * This file is used by Cypress tests for block-related testing
  * @param {Array} blocks - All discovered blocks
  */
-export async function generateTestBlocksJson(blocks) {
+export async function generateTestBlocksJson(blocks, CONFIG = DEFAULT_CONFIG) {
   const activeTheme = CONFIG.activeTheme
   if (!activeTheme) {
     verbose('No active theme set, skipping blocks.json generation')
@@ -195,7 +213,7 @@ export async function generateTestBlocksJson(blocks) {
   }
 
   // Check if tests directory exists
-  const fixturesDir = join(CONFIG.themesDir, activeTheme, 'tests', 'cypress', 'fixtures')
+  const { fixturesDir, root } = testFixturesPlace(CONFIG)
   if (!existsSync(fixturesDir)) {
     verbose(`Test fixtures directory not found for theme "${activeTheme}", skipping blocks.json`)
     return
@@ -229,6 +247,6 @@ export async function generateTestBlocksJson(blocks) {
   }
 
   const outputPath = join(fixturesDir, 'blocks.json')
-  await writeFile(outputPath, JSON.stringify(jsonContent, null, 2), 'utf8')
+  await projectFiles(root).writeFile(outputPath, JSON.stringify(jsonContent, null, 2), 'utf8')
   log(`blocks.json generated for theme "${activeTheme}" (${blocks.length} blocks)`, 'success')
 }

package/scripts/build/registry/project-mode.mjs

@@ -0,0 +1,76 @@
+/**
+ * How core is installed in a project, told from the project alone: from npm, or
+ * as a package of the NextSpark monorepo. Nothing here reads configuration or
+ * loads a .env, so a check that runs before the build - in the build itself or
+ * in `nextspark` - can ask it.
+ *
+ * @module core/scripts/build/registry/project-mode
+ */
+
+import { existsSync, lstatSync, readlinkSync } from 'fs'
+import { dirname, join } from 'path'
+
+/**
+ * Detect monorepo root by searching for pnpm-workspace.yaml
+ * @param {string} startDir - Directory to start searching from
+ * @returns {string|null} Monorepo root path or null if not in monorepo
+ */
+export function detectMonorepoRoot(startDir = process.cwd()) {
+  let dir = startDir
+  const maxDepth = 10
+  let depth = 0
+
+  while (dir !== '/' && depth < maxDepth) {
+    if (existsSync(join(dir, 'pnpm-workspace.yaml'))) {
+      return dir
+    }
+    dir = dirname(dir)
+    depth++
+  }
+
+  return null
+}
+
+/**
+ * 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 from npm registry
+ */
+export function isInstalledAsPackage(root) {
+  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/ or .pnpmN/ directory, it's a real npm installation via pnpm
+    // The .pnpm/.pnpm2/etc directory is pnpm's content-addressable store
+    if (/\.pnpm\d?[/\\]/.test(linkTarget)) {
+      return true
+    }
+
+    // Otherwise it's a workspace symlink (monorepo development)
+    return false
+  } catch {
+    return false
+  }
+}
+

package/scripts/build/registry/shared/typescript-compiler.mjs

@@ -0,0 +1,77 @@
+/**
+ * TypeScript Compiler Loader
+ *
+ * Resolves the TypeScript 5/6 compiler API a registry build step needs to
+ * read a source file's real syntax tree, shared by every discovery or
+ * generation step that parses TypeScript instead of scanning raw text.
+ *
+ * @module core/scripts/build/registry/shared/typescript-compiler
+ */
+
+import { createRequire } from 'node:module'
+import { join } from 'node:path'
+import { errorWithLines } from '../../../utils/logging.mjs'
+
+/** TypeScript 7's native port doesn't ship the compiler API - its package
+ * exports are `./lib/version.cjs` plus `./unstable/*` - so a candidate module
+ * is checked for the API surface this build needs, not just for existing. */
+function hasCompilerApi(ts) {
+  return Boolean(ts && typeof ts.createSourceFile === 'function' && typeof ts.getScriptKindFromFileName === 'function' && ts.ScriptKind)
+}
+
+/**
+ * Try each TypeScript candidate in order and return the first module whose API this
+ * build needs. A candidate that loads but lacks the API is recorded and the next
+ * one is tried, rather than failing on the first hit - the point of trying more than
+ * one candidate at all.
+ */
+export async function selectTypeScriptModule(candidates) {
+  const rejected = []
+
+  for (const candidate of candidates) {
+    let loaded
+    try {
+      loaded = await candidate.load()
+    } catch (error) {
+      rejected.push(`${candidate.label}: could not be loaded (${error.message})`)
+      continue
+    }
+
+    const ts = loaded?.default ?? loaded
+    if (hasCompilerApi(ts)) {
+      return ts
+    }
+    rejected.push(
+      `${candidate.label}: found TypeScript ${ts?.version ?? 'of an unknown version'}, which does not export the TypeScript 5/6 ` +
+        'compiler API (createSourceFile, getScriptKindFromFileName, ScriptKind) the registry build needs'
+    )
+  }
+
+  throw errorWithLines([
+    'Parsing a source file for the registry build requires the TypeScript 5 or 6 compiler API, but no candidate provided it:',
+    ...rejected.map(reason => `  - ${reason}`),
+  ])
+}
+
+const modulePromises = new Map()
+
+/**
+ * The TypeScript compiler, resolved from core first and then from `projectRoot`:
+ * it is a dependency of core (#195), so it is always found there regardless of
+ * the TypeScript version the project itself has installed; the project is a
+ * fallback for setups where core's own copy is not reachable from the caller's
+ * location on disk. Cached per project root so repeated calls in the same
+ * build don't re-resolve the module.
+ */
+export function loadTypeScriptFor(projectRoot) {
+  if (!modulePromises.has(projectRoot)) {
+    modulePromises.set(
+      projectRoot,
+      selectTypeScriptModule([
+        { label: '@nextsparkjs/core', load: () => import('typescript') },
+        { label: `the project at ${projectRoot}`, load: async () => createRequire(join(projectRoot, 'package.json'))('typescript') },
+      ])
+    )
+  }
+  return modulePromises.get(projectRoot)
+}

package/scripts/build/registry/validate-env.test.mjs

@@ -6,19 +6,23 @@
 
 import { describe, it } from 'node:test'
 import assert from 'node:assert'
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
 import { validateEnvironment } from './config.mjs'
 
 describe('validateEnvironment', () => {
   it('should return valid when .env exists and activeTheme is set', () => {
-    // Use the current working directory which has a .env file
-    const config = {
-      projectRoot: process.cwd(),
-      activeTheme: 'default'
+    const projectRoot = mkdtempSync(join(tmpdir(), 'nextspark-validate-env-test-'))
+
+    try {
+      writeFileSync(join(projectRoot, '.env'), '')
+      const result = validateEnvironment({ projectRoot, activeTheme: 'default' })
+      assert.strictEqual(result.valid, true)
+      assert.strictEqual(result.errors.length, 0)
+    } finally {
+      rmSync(projectRoot, { recursive: true, force: true })
     }
-
-    const result = validateEnvironment(config)
-    assert.strictEqual(result.valid, true)
-    assert.strictEqual(result.errors.length, 0)
   })
 
   it('should return error when .env file is missing', () => {

package/scripts/build/registry/watch.mjs

@@ -9,9 +9,8 @@
 import { existsSync, watch } from 'fs'
 import { join } from 'path'
 
-import { log, verbose } from '../../utils/index.mjs'
+import { log } from '../../utils/index.mjs'
 import { CONFIG } from './config.mjs'
-import { cleanupDeletedTemplate } from './post-build/route-cleanup.mjs'
 
 /**
  * Start watching contents directory for changes
@@ -29,35 +28,6 @@ export async function watchContents(buildRegistries) {
   ]
 
   let debounceTimer = null
-  const templateFileTracker = new Map() // Track existing template files
-
-  // Initialize template file tracker
-  for (const watchPath of watchPaths) {
-    if (existsSync(watchPath) && watchPath.includes('themes')) {
-      const { readdir } = await import('fs/promises')
-      try {
-        const trackTemplates = async (dir, basePath = '') => {
-          const entries = await readdir(dir, { withFileTypes: true })
-          for (const entry of entries) {
-            const fullPath = join(dir, entry.name)
-            const relativePath = join(basePath, entry.name)
-
-            if (entry.isDirectory()) {
-              await trackTemplates(fullPath, relativePath)
-            } else if (entry.isFile() && relativePath.includes('/templates/') &&
-                       (entry.name.endsWith('.tsx') || entry.name.endsWith('.ts'))) {
-              templateFileTracker.set(relativePath, true)
-            }
-          }
-        }
-
-        await trackTemplates(watchPath)
-        verbose(`Tracking ${templateFileTracker.size} template files for deletion detection`)
-      } catch (error) {
-        verbose(`Failed to initialize template tracker: ${error.message}`)
-      }
-    }
-  }
 
   for (const watchPath of watchPaths) {
     if (existsSync(watchPath)) {
@@ -81,7 +51,8 @@ export async function watchContents(buildRegistries) {
           return // Skip rebuild for test artifacts
         }
 
-        // ENHANCED: Handle template deletions before rebuilding
+        // A deleted template needs nothing of its own here: the rebuild leaves its
+        // route out of app/(templates) and backs the old file up.
         const shouldRebuild = !filename || // Always rebuild if filename is null (deletions)
           filename.endsWith('.config.ts') ||
           filename.endsWith('route.ts') ||
@@ -90,27 +61,6 @@ export async function watchContents(buildRegistries) {
           filename.includes('/templates/') || // Any change in templates directory
           eventType === 'rename' // Catch rename events (often deletions)
 
-        // Handle template file deletions
-        if (filename && filename.includes('/templates/') &&
-            (filename.endsWith('.tsx') || filename.endsWith('.ts'))) {
-
-          const fullTemplatePath = join(watchPath, filename)
-          const wasTracked = templateFileTracker.has(filename)
-          const currentlyExists = existsSync(fullTemplatePath)
-
-          // File was deleted (was tracked but no longer exists)
-          if (wasTracked && !currentlyExists) {
-            log(`Template deleted: ${filename}`, 'info')
-            await cleanupDeletedTemplate(fullTemplatePath, CONFIG)
-            templateFileTracker.delete(filename)
-          }
-          // File was added (exists but wasn't tracked)
-          else if (!wasTracked && currentlyExists) {
-            templateFileTracker.set(filename, true)
-            verbose(`Template added to tracker: ${filename}`)
-          }
-        }
-
         if (shouldRebuild) {
           // Debounce rebuilds
           clearTimeout(debounceTimer)