@transclude/core 0.11.0 → 0.11.1

package/bin/build.js

@@ -18,6 +18,7 @@ import transclude from '../src/plugin.js';
 import { loadProject } from '../src/project.js';
 import { renderRoute, urlFor } from '../src/document.js';
 import { prerenderContext, refusePrerender } from '../src/prerender.js';
+import { isGated, readGated } from '../src/gate.js';
 import { feed, feedPath } from '../src/feed.js';
 import { includeContext } from '../src/include.js';
 import { nodeLookup } from '../src/lookup.js';
@@ -121,7 +122,20 @@ fs.writeFileSync(entry, `// @ts-nocheck\n${fs.readFileSync(entry, 'utf8')}`);
 
 // ---- prerender ------------------------------------------------------------
 
-const { pages } = await import(pathToFileURL(entry).href);
+const { pages, gated: declared } = await import(pathToFileURL(entry).href);
+
+/**
+ * Paths `app/server.js` says are not public, and the routes they cover.
+ *
+ * Middleware does not run during a build, so nothing here can tell a payment
+ * gate or an auth check from an open page. Without the declaration a gated page
+ * is written to `dist/static` and served by any static host that finds it, and
+ * the build reports it as a page it prerendered.
+ *
+ * An entry matching nothing is a typo, and a typo here fails open, so it is an
+ * error rather than a shrug.
+ */
+const gated = readGated(declared);
 
 // ---- drafts ---------------------------------------------------------------
 
@@ -158,16 +172,19 @@ manifest.routes = manifest.routes.filter((route) => !isDraft(route));
  */
 async function urlsFor(route) {
   if (pages[route.id]?.prerender === false) return [];
-  if (!route.params.length) return [{ url: route.pattern, params: {} }];
+  if (!route.params.length) {
+    return isGated(route.pattern, gated) ? [] : [{ url: route.pattern, params: {} }];
+  }
 
   const paths = pages[route.id]?.paths;
   if (typeof paths !== 'function') return [];
 
   const listed = (await paths()) ?? [];
-  return listed.map((params) => ({
-    url: urlFor(route, params),
-    params,
-  }));
+  return listed
+    .map((params) => ({ url: urlFor(route, params), params }))
+    // Matched per URL, not per route: `/notes/[id]` can be open while
+    // `/notes/secret` is not, and the pattern is the same for both.
+    .filter(({ url }) => !isGated(url, gated));
 }
 
 /**
@@ -284,7 +301,7 @@ const prerendered = outcomes.filter((outcome) => outcome.ok).map((outcome) => ou
 // site with no sitemap there would be missing one only on the host that needs it
 // written down most.
 if (config.sitemap) {
-  write('sitemap.xml', await sitemap({ routes: manifest.routes }, pages, config.sitemap));
+  write('sitemap.xml', await sitemap({ routes: manifest.routes, gated }, pages, config.sitemap));
   prerendered.push('/sitemap.xml');
 }
 
@@ -306,6 +323,10 @@ fs.writeFileSync(
   path.join(dist, 'routes.json'),
   JSON.stringify(
     {
+      // Carried so `/sitemap.xml` at runtime leaves out what the build left out.
+      // The gate itself is `app/server.js` middleware, which runs at runtime and
+      // needs no help from here.
+      gated,
       dynamic: dynamic.map((route) => ({
         id: route.id,
         pattern: route.pattern,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@transclude/core",
-  "version": "0.11.0",
+  "version": "0.11.1",
   "description": "An HTML-first server framework. A page is an .html file, the directory tree is the route table, and any fragment of a page is a URL of its own. Runs on Node, Bun, Deno and workerd, and ships no client JavaScript by default.",
   "keywords": [
     "html",

package/skills/transclude/SKILL.md

@@ -277,6 +277,19 @@ element name. `card.html` is not, and the file is dropped.
 **`<transclude>` has no self-closing form.** `<transclude src="#a" />` is read
 as an open tag and the rest of the page becomes its fallback content.
 
+**Middleware does not run during the build.** A page gated only by
+`app/server.js` is prerendered to a file and served by any static host. Declare
+the paths so the build knows:
+
+```js
+// app/server.js
+export const gated = ['/premium', '/api/*'];
+```
+
+No file is written for them and the sitemap leaves them out. They are still
+routes. A layout guard needs no declaration: the build runs layout loaders, and
+a guard reads a cookie.
+
 **Reading a cookie makes a page personal.** It is then not cached and not
 prerendered. Writing one does not do this; reading one does.
 

package/src/gate.js

@@ -0,0 +1,70 @@
+// Paths an app says are not public, and whether a URL is one of them.
+//
+// Middleware does not run during a build, so nothing in `bin/build.js` can tell
+// a payment gate or an auth check from an open page. `export const gated` in
+// `app/server.js` is the only thing a build can read about a gate, and without
+// it a gated page is written to `dist/static` and handed out by any static host,
+// with the build reporting it as a page it prerendered.
+//
+// A layout guard is caught already, for a reason worth knowing: the build runs
+// layout loaders, and a guard reads a cookie. Nothing runs `app/server.js` here.
+//
+// Pure. No `node:` imports: the sitemap reads this at runtime, on every runtime.
+/**
+ * Whether a URL is one the app declared not public.
+ *
+ * `export const gated` in `app/server.js` is the only thing a build can read
+ * about a gate, because middleware does not run during one. A layout guard is
+ * caught already: the build runs layout loaders and a guard reads a cookie. A
+ * gate in `app/server.js` is run by nobody here, so a paid or signed-in page
+ * with an ordinary loader is written to `dist/static` and handed out by any
+ * static host, with the build reporting it as a success.
+ *
+ * `/premium` matches that path only. `/premium/*` matches it and everything
+ * under it. Nothing else is a pattern: this decides whether to write a file, and
+ * a rule nobody can read at a glance is the wrong shape for that.
+ *
+ * @param {string} url the path the build is about to write
+ * @param {string[]} patterns
+ * @returns {boolean}
+ */
+export function isGated(url, patterns = []) {
+  return patterns.some((pattern) => {
+    if (!pattern.endsWith('/*')) return url === pattern;
+    const base = pattern.slice(0, -2);
+    return url === base || url.startsWith(`${base}/`);
+  });
+}
+
+/**
+ * The declaration, or a refusal naming what is wrong with it.
+ *
+ * Checked rather than trusted, because every mistake here fails open. A typo
+ * matches nothing, the page is written, and the build says it prerendered a page
+ * that was supposed to need paying for.
+ *
+ * @param {unknown} gated whatever `app/server.js` exported
+ * @returns {string[]}
+ * @throws when it is not a list of paths
+ */
+export function readGated(gated) {
+  if (gated === undefined || gated === null) return [];
+
+  if (!Array.isArray(gated)) {
+    throw new Error(
+      `[transclude] app/server.js exports "gated" as ${typeof gated}. It is a list of paths, ` +
+        `like ['/premium', '/api/*'].`,
+    );
+  }
+
+  for (const entry of gated) {
+    if (typeof entry !== 'string' || !entry.startsWith('/')) {
+      throw new Error(
+        `[transclude] "gated" in app/server.js has ${JSON.stringify(entry)}. ` +
+          `Every entry is a path beginning with "/", and "/*" at the end covers what is under it.`,
+      );
+    }
+  }
+
+  return gated;
+}

package/src/plugin.js

@@ -289,7 +289,7 @@ export default function transclude({
         return `
 ${ids.map((pageId, i) => `import * as __P${i} from ${JSON.stringify(`${P_PAGE}${pageId}`)};`).join('\n')}
 ${apiIds.map((apiId, i) => `import * as __E${i} from ${apiSpec(endpoints.get(apiId))};`).join('\n')}
-${hasMiddleware ? `import __middleware from ${JSON.stringify(specifier)};` : ''}
+${hasMiddleware ? `import * as __server from ${JSON.stringify(specifier)};` : ''}
 
 export const pages = {
 ${ids.map((pageId, i) => `  ${JSON.stringify(pageId)}: __P${i},`).join('\n')}
@@ -299,7 +299,12 @@ export const endpoints = {
 ${apiIds.map((apiId, i) => `  ${JSON.stringify(apiId)}: __E${i},`).join('\n')}
 };
 
-export const middleware = ${hasMiddleware ? '__middleware ?? null' : 'null'};
+export const middleware = ${hasMiddleware ? '__server.default ?? null' : 'null'};
+
+// Paths the app says are not public. The build reads this and writes no file for
+// them, because middleware does not run during a build and a file it was meant
+// to gate would be served by any static host.
+export const gated = ${hasMiddleware ? '__server.gated ?? []' : '[]'};
 `;
       }
 

package/src/sitemap.js

@@ -7,6 +7,7 @@
 // crawler can reach by guessing, so it is left out.
 
 import { urlFor } from './document.js';
+import { isGated } from './gate.js';
 
 /** The protocol's cap for one file. Past it the response is an index of files. */
 const LIMIT = 50000;
@@ -65,9 +66,16 @@ export async function sitemapEntries(manifest, pages, { entries = [], exclude =
   const extra = typeof entries === 'function' ? ((await entries()) ?? []) : entries;
   const all = [...found, ...extra];
 
+  // `manifest.gated` rather than a second config key. A path the app declared
+  // not public should not be advertised, and reading it here covers the file the
+  // build writes and the `/sitemap.xml` route together. Two lists is two answers
+  // about which URLs a crawler is invited to.
+  const gated = manifest.gated ?? [];
+
   const seen = new Set();
   return all.filter((entry) => {
     if (seen.has(entry.path) || excluded(entry.path, exclude)) return false;
+    if (isGated(entry.path, gated)) return false;
     seen.add(entry.path);
     return true;
   });