freestruct 0.0.0-stage → 1.0.0

package/engine/inject.js

@@ -0,0 +1,287 @@
+#!/usr/bin/env node
+// engine/inject.js - post-build SEO layer for static doc sites (Phase 1, ESM)
+// Module map (was a 577-LOC single file, PRD 1.1):
+//   config.js    config discovery + validation
+//   scan.js      tree walk + page model (slugs, mtimes, noindex detection)
+//   seo.js       meta/OG/Twitter/JSON-LD injection + late passes
+//   xmllike.js   escaping + sitemap + robots + RSS
+//   notfound.js  404 pipeline
+//   linkcheck.js link validation
+//   search.js    opt-in search.json
+//   hooks.js     purge hooks
+//
+// CLI (Phase 0/2 contract):
+//   --version   print the package.json version and exit 0 (works configless;
+//               resolved one level up: engine/ is the package root's sibling dir)
+//   validate | init [dir] | help   subcommands (see the helpers below)
+//   --strict    opt-in: broken internal links exit 1 instead of
+//               shipping green
+//   --tolerant  opt-out for CI tolerance: fatal config errors log and exit 0
+//               (default is FAST_FAIL exit codes, see below)
+//   <outputDir> positional output-directory override
+//
+// FAST_FAIL exit codes (PRD Phase 2, config-first diagnostics):
+//   0 success | 1 config fatal | 2 template missing | 3 output dir missing
+//
+// Root resolution (Phase 1.2): the config is discovered by walking UP from
+// the cwd; templates/snippets resolve next to the config file; the output
+// dir defaults to docs/_site next to the config.
+
+import fs from 'fs';
+import path from 'path';
+import { pathToFileURL, fileURLToPath } from 'url';
+
+import { loadConfig } from './config.js';
+import { getHtmlFiles, buildPages, computeBuildHash, htmlIsNoindex } from './scan.js';
+import { injectPage, addReadingTime, addLastModified, addLazyLoading } from './seo.js';
+import { generateSitemap, generateRobots, generateFeed } from './xmllike.js';
+import { generate404, pipeline404 } from './notfound.js';
+import { checkLinks } from './linkcheck.js';
+import { generateSearchIndex } from './search.js';
+import { runPurgeHooks } from './hooks.js';
+
+const FLAG_VALUES = new Set(['--version', '--strict', '--tolerant']);
+const _argv = process.argv.slice(2);
+const _flags = _argv.filter(a => FLAG_VALUES.has(a));
+// Subcommands before the positional output-dir: the first bare word decides
+// what the run is (validate/init/help mirror prestruct's command surface);
+// any other bare word stays the outputDir override it always was.
+const COMMANDS = new Set(['validate', 'init', 'help']);
+const _firstArg = _argv.find(a => !a.startsWith('--'));
+const _positional = _firstArg && !COMMANDS.has(_firstArg) ? _firstArg : undefined;
+
+export const EXIT_OK = 0;
+export const EXIT_CONFIG = 1;
+export const EXIT_TEMPLATE = 2;
+export const EXIT_OUTPUT = 3;
+
+function fail(message, code = EXIT_CONFIG) {
+  console.error('[freestruct] ' + message);
+  if (_flags.includes('--tolerant')) {
+    console.log('[freestruct] --tolerant: continuing with exit 0 (CI tolerance mode)');
+    process.exit(EXIT_OK);
+  }
+  process.exit(code);
+}
+
+function printVersion() {
+  // engine/inject.js sits in engine/, one level under the package root -
+  // that stays true inside an npm install (node_modules/freestruct/engine/).
+  const pkg = JSON.parse(fs.readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+  console.log(pkg.version);
+}
+
+// ---------- CLI subcommands (prestruct's init/validate/help surface) ----------
+
+const HELP = `
+freestruct -- post-build SEO layer for static doc sites
+
+  freestruct                Run the full post-build pass (config discovered
+                            by walking up from cwd; output dir defaults to
+                            docs/_site, or pass one as an argument)
+  freestruct validate       Load + validate the config; exit 1 on fatal errors
+                            (no output tree is touched)
+  freestruct init [dir]     Scaffold the consumer kit (starter config +
+                            template copies) into <dir>/docs; the default dir
+                            is the cwd. Existing files are never clobbered.
+  freestruct help (--help)  This text.
+
+Flags: --version | --strict | --tolerant
+Exit codes: 0 ok | 1 config fatal | 2 template missing | 3 output dir missing
+`;
+
+function printHelp() {
+  console.log(HELP);
+}
+
+/**
+ * `freestruct validate`: config-only preflight for CI. Warnings still print
+ * (collectConfigDiagnostics runs inside loadConfig); a fatal config error
+ * exits EXIT_CONFIG, honoring --tolerant like every other fatal.
+ */
+function cmdValidate() {
+  let loaded;
+  try {
+    loaded = loadConfig(process.cwd());
+  } catch (e) {
+    fail(e.message, EXIT_CONFIG);
+  }
+  console.log('[freestruct] config ok: ' + loaded.configPath);
+  process.exit(EXIT_OK);
+}
+
+/**
+ * `freestruct init [dir]`: copy the consumer scaffold kit (init/docs: starter
+ * config + template copies) into <dir>/docs (default dir: cwd), never
+ * clobbering an existing file. Mirrors the manual `cp -r node_modules/
+ * freestruct/init/docs .` shape the init kit README describes.
+ */
+function cmdInit(dirArg) {
+  const targetRoot = path.resolve(process.cwd(), dirArg || '.');
+  const docsDir = path.join(targetRoot, 'docs');
+  // engine/inject.js -> package root -> init/docs (files list ships init/)
+  const kitDir = path.join(fileURLToPath(new URL('../init/docs', import.meta.url)));
+  if (!fs.existsSync(kitDir)) fail('Scaffold kit not found at ' + kitDir, EXIT_TEMPLATE);
+
+  let created = 0;
+  let skipped = 0;
+  function copy(src, dest) {
+    if (fs.statSync(src).isDirectory()) {
+      fs.mkdirSync(dest, { recursive: true });
+      for (const entry of fs.readdirSync(src)) copy(path.join(src, entry), path.join(dest, entry));
+      return;
+    }
+    if (fs.existsSync(dest)) { skipped++; console.log('  skip (exists): ' + path.relative(targetRoot, dest)); return; }
+    fs.copyFileSync(src, dest);
+    created++;
+    console.log('  created: ' + path.relative(targetRoot, dest));
+  }
+  copy(kitDir, docsDir);
+  console.log('[freestruct] init: ' + created + ' file(s) created in ' + docsDir + (skipped > 0 ? ', ' + skipped + ' existing file(s) left untouched' : ''));
+  if (created === 0) console.log('[freestruct] init: nothing new to scaffold - the kit was already present');
+  process.exit(EXIT_OK);
+}
+
+const STRICT = _flags.includes('--strict');
+
+export function runInject(options = {}) {
+  const cwd = options.cwd || process.cwd();
+  console.log('freestruct: Loading config...');
+
+  let loaded;
+  try {
+    loaded = loadConfig(cwd);
+  } catch (e) {
+    fail(e.message, EXIT_CONFIG);
+  }
+  const { config, configDir } = loaded;
+
+  // output dir: CLI positional > config.outputDir > docs/_site (configDir already ends in docs/)
+  const outputDir = _positional
+    ? path.resolve(cwd, _positional)
+    : path.resolve(configDir, config.outputDir || '_site');
+
+  if (!fs.existsSync(outputDir)) fail('Output directory not found: ' + outputDir, EXIT_OUTPUT);
+  // Template resolution: user-staged first (docs/_freestruct next to the
+  // config), then the PACKAGE-shipped copy (npm install ships engine/_freestruct
+  // - repo-shaped runs always hit the staged one, fresh-machine installs fall
+  // back here; caught by the tarball e2e on a fresh install). The battery
+  // pins the staged-only exit-2 shape via FREESTRUCT_SKIP_PACKAGE_FALLBACK.
+  // engine/_freestruct is a SIBLING of this engine file, hence './', not '../'.
+  const packageTemplateDir = path.join(fileURLToPath(new URL('./_freestruct/', import.meta.url)));
+  let snippetDir = path.join(configDir, '_freestruct');
+  if (!fs.existsSync(path.join(snippetDir, 'inject-brand.html')) &&
+      process.env.FREESTRUCT_SKIP_PACKAGE_FALLBACK !== '1' &&
+      fs.existsSync(path.join(packageTemplateDir, 'inject-brand.html'))) {
+    snippetDir = packageTemplateDir;
+  }
+  const templatePath = path.join(snippetDir, 'inject-brand.html');
+  if (!fs.existsSync(templatePath)) {
+    fail('Template not found: ' + templatePath + ' (shipped copy also missing at ' + packageTemplateDir + ')', EXIT_TEMPLATE);
+  }
+  const template = fs.readFileSync(templatePath, 'utf8');
+
+  const htmlFiles = getHtmlFiles(outputDir);
+  console.log('Found ' + htmlFiles.length + ' HTML files');
+
+  // Build hash is content-derived (see scan.js computeBuildHash): the pages
+  // snapshot must exist before it can be computed, and empty trees hash the
+  // config alone.
+  const pagesForHash = htmlFiles.length > 0 ? buildPages(htmlFiles, outputDir) : [];
+  const buildHash = computeBuildHash(config, pagesForHash);
+  console.log('Build: ' + buildHash);
+
+  if (htmlFiles.length > 0) {
+    const pages = pagesForHash;
+    const sitePages = pages.filter(p => !p.is404);
+
+    // SEO pipeline over every regular page
+    const injectCtx = { config, template, buildHash, snippetDir };
+    for (const page of sitePages) injectPage(page, injectCtx);
+
+    // 404 pipeline: generated when absent, user-supplied folded into the
+    // same full treatment (Phase 1.4). Runs after regular pages so a 404
+    // already present in the tree is not double-processed above.
+    const processed404s = [];
+    if (config.generate404 !== false) {
+      let page404 = pages.find(p => p.is404);
+      if (!page404) {
+        const file404 = generate404(config, outputDir, buildHash, template, snippetDir);
+        const html404 = fs.readFileSync(file404, 'utf8');
+        page404 = {
+          file: file404,
+          rel: '404.html',
+          slug: '/404',
+          is404: true,
+          html: html404,
+          mtime: new Date(),
+          title: html404.match(/<title>([^<]+)<\/title>/i)?.[1]?.split(' | ')[0] || null,
+          description: html404.match(/<meta name="description" content="([^"]+)"/i)?.[1] || null,
+        };
+      }
+      processed404s.push(pipeline404(page404, injectCtx));
+    }
+
+    // Late passes over every processed page, 404s included (Phase 1.4)
+    const latePages = [...sitePages, ...processed404s];
+    if (config.readingTime !== false) for (const page of latePages) addReadingTime(page.file);
+    if (config.lastModified !== false) for (const page of latePages) addLastModified(page.file);
+    if (config.lazyLoad !== false) for (const page of latePages) addLazyLoading(page.file);
+
+    // noindex is honored by default (owner decision, issue #5):
+    // noindex pages never ship into sitemap/feed/search
+    const indexablePages = pages.filter(p => !p.is404 && !htmlIsNoindex(p.html));
+
+    if (config.generateSitemap !== false) generateSitemap(indexablePages, config, outputDir);
+    if (config.generateRobots !== false) generateRobots(config, outputDir);
+    if (config.generateFeed !== false) generateFeed(indexablePages, config, outputDir);
+
+    // link check over regular pages (404 targets excluded by design)
+    const brokenLinks = config.linkCheck !== false ? checkLinks(sitePages.map(p => p.file), outputDir) : [];
+
+    // opt-in search index (owner decision: search.json is opt-in as of Phase 2)
+    if (config.searchIndex === true) generateSearchIndex(indexablePages, config, outputDir);
+
+    // --strict: report-only classes become build failures (Phase 0 contract)
+    if (STRICT) {
+      const problems = [];
+      if (brokenLinks.length > 0) {
+        problems.push(brokenLinks.length + ' broken internal link(s)');
+      }
+      // noindex cannot leak into generated artifacts anymore (filtered above);
+      // the gate stays as a defensive tripwire for future artifact changes.
+      if (problems.length > 0) {
+        console.log('[freestruct] strict mode: build failed:');
+        for (const problem of problems) console.log('  - ' + problem);
+        for (const b of brokenLinks) console.log('  BROKEN: ' + b.file + ' -> ' + b.link);
+        process.exit(1);
+      }
+    }
+  }
+
+  // purge hooks, if configured (gated by runHooks)
+  if (config.cacheBusting?.purge) runPurgeHooks(config, buildHash, outputDir);
+
+  console.log('freestruct: Done (' + buildHash + ')');
+}
+
+// Module-level command dispatch: the bin shim IMPORTS runInject() rather
+// than invoking this file as main, so commands must dispatch at import time
+// (the pre-change --version module-level check had the same shape). Library
+// importers pass no such argv and simply skip all of these.
+if (_flags.includes('--version')) { printVersion(); process.exit(0); }
+// `help` is the subcommand; --help is the flag alias (both print the same text)
+if (_firstArg === 'help' || _argv.includes('--help')) { printHelp(); process.exit(EXIT_OK); }
+if (_firstArg === 'validate') cmdValidate();
+if (_firstArg === 'init') cmdInit(_argv[_argv.indexOf('init') + 1]);
+
+// Main-module detection: npm's .bin shim is a symlink, but import.meta.url
+// resolves the target's real path. Comparing only the raw argv[1] made real
+// installs run silently (exit 0, no work) - caught by the tarball e2e. Only
+// the DEFAULT full-pass run needs the main-module gate.
+const argvReal = process.argv[1]
+  ? (() => { try { return fs.realpathSync(process.argv[1]); } catch (e) { return process.argv[1]; } })()
+  : '';
+const moduleReal = fileURLToPath(import.meta.url);
+const invokedAsMain = argvReal === moduleReal || import.meta.url === pathToFileURL(process.argv[1] || '').href;
+if (invokedAsMain) runInject();

package/engine/linkcheck.js

@@ -0,0 +1,49 @@
+// engine/linkcheck.js - internal link validation (Phase 1.1 split)
+// Report-only by default; --strict (see bin) consumes the returned broken list.
+
+import fs from 'fs';
+import path from 'path';
+
+/**
+ * Check internal links across every page. Returns [{file, link}] for broken
+ * targets and prints the human-readable report (same output as 0.4.x).
+ */
+export function checkLinks(files, outputDir) {
+  const broken = [];
+
+  for (const file of files) {
+    const html = fs.readFileSync(file, 'utf8');
+    const baseDir = path.dirname(file);
+
+    const linkRegex = /href="([^"#]+)(?:#[^"]*)?"/g;
+    let match;
+    while ((match = linkRegex.exec(html)) !== null) {
+      const link = match[1];
+
+      // Skip external, mailto, tel
+      if (link.startsWith('http') || link.startsWith('mailto:') || link.startsWith('tel:') || link.startsWith('//')) continue;
+
+      const absPath = path.join(baseDir, link);
+      const normalized = path.normalize(absPath);
+
+      let checkPath = normalized;
+      if (fs.existsSync(path.join(normalized, 'index.html'))) {
+        checkPath = path.join(normalized, 'index.html');
+      }
+
+      if (normalized.endsWith('.html') && !fs.existsSync(normalized)) {
+        broken.push({ file: path.relative(outputDir, file), link });
+      }
+    }
+  }
+
+  if (broken.length > 0) {
+    console.log('Link check: ' + broken.length + ' broken links found');
+    for (const b of broken.slice(0, 10)) {
+      console.log('  BROKEN: ' + b.file + ' -> ' + b.link);
+    }
+  } else {
+    console.log('Link check: All links OK');
+  }
+  return broken;
+}

package/engine/notfound.js

@@ -0,0 +1,73 @@
+// engine/notfound.js - the 404 pipeline (Phase 1.4)
+// FIX (freestruct issue #11): generated AND custom 404 pages now get the full
+// SEO pipeline via the same injectPage call every normal page uses, plus a
+// robots noindex meta. The CHANGELOG's long-claimed noindex finally ships.
+
+import fs from 'fs';
+import path from 'path';
+import { injectPage } from './seo.js';
+import { pageUrlFor } from './urls.js';
+import { stripRobotsMeta } from './scan.js';
+
+/** Generate the fallback 404 page (search form + links), then run it through the SEO pipeline. */
+export function generate404(config, outputDir, buildHash, template, snippetDir) {
+  const file = path.join(outputDir, '404.html');
+  // Links follow the pageUrlFor contract (basePath-aware) - raw site.url
+  // guesses like '/docs/' point at 404s on sub-path installs (#3 class).
+  const siteName = config.site.name || 'Site';
+  const homeUrl = pageUrlFor(config, '/');
+  const notFound = `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>404 - Page Not Found | ${siteName}</title>
+  <style>
+    body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; max-width: 600px; margin: 100px auto; padding: 20px; text-align: center; }
+    h1 { font-size: 4rem; margin: 0; color: #333; }
+    p { font-size: 1.2rem; color: #666; margin: 20px 0; }
+    .search { margin: 30px 0; }
+    .search input { width: 70%; padding: 12px; font-size: 1rem; border: 1px solid #ddd; border-radius: 4px; }
+    .search button { padding: 12px 20px; font-size: 1rem; background: #333; color: #fff; border: none; border-radius: 4px; cursor: pointer; }
+    .links { margin-top: 40px; }
+    .links a { color: #0066cc; margin: 0 15px; }
+  </style>
+</head>
+<body>
+  <h1>404</h1>
+  <p>Page not found</p>
+  <p>The page you're looking for doesn't exist or was moved.</p>
+  <div class="search">
+    <form action="${homeUrl}" method="get">
+      <input type="text" name="s" placeholder="Search docs...">
+      <button type="submit">Search</button>
+    </form>
+  </div>
+  <div class="links">
+    <a href="${homeUrl}">Home</a>
+  </div>
+</body>
+</html>`;
+
+  fs.writeFileSync(file, notFound);
+  console.log('404.html generated');
+  return file;
+}
+
+/**
+ * Bring any 404 page (generated or user-supplied) into the full pipeline:
+ * injectPage for SEO + an explicit noindex robots meta. Returns the page
+ * model so the orchestrator's late passes treat it like every other page.
+ */
+export function pipeline404(page, context) {
+  let html = fs.readFileSync(page.file, 'utf8');
+  // drop any pre-existing robots meta so ours is the single source of truth
+  // (scan.js's stripper exists for exactly this - one regex, one owner)
+  html = stripRobotsMeta(html);
+  html = html.replace(/<\/head>/i, '<meta name="robots" content="noindex, nofollow">\n</head>');
+  fs.writeFileSync(page.file, html);
+  page.html = html;
+
+  injectPage(page, context);
+  return page;
+}

package/engine/scan.js

@@ -0,0 +1,151 @@
+// engine/scan.js - output tree walk + page model (Phase 1.1)
+// Every page freestruct touches is modeled once here: file path, alias-relative
+// slug, 404 flag, and the pre-injection HTML snapshot the SEO gate needs.
+
+import fs from 'fs';
+import path from 'path';
+import crypto from 'crypto';
+
+/** Recursively list HTML files under dir (exists-checked). */
+export function getHtmlFiles(dir) {
+  const files = [];
+  if (!fs.existsSync(dir)) return files;
+  for (const item of fs.readdirSync(dir, { withFileTypes: true })) {
+    const fp = path.join(dir, item.name);
+    if (item.isDirectory()) files.push(...getHtmlFiles(fp));
+    else if (item.name.endsWith('.html')) files.push(fp);
+  }
+  return files;
+}
+
+/**
+ * Canonical slug for a file relative to the output root.
+ *   index.html       -> '/'
+ *   guide/index.html -> '/guide/'
+ *   a&b.html         -> '/a&b'
+ */
+export function slugFor(rel) {
+  let p = String(rel).replace(/\\/g, '/');
+  if (p === '/index.html' || p === 'index.html') return '/';
+  p = '/' + p;
+  p = p
+    .replace(/\/index\.html$/, '/')
+    .replace(/\.html$/, '');
+  return p;
+}
+
+/** 404.html at root or any directory level is the 404 pipeline's business. */
+export function is404File(rel) {
+  const p = String(rel).replace(/\\/g, '/');
+  return p === '404.html' || p.endsWith('/404.html');
+}
+
+/** Robots noindex detection on (possibly injected) HTML. */
+export function htmlIsNoindex(html) {
+  const m = html.match(/<meta[^>]*name=["']robots["'][^>]*>/i);
+  return Boolean(m && /noindex/i.test(m[0]));
+}
+
+/** Strip any existing robots meta (404 pages get ours, un-duplicated). */
+export function stripRobotsMeta(html) {
+  return html.replace(/<meta[^>]*name=["']robots["'][^>]*>/i, '');
+}
+
+/** Extract SEO candidates from raw page HTML. (kept from 0.3.x semantics) */
+export function extractTitle(html) {
+  const m = html.match(/<meta name="title" content="([^"]+)"/i);
+  if (m) return m[1];
+  const t = html.match(/<title>([^<]+)<\/title>/i);
+  return t ? t[1].split(' | ')[0] : null;
+}
+
+export function extractDescription(html) {
+  const m = html.match(/<meta name="description" content="([^"]+)"/i);
+  return m ? m[1] : null;
+}
+
+/**
+ * Does the page already import SEO of the given type from SSG/frontmatter?
+ * Used by the missing-only injection gate ('description' added in Phase 1: a
+ * plain <meta name="description"> counts as covered).
+ */
+export function hasSeoType(html, type) {
+  if (type === 'og') {
+    return html.includes('property="og:title"') || html.includes('property="og:description"');
+  }
+  if (type === 'twitter') {
+    return html.includes('name="twitter:card"') || html.includes('name="twitter:title"');
+  }
+  if (type === 'jsonld') {
+    return html.includes('application/ld+json');
+  }
+  if (type === 'canonical') {
+    return html.includes('rel="canonical"');
+  }
+  if (type === 'description') {
+    return /<meta[^>]*name=["']description["']/.test(html);
+  }
+  return false;
+}
+
+/**
+ * Snapshot every page once, before freestruct writes anything.
+ * mtime is captured HERE so sitemap lastmod / RSS pubDate reflect the last
+ * real content change (the SSG build), not freestruct's own decoration writes.
+ */
+export function buildPages(files, outputDir) {
+  const pages = [];
+  for (const file of files) {
+    const rel = path.relative(outputDir, file);
+    const html = fs.readFileSync(file, 'utf8');
+    pages.push({
+      file,
+      rel,
+      slug: slugFor(rel),
+      is404: is404File(rel),
+      html,
+      mtime: fs.statSync(file).mtime,
+      title: extractTitle(html),
+      description: extractDescription(html),
+    });
+  }
+  return pages;
+}
+
+/**
+ * Deterministic content hash (ported principle from prestruct's deploy-id
+ * audit: a timestamp-seeded hash churns ?v= asset params and CDN caches on
+ * every run even when nothing changed). Derived from config + the sorted
+ * pre-injection page content, so identical content always yields an
+ * identical hash regardless of build time or machine.
+ *
+ * Everything this tool itself rewrites between runs is stripped or excluded
+ * before hashing: the regenerated last-modified/reading-time/freestruct-build
+ * metas, the previous ?v= bust params, and the whole head region after the
+ * freestruct marker (that region holds the custom header snippet, whose
+ * substituted {{buildHash}} would make the hash self-referential).
+ * blurred lines, accepted consequences:
+ *  - robots metas are excluded too: the 404 pipeline strip-and-reappears it
+ *    at a different position each run (404 is tool-owned anyway); a noindex
+ *    toggle on a user page will therefore not change the bust hash, and the
+ *    page is not crawled either way.
+ *  - a body/footer snippet that embeds {{buildHash}} self-references; that
+ *    is documented as a no-go, not hacked around in the regex.
+ */
+export function computeBuildHash(config, pages) {
+  const h = crypto.createHash('sha1');
+  h.update(JSON.stringify(config || {}));
+  // 404 pages sit outside the hash entirely: freestruct generates the missing
+  // one mid-run (so run 1 and run 2 would otherwise disagree on page count),
+  // and a noindex 404 is never crawled regardless.
+  const stable = (html) => html
+    .replace(/<meta[^>]*name="(freestruct-build|last-modified|reading-time|robots)"[^>]*>/gi, '')
+    .replace(/<!-- freestruct -->[\s\S]*?(?=<\/head>)/i, '')
+    .replace(/\?v=[0-9a-f]{8}/g, '')
+    .replace(/ loading="lazy"/g, '');
+  for (const page of pages.filter(p => !p.is404).sort((a, b) => (a.rel < b.rel ? -1 : a.rel > b.rel ? 1 : 0))) {
+    h.update(page.rel);
+    h.update(stable(page.html));
+  }
+  return h.digest('hex').slice(0, 8);
+}

package/engine/search.js

@@ -0,0 +1,41 @@
+// engine/search.js - search.json generation (Phase 1.1 split)
+// OPT-IN feature (owner decision): only generated when config.searchIndex is
+// explicitly true. FIXES from the 0.4.x state:
+//  - noindex pages are excluded (owner: noindex honored by default, issue #5)
+//  - URLs come from scan.js slugs, so 'noindex.html' no longer becomes /no
+//    and the root page is indexed under '/', not '/index'
+
+import fs from 'fs';
+import path from 'path';
+import { pageUrlFor } from './urls.js';
+
+export function generateSearchIndex(pages, config, outputDir) {
+  const index = [];
+
+  for (const page of pages) {
+    if (page.slug === '/404') continue;
+    // Fresh raw HTML for the content pass (pre-injection snapshot excludes
+    // what freestruct itself writes, but post-injection is what a browser
+    // would search; raw file content at this point is the injected page).
+    const html = fs.readFileSync(page.file, 'utf8');
+
+    const titleMatch = html.match(/<title>([^<]+)<\/title>/i);
+    const descMatch = html.match(/<meta[^>]*name="description"[^>]*content="([^"]+)"/i);
+    const h1Match = html.match(/<h1[^>]*>([^<]+)<\/h1>/i);
+
+    const bodyMatch = html.match(/<body[^>]*>([\s\S]*)<\/body>/i);
+    const content = bodyMatch
+      ? bodyMatch[1].replace(/<[^>]+>/g, ' ').replace(/\s+/g, ' ').trim().slice(0, 500)
+      : '';
+
+    const title = titleMatch ? titleMatch[1].split(' | ')[0] : path.basename(page.file, '.html');
+    const description = descMatch ? descMatch[1] : '';
+    const heading = h1Match ? h1Match[1] : title;
+    const url = pageUrlFor(config, page.slug);
+
+    index.push({ title, heading, description, content, url });
+  }
+
+  fs.writeFileSync(path.join(outputDir, 'search.json'), JSON.stringify(index, null, 2));
+  console.log('search.json generated (' + index.length + ' pages)');
+}