@zeropress/build-core 0.1.0 → 0.1.2

package/README.md

@@ -13,6 +13,11 @@ This package is the deterministic rendering engine used by:
 
 It accepts canonical preview-data plus a validated theme package and produces static HTML artifacts through a writer interface.
 
+`preview-data` stays the canonical input graph. Actual artifact output is the intersection of:
+
+- renderable preview-data entries
+- theme template capability
+
 ---
 
 ## Install
@@ -109,6 +114,15 @@ Renders only selected post and list routes while preserving full-build parity fo
 
 This is intended for selective publish and other partial-render workflows.
 
+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,
@@ -177,6 +191,15 @@ Theme validation is enforced through:
 
 - [`@zeropress/theme-validator`](https://www.npmjs.com/package/@zeropress/theme-validator)
 
+Optional route templates behave as rendering capabilities, not guaranteed outputs:
+
+- `archive.html`
+- `category.html`
+- `tag.html`
+- `404.html`
+
+If preview-data includes archive/category/tag route arrays but the theme omits the matching optional template, build-core skips those outputs. Special files are derived from emitted outputs rather than raw preview-data alone.
+
 ---
 
 ## Build Options

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zeropress/build-core",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Shared ZeroPress build and partial-render core",
   "type": "module",
   "license": "MIT",

package/src/api/build-site.js

@@ -27,16 +27,22 @@ export async function buildSite(input) {
     await renderPage(state, page);
   }
 
-  for (const route of input.previewData.routes.categories) {
-    await renderRoute(state, 'category', route);
+  if (hasTemplate(state, 'category')) {
+    for (const route of input.previewData.routes.categories) {
+      await renderRoute(state, 'category', route);
+    }
   }
 
-  for (const route of input.previewData.routes.tags) {
-    await renderRoute(state, 'tag', route);
+  if (hasTemplate(state, 'tag')) {
+    for (const route of input.previewData.routes.tags) {
+      await renderRoute(state, 'tag', route);
+    }
   }
 
-  for (const route of input.previewData.routes.archive) {
-    await renderRoute(state, 'archive', route);
+  if (hasTemplate(state, 'archive')) {
+    for (const route of input.previewData.routes.archive) {
+      await renderRoute(state, 'archive', route);
+    }
   }
 
   for (const assetOutput of state.assetOutputs) {
@@ -44,10 +50,11 @@ export async function buildSite(input) {
   }
 
   if (options.generateSpecialFiles) {
-    await writeOutput(state.writer, state.summaries, 'sitemap.xml', buildSitemapXml(input.previewData), 'application/xml');
-    await writeOutput(state.writer, state.summaries, 'feed.xml', buildFeedXml(input.previewData), 'application/rss+xml');
+    await maybeRenderNotFoundPage(state);
+    await writeOutput(state.writer, state.summaries, 'sitemap.xml', buildSitemapXml(state.previewData.site, state.emitted, state.generatedAt), 'application/xml');
+    await writeOutput(state.writer, state.summaries, 'feed.xml', buildFeedXml(state.previewData.site, state.emitted, state.generatedAt), 'application/rss+xml');
     await writeOutput(state.writer, state.summaries, 'robots.txt', buildRobotsTxt(input.previewData), 'text/plain');
-    await writeOutput(state.writer, state.summaries, 'meta.json', buildMetaJson(input.previewData), 'application/json');
+    await writeOutput(state.writer, state.summaries, 'meta.json', buildMetaJson(state.previewData.site, state.emitted, state.generatedAt), 'application/json');
   }
 
   return finalizeBuildResult(state.writer, state.summaries, options);
@@ -76,21 +83,27 @@ export async function buildSelectedRoutes(input) {
     }
   }
 
-  for (const route of input.previewData.routes.archive) {
-    if (selectedArchiveRoutes.has(normalizeRoutePath(route.path))) {
-      await renderRoute(state, 'archive', route);
+  if (hasTemplate(state, 'archive')) {
+    for (const route of input.previewData.routes.archive) {
+      if (selectedArchiveRoutes.has(normalizeRoutePath(route.path))) {
+        await renderRoute(state, 'archive', route);
+      }
     }
   }
 
-  for (const route of input.previewData.routes.categories) {
-    if (selectedCategoryRoutes.has(normalizeRoutePath(route.path))) {
-      await renderRoute(state, 'category', route);
+  if (hasTemplate(state, 'category')) {
+    for (const route of input.previewData.routes.categories) {
+      if (selectedCategoryRoutes.has(normalizeRoutePath(route.path))) {
+        await renderRoute(state, 'category', route);
+      }
     }
   }
 
-  for (const route of input.previewData.routes.tags) {
-    if (selectedTagRoutes.has(normalizeRoutePath(route.path))) {
-      await renderRoute(state, 'tag', route);
+  if (hasTemplate(state, 'tag')) {
+    for (const route of input.previewData.routes.tags) {
+      if (selectedTagRoutes.has(normalizeRoutePath(route.path))) {
+        await renderRoute(state, 'tag', route);
+      }
     }
   }
 
@@ -132,6 +145,15 @@ async function createBuildState(input, options) {
     assetOutputs,
     assetMap,
     options,
+    generatedAt: new Date(),
+    emitted: {
+      indexRoutes: [],
+      archiveRoutes: [],
+      categoryRoutes: [],
+      tagRoutes: [],
+      posts: [],
+      pages: [],
+    },
   };
 }
 
@@ -158,13 +180,15 @@ async function finalizeBuildResult(writer, summaries, options) {
 }
 
 async function renderRoute(state, templateName, route) {
+  const currentUrl = normalizeRoutePath(route.path);
   let html = await state.engine.render(
     templateName,
     { ...route },
-    createRenderContext(state.previewData.site, route.path),
+    createRenderContext(state.previewData.site, currentUrl),
   );
   html = state.assetProcessor.updateAssetReferences(html, state.assetMap);
   await writeOutput(state.writer, state.summaries, routePathToOutputPath(route.path), html, 'text/html');
+  recordRouteEmission(state, templateName, route, currentUrl);
 }
 
 async function renderPost(state, post) {
@@ -178,6 +202,14 @@ async function renderPost(state, post) {
     html = injectHtmxScript(html);
   }
   await writeOutput(state.writer, state.summaries, `posts/${encodeSlugSegment(post.slug)}/index.html`, html, 'text/html');
+  state.emitted.posts.push({
+    url: `/posts/${encodeSlugSegment(post.slug)}/`,
+    title: post.title,
+    description: post.excerpt,
+    publishedAt: post.published_at_iso,
+    updatedAt: post.updated_at_iso,
+    status: post.status,
+  });
 }
 
 async function renderPage(state, page) {
@@ -188,6 +220,25 @@ async function renderPage(state, page) {
   );
   html = state.assetProcessor.updateAssetReferences(html, state.assetMap);
   await writeOutput(state.writer, state.summaries, `${encodeSlugSegment(page.slug)}/index.html`, html, 'text/html');
+  state.emitted.pages.push({
+    url: `/${encodeSlugSegment(page.slug)}/`,
+    title: page.title,
+    status: page.status,
+  });
+}
+
+async function maybeRenderNotFoundPage(state) {
+  if (!state.engine.themePackage?.templates?.has('404')) {
+    return;
+  }
+
+  let html = await state.engine.render(
+    '404',
+    {},
+    createRenderContext(state.previewData.site, '/404.html'),
+  );
+  html = state.assetProcessor.updateAssetReferences(html, state.assetMap);
+  await writeOutput(state.writer, state.summaries, '404.html', html, 'text/html');
 }
 
 function validateSelection(selection) {
@@ -207,6 +258,30 @@ function validateSelection(selection) {
   }
 }
 
+function hasTemplate(state, templateName) {
+  return state.engine.themePackage?.templates?.has(templateName) === true;
+}
+
+function recordRouteEmission(state, templateName, route, currentUrl) {
+  const targetMap = {
+    index: state.emitted.indexRoutes,
+    archive: state.emitted.archiveRoutes,
+    category: state.emitted.categoryRoutes,
+    tag: state.emitted.tagRoutes,
+  }[templateName];
+
+  if (!targetMap) {
+    return;
+  }
+
+  targetMap.push({
+    url: currentUrl,
+    page: route.page,
+    totalPages: route.totalPages,
+    slug: route.slug,
+  });
+}
+
 async function assertValidThemePackage(themePackage) {
   if (!themePackage?.templates || !themePackage?.partials || !themePackage?.assets || !themePackage?.metadata) {
     throw new Error('Invalid themePackage: expected metadata, templates, partials, and assets');
@@ -305,7 +380,8 @@ function normalizeRoutePath(routePath) {
   if (!routePath || routePath === '/') {
     return '/';
   }
-  return `/${String(routePath).replace(/^\/+|\/+$/g, '')}/`;
+  const normalized = decodeRoutePath(String(routePath)).replace(/^\/+|\/+$/g, '');
+  return `/${normalized}/`;
 }
 
 function normalizeOutputPath(filePath) {
@@ -326,37 +402,44 @@ function injectHtmxScript(html) {
   return html.replace('</body>', '<script src="https://unpkg.com/htmx.org@2.0.4" crossorigin="anonymous"></script>\n</body>');
 }
 
-function buildSitemapXml(previewData) {
+function buildSitemapXml(site, emitted, generatedAt) {
   const entries = [
-    { url: '/', lastmod: new Date(), changefreq: 'daily', priority: 1.0 },
-    ...previewData.content.posts.map((post) => ({
-      url: `/posts/${encodeSlugSegment(post.slug)}/`,
-      lastmod: toDate(post.updated_at_iso),
+    ...emitted.indexRoutes
+      .filter((route) => route.url === '/')
+      .map((route) => ({
+      url: route.url,
+      lastmod: generatedAt,
+      changefreq: 'daily',
+      priority: 1.0,
+    })),
+    ...emitted.posts.map((post) => ({
+      url: post.url,
+      lastmod: toDate(post.updatedAt),
       changefreq: 'weekly',
       priority: 0.8,
     })),
-    ...previewData.content.pages.map((page) => ({
-      url: `/${encodeSlugSegment(page.slug)}/`,
-      lastmod: new Date(),
+    ...emitted.pages.map((page) => ({
+      url: page.url,
+      lastmod: generatedAt,
       changefreq: 'monthly',
       priority: 0.7,
     })),
-    ...previewData.content.categories.filter((category) => category.postCount > 0).map((category) => ({
-      url: `/categories/${encodeSlugSegment(category.slug)}/`,
-      lastmod: new Date(),
+    ...emitted.categoryRoutes.filter((route) => route.page === 1).map((route) => ({
+      url: route.url,
+      lastmod: generatedAt,
       changefreq: 'weekly',
       priority: 0.6,
     })),
-    ...previewData.content.tags.filter((tag) => tag.postCount > 0).map((tag) => ({
-      url: `/tags/${encodeSlugSegment(tag.slug)}/`,
-      lastmod: new Date(),
+    ...emitted.tagRoutes.filter((route) => route.page === 1).map((route) => ({
+      url: route.url,
+      lastmod: generatedAt,
       changefreq: 'weekly',
       priority: 0.5,
     })),
   ];
 
   const body = entries.map((entry) => {
-    const loc = escapeXml(new URL(entry.url, previewData.site.url).toString());
+    const loc = escapeXml(resolveSiteUrl(site.url, entry.url));
     const lastmod = entry.lastmod.toISOString().split('T')[0];
     return `  <url>\n    <loc>${loc}</loc>\n    <lastmod>${lastmod}</lastmod>\n    <changefreq>${entry.changefreq}</changefreq>\n    <priority>${entry.priority.toFixed(1)}</priority>\n  </url>`;
   }).join('\n');
@@ -364,36 +447,36 @@ function buildSitemapXml(previewData) {
   return `<?xml version="1.0" encoding="UTF-8"?>\n<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">\n${body}\n</urlset>`;
 }
 
-function buildFeedXml(previewData) {
-  const items = [...previewData.content.posts]
-    .sort((a, b) => toDate(b.published_at_iso).getTime() - toDate(a.published_at_iso).getTime())
+function buildFeedXml(site, emitted, generatedAt) {
+  const items = [...emitted.posts]
+    .sort((a, b) => toDate(b.publishedAt).getTime() - toDate(a.publishedAt).getTime())
     .slice(0, 20)
     .map((post) => {
-      const url = new URL(`/posts/${encodeSlugSegment(post.slug)}/`, previewData.site.url).toString();
-      return `    <item>\n      <title>${escapeXml(post.title)}</title>\n      <link>${escapeXml(url)}</link>\n      <guid>${escapeXml(url)}</guid>\n      <pubDate>${toDate(post.published_at_iso).toUTCString()}</pubDate>\n      <description>${escapeXml(post.excerpt)}</description>\n    </item>`;
+      const url = resolveSiteUrl(site.url, post.url);
+      return `    <item>\n      <title>${escapeXml(post.title)}</title>\n      <link>${escapeXml(url)}</link>\n      <guid>${escapeXml(url)}</guid>\n      <pubDate>${toDate(post.publishedAt).toUTCString()}</pubDate>\n      <description>${escapeXml(post.description)}</description>\n    </item>`;
     })
     .join('\n');
 
-  return `<?xml version="1.0" encoding="UTF-8"?>\n<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom">\n  <channel>\n    <title>${escapeXml(previewData.site.title)}</title>\n    <link>${escapeXml(previewData.site.url)}</link>\n    <description>${escapeXml(previewData.site.description)}</description>\n    <language>${previewData.site.language}</language>\n    <lastBuildDate>${new Date().toUTCString()}</lastBuildDate>\n    <atom:link href="${escapeXml(new URL('/feed.xml', previewData.site.url).toString())}" rel="self" type="application/rss+xml" />\n${items}\n  </channel>\n</rss>`;
+  return `<?xml version="1.0" encoding="UTF-8"?>\n<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom">\n  <channel>\n    <title>${escapeXml(site.title)}</title>\n    <link>${escapeXml(site.url)}</link>\n    <description>${escapeXml(site.description)}</description>\n    <language>${site.language}</language>\n    <lastBuildDate>${generatedAt.toUTCString()}</lastBuildDate>\n    <atom:link href="${escapeXml(new URL('/feed.xml', site.url).toString())}" rel="self" type="application/rss+xml" />\n${items}\n  </channel>\n</rss>`;
 }
 
 function buildRobotsTxt(previewData) {
   return `User-agent: *\nAllow: /\n\nSitemap: ${previewData.site.url}/sitemap.xml\n`;
 }
 
-function buildMetaJson(previewData) {
+function buildMetaJson(site, emitted, generatedAt) {
   const pages = [
-    ...previewData.content.posts.map((post) => ({
-      url: `/posts/${encodeSlugSegment(post.slug)}/`,
+    ...emitted.posts.map((post) => ({
+      url: post.url,
       title: post.title,
-      description: post.excerpt,
-      publishedAt: post.published_at_iso,
-      updatedAt: post.updated_at_iso,
+      description: post.description,
+      publishedAt: post.publishedAt,
+      updatedAt: post.updatedAt,
       type: 'post',
       metadata: { status: post.status },
     })),
-    ...previewData.content.pages.map((page) => ({
-      url: `/${encodeSlugSegment(page.slug)}/`,
+    ...emitted.pages.map((page) => ({
+      url: page.url,
       title: page.title,
       type: 'page',
       metadata: { status: page.status },
@@ -401,12 +484,12 @@ function buildMetaJson(previewData) {
   ];
 
   return JSON.stringify({
-    generated: new Date().toISOString(),
+    generated: generatedAt.toISOString(),
     site: {
-      title: previewData.site.title,
-      description: previewData.site.description,
-      url: previewData.site.url,
-      language: previewData.site.language,
+      title: site.title,
+      description: site.description,
+      url: site.url,
+      language: site.language,
     },
     pages,
   }, null, 2);
@@ -438,7 +521,36 @@ function getContentType(assetPath) {
 }
 
 function encodeSlugSegment(slug) {
-  return encodeURIComponent(String(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);
+  } catch {
+    return routePath;
+  }
+}
+
+function resolveSiteUrl(siteUrl, relativePath) {
+  return decodeURI(new URL(relativePath, siteUrl).toString());
 }
 
 function toDate(value) {