@zeropress/build-core 0.1.10 → 0.1.12

package/README.md

@@ -4,7 +4,7 @@
 ![license](https://img.shields.io/npm/l/%40zeropress%2Fbuild-core)
 ![node](https://img.shields.io/node/v/%40zeropress%2Fbuild-core)
 
-Shared build and partial-render core for ZeroPress.
+Shared build core for ZeroPress.
 
 This package is the deterministic rendering engine used by:
 
@@ -33,7 +33,6 @@ npm install @zeropress/build-core
 ```js
 import {
   buildSite,
-  buildSelectedRoutes,
   buildSiteFromThemeDir,
   MemoryWriter,
   FilesystemWriter,
@@ -123,47 +122,6 @@ Notes:
 - `sitemap.xml` and `feed.xml` are emitted only when `site.url` is a non-empty canonical URL
 - `robots.txt` and `meta.json` are still emitted when `generateSpecialFiles` is enabled
 
-### `buildSelectedRoutes(input)`
-
-Renders only selected post and list routes while preserving full-build parity for those outputs.
-
-This is intended for targeted rebuilds, output parity checks, and other partial-render workflows.
-
-Current selection scope is limited to:
-
-- post detail routes
-- index pagination routes
-- archive routes
-- category routes
-- tag routes
-
-It does not currently support selecting individual page routes.
-
-Optional route templates are respected during both full and partial renders:
-
-- missing `archive.html` skips archive outputs
-- missing `category.html` skips category outputs
-- missing `tag.html` skips tag outputs
-- missing `404.html` skips `404.html` emission
-
-These cases do not fail the build.
-
-```js
-await buildSelectedRoutes({
-  previewData,
-  themePackage,
-  writer,
-  selection: {
-    posts: ['hello-zeropress'],
-    indexRoutes: ['/'],
-    archiveRoutes: ['/archive/'],
-    categoryRoutes: ['/categories/general/'],
-    tagRoutes: ['/tags/intro/'],
-    includeAssets: false,
-  },
-});
-```
-
 ### `buildSiteFromThemeDir(input)`
 
 Loads a theme directory from disk and renders it using the same core pipeline.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@zeropress/build-core",
-  "version": "0.1.10",
-  "description": "Shared ZeroPress build and partial-render core",
+  "version": "0.1.12",
+  "description": "Shared ZeroPress build core",
   "type": "module",
   "license": "MIT",
   "exports": {
@@ -33,8 +33,9 @@
     "node": ">=18.18.0"
   },
   "dependencies": {
-    "@zeropress/preview-data-validator": "^0.4.0",
-    "@zeropress/theme-validator": "^0.2.4",
+    "@zeropress/slug-policy": "^0.1.0",
+    "@zeropress/preview-data-validator": "^0.4.1",
+    "@zeropress/theme-validator": "^0.3.0",
     "highlight.js": "^11.11.1",
     "markdown-it": "^14.1.0",
     "markdown-it-anchor": "^9.2.0"

package/src/api/build-site.js

@@ -1,5 +1,6 @@
 import { createHash } from 'node:crypto';
 import { assertPreviewData } from '@zeropress/preview-data-validator';
+import { isSafeSlugSegment, normalizeStoredSlug } from '@zeropress/slug-policy';
 import { validateThemeFiles } from '@zeropress/theme-validator';
 import { AssetProcessor } from '../assets/asset-processor.js';
 import { renderDocumentContent } from '../render/content-renderer.js';
@@ -17,9 +18,11 @@ const DEFAULT_DATE_FORMAT = 'YYYY-MM-DD';
 const DEFAULT_TIME_FORMAT = 'HH:mm';
 const DEFAULT_TIMEZONE = 'UTC';
 const DEFAULT_LOCALE = 'en-US';
+const OUTPUT_PATH_CONTROL_CHAR_PATTERN = /[\u0000-\u001F\u007F]/;
 export async function buildSite(input) {
   const options = { ...DEFAULT_OPTIONS, ...(input.options || {}) };
   const state = await createBuildState(input, options);
+  assertPlannedOutputPathsSafe(state);
 
   for (const route of state.renderData.indexRoutes) {
     await renderRoute(state, 'index', route);
@@ -68,62 +71,6 @@ export async function buildSite(input) {
   return finalizeBuildResult(state.writer, state.summaries, options);
 }
 
-export async function buildSelectedRoutes(input) {
-  const options = { ...DEFAULT_OPTIONS, ...(input.options || {}) };
-  validateSelection(input.selection);
-
-  const state = await createBuildState(input, options);
-  const selectedPostSlugs = new Set((input.selection.posts || []).map((slug) => String(slug)));
-  const selectedIndexRoutes = new Set((input.selection.indexRoutes || []).map((route) => normalizeRoutePath(route)));
-  const selectedArchiveRoutes = new Set((input.selection.archiveRoutes || []).map((route) => normalizeRoutePath(route)));
-  const selectedCategoryRoutes = new Set((input.selection.categoryRoutes || []).map((route) => normalizeRoutePath(route)));
-  const selectedTagRoutes = new Set((input.selection.tagRoutes || []).map((route) => normalizeRoutePath(route)));
-
-  for (const post of state.renderData.posts) {
-    if (selectedPostSlugs.has(post.slug)) {
-      await renderPost(state, post);
-    }
-  }
-
-  for (const route of state.renderData.indexRoutes) {
-    if (selectedIndexRoutes.has(normalizeRoutePath(route.path))) {
-      await renderRoute(state, 'index', route);
-    }
-  }
-
-  if (hasTemplate(state, 'archive')) {
-    for (const route of state.renderData.archiveRoutes) {
-      if (selectedArchiveRoutes.has(normalizeRoutePath(route.path))) {
-        await renderRoute(state, 'archive', route);
-      }
-    }
-  }
-
-  if (hasTemplate(state, 'category')) {
-    for (const route of state.renderData.categoryRoutes) {
-      if (selectedCategoryRoutes.has(normalizeRoutePath(route.path))) {
-        await renderRoute(state, 'category', route);
-      }
-    }
-  }
-
-  if (hasTemplate(state, 'tag')) {
-    for (const route of state.renderData.tagRoutes) {
-      if (selectedTagRoutes.has(normalizeRoutePath(route.path))) {
-        await renderRoute(state, 'tag', route);
-      }
-    }
-  }
-
-  if (input.selection.includeAssets) {
-    for (const assetOutput of state.assetOutputs) {
-      await writeOutput(state.writer, state.summaries, assetOutput.path, assetOutput.content, assetOutput.contentType);
-    }
-  }
-
-  return finalizeBuildResult(state.writer, state.summaries, options);
-}
-
 async function createBuildState(input, options) {
   if (!input?.writer || typeof input.writer.write !== 'function') {
     throw new Error('buildSite requires a writer with an async write(file) method');
@@ -194,6 +141,7 @@ async function renderRoute(state, templateName, route) {
   let html = await state.engine.render(
     templateName,
     {
+      menus: state.previewData.menus,
       ...route,
       meta: buildPageMeta(state.previewData.site, {
         currentUrl,
@@ -214,6 +162,7 @@ async function renderPost(state, post) {
   let html = await state.engine.render(
     'post',
     {
+      menus: state.previewData.menus,
       post,
       meta: buildPageMeta(state.previewData.site, {
         currentUrl,
@@ -247,6 +196,7 @@ async function renderPage(state, page) {
   let html = await state.engine.render(
     'page',
     {
+      menus: state.previewData.menus,
       page,
       meta: buildPageMeta(state.previewData.site, {
         currentUrl,
@@ -276,6 +226,7 @@ async function maybeRenderNotFoundPage(state) {
   let html = await state.engine.render(
     '404',
     {
+      menus: state.previewData.menus,
       meta: buildPageMeta(state.previewData.site, {
         currentUrl: '/404.html',
         title: state.previewData.site.title,
@@ -289,23 +240,6 @@ async function maybeRenderNotFoundPage(state) {
   await writeOutput(state.writer, state.summaries, '404.html', html, 'text/html');
 }
 
-function validateSelection(selection) {
-  if (!selection || typeof selection !== 'object') {
-    throw new Error('buildSelectedRoutes requires a selection object');
-  }
-
-  const keys = ['posts', 'indexRoutes', 'archiveRoutes', 'categoryRoutes', 'tagRoutes'];
-  for (const key of keys) {
-    if (!Array.isArray(selection[key])) {
-      throw new Error(`buildSelectedRoutes selection.${key} must be an array`);
-    }
-  }
-
-  if (typeof selection.includeAssets !== 'boolean') {
-    throw new Error('buildSelectedRoutes selection.includeAssets must be a boolean');
-  }
-}
-
 function normalizePreviewData(previewData) {
   const normalizedSite = {
     ...previewData.site,
@@ -1028,7 +962,9 @@ function isAbsoluteUrl(value) {
 }
 
 async function writeOutput(writer, summaries, path, content, contentType) {
-  const normalizedPath = normalizeOutputPath(path);
+  const rawPath = String(path || '');
+  const normalizedPath = normalizeOutputPath(rawPath);
+  assertSafeRelativeOutputPath(rawPath, normalizedPath);
   await writer.write({ path: normalizedPath, content, contentType });
   summaries.push({
     path: normalizedPath,
@@ -1058,6 +994,95 @@ function normalizeOutputPath(filePath) {
   return String(filePath || '').replace(/^\/+/, '');
 }
 
+function assertPlannedOutputPathsSafe(state) {
+  for (const post of state.renderData.posts) {
+    assertSafeSlugDerivedOutputPath(post.slug, `posts/${encodeSlugSegment(post.slug)}/index.html`);
+  }
+
+  for (const page of state.renderData.pages) {
+    assertSafeSlugDerivedOutputPath(page.slug, `${encodeSlugSegment(page.slug)}/index.html`);
+  }
+
+  for (const category of state.previewData.content.categories) {
+    assertSafeSlugDerivedOutputPath(category.slug, `categories/${encodeSlugSegment(category.slug)}/index.html`);
+  }
+
+  for (const tag of state.previewData.content.tags) {
+    assertSafeSlugDerivedOutputPath(tag.slug, `tags/${encodeSlugSegment(tag.slug)}/index.html`);
+  }
+
+  const plannedPaths = [
+    ...state.renderData.indexRoutes.map((route) => routePathToOutputPath(route.path)),
+    ...state.renderData.archiveRoutes.map((route) => routePathToOutputPath(route.path)),
+    ...state.renderData.categoryRoutes.map((route) => routePathToOutputPath(route.path)),
+    ...state.renderData.tagRoutes.map((route) => routePathToOutputPath(route.path)),
+    ...state.renderData.posts.map((post) => `posts/${encodeSlugSegment(post.slug)}/index.html`),
+    ...state.renderData.pages.map((page) => `${encodeSlugSegment(page.slug)}/index.html`),
+    ...state.assetOutputs.map((assetOutput) => assetOutput.path),
+  ];
+
+  if (state.options.generateSpecialFiles) {
+    plannedPaths.push('404.html', 'robots.txt', 'meta.json');
+    if (hasCanonicalSiteUrl(state.previewData.site.url)) {
+      plannedPaths.push('sitemap.xml', 'feed.xml');
+    }
+  }
+
+  for (const plannedPath of plannedPaths) {
+    const rawPath = String(plannedPath || '');
+    const normalizedPath = normalizeOutputPath(rawPath);
+    assertSafeRelativeOutputPath(rawPath, normalizedPath);
+  }
+}
+
+function assertSafeSlugDerivedOutputPath(rawSlug, outputPath) {
+  const originalSlug = typeof rawSlug === 'string' ? rawSlug : '';
+  const decodedSlug = encodeSlugSegment(rawSlug);
+
+  if (
+    !isSafeSlugPathSegment(originalSlug) ||
+    !isSafeSlugPathSegment(decodedSlug)
+  ) {
+    throw new Error(`Unsafe output path detected: ${outputPath}`);
+  }
+}
+
+function isSafeSlugPathSegment(value) {
+  return isSafeSlugSegment(value);
+}
+
+function assertSafeRelativeOutputPath(rawPath, normalizedPath = normalizeOutputPath(rawPath)) {
+  const originalPath = String(rawPath || '');
+  const candidatePath = String(normalizedPath || '');
+  const normalizedSeparators = candidatePath.replace(/\\/g, '/');
+
+  if (originalPath.trim() === '' || candidatePath.trim() === '') {
+    throw new Error(`Unsafe output path detected: ${originalPath || candidatePath || '<empty>'}`);
+  }
+
+  if (OUTPUT_PATH_CONTROL_CHAR_PATTERN.test(originalPath) || OUTPUT_PATH_CONTROL_CHAR_PATTERN.test(candidatePath)) {
+    throw new Error(`Unsafe output path detected: ${originalPath}`);
+  }
+
+  if (candidatePath.includes('%')) {
+    throw new Error(`Unsafe output path detected: ${originalPath}`);
+  }
+
+  if (
+    originalPath.startsWith('/') ||
+    originalPath.startsWith('\\') ||
+    /^[A-Za-z]:[\\/]/.test(originalPath) ||
+    normalizedSeparators.startsWith('//')
+  ) {
+    throw new Error(`Unsafe output path detected: ${originalPath}`);
+  }
+
+  const segments = normalizedSeparators.split('/');
+  if (segments.some((segment) => segment === '' || segment === '.' || segment === '..')) {
+    throw new Error(`Unsafe output path detected: ${originalPath}`);
+  }
+}
+
 function getContentSize(content) {
   return typeof content === 'string' ? Buffer.byteLength(content) : content.byteLength;
 }
@@ -1189,23 +1214,6 @@ function encodeSlugSegment(slug) {
   return normalizeStoredSlug(slug);
 }
 
-function normalizeStoredSlug(slug) {
-  if (typeof slug !== 'string') {
-    return '';
-  }
-
-  const trimmed = slug.trim();
-  if (!trimmed.includes('%')) {
-    return trimmed;
-  }
-
-  try {
-    return decodeURIComponent(trimmed);
-  } catch {
-    return trimmed;
-  }
-}
-
 function decodeRoutePath(routePath) {
   try {
     return decodeURI(routePath);

package/src/index.d.ts

@@ -8,10 +8,14 @@ export interface ThemePackage {
     description?: string;
     thumbnail?: string;
     settings?: Record<string, unknown>;
+    menuSlots?: Record<string, {
+      title: string;
+      description?: string;
+    }>;
     namespace?: string;
     slug?: string;
     license?: 'MIT' | 'Apache-2.0' | 'BSD-3-Clause' | 'GPL-3.0-only' | 'GPL-3.0-or-later';
-    runtime?: '0.2';
+    runtime?: '0.3';
   };
   templates: Map<string, string>;
   partials: Map<string, string>;
@@ -35,15 +39,6 @@ export interface BuildOptions {
   writeManifest?: boolean;
 }
 
-export interface BuildSelection {
-  posts: string[];
-  indexRoutes: string[];
-  archiveRoutes: string[];
-  categoryRoutes: string[];
-  tagRoutes: string[];
-  includeAssets: boolean;
-}
-
 export interface BuildSummaryFile {
   path: string;
   contentType: string;
@@ -68,14 +63,6 @@ export function buildSite(input: {
   options?: BuildOptions;
 }): Promise<BuildSiteResult>;
 
-export function buildSelectedRoutes(input: {
-  previewData: PreviewDataV05;
-  themePackage: ThemePackage;
-  writer: BuildWriter;
-  selection: BuildSelection;
-  options?: BuildOptions;
-}): Promise<BuildSiteResult>;
-
 export function buildSiteFromThemeDir(input: {
   previewData: PreviewDataV05;
   themeDir: string;

package/src/index.js

@@ -1,5 +1,4 @@
 export { buildSite } from './api/build-site.js';
-export { buildSelectedRoutes } from './api/build-site.js';
 export { buildSiteFromThemeDir } from './api/build-site-from-theme-dir.js';
 export { MemoryWriter } from './output/memory-writer.js';
 export { FilesystemWriter } from './output/filesystem-writer.js';

package/src/render/variable-resolver.js

@@ -1,17 +1,15 @@
 export class VariableResolver {
-  static VARIABLE_PATTERN = /\{\{([a-zA-Z_][a-zA-Z0-9_]*\.[a-zA-Z_][a-zA-Z0-9_]*)\}\}/g;
+  static MENU_PATTERN = /\{\{menu:([a-z][a-z0-9_-]{0,63})\}\}/g;
+  static VARIABLE_PATTERN = /\{\{([a-zA-Z_][a-zA-Z0-9_]*(?:\.[a-zA-Z_][a-zA-Z0-9_]*)+)\}\}/g;
   static STANDALONE_PATTERN = /\{\{([a-zA-Z_][a-zA-Z0-9_]*)\}\}/g;
 
   resolve(template, data) {
-    let result = template.replace(VariableResolver.VARIABLE_PATTERN, (_, variablePath) => {
-      const [prefix, field] = variablePath.split('.');
-      const prefixData = data[prefix];
-
-      if (!prefixData || typeof prefixData !== 'object') {
-        return '';
-      }
+    let result = template.replace(VariableResolver.MENU_PATTERN, (_, menuId) => {
+      return this.renderMenu(data?.menus?.[menuId]);
+    });
 
-      const value = prefixData[field];
+    result = result.replace(VariableResolver.VARIABLE_PATTERN, (_, variablePath) => {
+      const value = this.resolvePath(data, variablePath);
       return value == null ? '' : String(value);
     });
 
@@ -26,4 +24,51 @@ export class VariableResolver {
 
     return result;
   }
+
+  resolvePath(data, variablePath) {
+    const segments = variablePath.split('.');
+    let current = data;
+
+    for (const segment of segments) {
+      if (current == null || typeof current !== 'object') {
+        return undefined;
+      }
+
+      current = current[segment];
+    }
+
+    return current;
+  }
+
+  renderMenu(menu) {
+    if (!menu || !Array.isArray(menu.items) || menu.items.length === 0) {
+      return '';
+    }
+
+    return `<ul>${menu.items.map((item) => this.renderMenuItem(item)).join('')}</ul>`;
+  }
+
+  renderMenuItem(item) {
+    if (!item || typeof item !== 'object') {
+      return '';
+    }
+
+    const title = this.escapeHtml(String(item.title || ''));
+    const url = this.escapeHtml(String(item.url || ''));
+    const target = item.target === '_blank' ? '_blank' : '_self';
+    const rel = target === '_blank' ? ' rel="noreferrer noopener"' : '';
+    const children = Array.isArray(item.children) && item.children.length > 0
+      ? `<ul>${item.children.map((child) => this.renderMenuItem(child)).join('')}</ul>`
+      : '';
+
+    return `<li><a href="${url}" target="${target}"${rel}>${title}</a>${children}</li>`;
+  }
+
+  escapeHtml(value) {
+    return value
+      .replaceAll('&', '&amp;')
+      .replaceAll('<', '&lt;')
+      .replaceAll('>', '&gt;')
+      .replaceAll('"', '&quot;');
+  }
 }