webspresso 0.0.101 → 0.0.103

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (62) hide show
  1. package/.agents/AGENTS.md +1 -1
  2. package/.agents/ARCHITECTURE.md +11 -0
  3. package/.agents/CONVENTIONS.md +4 -0
  4. package/.agents/ORM.md +13 -4
  5. package/.agents/PLUGINS.md +32 -6
  6. package/.agents/ROUTING.md +99 -2
  7. package/.agents/skills/webspresso-framework/SKILL.md +32 -0
  8. package/.agents/skills/webspresso-orm-and-database/SKILL.md +4 -5
  9. package/.agents/skills/webspresso-routing-and-api/SKILL.md +4 -4
  10. package/AGENTS.md +6 -0
  11. package/README.md +20 -7
  12. package/bin/commands/add-tailwind.js +10 -0
  13. package/bin/commands/build.js +34 -0
  14. package/bin/commands/routes.js +8 -0
  15. package/core/applySchema.js +18 -1
  16. package/core/auth/jwt.js +10 -17
  17. package/core/auth/user-agent.js +61 -42
  18. package/core/compression/compression-stream.js +2 -2
  19. package/core/compression/middleware.js +1 -1
  20. package/core/compression/negotiate.js +11 -4
  21. package/core/events/dispatcher.js +56 -33
  22. package/core/openapi/orm-components.js +2 -3
  23. package/core/orm/cache/listeners.js +12 -2
  24. package/core/orm/json-fields.js +7 -1
  25. package/core/orm/model.js +99 -8
  26. package/core/orm/query-builder.js +71 -25
  27. package/core/orm/repository.js +42 -17
  28. package/core/orm/schema-helpers.js +49 -0
  29. package/core/orm/scopes.js +40 -9
  30. package/core/orm/types.js +12 -1
  31. package/core/queue/manager.js +5 -0
  32. package/core/validation/index.js +9 -3
  33. package/index.d.ts +178 -6
  34. package/index.js +71 -16
  35. package/package.json +6 -5
  36. package/plugins/admin-panel/index.js +12 -0
  37. package/plugins/audit-log/middleware.js +39 -4
  38. package/plugins/csrf/index.js +1 -1
  39. package/plugins/email/service.js +32 -1
  40. package/plugins/file-manager/api-handlers.js +10 -17
  41. package/plugins/file-manager/index.js +24 -9
  42. package/plugins/file-manager/security.js +18 -6
  43. package/plugins/index.js +2 -0
  44. package/plugins/lazy.js +258 -0
  45. package/plugins/site-analytics/bot-patterns.js +3 -0
  46. package/plugins/site-analytics/client-error-handler.js +3 -1
  47. package/plugins/site-analytics/index.js +10 -1
  48. package/plugins/site-analytics/tracking.js +245 -46
  49. package/src/api/api-loader.js +18 -2
  50. package/src/api/validation-i18n.js +231 -0
  51. package/src/discovery/route-manifest.js +197 -0
  52. package/src/discovery/scan-routes.js +84 -8
  53. package/src/file-router.js +215 -97
  54. package/src/helpers.js +139 -26
  55. package/src/njk-frontmatter.js +17 -1
  56. package/src/plugin-manager.js +46 -13
  57. package/src/routing/route-table.js +15 -5
  58. package/src/server.js +86 -15
  59. package/src/services/builtins/system.js +4 -6
  60. package/src/services/registry.js +12 -2
  61. package/src/services/validator.js +57 -32
  62. package/src/template/precompile.js +247 -0
package/src/server.js CHANGED
@@ -24,6 +24,8 @@ const { registerClearHook } = require('./njk-frontmatter');
24
24
  const { createPluginManager } = require('./plugin-manager');
25
25
  const { createServiceRegistry } = require('./services');
26
26
  const { scanRoutes } = require('./discovery/scan-routes');
27
+ const { loadRouteManifest } = require('./discovery/route-manifest');
28
+ const { loadPrecompiledTemplates } = require('./template/precompile');
27
29
  const { compileRouteTable } = require('./routing/route-table');
28
30
  const { mountDiscoveredRoutes } = require('./routing/mount-discovered-routes');
29
31
  const { discoverModuleDetails } = require('./modules/module-discovery');
@@ -52,6 +54,19 @@ const {
52
54
  // Async storage for tracking template render call stacks (circular extends guard)
53
55
  const renderStackStorage = new AsyncLocalStorage();
54
56
 
57
+ let isWebspressoPackageCache = null;
58
+ function checkIsWebspressoPackage() {
59
+ if (isWebspressoPackageCache === null) {
60
+ try {
61
+ const pkg = JSON.parse(fs.readFileSync(path.join(process.cwd(), 'package.json'), 'utf8'));
62
+ isWebspressoPackageCache = Boolean(pkg && pkg.name === 'webspresso');
63
+ } catch (_) {
64
+ isWebspressoPackageCache = false;
65
+ }
66
+ }
67
+ return isWebspressoPackageCache;
68
+ }
69
+
55
70
  /**
56
71
  * Fast hardware-accelerated Weak ETag generator using native zlib.crc32
57
72
  * Up to 13x faster than Express default SHA-1, zero external dependencies.
@@ -89,6 +104,7 @@ function fastETag(body, encoding) {
89
104
  */
90
105
  function normalizeTemplateName(name) {
91
106
  if (typeof name !== 'string') return name;
107
+ if (!name.includes('\\') && !name.includes('views')) return name;
92
108
  let normalized = name.replace(/\\/g, '/');
93
109
  // Collapse any repeated views/views/... to a single views/ or clean path
94
110
  while (/(?:^|\/)views\/(?:\.\/)?views(?:\/|$)/.test(normalized)) {
@@ -100,12 +116,20 @@ function normalizeTemplateName(name) {
100
116
  function canonicalTemplateKey(name) {
101
117
  const norm = normalizeTemplateName(name);
102
118
  if (typeof norm !== 'string') return String(norm);
119
+ if (!norm.startsWith('.') && !norm.startsWith('views/')) return norm;
103
120
  // Canonical key strips leading ./ or views/ for cycle detection
104
121
  return norm.replace(/^\.\//, '').replace(/^views\//, '');
105
122
  }
106
123
 
107
124
  function configureSafeNunjucks(templateDirs, options = {}) {
108
125
  const env = nunjucks.configure(templateDirs, options);
126
+ if (options.precompiledLoader && Array.isArray(env.loaders)) {
127
+ options.precompiledLoader.cache = options.precompiledLoader.cache || {};
128
+ env.loaders.unshift(options.precompiledLoader);
129
+ if (typeof env._initLoaders === 'function') {
130
+ env._initLoaders();
131
+ }
132
+ }
109
133
  const origGetTemplate = env.getTemplate.bind(env);
110
134
  const origRender = env.render.bind(env);
111
135
  const origRenderString = env.renderString.bind(env);
@@ -582,10 +606,7 @@ function createApp(options = {}) {
582
606
 
583
607
  const rootDir = options.rootDir || (() => {
584
608
  if (process.env.NODE_ENV === 'test') {
585
- try {
586
- const pkg = JSON.parse(fs.readFileSync(path.join(process.cwd(), 'package.json'), 'utf8'));
587
- if (pkg.name === 'webspresso') return process.cwd();
588
- } catch (_) {}
609
+ if (checkIsWebspressoPackage()) return process.cwd();
589
610
  return path.resolve(__dirname, '..');
590
611
  }
591
612
  return process.cwd();
@@ -699,6 +720,7 @@ function createApp(options = {}) {
699
720
 
700
721
  const app = express();
701
722
  app.serviceRegistry = serviceRegistry;
723
+ app.pluginManager = pluginManager;
702
724
  app.events = eventDispatcher;
703
725
  if (options.queue) {
704
726
  app.queue = options.queue;
@@ -865,9 +887,13 @@ function createApp(options = {}) {
865
887
  for (let i = 0; i < paramNames.length; i++) {
866
888
  const val = match[i + 1];
867
889
  if (val !== undefined) {
868
- try {
869
- params[paramNames[i]] = decodeURIComponent(val);
870
- } catch (_) {
890
+ if (typeof val === 'string' && val.includes('%')) {
891
+ try {
892
+ params[paramNames[i]] = decodeURIComponent(val);
893
+ } catch (_) {
894
+ params[paramNames[i]] = val;
895
+ }
896
+ } else {
871
897
  params[paramNames[i]] = val;
872
898
  }
873
899
  }
@@ -1286,12 +1312,29 @@ function createApp(options = {}) {
1286
1312
  templateDirs.push(path.join(rootDir, 'pages'));
1287
1313
  }
1288
1314
 
1315
+ // Load precompiled Nunjucks templates if enabled or available
1316
+ let precompiledResult = null;
1317
+ const usePrecompiled = options.precompiledTemplates === true ||
1318
+ (typeof options.precompiledTemplates === 'string') ||
1319
+ (options.precompiledTemplates !== false && !isDev);
1320
+
1321
+ if (usePrecompiled) {
1322
+ precompiledResult = loadPrecompiledTemplates({
1323
+ rootDir,
1324
+ bundlePath: typeof options.precompiledTemplates === 'string' ? options.precompiledTemplates : undefined,
1325
+ });
1326
+ if (precompiledResult) {
1327
+ app.precompiledTemplates = precompiledResult.bundle;
1328
+ }
1329
+ }
1330
+
1289
1331
  const nunjucksOpts = options.nunjucks || {};
1290
1332
  const nunjucksEnv = configureSafeNunjucks(templateDirs, {
1291
1333
  autoescape: true,
1292
1334
  express: app,
1293
1335
  watch: isDev && !isTest,
1294
1336
  noCache: nunjucksOpts.noCache ?? (isDev || isTest),
1337
+ precompiledLoader: precompiledResult ? precompiledResult.loader : null,
1295
1338
  ...nunjucksOpts,
1296
1339
  });
1297
1340
 
@@ -1381,13 +1424,35 @@ function createApp(options = {}) {
1381
1424
  app.use(profilerMiddleware);
1382
1425
  }
1383
1426
 
1384
- // 1. Scan and compile discovered routes (src/pages, src/api, modules/*)
1385
- const discoveredDescriptors = scanRoutes({
1386
- rootDir,
1387
- pages: options.pages !== undefined ? options.pages : (options.pagesDir ? { dir: options.pagesDir } : true),
1388
- api: options.api,
1389
- modules: options.modules,
1390
- });
1427
+ // 1. Scan and compile discovered routes (AOT route manifest or disk scan)
1428
+ let discoveredDescriptors = null;
1429
+ let loadedManifest = null;
1430
+
1431
+ // In production (or when explicitly requested/enabled via options.routesManifest), attempt loading AOT manifest
1432
+ const useManifest = options.routesManifest === true ||
1433
+ (typeof options.routesManifest === 'string') ||
1434
+ (options.routesManifest !== false && !isDev);
1435
+
1436
+ if (useManifest) {
1437
+ const manifestResult = loadRouteManifest({
1438
+ rootDir,
1439
+ manifestPath: typeof options.routesManifest === 'string' ? options.routesManifest : undefined,
1440
+ });
1441
+ if (manifestResult) {
1442
+ discoveredDescriptors = manifestResult.descriptors;
1443
+ loadedManifest = manifestResult.manifest;
1444
+ app.routesManifest = loadedManifest;
1445
+ }
1446
+ }
1447
+
1448
+ if (!discoveredDescriptors) {
1449
+ discoveredDescriptors = scanRoutes({
1450
+ rootDir,
1451
+ pages: options.pages !== undefined ? options.pages : (options.pagesDir ? { dir: options.pagesDir } : true),
1452
+ api: options.api,
1453
+ modules: options.modules,
1454
+ });
1455
+ }
1391
1456
 
1392
1457
  const routeTable = compileRouteTable(discoveredDescriptors, {
1393
1458
  explicitRoutes: options.routes || [],
@@ -1495,12 +1560,18 @@ function createApp(options = {}) {
1495
1560
  options,
1496
1561
  });
1497
1562
 
1498
- // 2. Mount classic file-based routes for backwards compatibility
1563
+ // 2. Mount classic file-based routes for backwards compatibility (reuses pre-scanned files from discovery)
1499
1564
  let classicRouteMeta = [];
1500
1565
  let registerDynamicFileRoutes = () => {};
1501
1566
  if (pagesDir && fs.existsSync(path.resolve(pagesDir))) {
1567
+ const resolvedPagesDir = path.resolve(pagesDir);
1568
+ const scannedFiles = (discoveredDescriptors && discoveredDescriptors.scannedPagesDir === resolvedPagesDir)
1569
+ ? discoveredDescriptors.scannedPagesFiles
1570
+ : null;
1571
+
1502
1572
  const classicMount = mountPages(app, {
1503
1573
  pagesDir,
1574
+ scannedFiles,
1504
1575
  nunjucks: nunjucksEnv,
1505
1576
  middlewares,
1506
1577
  pluginManager,
@@ -4,8 +4,6 @@
4
4
  */
5
5
 
6
6
  const os = require('os');
7
- const { z } = require('zod');
8
- const { cleanExpiredTokens, createKnexAuthTokensAdapter } = require('../../../core/auth/tokens');
9
7
 
10
8
  /**
11
9
  * Format memory usage bytes into human-readable MB
@@ -29,7 +27,7 @@ function createSystemServices(options = {}) {
29
27
 
30
28
  return {
31
29
  'system.health': {
32
- schema: z.object({
30
+ schema: ({ z }) => z.object({
33
31
  detailed: z.boolean().default(false),
34
32
  }),
35
33
  async handler(input, ctx) {
@@ -81,7 +79,7 @@ function createSystemServices(options = {}) {
81
79
  },
82
80
 
83
81
  'system.cleanup': {
84
- schema: z.object({
82
+ schema: ({ z }) => z.object({
85
83
  olderThanDays: z.number().int().positive().default(90),
86
84
  purgeAuthTokens: z.boolean().default(true),
87
85
  purgeAuditLogs: z.boolean().default(true),
@@ -138,7 +136,7 @@ function createSystemServices(options = {}) {
138
136
  },
139
137
 
140
138
  'system.cache-flush': {
141
- schema: z.object({
139
+ schema: ({ z }) => z.object({
142
140
  scope: z.enum(['all', 'orm', 'services']).default('all'),
143
141
  model: z.string().optional(),
144
142
  }),
@@ -182,7 +180,7 @@ function createSystemServices(options = {}) {
182
180
  },
183
181
 
184
182
  'system.info': {
185
- schema: z.object({}),
183
+ schema: ({ z }) => z.object({}),
186
184
  auth: 'admin',
187
185
  async handler(input, ctx) {
188
186
  const activeDb = ctx.db || db;
@@ -125,12 +125,12 @@ class ServiceRegistry {
125
125
  * @param {Object|Function} definition - Service definition or handler function
126
126
  * @returns {ServiceRegistry}
127
127
  */
128
- register(name, definition) {
128
+ register(name, definition, options = {}) {
129
129
  if (!name || typeof name !== 'string') {
130
130
  throw new WebspressoError('Service name must be a non-empty string');
131
131
  }
132
132
 
133
- if (this.services.has(name)) {
133
+ if (this.services.has(name) && !options.overwrite) {
134
134
  throw new ConfigurationError(`Duplicate service registered: ${name}`);
135
135
  }
136
136
 
@@ -170,6 +170,16 @@ class ServiceRegistry {
170
170
  return this;
171
171
  }
172
172
 
173
+ /**
174
+ * Unregister a service by name
175
+ * @param {string} name - Service name
176
+ * @returns {boolean} Whether service was found and removed
177
+ */
178
+ unregister(name) {
179
+ if (!name || typeof name !== 'string') return false;
180
+ return this.services.delete(name);
181
+ }
182
+
173
183
  /**
174
184
  * Get a service definition by name or alias
175
185
  * @param {string} name - Service name
@@ -8,12 +8,17 @@ const { ValidationError } = require('../../core/errors');
8
8
  const { z: zForServices, sanitizeInput, hasDangerousKeys } = require('../../core/validation');
9
9
  const z = zForServices;
10
10
 
11
+ const descriptorCache = new Map();
12
+
11
13
  /**
12
14
  * Compile a concise type string descriptor into a Zod schema
13
15
  * @param {string} typeName - Type name descriptor (e.g. 'number', 'string', 'email', 'string?')
14
16
  * @returns {z.ZodTypeAny}
15
17
  */
16
18
  function descriptorToZod(typeName) {
19
+ const cached = descriptorCache.get(typeName);
20
+ if (cached) return cached;
21
+
17
22
  const isOptional = typeName.endsWith('?');
18
23
  const baseType = isOptional ? typeName.slice(0, -1).toLowerCase() : typeName.toLowerCase();
19
24
 
@@ -60,9 +65,15 @@ function descriptorToZod(typeName) {
60
65
  break;
61
66
  }
62
67
 
63
- return isOptional ? schema.optional() : schema;
68
+ const finalSchema = isOptional ? schema.optional() : schema;
69
+ if (descriptorCache.size < 200) {
70
+ descriptorCache.set(typeName, finalSchema);
71
+ }
72
+ return finalSchema;
64
73
  }
65
74
 
75
+ const compiledSchemaCache = new WeakMap();
76
+
66
77
  /**
67
78
  * Compile service schema definition into an executable validator
68
79
  * @param {Function|Object|null} rawSchema - Schema definition
@@ -71,50 +82,64 @@ function descriptorToZod(typeName) {
71
82
  function compileServiceSchema(rawSchema) {
72
83
  if (!rawSchema) return null;
73
84
 
74
- // If already a Zod schema
75
- if (rawSchema instanceof z.ZodType || typeof rawSchema.safeParse === 'function') {
76
- return rawSchema;
85
+ if (typeof rawSchema === 'object' || typeof rawSchema === 'function') {
86
+ const cached = compiledSchemaCache.get(rawSchema);
87
+ if (cached !== undefined) {
88
+ return cached;
89
+ }
77
90
  }
78
91
 
79
- // If function: check if ({ z }) schema compiler or custom validator function
80
- if (typeof rawSchema === 'function') {
92
+ let compiled = null;
93
+
94
+ // If already a Zod schema
95
+ if (rawSchema instanceof z.ZodType || typeof rawSchema.safeParse === 'function') {
96
+ compiled = rawSchema;
97
+ } else if (typeof rawSchema === 'function') {
98
+ // If function: check if ({ z }) schema compiler or custom validator function
81
99
  try {
82
- const compiled = rawSchema({ z: zForServices });
83
- if (compiled && (compiled instanceof z.ZodType || typeof compiled.safeParse === 'function')) {
84
- return compiled;
100
+ const res = rawSchema({ z: zForServices });
101
+ if (res && (res instanceof z.ZodType || typeof res.safeParse === 'function')) {
102
+ compiled = res;
85
103
  }
86
104
  } catch (e) {
87
105
  // If invoking with { z } throws, treat as a direct validator function
88
106
  }
89
- return rawSchema;
90
- }
91
-
92
- // If object descriptor: { id: 'number', name: 'string', email: 'email' }
93
- if (typeof rawSchema === 'object' && rawSchema !== null) {
107
+ if (!compiled) {
108
+ compiled = rawSchema;
109
+ }
110
+ } else if (typeof rawSchema === 'object' && rawSchema !== null) {
111
+ // If object descriptor: { id: 'number', name: 'string', email: 'email' }
94
112
  const keys = Object.keys(rawSchema);
95
113
  if (keys.length === 0) {
96
- return null;
97
- }
98
- const shape = {};
99
- for (const [key, val] of Object.entries(rawSchema)) {
100
- if (typeof val === 'string') {
101
- shape[key] = descriptorToZod(val);
102
- } else if (val instanceof z.ZodType || (val && typeof val.safeParse === 'function')) {
103
- shape[key] = val;
104
- } else if (typeof val === 'object' && val !== null) {
105
- const isOpt = val.optional === true || val.required === false;
106
- let base = val.type ? descriptorToZod(String(val.type)) : z.any();
107
- shape[key] = isOpt ? base.optional() : base;
108
- } else if (typeof val === 'function') {
109
- shape[key] = z.custom(val);
110
- } else {
111
- shape[key] = z.any();
114
+ compiled = null;
115
+ } else {
116
+ const shape = {};
117
+ for (const [key, val] of Object.entries(rawSchema)) {
118
+ if (typeof val === 'string') {
119
+ shape[key] = descriptorToZod(val);
120
+ } else if (val instanceof z.ZodType || (val && typeof val.safeParse === 'function')) {
121
+ shape[key] = val;
122
+ } else if (typeof val === 'object' && val !== null) {
123
+ const isOpt = val.optional === true || val.required === false;
124
+ let base = val.type ? descriptorToZod(String(val.type)) : z.any();
125
+ shape[key] = isOpt ? base.optional() : base;
126
+ } else if (typeof val === 'function') {
127
+ shape[key] = z.custom(val);
128
+ } else {
129
+ shape[key] = z.any();
130
+ }
112
131
  }
132
+ compiled = z.object(shape);
113
133
  }
114
- return z.object(shape);
134
+ } else {
135
+ compiled = rawSchema;
136
+ }
137
+
138
+ if (typeof rawSchema === 'object' || typeof rawSchema === 'function') {
139
+ compiledSchemaCache.set(rawSchema, compiled);
115
140
  }
116
141
 
117
- return rawSchema;
142
+ return compiled;
118
143
  }
119
144
 
120
145
  /**
@@ -0,0 +1,247 @@
1
+ 'use strict';
2
+
3
+ /**
4
+ * Webspresso - Nunjucks Template Pre-compiler & AOT Bundle
5
+ * Pre-compiles Nunjucks templates into zero-parse, pure JavaScript functions to
6
+ * eliminate disk reading and AST tokenization/parsing overhead during SSR.
7
+ * @module src/template/precompile
8
+ */
9
+
10
+ const fs = require('fs');
11
+ const path = require('path');
12
+ const nunjucks = require('nunjucks');
13
+ const { parseNjkFrontmatter, frontmatterToPatches, seedProdRouteCache } = require('../njk-frontmatter');
14
+
15
+ const DEFAULT_PRECOMPILED_REL_PATH = path.join('.webspresso', 'templates.compiled.js');
16
+
17
+ /**
18
+ * Recursively scans a directory for template files (.njk, .html).
19
+ * @param {string} dir
20
+ * @param {string} [baseDir=dir]
21
+ * @returns {Array<{ absolutePath: string, relativePath: string }>}
22
+ */
23
+ function scanTemplateDir(dir, baseDir = dir) {
24
+ if (!fs.existsSync(dir)) return [];
25
+ const entries = fs.readdirSync(dir, { withFileTypes: true });
26
+ const results = [];
27
+
28
+ for (const entry of entries) {
29
+ const full = path.join(dir, entry.name);
30
+ if (entry.isDirectory()) {
31
+ if (entry.name.startsWith('.') || entry.name === 'node_modules') continue;
32
+ results.push(...scanTemplateDir(full, baseDir));
33
+ } else if (entry.isFile()) {
34
+ const ext = path.extname(entry.name);
35
+ if (ext === '.njk' || ext === '.html') {
36
+ const rel = path.relative(baseDir, full).split(path.sep).join('/');
37
+ results.push({ absolutePath: full, relativePath: rel });
38
+ }
39
+ }
40
+ }
41
+
42
+ return results;
43
+ }
44
+
45
+ /**
46
+ * Normalizes a template name for uniform lookup.
47
+ * @param {string} name
48
+ * @returns {string}
49
+ */
50
+ function normalizeTemplateKey(name) {
51
+ if (typeof name !== 'string') return '';
52
+ return name.replace(/\\/g, '/').replace(/^\.\//, '').replace(/^views\//, '');
53
+ }
54
+
55
+ /**
56
+ * Precompiles all Nunjucks templates in views/ and pages/ directories into an AOT bundle.
57
+ *
58
+ * @param {Object} [options={}]
59
+ * @param {string} [options.rootDir=process.cwd()] - Project root directory
60
+ * @param {string} [options.viewsDir] - Custom views directory path
61
+ * @param {string} [options.pagesDir] - Custom pages directory path
62
+ * @param {string} [options.outDir] - Directory where precompiled bundle is written
63
+ * @param {string} [options.outFile] - Custom output file path
64
+ * @param {import('nunjucks').Environment} [options.env] - Optional Nunjucks Environment
65
+ * @returns {{ templateCount: number, manifestPath: string, bundle: Object }}
66
+ */
67
+ function precompileTemplates(options = {}) {
68
+ const rootDir = options.rootDir ? path.resolve(options.rootDir) : process.cwd();
69
+ const viewsDir = options.viewsDir ? path.resolve(options.viewsDir) : path.join(rootDir, 'views');
70
+ const pagesDir = options.pagesDir ? path.resolve(options.pagesDir) : path.join(rootDir, 'pages');
71
+
72
+ const env = options.env || new nunjucks.Environment([], { autoescape: true });
73
+
74
+ const templates = {};
75
+ const frontmatter = {};
76
+ const processedKeys = new Set();
77
+
78
+ const dirsToScan = [
79
+ { dir: viewsDir, prefix: '', isViews: true },
80
+ { dir: pagesDir, prefix: '', isPages: true },
81
+ ];
82
+
83
+ for (const { dir, isViews } of dirsToScan) {
84
+ if (!fs.existsSync(dir)) continue;
85
+ const files = scanTemplateDir(dir);
86
+
87
+ for (const file of files) {
88
+ try {
89
+ const raw = fs.readFileSync(file.absolutePath, 'utf8');
90
+ const { body, fm, hasDelimiter } = parseNjkFrontmatter(raw);
91
+ const patches = frontmatterToPatches(fm);
92
+
93
+ const relToRoot = path.relative(rootDir, file.absolutePath).split(path.sep).join('/');
94
+ frontmatter[relToRoot] = {
95
+ useStringRender: false,
96
+ templateBody: null,
97
+ metaPatch: patches.metaPatch,
98
+ dataPatch: patches.dataPatch,
99
+ };
100
+
101
+ const compiledArray = nunjucks.precompileString(body, {
102
+ name: file.relativePath,
103
+ asFunction: false,
104
+ env,
105
+ wrapper: (items) => items,
106
+ });
107
+
108
+ if (compiledArray && compiledArray[0] && compiledArray[0].template) {
109
+ const code = compiledArray[0].template;
110
+ templates[file.relativePath] = code;
111
+
112
+ // Also register canonical stripped name for views
113
+ const normalized = normalizeTemplateKey(file.relativePath);
114
+ if (normalized !== file.relativePath) {
115
+ templates[normalized] = code;
116
+ }
117
+ if (isViews && !file.relativePath.startsWith('views/')) {
118
+ templates[`views/${file.relativePath}`] = code;
119
+ }
120
+
121
+ processedKeys.add(file.relativePath);
122
+ }
123
+ } catch (err) {
124
+ console.warn(`[webspresso] Failed to precompile template "${file.relativePath}":`, err.message);
125
+ }
126
+ }
127
+ }
128
+
129
+ const bundle = {
130
+ version: 1,
131
+ generatedAt: new Date().toISOString(),
132
+ templates,
133
+ frontmatter,
134
+ };
135
+
136
+ const outFile = options.outFile
137
+ ? path.resolve(options.outFile)
138
+ : (options.outDir
139
+ ? path.join(path.resolve(options.outDir), 'templates.compiled.js')
140
+ : path.join(rootDir, DEFAULT_PRECOMPILED_REL_PATH));
141
+
142
+ const outDir = path.dirname(outFile);
143
+ if (!fs.existsSync(outDir)) {
144
+ fs.mkdirSync(outDir, { recursive: true });
145
+ }
146
+
147
+ const fileContent = `/**
148
+ * Webspresso Precompiled Nunjucks Templates Bundle
149
+ * Generated: ${bundle.generatedAt}
150
+ * Total Templates: ${processedKeys.size}
151
+ */
152
+ module.exports = ${JSON.stringify(bundle, null, 2)};
153
+ `;
154
+
155
+ fs.writeFileSync(outFile, fileContent, 'utf8');
156
+
157
+ return {
158
+ templateCount: processedKeys.size,
159
+ manifestPath: outFile,
160
+ bundle,
161
+ };
162
+ }
163
+
164
+ /**
165
+ * Loads precompiled templates bundle from disk and constructs a PrecompiledLoader.
166
+ *
167
+ * @param {Object} [options={}]
168
+ * @param {string} [options.rootDir=process.cwd()] - Project root directory
169
+ * @param {string} [options.bundlePath] - Custom bundle file path
170
+ * @returns {{ loader: import('nunjucks').PrecompiledLoader, templateCount: number, bundle: Object }|null}
171
+ */
172
+ function loadPrecompiledTemplates(options = {}) {
173
+ const rootDir = options.rootDir ? path.resolve(options.rootDir) : process.cwd();
174
+ const bundlePath = options.bundlePath
175
+ ? path.resolve(options.bundlePath)
176
+ : path.join(rootDir, DEFAULT_PRECOMPILED_REL_PATH);
177
+
178
+ if (!fs.existsSync(bundlePath)) {
179
+ return null;
180
+ }
181
+
182
+ try {
183
+ // Delete require cache in case bundle was updated
184
+ if (require.cache[require.resolve(bundlePath)]) {
185
+ delete require.cache[require.resolve(bundlePath)];
186
+ }
187
+
188
+ const bundle = require(bundlePath);
189
+ if (!bundle || typeof bundle.templates !== 'object') {
190
+ return null;
191
+ }
192
+
193
+ const compiledMap = {};
194
+ for (const [name, code] of Object.entries(bundle.templates)) {
195
+ try {
196
+ compiledMap[name] = (new Function(code))();
197
+ } catch (compileErr) {
198
+ console.warn(`[webspresso] Failed to evaluate precompiled template "${name}":`, compileErr.message);
199
+ }
200
+ }
201
+
202
+ // Hydrate frontmatter cache for instant loadNjkRouteTemplate execution
203
+ if (bundle.frontmatter && typeof bundle.frontmatter === 'object') {
204
+ const absMap = {};
205
+ for (const [relPath, fmData] of Object.entries(bundle.frontmatter)) {
206
+ absMap[path.resolve(rootDir, relPath)] = fmData;
207
+ }
208
+ seedProdRouteCache(absMap);
209
+ }
210
+
211
+ const loader = new nunjucks.PrecompiledLoader(compiledMap);
212
+ loader.cache = {};
213
+ const origGetSource = loader.getSource.bind(loader);
214
+
215
+ loader.getSource = function(name) {
216
+ if (this.precompiled[name]) {
217
+ return {
218
+ src: { type: 'code', obj: this.precompiled[name] },
219
+ path: name,
220
+ };
221
+ }
222
+ const clean = normalizeTemplateKey(name);
223
+ if (this.precompiled[clean]) {
224
+ return {
225
+ src: { type: 'code', obj: this.precompiled[clean] },
226
+ path: clean,
227
+ };
228
+ }
229
+ return null;
230
+ };
231
+
232
+ return {
233
+ loader,
234
+ templateCount: Object.keys(compiledMap).length,
235
+ bundle,
236
+ };
237
+ } catch (err) {
238
+ return null;
239
+ }
240
+ }
241
+
242
+ module.exports = {
243
+ DEFAULT_PRECOMPILED_REL_PATH,
244
+ precompileTemplates,
245
+ loadPrecompiledTemplates,
246
+ normalizeTemplateKey,
247
+ };