freestruct 1.0.0 → 1.1.0

package/engine/inject.js

@@ -8,12 +8,14 @@
 //   notfound.js  404 pipeline
 //   linkcheck.js link validation
 //   search.js    opt-in search.json
-//   hooks.js     purge hooks
+//   hooks.js     purge hooks + postBuild hooks
+//   audit.js     the `freestruct audit` post-build verifier (issue #18)
+//   indexnow.js  IndexNow key emission + submission (issue #19)
 //
 // 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)
+//   validate | init [dir] | audit [--json] [--external] [outputDir] | help  subcommands
 //   --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
@@ -22,6 +24,7 @@
 //
 // FAST_FAIL exit codes (PRD Phase 2, config-first diagnostics):
 //   0 success | 1 config fatal | 2 template missing | 3 output dir missing
+//   4 postBuild hook failure (issue #21: nonzero hook exits fail the build)
 //
 // 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
@@ -32,13 +35,17 @@ import path from 'path';
 import { pathToFileURL, fileURLToPath } from 'url';
 
 import { loadConfig } from './config.js';
-import { getHtmlFiles, buildPages, computeBuildHash, htmlIsNoindex } from './scan.js';
+import { getHtmlFiles, buildPages, computeBuildHash, htmlIsNoindex, hasSeoType } 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';
+import { generateLlms } from './llms.js';
+import { runPurgeHooks, runPostBuildHooks } from './hooks.js';
+import { auditOutput, auditExternalLinks } from './audit.js';
+import { resolveIndexNowKey, emitIndexNowKeyFile, submitIndexNow, isValidIndexNowKey } from './indexnow.js';
+import { resolveOgImageGeneration, renderPageOgImage } from './ogimage.js';
 
 const FLAG_VALUES = new Set(['--version', '--strict', '--tolerant']);
 const _argv = process.argv.slice(2);
@@ -46,14 +53,22 @@ 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 COMMANDS = new Set(['validate', 'init', 'help', 'audit', 'indexnow']);
 const _firstArg = _argv.find(a => !a.startsWith('--'));
 const _positional = _firstArg && !COMMANDS.has(_firstArg) ? _firstArg : undefined;
+// Pass 26.16: dash-shaped args are FLAGS, never output dirs. The audit and
+// indexnow subcommands validate their own flags; the default run must do the
+// same for its set, instead of letting a typo'd flag ride as a positional
+// and inject somewhere the user never meant (the same quiet-mistake class
+// the source-tree guard closes).
+const KNOWN_DEFAULT_DASHES = ['-h', '--help', '--version', '--strict', '--tolerant'];
+const unknownDashArgs = _argv.filter(a => a.startsWith('-') && !KNOWN_DEFAULT_DASHES.includes(a));
 
 export const EXIT_OK = 0;
 export const EXIT_CONFIG = 1;
 export const EXIT_TEMPLATE = 2;
 export const EXIT_OUTPUT = 3;
+export const EXIT_HOOK = 4;
 
 function fail(message, code = EXIT_CONFIG) {
   console.error('[freestruct] ' + message);
@@ -84,10 +99,23 @@ freestruct -- post-build SEO layer for static doc sites
   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 audit [--json] [--external] [outputDir]
+                            Verify the BAKED output (per-page head hygiene +
+                            sitemap/robots/404-noindex contract) without
+                            touching it; exit 0 clean / 1 findings. Works
+                            against any SSG's build (issue #18). --external
+                            also HEAD-checks up to 50 unique external hrefs
+                            (warn-grade; needs a live network).
+  freestruct indexnow [--dry-run] [outputDir]
+                            POST the baked sitemap URL list to api.indexnow.
+                            org (Bing/Seznam/Yandex). POST-deploy step: the
+                            key file emitted during the run must be live.
+                            --dry-run prints the request body for CI.
   freestruct help (--help)  This text.
 
 Flags: --version | --strict | --tolerant
 Exit codes: 0 ok | 1 config fatal | 2 template missing | 3 output dir missing
+            | 4 hook failure | 1 audit findings (audit subcommand)
 `;
 
 function printHelp() {
@@ -145,6 +173,16 @@ function cmdInit(dirArg) {
 const STRICT = _flags.includes('--strict');
 
 export function runInject(options = {}) {
+  // Subcommand exclusivity: validate/init/help/audit/indexnow dispatch and
+  // exit during the module body - the full pass must never run alongside
+  // them (with --external the only path that lives past the import, this
+  // guard is what keeps the engine from re-injecting mid-audit).
+  if (_firstArg && COMMANDS.has(_firstArg)) return;
+  // Unknown dash-words are typos, not directories: fail with the usage hint
+  // instead of riding as a positional (Pass 26.16).
+  if (unknownDashArgs.length) {
+    fail('unknown flag(s): ' + unknownDashArgs.join(' ') + ' - run freestruct --help for the flag list', EXIT_CONFIG);
+  }
   const cwd = options.cwd || process.cwd();
   console.log('freestruct: Loading config...');
 
@@ -161,7 +199,29 @@ export function runInject(options = {}) {
     ? path.resolve(cwd, _positional)
     : path.resolve(configDir, config.outputDir || '_site');
 
+  // File-at-path hardening (Pass 26.13): the existence check alone let an
+  // outputDir pointing at a FILE through, and the tree walk crashed with an
+  // uncaught ENOTDIR stack - fatal errors need a named cause + exit code.
   if (!fs.existsSync(outputDir)) fail('Output directory not found: ' + outputDir, EXIT_OUTPUT);
+  else if (!fs.statSync(outputDir).isDirectory()) fail('Output directory is not a directory: ' + outputDir, EXIT_OUTPUT);
+  // Source-tree hardening (Pass 26.15, tightened after CI): the outputDir
+  // positional accepts any directory, and pointing it at an SSG SOURCE tree
+  // (this repo's docs/, today - committed template copies and layout HTML
+  // injected in place) poisons files silently. Sentinels are ONLY staging
+  // dirs: Jekyll never exports underscore dirs into _site, but it DOES copy
+  // bare files like the config into it (CI hit the over-fire), so config
+  // files are not evidence. Staging dirs inside a built tree mean the
+  // caller aimed at source: abort loudly with the fix spelled out.
+  const sourceMarkers = [
+    ['_layouts', '_layouts/ staging'],
+    ['_freestruct', 'template staging'],
+  ];
+  for (const [marker, meaning] of sourceMarkers) {
+    if (fs.existsSync(path.join(outputDir, marker))) {
+      fail('Refusing to inject: ' + outputDir + ' looks like an SSG source tree (' + meaning +
+        ' found inside). Point freestruct at the BUILT output instead (e.g. docs/_site).', 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
@@ -195,8 +255,29 @@ export function runInject(options = {}) {
     const pages = pagesForHash;
     const sitePages = pages.filter(p => !p.is404);
 
-    // SEO pipeline over every regular page
-    const injectCtx = { config, template, buildHash, snippetDir };
+    // Per-page OG image generation (issue #22) runs BEFORE injection so the
+    // SEO pipeline can wire the fresh PNGs into og/twitter (missing-only:
+    // pages with their own og:image or a per-page override keep theirs).
+    const generation = resolveOgImageGeneration(config, configDir);
+    const generatedImages = {};
+    if (generation) {
+      for (const page of sitePages) {
+        // Noindex pages are excluded from all artifacts (issue #5 posture):
+        // a robots-blocked page needs no share preview.
+        if (htmlIsNoindex(page.html)) continue;
+        // Pages that ship their own og:image keep theirs (missing-only,
+        // the pitch's own rule); a per-page ogImage override also wins
+        // because the seo seam resolves overrides before generation.
+        if (hasSeoType(page.html, 'og')) continue;
+        const rendered = renderPageOgImage(generation, page, config, outputDir);
+        if (rendered) generatedImages[page.slug] = rendered;
+      }
+    }
+
+    // SEO pipeline over every regular page. The injectWarnings array is the
+    // shuttle for per-page image-policy offenses (issue #20): report-only by
+    // default, graduated to build failures by the --strict block below.
+    const injectCtx = { config, template, buildHash, snippetDir, injectWarnings: [], generatedImages };
     for (const page of sitePages) injectPage(page, injectCtx);
 
     // 404 pipeline: generated when absent, user-supplied folded into the
@@ -242,17 +323,30 @@ export function runInject(options = {}) {
     // opt-in search index (owner decision: search.json is opt-in as of Phase 2)
     if (config.searchIndex === true) generateSearchIndex(indexablePages, config, outputDir);
 
+    // opt-in llms.txt (SEO-gap pass, config.llms): the AI-consumable docs
+    // summary, built from the same indexable page set sitemap/feed honor
+    // (noindex stays honored everywhere). Missing-only: an existing file
+    // is never overwritten.
+    if (config.llms === true) generateLlms(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)');
       }
+      // issue #20: SVG og:image offenses collected by the SEO pipeline (the
+      // 404 pipeline included, same ctx) - report-only classes graduate here,
+      // same as broken links.
+      if (injectCtx.injectWarnings.length > 0) {
+        problems.push(injectCtx.injectWarnings.length + ' SVG og:image value(s) (share previews blank; use a raster image or allowSvg: true)');
+      }
       // 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 w of injectCtx.injectWarnings) console.log('  - [issue #20] ' + w);
         for (const b of brokenLinks) console.log('  BROKEN: ' + b.file + ' -> ' + b.link);
         process.exit(1);
       }
@@ -262,6 +356,20 @@ export function runInject(options = {}) {
   // purge hooks, if configured (gated by runHooks)
   if (config.cacheBusting?.purge) runPurgeHooks(config, buildHash, outputDir);
 
+  // indexnow key file (issue #19): emitted during the run so the deployed
+  // keyLocation resolves (the engine that owns the sitemap ships the key
+  // file next to it). Submission is a separate subcommand - post-deploy.
+  const indexNowContext = resolveIndexNowKey(config, configDir);
+  if (indexNowContext) emitIndexNowKeyFile(indexNowContext.key, outputDir);
+
+  // postBuild hooks (issue #21): general commands chained after the pass,
+  // same runHooks gate as the purges. Unlike purges, a nonzero hook exit is
+  // a build failure: exit 4, the first failing hook wins.
+  const hookFailures = runPostBuildHooks(config, buildHash, outputDir);
+  if (hookFailures.length > 0) {
+    fail(hookFailures.length + ' postBuild hook(s) failed (exit ' + hookFailures.map(f => f.status).join(', ') + ')', EXIT_HOOK);
+  }
+
   console.log('freestruct: Done (' + buildHash + ')');
 }
 
@@ -272,8 +380,111 @@ export function runInject(options = {}) {
 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); }
+// ---------- audit subcommand (issue #18) ----------
+
+// `freestruct audit [outputDir] [--json]`: verify the BAKED output (heads +
+// site artifacts) after any freestruct run. Reads only the directory, so it
+// works against any SSG's build. Exit 0 clean / exit 1 findings; a missing
+// output dir is the familiar exit 3. The config is discovered the same way
+// the run walks up from cwd (it maps basePath for the on-disk asset checks);
+// a configless audit just runs without the disk-mapping extras.
+async function cmdAudit() {
+  const auditArgs = _argv.slice(_argv.indexOf('audit') + 1);
+  const useJson = auditArgs.includes('--json');
+  const useExternal = auditArgs.includes('--external');
+  const explicitDir = auditArgs.find(a => !a.startsWith('--'));
+
+  if (auditArgs.filter(a => a.startsWith('--')).some(a => a !== '--json' && a !== '--external')) {
+    fail('audit: only --json and --external are supported flags (got ' + auditArgs.filter(a => a.startsWith('--')).join(' ') + ')');
+  }
+
+  let config = null;
+  let configDir = process.cwd();
+  try {
+    const loaded = loadConfig(process.cwd());
+    config = loaded.config;
+    configDir = loaded.configDir;
+  } catch (e) {
+    console.log('[freestruct] audit: config not discoverable (' + e.message.split('\n')[0] + ') - running without the on-disk asset mapping');
+  }
+
+  const outputDir = explicitDir
+    ? path.resolve(process.cwd(), explicitDir)
+    : path.resolve(configDir, (config && config.outputDir) || '_site');
+
+  if (!fs.existsSync(outputDir) || !fs.statSync(outputDir).isDirectory()) {
+    fail('Output directory not found (or not a directory): ' + outputDir, EXIT_OUTPUT);
+  }
+
+  const result = auditOutput({ outputDir, config, json: useJson && !useExternal, capture: useJson && useExternal });
+  // The no-external path exits HERE, synchronously, exactly like the pre-
+  // --external audit: a sync-crashing auditOutput must never let the
+  // engine's own full pass run on an audit invocation.
+  if (!useExternal) process.exit(result.fails.length > 0 ? 1 : EXIT_OK);
+  // External mode is the only async path: collect the network warn rows
+  // after the local audit, then decide the exit code.
+  const { warns: externalWarns } = await auditExternalLinks({ outputDir, json: useJson });
+  if (useJson) {
+    console.log(JSON.stringify({ ok: result.fails.length === 0, pages: result.pages, fails: result.fails, warns: [...result.warns, ...externalWarns] }));
+  } else {
+    const totalWarns = result.warns.length + externalWarns.length;
+    console.log(result.fails.length === 0
+      ? '[freestruct] audit: 0 failures, ' + totalWarns + ' warning(s) - clean'
+      : '[freestruct] audit: ' + result.fails.length + ' failure(s), ' + totalWarns + ' warning(s) - exiting 1');
+  }
+  process.exit(result.fails.length > 0 ? 1 : EXIT_OK);
+}
+
+// ---------- indexnow subcommand (issue #19) ----------
+
+// `freestruct indexnow [--dry-run] [outputDir]`: read the baked sitemap.xml
+// and POST its URL list to api.indexnow.org. POST-deploy by design - the
+// keyLocation file emitted during the run must be LIVE for the engines to
+// verify ownership, so this is documented as the post-deploy step (CI often
+// wants --dry-run at build time). Exit 0 accepted/dry-run | 1 failure.
+async function cmdIndexNow() {
+  const idxArgs = _argv.slice(_argv.indexOf('indexnow') + 1);
+  const dryRun = idxArgs.includes('--dry-run');
+  const explicitDir = idxArgs.find(a => !a.startsWith('--'));
+
+  if (idxArgs.filter(a => a.startsWith('--')).some(a => a !== '--dry-run')) {
+    fail('indexnow: only --dry-run is a supported flag');
+  }
+
+  let config = null;
+  let configDir = process.cwd();
+  try {
+    const loaded = loadConfig(process.cwd());
+    config = loaded.config;
+    configDir = loaded.configDir;
+  } catch (e) {
+    fail(e.message, EXIT_CONFIG);
+  }
+  if (config.indexNow === undefined || config.indexNow === null || config.indexNow === false) {
+    fail('indexnow: indexNow is not configured in the config (set indexNow: true or { key: "<32-hex>" })', EXIT_CONFIG);
+  }
+  if (typeof config.indexNow === 'string' || (config.indexNow && typeof config.indexNow === 'object' && config.indexNow.key !== undefined)) {
+    const key = typeof config.indexNow === 'string' ? config.indexNow : config.indexNow.key;
+    if (!isValidIndexNowKey(key)) {
+      fail('indexnow: the configured key is not 32 lowercase hex chars - refusing to submit a broken ownership signal', EXIT_CONFIG);
+    }
+  }
+
+  const outputDir = explicitDir
+    ? path.resolve(process.cwd(), explicitDir)
+    : path.resolve(configDir, config.outputDir || '_site');
+  if (!fs.existsSync(outputDir) || !fs.statSync(outputDir).isDirectory()) {
+    fail('Output directory not found (or not a directory): ' + outputDir + ' - run freestruct first (indexnow reads the baked sitemap)', EXIT_OUTPUT);
+  }
+
+  const result = await submitIndexNow({ config, configDir, outputDir, dryRun });
+  process.exit(result.ok ? EXIT_OK : 1);
+}
+
 if (_firstArg === 'validate') cmdValidate();
 if (_firstArg === 'init') cmdInit(_argv[_argv.indexOf('init') + 1]);
+if (_firstArg === 'audit') cmdAudit().catch((e) => fail('audit: ' + (e && e.message ? e.message : e)));
+if (_firstArg === 'indexnow') { cmdIndexNow(); }
 
 // 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

package/engine/linkcheck.js

@@ -7,12 +7,28 @@ 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).
+ *
+ * Two route shapes (Pass 26.10 - the old check acknowledged only literal
+ * files): a target WITH an .html/.htm extension is checked as the file;
+ * an extension-less (pretty-URL) target resolves through the same route
+ * model the walker owns - directory index first (index.html / index.htm),
+ * then the .html/.htm sibling file. Assets stay out of the checker's
+ * purview (see the shape test above the flags).
  */
 export function checkLinks(files, outputDir) {
   const broken = [];
 
   for (const file of files) {
-    const html = fs.readFileSync(file, 'utf8');
+    // Payload stripping (Pass 26.14): inline JS template strings
+    // ("<a href=" + url + ">" shapes) are NOT links; rouge-fenced code
+    // TEACHES link shapes (the style guide's <a href="guides/foo">) -
+    // neither is a route. Scan the document with script, style, pre and
+    // code payloads removed (real nav hrefs never live in any of them).
+    const html = fs.readFileSync(file, 'utf8')
+      .replace(/<script[\s\S]*?<\/script>/gi, '')
+      .replace(/<style[\s\S]*?<\/style>/gi, '')
+      .replace(/<pre[\s\S]*?<\/pre>/gi, '')
+      .replace(/<code[\s\S]*?<\/code>/gi, '');
     const baseDir = path.dirname(file);
 
     const linkRegex = /href="([^"#]+)(?:#[^"]*)?"/g;
@@ -20,18 +36,42 @@ export function checkLinks(files, outputDir) {
     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;
+      // Skip external, absolute-protocol, and ANY scheme-shaped target
+      // (data:, javascript:, tel:, mailto:, ...): schemes are not routes.
+      if (/^[a-z][a-z0-9+.-]*:/i.test(link) || link.startsWith('//')) continue;
 
-      const absPath = path.join(baseDir, link);
+      // Root-relative hrefs (the whole nav menu: "/guides/cli") resolve
+      // against the OUTPUT ROOT - path.join(baseDir, '/x') APPENDS, it never
+      // resets, which turned every menu link on a nested page into a miss
+      // (the CI --strict run caught it). Relative hrefs stay page-relative.
+      const absPath = link.startsWith('/')
+        ? path.join(outputDir, link)
+        : 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');
+      // Targeted file link: extension decides the check shape (case-
+      // insensitive .html/.htm - Pass 26.10, mixed-case SSG output is a
+      // page like any other).
+      if (/\.html?$/i.test(normalized)) {
+        if (!fs.existsSync(normalized)) {
+          broken.push({ file: path.relative(outputDir, file), link });
+        }
+        continue;
       }
 
-      if (normalized.endsWith('.html') && !fs.existsSync(normalized)) {
+      // Pretty-URL link: resolve like the route model - directory index
+      // first, then the .html/.htm sibling. Asset-like targets (their last
+      // segment carries an extension that is not a page route: .css, .js,
+      // .png, .json, ...) are the host's business and stay out of the
+      // link checker.
+      const lastSegment = normalized.split(path.sep).pop() || '';
+      if (lastSegment.includes('.')) continue;
+
+      const dirIndex = fs.existsSync(path.join(normalized, 'index.html'))
+        || fs.existsSync(path.join(normalized, 'index.htm'));
+      const prettySibling = fs.existsSync(path.join(normalized + '.html'))
+        || fs.existsSync(path.join(normalized + '.htm'));
+      if (!dirIndex && !prettySibling) {
         broken.push({ file: path.relative(outputDir, file), link });
       }
     }

package/engine/llms.js

@@ -0,0 +1,52 @@
+// engine/llms.js - llms.txt emission (the SEO-gap pass, config.llms)
+// The AI-consumable docs-summary convention (llmstxt.org shape): one H1, a
+// blockquote tagline, then a Docs section listing every indexable page's
+// title, absolute URL and description. Natural to this engine: the scan
+// pass already carries every page's slug/title/description and the run
+// already owns the indexable (non-noindex) page set - zero new scanning.
+// Generated-only: never overwrites, same contract as sitemap/feed/robots.
+
+import fs from 'fs';
+import path from 'path';
+import { pageUrlFor } from './urls.js';
+
+/**
+ * One line of plain text, whatever it was given: a newline (or CR) inside a
+ * title/description would split a list entry into two, silently corrupting
+ * the summary's shape, and an XML-era control character would ride into the
+ * plain-text file as garbage. Bad bytes drop, whitespace collapses.
+ */
+function oneline(value) {
+  return String(value)
+    .replace(/[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F]/g, '')
+    .replace(/[\r\n]+/g, ' ')
+    .trim();
+}
+
+/**
+ * Write llms.txt into the output dir. Pages only: indexable = non-404,
+ * non-noindex (the same gate sitemap/feed honor, so noindex stays honored
+ * everywhere). Missing-only: an existing llms.txt (hand-rolled or
+ * SSG-written) is never touched.
+ */
+export function generateLlms(indexablePages, config, outputDir) {
+  const target = path.join(outputDir, 'llms.txt');
+  if (fs.existsSync(target)) {
+    console.log('[freestruct] llms.txt exists - leaving it untouched');
+    return null;
+  }
+  const lines = [];
+  lines.push('# ' + oneline(config.site.name));
+  if (config.site.description) lines.push('', '> ' + oneline(config.site.description));
+  lines.push('', '## Docs', '');
+  for (const page of indexablePages) {
+    const url = pageUrlFor(config, page.slug);
+    const title = oneline(page.title || page.slug);
+    const desc = page.description ? ': ' + oneline(page.description) : '';
+    lines.push('- [' + title + '](' + url + ')' + desc);
+  }
+  fs.writeFileSync(target, lines.join('\n') + '\n');
+  const count = indexablePages.length;
+  console.log('[freestruct] llms.txt: emitted for ' + count + ' page(s)');
+  return target;
+}

package/engine/ogimage.js

@@ -0,0 +1,142 @@
+// engine/ogimage.js - per-page OG image generation (issue #22)
+// Post-render OG-image generation: read each page's title/description (the
+// engine already extracts both), render a branded 1200x630 image per page
+// from a consumer-authored SVG template, write it into the output tree, and
+// hand the per-page source to the SEO pipeline so og/twitter tags wire to
+// it (missing-only intact: pages with their own og:image, or a per-page
+// ogImage override, keep theirs).
+//
+// Rasterization honesty (the pitch's own 'hard part'): PNG cannot be made
+// in pure Node. The rasterizer is the OPTIONAL npm package
+// @resvg/resvg-js - loaded lazily with createRequire and loud-skipped when
+// it is not installed (the run never breaks and never ships a half
+// feature). Pure-Node output shape: SVG rendering is deterministic (same
+// page meta -> same bytes; the build hash stays content-derived). Fonts:
+// system fonts are unreliable in build sandboxes, so ogImageGeneration.font
+// loads a TTF/OTF buffer straight into the rasterizer.
+//
+// Config shape (configDir-relative paths):
+//   ogImageGeneration:
+//     template: og-template.svg   # 1200x630 SVG with {{ogTitle}} /
+//                                 # {{ogDescription}} / {{ogUrl}}
+//     font: ./brand/brand-bold.ttf  # optional
+//     width: 1200                  # optional; must be 1200x630 ratio-safe
+//     height: 630                  # optional
+
+import fs from 'fs';
+import path from 'path';
+import { createRequire } from 'module';
+import { escXml } from './xmllike.js';
+import { pageUrlFor } from './urls.js';
+
+const _require = createRequire(import.meta.url);
+
+/** Directory-slug for the image filename: '/' and nested paths flatten. */
+function imageSlug(page) {
+  return page.slug.replace(/^\/+|\/+$/g, '').replace(/\//g, '-') || 'index';
+}
+
+/** Lazily resolve the optional rasterizer CLASS; null when not installed. */
+function resolveRasterizer() {
+  try {
+    const mod = _require('@resvg/resvg-js');
+    // CJS shape: { default?: Resvg, Resvg } ; ESM default handled too.
+    const ctor = mod.Resvg || mod.default || mod;
+    return (typeof ctor === 'function') ? ctor : null;
+  } catch (e) {
+    return null;
+  }
+}
+
+/**
+ * Validate + resolve the generation block. Returns null when it is not
+ * configured; every disqualifying shape logs a loud single warning (config
+ * diagnostics already handled key-name mistakes).
+ */
+export function resolveOgImageGeneration(config, configDir) {
+  const gen = config.ogImageGeneration;
+  if (gen === undefined || gen === null || gen === false) return null;
+  if (typeof gen !== 'object' || Array.isArray(gen)) {
+    console.log('[freestruct] config warning: ogImageGeneration must be a { template, font?, width?, height? } object');
+    return null;
+  }
+  if (typeof gen.template !== 'string' || gen.template === '') {
+    console.log('[freestruct] config warning: ogImageGeneration.template missing - no og image generation');
+    return null;
+  }
+  const templatePath = path.resolve(configDir, gen.template);
+  if (!fs.existsSync(templatePath)) {
+    console.log('[freestruct] config warning: ogImageGeneration.template "'
+      + gen.template + '" not found at ' + templatePath + ' - no og image generation');
+    return null;
+  }
+  const width = Number(gen.width ?? 1200);
+  const height = Number(gen.height ?? 630);
+  if (!Number.isFinite(width) || !Number.isFinite(height) || width <= 0 || height <= 0) {
+    console.log('[freestruct] config warning: ogImageGeneration width/height must be positive numbers - no og image generation');
+    return null;
+  }
+  const fontPath = gen.font ? path.resolve(configDir, gen.font) : null;
+  if (gen.font && (!fontPath || !fs.existsSync(fontPath))) {
+    console.log('[freestruct] config warning: ogImageGeneration.font "'
+      + gen.font + '" not found - the rasterizer will fall back to system fonts (unreliable in build sandboxes)');
+    return null;
+  }
+  const template = fs.readFileSync(templatePath, 'utf8');
+  const fontBytes = fontPath ? fs.readFileSync(fontPath) : null;
+  if (/<text/i.test(template) && !fontBytes) {
+    console.log('[freestruct] ogimage: template carries <text> but no font is configured - add ogImageGeneration.font so build sandboxes without system fonts do not drop titles');
+  }
+  return { template, templatePath, fontPath, fontBytes, width, height };
+}
+
+/**
+ * Render one per-page image and hand back the tag-ready facts.
+ * Returns null when the rasterizer is not installed (loud skip by caller)
+ * or the SVG renders to no bytes.
+ */
+export function renderPageOgImage(generation, page, config, outputDir) {
+  const Resvg = resolveRasterizer();
+  if (!Resvg) {
+    if (!renderPageOgImage._skippedLoudly) {
+      renderPageOgImage._skippedLoudly = true;
+      console.log('[freestruct] ogimage: @resvg/resvg-js is not installed - generation skips loudly'
+        + ' (pure-Node cannot rasterize; install it with: npm install --save-dev @resvg/resvg-js)');
+    }
+    return null;
+  }
+
+  const pageUrl = pageUrlFor(config, page.slug);
+  const displayTitle = page.title || page.rel || 'Preview';
+  let svg = generation.template
+    .split('{{ogTitle}}').join(escXml(displayTitle))
+    .split('{{ogDescription}}').join(escXml(page.description || ''))
+    .split('{{ogUrl}}').join(escXml(pageUrl));
+
+  const fontBuffers = generation.fontBytes ? [generation.fontBytes] : undefined;
+  let png;
+  try {
+    const rendered = new Resvg(svg, {
+      fitTo: { mode: 'width', value: generation.width },
+      font: fontBuffers ? { fontBuffers, loadSystemFonts: false } : { loadSystemFonts: false },
+    });
+    png = rendered.render().asPng();
+  } catch (e) {
+    console.log('[freestruct] ogimage: page ' + page.rel + ' failed to rasterize: ' + e.message);
+    return null;
+  }
+
+  const name = imageSlug(page);
+  const genDir = path.join(outputDir, 'og');
+  if (!fs.existsSync(genDir)) fs.mkdirSync(genDir, { recursive: true });
+  const file = path.join(genDir, name + '.png');
+  fs.writeFileSync(file, png);
+
+  return {
+    file,
+    src: '/og/' + name + '.png',
+    width: generation.width,
+    height: generation.height,
+    alt: displayTitle + ' - page preview image',
+  };
+}