freestruct 0.0.0-stage → 0.9.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dhaupin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,287 @@
-# Temporary Holding Version
+# Freestruct
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**The post-build SEO layer for static doc sites.**
+
+Build your docs with any SSG - Jekyll, Hugo, Docusaurus, MkDocs, VitePress, Astro, Eleventy.
+Then run Freestruct over the output: complete SEO metadata (title, description, canonical,
+Open Graph, Twitter, JSON-LD), `sitemap.xml` with real per-page `lastmod`, `robots.txt`
+with the right sitemap pointer, an RSS `feed.xml` with honest per-page dates, a `404.html`
+that carries noindex, cache-busted assets, and internal-link validation. One dependency
+(`js-yaml`), no SSG plugin, no template edits.
+
+Part of the [Creadev](https://creadev.org) doc-system family - the same docs frame and
+engineering conventions as its siblings (see Project family below).
+
+---
+
+## Quick start
+
+Freestruct runs **after** your SSG, straight into the build output.
+
+### 1. Install
+
+```bash
+npm install --save-dev freestruct
+```
+
+### 2. Create the config
+
+Create `docs/freestruct.config.yml` next to your docs folder (the legacy name
+`docs/ssr-config.yml` is still read; discovery walks upward from your cwd):
+
+```yaml
+# docs/freestruct.config.yml
+site:
+  name: My Docs
+  url: https://example.com/docs
+  description: My documentation
+twitter:
+  username: "@handle"
+og:
+  image: /og-default.png
+```
+
+`site.name` and `site.url` are required; everything else has a working default
+(the full reference is the [Configuration](#configuration) table below, and the
+[config guide](https://freestruct.creadev.org/guides/freestruct-config) goes key by key).
+
+### 3. Build, then inject
+
+```bash
+# your SSG build first
+jekyll build            # or hugo, mkdocs, docusaurus build, ...
+
+# then freestruct
+npx freestruct          # discovers config + output dir automatically
+```
+
+Or wire both into one script:
+
+```json
+// package.json
+{
+  "scripts": {
+    "build": "jekyll build && freestruct"
+  }
+}
+```
+
+### 4. Verify
+
+```bash
+# The injected pages carry canonical + og meta and a build marker
+grep -l 'rel="canonical"' docs/_site/*.html
+
+# Cache-busting marker
+grep -o 'freestruct-build' docs/_site/index.html
+
+# Generated artifacts
+ls docs/_site/{sitemap.xml,robots.txt,feed.xml,404.html}
+```
+
+If any of those fail, Freestruct tells you why: config errors, a missing
+template, and an empty output dir each fail loudly with their own exit code
+(`1` config, `2` template, `3` output dir; `--tolerant` downgrades fatals to
+exit 0 for CI tolerance).
+
+### Useful flags and subcommands
+
+```bash
+npx freestruct --version        # installed version
+npx freestruct --strict         # fail (nonzero) on broken internal links
+                                # (noindex pages are structurally excluded from
+                                # artifacts and wire-guarded by the crashtest pack)
+npx freestruct --tolerant       # report everything, never fail the CI build
+npx freestruct path/to/output   # explicit output dir override
+npx freestruct validate         # config-only preflight; exit 1 on fatal errors
+npx freestruct init             # scaffold the starter kit into ./docs
+                                # (npx freestruct init mydir -> mydir/docs;
+                                #  existing files are never clobbered)
+```
+
+---
+
+## Features
+
+### SEO
+
+- Injects missing title, description, canonical, Open Graph, Twitter cards, and
+  JSON-LD (missing-only: existing tags are left alone)
+- Attribute-safe everywhere: og/twitter values are HTML-escaped, JSON-LD
+  literals are JSON-escaped (a raw `<` cannot close the script tag),
+  `og:image`/`twitter:image` ship only when an image is configured, and an
+  optional `author` key rides the Organization JSON-LD as a schema.org founder
+- Page-level tuning survives the build: a `<!-- freestruct: {...} -->` comment
+  overrides title/description/ogType/ogImage/twitterCard and adds
+  `article:published_time`/`author`/`section`; custom `jsonLd` objects append
+  structured data
+- Honest canonical URLs including sub-path (`basePath`) installs - the same
+  contract holds for the `sitemap.xml` locs, `robots.txt` sitemap pointer, the
+  RSS channel/self links, and the generated 404's home link
+- Tagged with a `freestruct-build` marker comment
+
+### Search
+
+- **Opt-in** `search.json` (set `searchIndex: true`); default runs generate
+  nothing - bring your own indexer (Pagefind/Algolia), the search guide covers
+  the wiring
+
+### Sitemap, robots, feed & 404
+
+- `sitemap.xml`: encoded URLs, real per-file `lastmod` (page mtime, not build
+  time), noindex pages excluded
+- `robots.txt`: `User-agent: *` + `Allow: /` + a basePath-aware sitemap pointer
+- `feed.xml` (RSS): escaped titles/descriptions, per-page `pubDate` from each
+  page's own mtime, basePath-aware channel/self links
+- `404.html`: generated when missing, gets the full SEO pipeline + explicit
+  noindex; a user-supplied 404 gets the same treatment
+
+### Performance
+
+- Cache-busting: asset query params (`?v={hash}`), optional canonical hash
+- Lazy loading on images, reading time + last-modified meta
+
+### DX
+
+- Config schema with loud `[freestruct] config warning` diagnostics; unknown
+  and retired keys never die silently
+- Link validation (report-only by default, `--strict` to make fatal - our own
+  docs CI runs `--strict` and it has already caught three production 404s)
+- Post-render hooks with purge-command safety (disabled by default; see
+  [Security](#security))
+
+---
+
+## Configuration
+
+Full key list (unknown or retired keys produce warnings, not silence):
+
+| Key                                    | Default        | Meaning                                                                                              |
+|----------------------------------------|----------------|------------------------------------------------------------------------------------------------------|
+| `site.name`                            | - (required)   | Site name; composes page titles                                                                       |
+| `site.url`                             | - (required)   | Canonical origin; URLs build from this                                                                |
+| `site.description`                     | -              | Fallback description for pages without one                                                            |
+| `author`                               | *(unset)*      | Author identity; ships as schema.org founder on the Organization JSON-LD                              |
+| `jsonLd`                               | *(unset)*      | Custom JSON-LD object(s) appended to the injected structured data                                     |
+| `basePath`                             | *(unset)*      | URL path prefix the output tree is served under; all generated URLs get exactly this prefix           |
+| `outputDir`                            | `docs/_site`   | Build output directory (or pass it as a CLI arg)                                                      |
+| `generateSitemap`                      | `true`         | Generate `sitemap.xml`                                                                               |
+| `generateRobots`                       | `true`         | Generate `robots.txt`                                                                                |
+| `generateFeed`                         | `true`         | Generate `feed.xml` (RSS)                                                                            |
+| `generate404`                          | `true`         | Generate `404.html` when missing                                                                     |
+| `readingTime`                          | `true`         | Inject `<meta name="reading-time">`                                                                  |
+| `lastModified`                         | `true`         | Inject `<meta name="last-modified">`                                                                 |
+| `lazyLoad`                             | `true`         | Add `loading="lazy"` to images                                                                        |
+| `linkCheck`                            | `true`         | Validate internal links (report-only; `--strict` makes them fatal)                                    |
+| `searchIndex`                          | `false`        | **Opt-in**: generate `search.json` for client-side search                                             |
+| `minify`                               | `false`        | Experimental HTML minifier (preserves `pre`/`script`/`style`/`textarea`)                              |
+| `runHooks`                             | `false`        | Gateway: only `true` lets `cacheBusting.purge` commands execute                                       |
+| `cacheBusting.assetQueryParam`         | `true`         | Append `?v={buildHash}` to linked assets                                                              |
+| `cacheBusting.hashInCanonicalUrl`      | `false`        | Append `?v={buildHash}` to canonical URLs                                                             |
+| `cacheBusting.purge`                   | *(unset)*      | Purge hook list (name + command); disabled without `runHooks: true`                                   |
+
+The docs ([freestruct.creadev.org](https://freestruct.creadev.org)) carry the
+key-by-key guides: the [config reference](https://freestruct.creadev.org/guides/freestruct-config),
+[cache busting](https://freestruct.creadev.org/guides/cache-busting), [custom
+injection](https://freestruct.creadev.org/guides/custom-injection),
+[CLI reference](https://freestruct.creadev.org/guides/cli),
+[post-render hooks](https://freestruct.creadev.org/guides/post-render-hooks),
+[CI/CD](https://freestruct.creadev.org/guides/cicd) and
+[troubleshooting](https://freestruct.creadev.org/guides/troubleshooting).
+
+---
+
+## Security
+
+Purge hooks run shell commands via `execSync`. Enable explicitly in config:
+
+```yaml
+# In freestruct.config.yml
+runHooks: true  # must be set to enable
+cacheBusting:
+  purge:
+    - name: cloudflare
+      command: "cf-cli purge $SITE_URL"
+```
+
+Use only trusted commands. Disabled by default. Available variables:
+`$SITE_URL`, `$BUILD_HASH`, `$OUTPUT_DIR`.
+
+---
+
+## Scaffolding + the crashtest pack
+
+Two shipped surfaces beyond the engine:
+
+- **`init/`** - the consumer scaffold kit: a commented starter config,
+  template copies, and a README ("copy + go"). Version-stamped on
+  `package.json`; `npx freestruct` resolves templates user-staged first,
+  package fallback second.
+- **`packs/`** - Freestruct's [crashtest](https://crashtest.creadev.org) pack
+  surface: `freestruct-docs-shapes` attacks a built docs tree the way a
+  static host serves it (traversal refusal, 404 noindex, noindex artifact
+  leaks, canonical query poisoning, XML shape). See
+  [packs/README.md](packs/README.md). The docs CI runs it against every
+  Pages build.
+
+---
+
+## Releases
+
+- Versions live in one place: `package.json`, pinned in CI against the
+  README/CHANGELOG truth. Single source, no drift.
+- `CHANGELOG.md` is the changelog; releases are tagged (`v*`) and
+  CHANGELOG-truthful or they don't ship.
+- Current release: **0.9.0** (the owner's version call, 2026-10-22; see
+  `labs/TASKS.md` for the version policy).
+- Deployment truth lives in [DEPLOY.md](DEPLOY.md): the GitHub Pages pipeline
+  (this repo's own docs site deploys through it) and the npm release runbook.
+
+## v0.9.0
+
+This number carries the full rehaul-era stack, accumulated under the 0.6.0
+freeze and released as one truthful number by owner call:
+
+- Config renamed to `freestruct.config.yml` with legacy read; schema-checked
+  with loud diagnostics; FAST_FAIL exit codes + `--tolerant`
+- Module decomposition: the engine is `engine/` (one orchestrator + eight
+  modules) with `bin/` shim and shipped templates; `init/` is the consumer
+  scaffold kit; template copies provably in sync via CI
+- `searchIndex` opt-in; noindex honored across sitemap/feed/search/404;
+  basePath contract across every generated URL (canonical, sitemap, feed,
+  robots pointer, 404 home link)
+- Honest XML: escaped values, per-page `lastmod`, per-page RSS dates;
+  escaped-or-fail on un-escapable content
+- Docs: single-source nav, audit gates wired to CI (style, truthfulness,
+  English-only language gate, engine comment format), the docs CI itself
+  runs `--strict` plus the crashtest pack dogfood
+- Release truth: tarball e2e CI gate + hard publish gate; version pinned
+- crashtest pack surface (`packs/public/freestruct-docs-shapes`) with CI
+  teeth on every push and the Pages build
+
+---
+
+## Project family
+
+Freestruct is one member of the Creadev doc-system family. The family shares
+conventions and a docs frame, but each project is separate and
+complimentary - freestruct imports nothing from its siblings.
+
+- [Freestruct docs](https://freestruct.creadev.org) - the docs site built from
+  this repo (`docs/` is itself the worked example: Jekyll + Freestruct + Pagefind)
+- [docs.creadev.org](https://docs.creadev.org) - the Creadev docs system hub
+- [prestruct](https://github.com/dhaupin/prestruct) /
+  [prestruct.creadev.org](https://prestruct.creadev.org) - a separate,
+  complimentary project: a React SSG for Cloudflare Pages that shares the
+  docs frame and conventions (and some gates' patterns) with freestruct, but
+  installs, builds and ships nothing together with it
+- [prestruct docs](https://docs.creadev.org/prestruct) - the prestruct docs
+  layer on the shared system
+- [crashtest](https://crashtest.creadev.org) - adversarial QA for agent-built
+  apps; Freestruct ships and CI-runs its own pack
+- [vant](https://github.com/dhaupin/vant) - the prototype Freestruct was
+  extracted from
+
+For agents: [AGENTS.md](AGENTS.md) is the orientation file (scope, house
+rules, gates). Humans and agents are welcome equally - see
+[CONTRIBUTING.md](CONTRIBUTING.md).

package/bin/freestruct.mjs

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+// Thin CLI entry (prestruct's bin/cli.mjs pattern): the engine lives in
+// engine/, this shim only forwards. Kept separate so the packaged runtime
+// surface (exports) never has to depend on where the CLI wires up.
+import { runInject } from '../engine/inject.js';
+
+runInject();

package/engine/_freestruct/inject-body-start.html

@@ -0,0 +1,2 @@
+<!-- Custom body start - injected after <body> -->
+<!-- Placeholders: {{siteName}}, {{siteUrl}} -->

package/engine/_freestruct/inject-brand.html

@@ -0,0 +1,49 @@
+<!-- freestruct SEO template - post-build injection -->
+<!-- Placeholders: {{pageTitle}}, {{pageDescription}}, {{pageUrl}}, {{canonicalUrl}} -->
+<!-- Config: {{siteUrl}}, {{siteName}}, {{siteDescription}}, {{twitterUsername}}, {{twitterCard}}, {{ogImage}}, {{ogType}}, {{ogLocale}} -->
+
+<meta name="description" content="{{pageDescription}}">
+<link rel="canonical" href="{{canonicalUrl}}">
+
+<!-- Open Graph -->
+<meta property="og:title" content="{{pageTitle}}">
+<meta property="og:description" content="{{pageDescription}}">
+<meta property="og:url" content="{{pageUrl}}">
+<meta property="og:site_name" content="{{siteName}}">
+<meta property="og:type" content="{{ogType}}">
+<meta property="og:locale" content="{{ogLocale}}">
+<meta property="og:image" content="{{ogImageFull}}">
+
+<!-- Twitter -->
+<meta name="twitter:card" content="{{twitterCard}}">
+<meta name="twitter:title" content="{{pageTitle}}">
+<meta name="twitter:description" content="{{pageDescription}}">
+<meta name="twitter:site" content="{{twitterUsername}}">
+<meta name="twitter:creator" content="{{twitterUsername}}">
+<meta name="twitter:image" content="{{ogImageFull}}">
+
+<!-- JSON-LD -->
+<script type="application/ld+json">
+{
+  "@context": "https://schema.org",
+  "@type": "Organization",
+  "name": "{{siteNameJson}}",
+  "url": "{{siteUrlJson}}",
+  "description": "{{siteDescriptionJson}}"{{authorJson}}
+}
+</script>
+
+<script type="application/ld+json">
+{
+  "@context": "https://schema.org",
+  "@type": "WebSite",
+  "name": "{{siteNameJson}}",
+  "url": "{{siteUrlJson}}",
+  "potentialAction": {
+    "@type": "SearchAction",
+    "target": "{{siteUrlJson}}/?s={search_term_string}"
+  }
+}
+</script>
+
+<!-- injected by freestruct: https://github.com/dhaupin/freestruct -->

package/engine/_freestruct/inject-footer.html

@@ -0,0 +1,13 @@
+<!-- Custom footer - injected into every page before </body> -->
+<!-- Placeholders: {{siteName}}, {{siteUrl}}, {{buildHash}} available -->
+
+<!-- Example: Analytics -->
+<!-- <script defer src="{{siteUrl}}/js/analytics.js"></script> -->
+
+<!-- Example: Community chat -->
+<!-- <script src="https://example.com/chat.js"></script> -->
+
+<!-- Example: Custom feedback widget (placeholders: {{siteName}}, {{siteUrl}}, {{buildHash}}) -->
+<!-- <div id="feedback"><a href="{{siteUrl}}/feedback">Feedback</a></div> -->
+
+<!-- freestruct footer: https://github.com/dhaupin/freestruct -->

package/engine/_freestruct/inject-header.html

@@ -0,0 +1,2 @@
+<!-- Custom header - injected before </head> -->
+<!-- Placeholders: {{siteName}}, {{siteUrl}} -->

package/engine/config.js

@@ -0,0 +1,132 @@
+// engine/config.js - config discovery, schema and validation (Phase 2)
+// Discovery order (owner-ratified rename): freestruct.config.yml first, with
+// back-compat reads of the old ssr-config.yml name.
+// Config-first, no magic: unknown flags and retired flags produce loud
+// [freestruct] diagnostics; fatal errors exit (CLI may opt out via --tolerant).
+
+import fs from 'fs';
+import path from 'path';
+import { load as yamlLoad } from 'js-yaml';
+
+export class ConfigError extends Error {}
+
+export const CONFIG_NEW = ['freestruct.config.yml'];
+export const CONFIG_LEGACY = ['ssr-config.yml'];
+
+// Every flag freestruct understands. Phase 2 contract: documented, schema-
+// checked, warn-and-continue on the unknown; nothing dies silently in config
+// files with 'docs said I could do this'.
+export const KNOWN_CONFIG_KEYS = Object.freeze([
+  'site', 'twitter', 'og', 'author', 'jsonLd', 'basePath', 'outputDir', 'minify', 'runHooks',
+  'generateSitemap', 'generateFeed', 'generate404', 'generateRobots',
+  'readingTime', 'lastModified', 'lazyLoad', 'linkCheck', 'searchIndex',
+  'cacheBusting',
+]);
+
+// Flags that EXISTED and no longer do anything. We warn loudly, never guess.
+export const RETIRED_CONFIG_KEYS = Object.freeze([
+  { key: 'preserveExistingMeta', note: 'freestruct only ever injects what is missing (missing-only gate is unconditional); remove this key' },
+  { key: 'generateNav', note: 'nav generation lives in your SSG or the docs frame, not freestruct; remove this key' },
+]);
+
+export const RETIRED_CACHE_KEYS = Object.freeze([
+  { key: 'hash', note: 'dead since 0.4.x (hash is always generated); remove this key' },
+]);
+
+/** Which top-level and nested keys are known, for diagnostics. */
+const KNOWN_CACHE_KEYS = ['assetQueryParam', 'hashInCanonicalUrl', 'purge'];
+
+/** Walk upward from cwd looking for freestruct.config.yml (then ssr-config.yml). */
+export function findConfigPath(cwd = process.cwd()) {
+  let dir = path.resolve(cwd);
+  for (;;) {
+    for (const name of [...CONFIG_NEW, ...CONFIG_LEGACY]) {
+      const candidate = path.join(dir, 'docs', name);
+      if (fs.existsSync(candidate)) return candidate;
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+/** Collect human-readable diagnostics (warnings) for a parsed config. */
+export function collectConfigDiagnostics(config, configName) {
+  const warnings = [];
+  const labels = { others: configName || 'config' };
+
+  for (const key of Object.keys(config)) {
+    if (KNOWN_CONFIG_KEYS.includes(key)) continue;
+    const retired = RETIRED_CONFIG_KEYS.find(r => r.key === key);
+    if (retired) {
+      warnings.push(`retired config key "${key}" has no effect: ${retired.note}`);
+    } else {
+      warnings.push(`unknown config key "${key}" (typo? see the config reference in README.md)`);
+    }
+  }
+
+  if (config.cacheBusting && typeof config.cacheBusting === 'object') {
+    for (const key of Object.keys(config.cacheBusting)) {
+      if (KNOWN_CACHE_KEYS.includes(key)) continue;
+      const retired = RETIRED_CACHE_KEYS.find(r => r.key === key);
+      if (retired) {
+        warnings.push(`retired cacheBusting.${key} has no effect: ${retired.note}`);
+      } else {
+        warnings.push(`unknown cacheBusting key "${key}"`);
+      }
+    }
+  }
+
+  if (config.site) {
+    if (config.site.name === undefined) warnings.push('site.name missing - page titles will compose without a site name');
+    if (config.site.url === undefined) warnings.push('site.url missing - canonical/sitemap/feed urls will be broken');
+  }
+
+  for (const w of warnings) {
+    console.log('[freestruct] config warning: ' + w);
+  }
+  return warnings;
+}
+
+/**
+ * Load + validate the config. Throws ConfigError with consumer-facing
+ * messages (the CLI prints and exits; --tolerant may downgrade).
+ */
+export function loadConfig(cwd = process.cwd()) {
+  const configPath = findConfigPath(cwd);
+  if (!configPath) {
+    throw new ConfigError(`Config not found: docs/freestruct.config.yml (legacy docs/ssr-config.yml also accepted; searched upward from ${cwd})`);
+  }
+
+  let parsed;
+  try {
+    parsed = yamlLoad(fs.readFileSync(configPath, 'utf8'));
+  } catch (e) {
+    throw new ConfigError('Config parse error: ' + e.message);
+  }
+
+  if (!parsed || !parsed.site) {
+    throw new ConfigError('Invalid config: must have site section');
+  }
+  if (!parsed.site.url || !parsed.site.name) {
+    throw new ConfigError('Invalid config: site.url and site.name are required');
+  }
+
+  // Documented env override (ssr-config.md "Environment Overrides"):
+  // FREESTRUCT_URL replaces site.url for staging-style CI runs. Announced,
+  // never silent, and it lands before every canonical/sitemap/feed consumer.
+  if (process.env.FREESTRUCT_URL) {
+    console.log('[freestruct] env override: site.url -> ' + process.env.FREESTRUCT_URL);
+    parsed.site.url = process.env.FREESTRUCT_URL;
+  }
+
+  const configName = path.basename(configPath);
+  collectConfigDiagnostics(parsed, configName);
+
+  return {
+    config: parsed,
+    configPath,
+    configName,
+    configDir: path.dirname(configPath),
+  };
+}

package/engine/hooks.js

@@ -0,0 +1,45 @@
+// engine/hooks.js - purge hooks (Phase 1.1 split)
+// Same security posture as 0.4.x: hooks run only with runHooks: true.
+
+import { execSync } from 'child_process';
+
+export function runPurgeHooks(config, buildHash, outputDir) {
+  const siteUrl = config.site.url;
+  const purgeList = Array.isArray(config.cacheBusting.purge)
+    ? config.cacheBusting.purge
+    : [config.cacheBusting.purge];
+
+  for (const purge of purgeList) {
+    const name = purge.name || 'unnamed';
+    let command = typeof purge === 'string' ? purge : purge.command;
+
+    if (!command) {
+      console.log('Purge hook ' + name + ': no command configured');
+      continue;
+    }
+
+    command = command
+      .replace(/\$SITE_URL/g, siteUrl)
+      .replace(/\$BUILD_HASH/g, buildHash)
+      .replace(/\$OUTPUT_DIR/g, outputDir);
+
+    command = command
+      .replace(/\$\{SITE_URL\}/g, siteUrl)
+      .replace(/\$\{BUILD_HASH\}/g, buildHash)
+      .replace(/\$\{OUTPUT_DIR\}/g, outputDir);
+
+    console.log('Purge hook ' + name + ': running...');
+    try {
+      if (!config.runHooks) {
+        console.log('  Command: ' + command.substring(0, 100) + '...');
+        console.log('  Purge hooks disabled (set runHooks: true to enable)');
+        return;
+      }
+      execSync(command, { stdio: 'inherit', timeout: 30000 });
+      console.log('  Command: ' + command.substring(0, 100) + '...');
+      console.log('Purge hook ' + name + ': done');
+    } catch (e) {
+      console.log('Purge hook ' + name + ': error - ' + e.message);
+    }
+  }
+}