prestruct 1.1.0 → 1.2.0

package/README.md

@@ -1,8 +1,10 @@
 # Prestruct
 
-**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.
+[![crashtest proxy hardening](https://img.shields.io/github/actions/workflow/status/dhaupin/prestruct/crashtest.yml?branch=main&label=crashtest%20hardening)](https://github.com/dhaupin/prestruct/actions/workflows/crashtest.yml)
+
+**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.
+
+Status: **1.2.0, released from the v1.2.0 tag.** npm carries the latest tagged release. `package.json` is the single version source; this line and the side package.jsons are held to it by a test, so a release cannot leave one behind.
 
 ---
 
@@ -16,16 +18,11 @@ 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`.
+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/`).
+**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).
+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).
 
 ---
 
@@ -50,8 +47,7 @@ export default {
 }
 ```
 
-Full reference (platform, islands, JSON-LD, `fetchRoutes()`, deployId footer,
-`PRESTRUCT_STRICT`): [docs/guides/config.md](./docs/guides/config.md).
+Full reference (platform, islands, JSON-LD, `fetchRoutes()`, deployId footer, `PRESTRUCT_STRICT`): [docs/guides/config.md](./docs/guides/config.md).
 
 ---
 
@@ -61,13 +57,12 @@ Full reference (platform, islands, JSON-LD, `fetchRoutes()`, deployId footer,
 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 audit     # grade the baked dist/; exit 1 on FAIL rows
+npx prestruct indexnow  # submit the baked sitemap URLs (--dry-run is CI-safe)
 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).
+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).
 
 ---
 
@@ -85,9 +80,7 @@ prestruct build (or npm run build in the template)
       `- 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.
+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.
 
 ---
 
@@ -96,62 +89,43 @@ after hydration.
 | 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). |
+| `bin/cli.mjs` | The `prestruct` executable (init/build/validate/audit/indexnow/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`. |
-| `packs/` | In-repo crashtest pack (`public/prestruct-proxy` v0.2.0) attacking the bot-proxy pair on both runtimes. |
+| `packs/` | In-repo crashtest pack (`public/prestruct-proxy` v0.4.0) attacking the bot-proxy pair on both runtimes. |
 | `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).
+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.
+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.
 
 ---
 
 ## Crash testing (in-repo pack)
 
-`packs/public/prestruct-proxy` (pack v0.2.0) is this repo's own adversarial
-pack for the bot-proxy pair above: four wire-level contracts (method matrix,
-hostile-path fuzz, bot-render 302 fallback, refresh-secret strict parity),
-run through the [crashtest](https://github.com/dhaupin/crashtest) harness
-against both runtimes. Attack route names come from the host `moduleCtx`, so
-the pack runs against any wiring. Latest results live in
-[labs/hardening.md](./labs/hardening.md), the CI-comparable ledger in
-[labs/crashledger.json](./labs/crashledger.json).
+`packs/public/prestruct-proxy` (pack v0.4.0) is this repo's own adversarial pack for the bot-proxy pair above: five wire-level contracts (method matrix, hostile-path fuzz, bot-render 302 fallback, refresh-secret strict parity, cache-key variant parity), run through the [crashtest](https://github.com/dhaupin/crashtest) harness against both runtimes. Attack route names come from the host `moduleCtx`, so the pack runs against any wiring. Latest results live in [labs/hardening.md](./labs/hardening.md), the CI-comparable ledger in [labs/crashledger.json](./labs/crashledger.json).
 
-The pack travels with the checkout, not the npm tarball. Adopting it from
-another repo is one line in that repo's `crashtest.config.js`:
-`packs: ['/abs/path/to/prestruct/packs']` -- contract table and runbook in
-[packs/README.md](./packs/README.md).
+The pack travels with the checkout, not the npm tarball. Adopting it from another repo is one line in that repo's `crashtest.config.js`: `packs: ['/abs/path/to/prestruct/packs']` -- contract table and runbook in [packs/README.md](./packs/README.md).
 
 ---
 
 ## Deploy
 
-- Cloudflare Pages: [docs/guides/cloudflare.md](./docs/guides/cloudflare.md)
-  (`npm run build`, output `dist/`, Node 20+).
+- Cloudflare Pages: [docs/guides/cloudflare.md](./docs/guides/cloudflare.md) (`npm run build`, output `dist/`, Node 20+).
 - Any static host works too: `dist/` is a plain static folder.
 
 ---
 
 ## Stack
 
-- Vite 5+ (examples and the template battery build on Vite 6)
+- Vite 5+ (the example lane runs Vite 7; the template battery builds on Vite 6)
 - React 18+
-- React Router v6 and v7 both work: v6 via the `./server.js` subpath, v7 via
-  the package-root fallback -- scaffold imports use the namespace+destructure
-  form so CJS v7 passes vite SSR (docs and generated HTML render from v7 live)
+- React Router v6 and v7 both work: v6 via the `./server.js` subpath, v7 via the package-root fallback -- scaffold imports use the namespace+destructure form so CJS v7 passes vite SSR (docs and generated HTML render from v7 live)
 - Cloudflare Pages default; any static host otherwise
 - Node 20+
 
@@ -159,29 +133,19 @@ another repo is one line in that repo's `crashtest.config.js`:
 
 ## Publishing state
 
-**prestruct is on npm: <https://www.npmjs.com/package/prestruct>** (1.1.0,
-published via `publish.yml`, GitHub Actions OIDC trusted publishing with
-npm provenance -- verify with `npm audit signatures`). Tags drive releases:
-`v*` triggers npm publish plus the GitHub release archive (template zip with
-a self-testing battery). `main` may be ahead of the latest tag; its version
-pins are the next planned release.
+**prestruct is on npm: <https://www.npmjs.com/package/prestruct>** (1.2.0 is the latest tagged release, published from the v1.2.0 tag). Releases go through `publish.yml`, GitHub Actions OIDC trusted publishing with npm provenance -- verify with `npm audit signatures`. The tag drives the whole lane: npm publish, then a GitHub release cut from the same tag with its notes extracted from `CHANGELOG.md`. `main` may be ahead of the latest tag; its version pins are the next planned release.
 
-Local install test from the registry tarball (35 files) passed: `init` never
-clobbers, `build` produces full `dist/` (baked meta, sitemap, 404). The
-release-body template inside `release.yml` was corrected in the v1.0.0
-aftermath to match what the archive actually contains.
+Local install test from the registry tarball passed: `init` never clobbers, `build` produces full `dist/` (baked meta, sitemap, 404).
 
-**Legal:** using prestruct means agreeing to [LICENSE](./LICENSE) and
-[LEGAL.md](./LEGAL.md). Fair-Code: commercial SaaS use is restricted.
+**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.
+- [AGENTS.md](./AGENTS.md) -- engineering history, gotchas, hard rules, what's in/out of scope.
 - [labs/prd-prestruct.md](./labs/prd-prestruct.md) -- roadmap.
-- [docs/](./docs/index.md) -- full site (SEO, routing, islands, proxy,
-  Cloudflare).
+- [docs/](./docs/index.md) -- full site (SEO, routing, islands, proxy, Cloudflare).
+- **The workshop** -> [Creadev.org](https://creadev.org) (the same home as the docs, the demo, and the npm package).
 
 _No runtime deps added. Config is the API._

package/bin/cli.mjs

@@ -9,6 +9,14 @@
  *   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 audit         Verify the BAKED dist/ (head hygiene, sitemap,
+ *                           robots, 404 noindex) without touching it; exit 1
+ *                           on FAIL-class findings, warnings never fail.
+ *   prestruct indexnow      Key file into dist/ + submit the baked sitemap
+ *                           URLs to api.indexnow.org (--dry-run prints the
+ *                           request body without touching the network); the
+ *                           submission only counts once the output is DEPLOYED
+ *                           (keyLocation must resolve).
  *   prestruct help          This text.
  *
  * The CLI runs inside the USER PROJECT: config comes from <workdir>/ssr.config.js,
@@ -26,15 +34,24 @@ process.on('unhandledRejection', (e) => console.error('[prestruct] unhandled rej
 const cliDir = path.dirname(fileURLToPath(import.meta.url))
 const packageRoot = path.resolve(cliDir, '..')
 
-const { validateConfig, formatDiagnostics } = await import(
+const { validateConfig, formatDiagnostics, configKeyWarnings, formatConfigWarnings } = 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(
+const { prerender, cleanCache, enginePaths, generateSitemap, assertXmlSafe } = await import(
   pathToFileURL(path.join(packageRoot, 'engine/scripts/prerender.js'))
 )
+const { auditOutput, auditExternalLinks, auditInternalLinks } = await import(
+  pathToFileURL(path.join(packageRoot, 'engine/scripts/audit.js'))
+)
+const { runPostBuildHooks } = await import(
+  pathToFileURL(path.join(packageRoot, 'engine/scripts/hooks.js'))
+)
+const { submitIndexNow, emitIndexNowKeyFile, resolveIndexNowKey, readSitemapUrls } = await import(
+  pathToFileURL(path.join(packageRoot, 'engine/scripts/indexnow.js'))
+)
 
 const HELP = `
 prestruct -- build-time SEO prerender for Vite + React
@@ -43,20 +60,43 @@ prestruct -- build-time SEO prerender for Vite + React
                            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.
+                           meta -> prerender routes -> hooks.postBuild ->
+                           audit (FAIL-class findings fail the build).
+                           --force rerenders all routes; --clean clears the
+                           incremental cache first.
   prestruct validate       Validate ssr.config.js (exit 1 on bad config).
+  prestruct audit [--json] [--external] [--internal] [dist]
+                           Verify the BAKED output (per-page head hygiene,
+                           duplicate-tag probes, og:image raster check,
+                           JSON-LD parse, sitemap/robots/404-noindex) without
+                           touching it. Exit 0 clean / 1 FAIL-class findings
+                           (length bands and absent companions are report-
+                           grade warnings and never fail). --external also
+                           HEAD-checks up to 50 unique external hrefs
+                           (warn-grade, needs live network); --internal lists
+                           unresolved internal hrefs (warn-grade). A target
+                           dir defaults to the config-owning project's dist/.
+  prestruct indexnow [--dry-run] [dist]
+                           Write the IndexNow key file into dist/ and POST
+                           the baked sitemap URLs to api.indexnow.org.
+                           --dry-run prints the request body untouched
+                           (CI-safe). Runs against a DEPLOYED output only:
+                           keyLocation must resolve for engines to accept.
   prestruct clean          Clear the prerender route cache.
+  prestruct --version      Print the engine version (also -v).
   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)
+  // Explicit workdir wins; otherwise walk up from cwd until ssr.config.js is
+  // found. Positional is position-independent (first non-flag), same contract
+  // as cmdInit/cmdAudit -- `prestruct build --force dir` used to read only
+  // args[0], see the flag, and silently build from cwd instead of dir.
+  const positional = args.find(a => !a.startsWith('-'))
+  if (positional) {
+    return path.resolve(positional)
   }
   let dir = process.cwd()
   while (dir !== path.dirname(dir)) {
@@ -85,14 +125,45 @@ async function loadConfig(workdir, { required = true } = {}) {
 
 function report(config) {
   // Returns the ok BOOLEAN (not an object) -- callers must not destructure it.
+  // Key warnings (#52) print alongside shape diagnostics but never fail: a
+  // typo'd key that does nothing says so loudly, diagnostics stay gates-free.
   const { ok, errors } = validateConfig(config)
   if (!ok) formatDiagnostics(errors).forEach(line => console.error(line))
+  formatConfigWarnings(configKeyWarnings(config)).forEach(line => console.warn(line))
   return ok
 }
 
+// -- quiet-mistake refusal (#54) --------------------------------------------
+//
+// A dash-shaped arg that is not a known flag was previously SILENTLY IGNORED
+// (build/validate/clean walked past it; init skipped it). The user meant a
+// flag and got, or lost, behavior they asked for with no signal -- the same
+// class freestruct hardened (26.16). Refuse loudly, exit 1, name the flags.
+// --help is a first-class flag on every command; print help and exit 0.
+
+function checkFlags(command, args, knownFlags) {
+  if (args.includes('--help')) {
+    console.log(HELP)
+    process.exit(0)
+  }
+  const unknown = args.filter(a => a.startsWith('-') && !knownFlags.includes(a))
+  if (unknown.length) {
+    console.error(`[prestruct] unknown flag(s): ${unknown.join(' ')} - the command takes no flags beyond: ${knownFlags.join(' ') || '(none)'}`)
+    console.error('[prestruct] run prestruct help for the command list')
+    process.exit(1)
+  }
+}
+
+const INIT_FLAGS   = []
+const BUILD_FLAGS  = ['--force', '-f', '--clean']
+const AUDIT_FLAGS  = ['--json', '--external', '--internal']
+const INDEXNOW_FLAGS = ['--dry-run']
+const NO_FLAGS     = []
+
 // -- init ----------------------------------------------------------------------
 
 function cmdInit(args) {
+  checkFlags('init', args, INIT_FLAGS)
   const target = path.resolve(args.find(a => !a.startsWith('-')) || '.')
   const templateRoot = path.join(packageRoot, 'init')
   if (!fs.existsSync(templateRoot)) {
@@ -135,6 +206,7 @@ function cmdInit(args) {
 // -- build ---------------------------------------------------------------------
 
 async function cmdBuild(args) {
+  checkFlags('build', args, BUILD_FLAGS)
   const workdir = findWorkdir(args)
   const config = await loadConfig(workdir)
   if (!config) process.exit(1)
@@ -171,11 +243,135 @@ async function cmdBuild(args) {
     console.error(`[prestruct] prerender failed for ${result.failed}/${result.total} route(s) -- failing build`)
     process.exit(1)
   }
+
+  // hooks.postBuild (#41): the pipeline owns these, so direct engine/CI
+  // invocations can no longer silently skip them the way the old npm-script
+  // chain could. Nothing executes without runHooks: true (surfaced loudly);
+  // per-hook failures collect here and turn the build itself red.
+  const hookFailures = runPostBuildHooks(config, {
+    siteUrl: config.siteUrl || '',
+    outputDir: path.join(workdir, 'dist'),
+  })
+  if (hookFailures.length > 0) {
+    console.error(`[prestruct] ${hookFailures.length} postBuild hook(s) failed -- failing build`)
+    process.exit(1)
+  }
+
+  // Audit gate: the docs promise `prestruct build` ends in the audit, so a
+  // head regression fails the build (docs/guides/cli.md). The npm-script
+  // chain in init/ ends with audit-if-configured.cjs; the CLI path must too,
+  // or CLI users get no gate. Warnings never fail, FAIL-class findings do.
+  const audit = auditOutput({ outputDir: path.join(workdir, 'dist'), config })
+  if (audit.fails.length > 0) {
+    console.error(`[prestruct] audit: ${audit.fails.length} FAIL-class finding(s) -- failing build`)
+    for (const f of audit.fails) console.error(`  FAIL ${f.page}: ${f.msg}`)
+    process.exit(1)
+  }
+  console.log(`[prestruct] audit: 0 failures, ${audit.warns.length} warning(s) - clean`)
+}
+
+// -- indexnow ------------------------------------------------------------------
+// Configless by design (mirrors audit): when a config is discoverable it
+// supplies the key; without one, only --dry-run against a baked tree makes
+// sense (the key comes from config; no config = nothing to submit).
+async function cmdIndexNow(args) {
+  checkFlags('indexnow', args, INDEXNOW_FLAGS)
+  const dryRun = args.includes('--dry-run')
+  const explicitDir = args.find(a => !a.startsWith('-'))
+
+  let config = null
+  let workdir = process.cwd()
+  let dir = process.cwd()
+  while (dir !== path.dirname(dir)) {
+    const candidate = path.join(dir, 'ssr.config.js')
+    if (fs.existsSync(candidate)) {
+      workdir = dir
+      config = await loadConfig(dir, { required: false })
+      break
+    }
+    dir = path.dirname(dir)
+  }
+  const outputDir = explicitDir
+    ? path.resolve(process.cwd(), explicitDir)
+    : path.join(workdir, 'dist')
+
+  // Key-file emission runs on the verb too (not only build): a host that
+  // hand-curated dist/ still needs the keyLocation file to ship.
+  const resolved = config ? resolveIndexNowKey(config, enginePaths(path.resolve(workdir)).cacheDir) : null
+  if (resolved) emitIndexNowKeyFile(resolved.key, outputDir)
+
+  const result = await submitIndexNow({ config: config || {}, configDir: enginePaths(path.resolve(workdir)).cacheDir, outputDir, dryRun })
+  if (!result.ok) process.exit(1)
+}
+
+// -- audit ---------------------------------------------------------------------
+
+// Configless by design: the audit verifies any baked tree. When ssr.config.js
+// IS discoverable it feeds the site-local og:image/JSON-LD disk mapping and
+// switches robots.txt grading on (the engine owns that file only under
+// config.robots; the author's public/robots.txt is never engine-touched).
+async function cmdAudit(args) {
+  checkFlags('audit', args, AUDIT_FLAGS)
+  const useJson = args.includes('--json')
+  const explicitDir = args.find(a => !a.startsWith('-'))
+
+  let config = null
+  let workdir = process.cwd()
+  let dir = process.cwd()
+  while (dir !== path.dirname(dir)) {
+    const candidate = path.join(dir, 'ssr.config.js')
+    if (fs.existsSync(candidate)) {
+      workdir = dir
+      config = await loadConfig(dir, { required: false })
+      break
+    }
+    dir = path.dirname(dir)
+  }
+
+  const outputDir = explicitDir
+    ? path.resolve(process.cwd(), explicitDir)
+    : path.join(workdir, 'dist')
+
+  // capture (never let auditOutput print its own digest) whenever the caller
+  // owns the JSON line below: the old `json: useJson && !--external` printed
+  // auditOutput's digest AND then the combined digest, so a plain `audit
+  // --json` emitted two concatenated JSON objects -- unparseable for jq/CI.
+  const result = auditOutput({ outputDir, config, capture: useJson })
+
+  const internal = args.includes('--internal') ? auditInternalLinks({ outputDir }) : []
+  if (internal.length && !useJson) {
+    console.log('[prestruct] internal link check: ' + internal.length + ' broken link(s)')
+    for (const b of internal) console.log('  WARN ' + b.file + ' -> ' + b.link)
+  }
+
+  const external = args.includes('--external') ? await auditExternalLinks({ outputDir, json: useJson }) : { warns: [] }
+
+  if (useJson) {
+    console.log(JSON.stringify({
+      ok: result.fails.length === 0,
+      pages: result.pages,
+      fails: result.fails,
+      warns: [
+        ...result.warns,
+        ...internal.map(b => ({ page: b.file, msg: 'broken internal link: ' + b.link })),
+        ...external.warns,
+      ],
+    }))
+  } else if (internal.length || external.warns.length) {
+    // Aux probes appended rows the base report never saw; pure-local audits
+    // keep auditOutput's single verdict (one verdict, not two).
+    const totalWarns = result.warns.length + internal.length + external.warns.length
+    console.log(result.fails.length === 0
+      ? '[prestruct] audit: 0 failures, ' + totalWarns + ' warning(s) - clean'
+      : '[prestruct] audit: ' + result.fails.length + ' failure(s), ' + totalWarns + ' warning(s)')
+  }
+  process.exit(result.fails.length > 0 ? 1 : 0)
 }
 
 // -- validate / clean ----------------------------------------------------------
 
 async function cmdValidate(args) {
+  checkFlags('validate', args, NO_FLAGS)
   const workdir = findWorkdir(args)
   const config = await loadConfig(workdir)
   if (!config) process.exit(1)
@@ -185,6 +381,7 @@ async function cmdValidate(args) {
 }
 
 function cmdClean(args) {
+  checkFlags('clean', args, NO_FLAGS)
   const workdir = findWorkdir(args)
   const p = enginePaths(path.resolve(workdir))
   cleanCache({ cacheFile: p.cacheFile })
@@ -199,8 +396,19 @@ try {
     case 'init':     cmdInit(args); break
     case 'build':    await cmdBuild(args); break
     case 'validate': await cmdValidate(args); break
+    case 'audit':    await cmdAudit(args); break
+    case 'indexnow': await cmdIndexNow(args); break
     case 'clean':    cmdClean(args); break
-    case 'help':     console.log(HELP); break
+    case 'version':
+    case '--version':
+    case '-v': {
+      const pkg = JSON.parse(fs.readFileSync(path.join(packageRoot, 'package.json'), 'utf8'))
+      console.log(pkg.version)
+      break
+    }
+    case 'help':
+    case '--help':
+    case '-h':       console.log(HELP); break
     default:
       console.error(`[prestruct] unknown command: ${command}`)
       console.log(HELP)