prestruct 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Creadev.org (AUTHOR: 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,160 @@
-# Temporary Holding Version
+# Prestruct
 
-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.
+**Build-time SEO prerender for Vite + React.** Validate your `ssr.config.js`,
+build, inject meta, prerender every route to static HTML. No framework
+migration, no runtime SSR.
+
+---
+
+## Quick Start
+
+```bash
+# In an existing Vite + React project:
+npm i -D prestruct
+npx prestruct init          # never clobbers existing files
+cp ssr.config.example.js ssr.config.js   # then edit siteUrl + routes
+npx prestruct build
+```
+
+Build runs the whole pipeline: validate -> `vite build` -> inject meta ->
+prerender routes. Output lands in `dist/` with one `index.html` per route,
+`sitemap.xml`, and `404.html`.
+
+**Live demo:** https://prestruct.creadev.org (built with prestruct; source in
+`example/`).
+
+Prefer raw npm scripts over the CLI? The `init/` template scaffolds
+`scripts/prerender.js` + `scripts/inject-brand.js` you can wire into
+`package.json` directly -- see [docs/guides/cli.md](./docs/guides/cli.md).
+
+---
+
+## Config
+
+```js
+// ssr.config.js
+export default {
+  siteUrl: 'https://yoursite.com',
+  siteName: 'Your Site',
+  routes: [
+    {
+      path: '/',
+      priority: '1.0',
+      meta: {
+        title: 'Home | Your Site',
+        description: 'Homepage description (150-160 chars).',
+      },
+    },
+    { path: '/about', priority: '0.8', meta: { title: 'About | Your Site' } },
+  ],
+}
+```
+
+Full reference (platform, islands, JSON-LD, `fetchRoutes()`, deployId footer,
+`PRESTRUCT_STRICT`): [docs/guides/config.md](./docs/guides/config.md).
+
+---
+
+## CLI
+
+```bash
+npx prestruct init      # scaffold template files, never clobber
+npx prestruct build     # validate -> vite build -> inject -> prerender
+npx prestruct validate  # check ssr.config.js; exit 1 on bad config
+npx prestruct clean     # clear the prerender route cache
+```
+
+Incremental builds: `.prestruct/cache/` stores rendered HTML; unchanged routes
+are skipped on rebuild unless the shell changes. Fix a config mistake silently?
+Rebuild with a validation pass first (`npx prestruct validate` prints errors
+line-by-line).
+
+---
+
+## Architecture
+
+```
+ssr.config.js
+      |
+      v
+prestruct build (or npm run build in the template)
+      |
+      |- validate        structured [prestruct] diagnostics
+      |- vite build      JS/CSS bundles in dist/assets/
+      |- inject-brand    meta + OG + JSON-LD into dist/index.html
+      `- prerender       vite.ssrLoadModule per route -> static HTML
+```
+
+Static HTML is served directly at deploy time (Cloudflare Pages default). No
+runtime SSR. Client-only dynamic content mounts into `<pre-island>` elements
+after hydration.
+
+---
+
+## Repo layout (this monorepos the npm package)
+
+| Path | Purpose |
+|------|---------|
+| `engine/` | Single source of truth for `prerender.js`, `inject-brand.js`, `validate-config.js`, islands + usePageMeta. |
+| `bin/cli.mjs` | The `prestruct` executable (init/build/validate/clean). |
+| `init/` | Project template `prestruct init` scaffolds, including `scripts/proxy.js` (VPS) and `proxy.worker.js` (Cloudflare Worker). |
+| `example/` | Working demo site (8 routes), kept byte-identical to engine via `scripts/sync-engine.mjs`. |
+| `docs/` | Full docs site, AGENTS-built with Pagefind. |
+| `tests/` | vitest battery, including the engine sync contract test. |
+
+If you touch `engine/`, run `node scripts/sync-engine.mjs` or CI will fail the
+byte-identical check. Details in [AGENTS.md](./AGENTS.md).
+
+---
+
+## Bot proxy (optional, additive)
+
+Prerendered HTML covers every route in `ssr.config.js`. Everything else serves
+the SPA shell. The optional render proxy intercepts bots and serves live
+Puppeteer HTML for the rest -- deploy it on a cheap VPS
+([README-proxy.md](./README-proxy.md), Option A: Node + Puppeteer) or as a
+Cloudflare Worker with Browser Rendering (Option B). Humans always get static
+CF Pages output; the two layers stack, they don't replace each other.
+
+---
+
+## Deploy
+
+- Cloudflare Pages: [docs/guides/cloudflare.md](./docs/guides/cloudflare.md)
+  (`npm run build`, output `dist/`, Node 18+).
+- Any static host works too: `dist/` is a plain static folder.
+
+---
+
+## Stack
+
+- Vite 5+
+- React 18+
+- React Router v6 (v7 works -- engine falls back to the package root when the
+  `./server.js` subpath is absent)
+- Cloudflare Pages default; any static host otherwise
+- Node 18+
+
+---
+
+## Publishing state
+
+`package.json` is at 1.0.0 but **not tagged and not published**. `publish.yml`
+(OIDC trusted publishing on `v*` tags) is wired and dormant -- it
+fires nothing until the first tag exists, by owner decision. When it fires,
+provenance is automatic and no stored npm token is needed.
+
+**Legal:** using prestruct means agreeing to [LICENSE](./LICENSE) and
+[LEGAL.md](./LEGAL.md). Fair-Code: commercial SaaS use is restricted.
+
+---
+
+## Read next
+
+- [AGENTS.md](./AGENTS.md) -- engineering history, gotchas, hard rules,
+  what's in/out of scope.
+- [labs/prd.md](./labs/prd.md) -- roadmap.
+- [docs/](./docs/index.md) -- full site (SEO, routing, islands, proxy,
+  Cloudflare).
+
+_No runtime deps added. Config is the API._

package/bin/cli.mjs

@@ -0,0 +1,212 @@
+#!/usr/bin/env node
+/**
+ * bin/cli.mjs - prestruct CLI
+ * ============================
+ * Commands (spec'd in labs/prd.md Phase 2):
+ *
+ *   prestruct init [dir]    Scaffold the template into dir (default: cwd).
+ *                           Never clobbers existing files.
+ *   prestruct build         Validate config, run vite build, inject meta,
+ *                           prerender routes -- full pipeline from ssr.config.js.
+ *   prestruct validate      Load + validate ssr.config.js; exit 1 on bad config.
+ *   prestruct help          This text.
+ *
+ * The CLI runs inside the USER PROJECT: config comes from <workdir>/ssr.config.js,
+ * vite/react/react-router-dom resolve from the project's own node_modules
+ * (peerDependencies), and build output lands in <workdir>/dist.
+ */
+
+import fs from 'fs'
+import path from 'path'
+import { fileURLToPath, pathToFileURL } from 'url'
+import { execSync } from 'child_process'
+
+process.on('unhandledRejection', (e) => console.error('[prestruct] unhandled rejection:', e && (e.stack || e)))
+
+const cliDir = path.dirname(fileURLToPath(import.meta.url))
+const packageRoot = path.resolve(cliDir, '..')
+
+const { validateConfig, formatDiagnostics } = await import(
+  pathToFileURL(path.join(packageRoot, 'engine/scripts/validate-config.js'))
+)
+const { injectBrand } = await import(
+  pathToFileURL(path.join(packageRoot, 'engine/scripts/inject-brand.js'))
+)
+const { prerender, cleanCache, enginePaths } = await import(
+  pathToFileURL(path.join(packageRoot, 'engine/scripts/prerender.js'))
+)
+
+const HELP = `
+prestruct -- build-time SEO prerender for Vite + React
+
+  prestruct init [dir]     Scaffold the template into dir (default: cwd).
+                           Existing files are never clobbered.
+  prestruct build [--force] [--clean]
+                           Full pipeline: validate -> vite build -> inject
+                           meta -> prerender routes. --force rerenders all
+                           routes; --clean clears the incremental cache first.
+  prestruct validate       Validate ssr.config.js (exit 1 on bad config).
+  prestruct clean          Clear the prerender route cache.
+  prestruct help           This text.
+
+  Config lives in ssr.config.js -- copy ssr.config.example.js to start.
+`
+
+function findWorkdir(args) {
+  // Explicit workdir wins; otherwise walk up from cwd until ssr.config.js is found
+  const [first] = args
+  if (first && !first.startsWith('-')) {
+    return path.resolve(first)
+  }
+  let dir = process.cwd()
+  while (dir !== path.dirname(dir)) {
+    if (fs.existsSync(path.join(dir, 'ssr.config.js'))) return dir
+    dir = path.dirname(dir)
+  }
+  return process.cwd()
+}
+
+async function loadConfig(workdir, { required = true } = {}) {
+  const configPath = path.join(workdir, 'ssr.config.js')
+  if (!fs.existsSync(configPath)) {
+    if (required) {
+      console.error(`[prestruct] ssr.config.js not found in ${workdir}`)
+      console.error('[prestruct] Copy ssr.config.example.js to ssr.config.js and edit it.')
+    }
+    return null
+  }
+  try {
+    return (await import(pathToFileURL(configPath))).default
+  } catch (err) {
+    console.error(`[prestruct] ssr.config.js failed to load: ${err.message}`)
+    return null
+  }
+}
+
+function report(config) {
+  // Returns the ok BOOLEAN (not an object) -- callers must not destructure it.
+  const { ok, errors } = validateConfig(config)
+  if (!ok) formatDiagnostics(errors).forEach(line => console.error(line))
+  return ok
+}
+
+// -- init ----------------------------------------------------------------------
+
+function cmdInit(args) {
+  const target = path.resolve(args.find(a => !a.startsWith('-')) || '.')
+  const templateRoot = path.join(packageRoot, 'init')
+  if (!fs.existsSync(templateRoot)) {
+    console.error('[prestruct] template missing from installed package')
+    process.exit(1)
+  }
+
+  let created = 0, skipped = 0
+  function walk(dir) {
+    for (const entry of fs.readdirSync(dir)) {
+      if (entry === 'node_modules' || entry === 'dist' || entry === '.prestruct') continue
+      // .npmignore belongs to the PACKAGE tarball build (excludes init's local
+      // node_modules/dist from npm pack), not to scaffolded apps. Shipping it
+      // into a user project would silently prune THEIR files if they ever
+      // npm-pack their own package.
+      if (entry === '.npmignore') continue
+      const src = path.join(dir, entry)
+      const dest = path.join(target, path.relative(templateRoot, src))
+      const st = fs.statSync(src)
+      if (st.isDirectory()) {
+        walk(src)
+      } else if (fs.existsSync(dest)) {
+        skipped++
+        console.log(`  skip   ${path.relative(process.cwd(), dest)} (exists)`)
+      } else {
+        fs.mkdirSync(path.dirname(dest), { recursive: true })
+        fs.copyFileSync(src, dest)
+        created++
+        console.log(`  create ${path.relative(process.cwd(), dest)}`)
+      }
+    }
+  }
+  walk(templateRoot)
+
+  console.log(`\n[prestruct] init done: ${created} created, ${skipped} skipped.`)
+  console.log('[prestruct] Next: cp ssr.config.example.js ssr.config.js, edit routes/siteUrl,')
+  console.log('[prestruct] add "prestruct build" (or npm run build) as your build step.')
+}
+
+// -- build ---------------------------------------------------------------------
+
+async function cmdBuild(args) {
+  const workdir = findWorkdir(args)
+  const config = await loadConfig(workdir)
+  if (!config) process.exit(1)
+  const configOk = report(config)
+  if (!configOk && process.env.PRESTRUCT_STRICT === '1') {
+    console.error('[prestruct] PRESTRUCT_STRICT=1 -- failing on config diagnostics')
+    process.exit(1)
+  }
+
+  const run = (cmd) => {
+    console.log(`[prestruct] $ ${cmd}`)
+    execSync(cmd, { cwd: workdir, stdio: 'inherit' })
+  }
+
+  run('npx --no-install vite build')
+  injectBrand(config, path.join(workdir, 'dist'))
+
+  // Forward --force/--clean through to the engine's incremental prerender.
+  // Found live by tarball e2e: without this pass-through, engine accepted the
+  // force flag but CLI silently dropped it -- "cached / (route)" under --force,
+  // which shipped stale static HTML and made users reach for rm -rf.
+  const force = args.includes('--force') || args.includes('-f')
+  if (args.includes('--clean')) {
+    const p = enginePaths(path.resolve(workdir))
+    cleanCache({ cacheFile: p.cacheFile })
+    console.log('[prestruct] prerender cache cleared (--clean)')
+  }
+  const result = await prerender(config, { root: workdir, force })
+  // Engine prerender() returns { total, succeeded, failed, failures }.
+  // Live-fire (2026-10): a route that fails to render still exits 0 -- the
+  // broken deploy rides through green. Match the engine's new contract:
+  // failures are a failed build.
+  if (result && result.failed > 0) {
+    console.error(`[prestruct] prerender failed for ${result.failed}/${result.total} route(s) -- failing build`)
+    process.exit(1)
+  }
+}
+
+// -- validate / clean ----------------------------------------------------------
+
+async function cmdValidate(args) {
+  const workdir = findWorkdir(args)
+  const config = await loadConfig(workdir)
+  if (!config) process.exit(1)
+  const ok = report(config)
+  if (ok) console.log(`[prestruct] ssr.config.js is valid (${(config.routes || []).length} routes)`)
+  else process.exit(1)
+}
+
+function cmdClean(args) {
+  const workdir = findWorkdir(args)
+  const p = enginePaths(path.resolve(workdir))
+  cleanCache({ cacheFile: p.cacheFile })
+}
+
+// -- dispatch ------------------------------------------------------------------
+
+const [command, ...args] = process.argv.slice(2)
+
+try {
+  switch (command || 'help') {
+    case 'init':     cmdInit(args); break
+    case 'build':    await cmdBuild(args); break
+    case 'validate': await cmdValidate(args); break
+    case 'clean':    cmdClean(args); break
+    case 'help':     console.log(HELP); break
+    default:
+      console.error(`[prestruct] unknown command: ${command}`)
+      console.log(HELP)
+      process.exit(1)
+  }
+} catch (err) {
+  console.error(`[prestruct] ${err.message}`)
+  process.exit(1)
+}