@marvalt/digivalt-core 0.2.6 → 0.2.9

package/CHANGELOG.md

@@ -5,6 +5,28 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.9] - 2026-04-03
+
+### Added
+- **Template + init:** **`functions/sitemap.xml.ts`** — Cloudflare Pages handler for **`/sitemap.xml`** using **`VITE_SEO_SITE_URL`** / **`SITE_URL`** and **`public/sitemap-paths.json`** (no WordPress). Default **`template/public/sitemap-paths.json`**. Listed in **`TEMPLATE_MANAGED_FILES`** for `--force-template` refresh of the handler only.
+
+### Changed
+- **Docs:** `DIGIVALT_SETUP.md`, **`docs/SEO-PERFORMANCE.md`** — sitemap section.
+
+## [0.2.8] - 2026-04-03
+
+### Changed
+- **Init env template:** `.env.example` managed SEO block comments now point to **`react-helmet-async` / `HelmetProvider`**, **`DigiValtSeoHead`**, and **`node_modules/@marvalt/digivalt-core/docs/SEO-PERFORMANCE.md`**.
+
+## [0.2.7] - 2026-04-03
+
+### Added
+- **`digivalt-init`:** Creates or reconciles **`.env.example`** and **`.env.local.example`** via a DigiValt-managed marker block (`bin/env-example-fragments.cjs`); preserves custom lines outside the block; appends with a warning when an existing file has no markers.
+
+### Changed
+- **Template `scripts/deploy-secrets.js`:** Allowlist extended with **`VITE_SEO_*`** and **`TURNSTILE_*`** (e.g. server-only `TURNSTILE_SECRET_KEY`).
+- **Docs:** `DIGIVALT_SETUP.md` (template + landing), `README.md` init / deploy-secrets notes updated for env templates and SEO secrets.
+
 ## [0.2.6] - 2026-04-09
 
 ### Changed (breaking)

package/README.md

@@ -43,6 +43,7 @@ Useful flags:
 What init now does:
 
 - copies missing template files into the app
+- creates or updates **`.env.example`** and **`.env.local.example`** using a marker-wrapped DigiValt-managed block (safe to rerun; custom lines outside the block are preserved)
 - adds or updates `generate`, `build`, and `build:dev` scripts when the app is still on plain Vite wiring
 - refreshes `scripts/generate.ts` when it matches an older DigiVAlt-managed version
 - warns instead of overwriting custom build logic or custom generator scripts
@@ -64,6 +65,6 @@ Use `node scripts/deploy-secrets.js` after `digivalt-init`.
 
 The helper now:
 
-- uploads only DigiVAlt-related environment variables
+- uploads only DigiVAlt-related environment variables (including **`VITE_SEO_*`** and server-only **`TURNSTILE_SECRET_KEY`** when present)
 - skips known local-only variables such as `VITE_LOCAL_DEVELOPMENT`
 - fails with a non-zero exit code when Wrangler or project detection fails

package/bin/env-example-fragments.cjs

@@ -0,0 +1,101 @@
+/**
+ * Managed inner bodies for digivalt-init (placed between start/end markers).
+ * Keep in sync with generators, getIntegrationConfig / vite-env, and deploy-secrets allowlist.
+ */
+
+const ENV_EXAMPLE_MANAGED_BODY = `# WordPress / static generation (public URLs)
+VITE_WORDPRESS_API_URL=https://cms.example.com/wp-json
+# direct | cloudflare_proxy | supabase_proxy
+VITE_AUTH_MODE=direct
+VITE_CLOUDFLARE_WORKER_URL=
+VITE_LOCAL_DEVELOPMENT=false
+
+# Multi-frontend (digivalt-multi-frontends)
+VITE_FRONTEND_ID=my-app
+VITE_FRONTEND_NAME=My App
+
+VITE_ENABLED_POST_TYPES=posts,pages
+VITE_DEFAULT_MAX_ITEMS=200
+VITE_USE_DSTYLER=true
+
+# Optional: Gravity Forms API base if not derived from WordPress URL
+# VITE_GRAVITY_FORMS_API_URL=
+
+# Integration URLs only (secrets belong in .env.local)
+VITE_MAUTIC_URL=
+VITE_MAUTIC_PROXY_URL=
+VITE_SUITECRM_URL=
+VITE_SUITECRM_PROXY_URL=
+VITE_SUPABASE_URL=
+VITE_SUPABASE_ANON_KEY=
+
+VITE_CHATWOOT_BASE_URL=
+VITE_CHATWOOT_WEBSITE_TOKEN=
+
+# Cloudflare account (wrangler / deploy-secrets; not a Vite embed unless duplicated as VITE_)
+CLOUDFLARE_ACCOUNT_ID=
+
+# SEO — consumed by getSEOConfig / DigiValtSeoHead (peer: react-helmet-async + root HelmetProvider).
+# Guide: node_modules/@marvalt/digivalt-core/docs/SEO-PERFORMANCE.md
+VITE_SEO_SITE_URL=https://www.example.com
+VITE_SEO_SITE_NAME=Example Site
+VITE_SEO_DEFAULT_TITLE=Example Site
+VITE_SEO_DEFAULT_DESCRIPTION=A short description for search results.
+VITE_SEO_DEFAULT_KEYWORDS=
+VITE_SEO_DEFAULT_OG_IMAGE=https://www.example.com/og-default.jpg
+VITE_SEO_TWITTER_SITE=@example
+VITE_SEO_FACEBOOK_APP_ID=
+VITE_SEO_GOOGLE_SITE_VERIFICATION=
+VITE_SEO_BING_SITE_VERIFICATION=
+
+# Performance toggles (optional; omit to use defaults in getPerformanceConfig)
+# VITE_PERF_LAZY_LOADING=true
+# VITE_PERF_IMAGE_OPTIMIZATION=true
+# VITE_PERF_CODE_SPLITTING=true
+# VITE_PERF_SERVICE_WORKER=false
+# VITE_PERF_CACHING=true`;
+
+const ENV_LOCAL_EXAMPLE_MANAGED_BODY = `# WordPress application password (static generation + API)
+VITE_WP_API_USERNAME=
+VITE_WP_APP_PASSWORD=
+# Optional aliases for Node-only scripts (see digivalt-core generators)
+# WP_API_USERNAME=
+# WP_APP_PASSWORD=
+
+# Cloudflare Access (WordPress behind Zero Trust)
+VITE_CF_ACCESS_CLIENT_ID=
+VITE_CF_ACCESS_CLIENT_SECRET=
+
+# Mautic API credentials
+VITE_MAUTIC_API_PUBLIC_KEY=
+VITE_MAUTIC_API_SECRET_KEY=
+
+# Gravity Forms REST consumer keys (if used)
+VITE_GF_CONSUMER_KEY=
+VITE_GF_CONSUMER_SECRET=
+
+# SuiteCRM (when SuiteCRM static generation is enabled)
+VITE_SUITECRM_CLIENT_ID=
+VITE_SUITECRM_CLIENT_SECRET=
+VITE_SUITECRM_USERNAME=
+VITE_SUITECRM_PASSWORD=
+
+# Supabase service role (only if needed; never expose in client bundles inappropriately)
+# VITE_SUPABASE_SERVICE_ROLE_KEY=
+
+# cf-wp-webhook-refresh + Cloudflare Pages Functions
+VITE_FRONTEND_SECRET=
+VITE_WP_REFRESH_SECRET=
+
+# Turnstile — site key for browser; secret is server-only for Pages Functions
+VITE_TURNSTILE_SITE_KEY=
+TURNSTILE_SECRET_KEY=
+
+# Optional: npm publish / CI
+# NPM_TOKEN=
+`;
+
+module.exports = {
+  ENV_EXAMPLE_MANAGED_BODY,
+  ENV_LOCAL_EXAMPLE_MANAGED_BODY,
+};

package/bin/init.cjs

@@ -3,6 +3,15 @@
 const fs = require('fs');
 const path = require('path');
 
+const {
+  ENV_EXAMPLE_MANAGED_BODY,
+  ENV_LOCAL_EXAMPLE_MANAGED_BODY,
+} = require('./env-example-fragments.cjs');
+
+const ENV_MANAGED_START =
+  '# --- DigiValt: managed by digivalt-init (do not edit this block by hand; rerun init to refresh) ---';
+const ENV_MANAGED_END = '# --- End DigiValt ---';
+
 const sourceDir = path.join(__dirname, '..', 'template');
 const args = process.argv.slice(2);
 
@@ -15,6 +24,7 @@ const TEMPLATE_MANAGED_FILES = new Set([
   '.dev.vars.example',
   'DIGIVALT_SETUP.md',
   'functions/api/fetch-with-access.ts',
+  'functions/sitemap.xml.ts',
   'functions/api/gravity-forms-submit.ts',
   'functions/api/mautic-submit.ts',
   'functions/api/webhook.js',
@@ -332,6 +342,57 @@ function reconcileGenerateScript(status, templateGenerateScript) {
   }
 }
 
+function buildEnvManagedBlock(managedBody) {
+  return `${ENV_MANAGED_START}\n${managedBody}\n${ENV_MANAGED_END}`;
+}
+
+function reconcileEnvExampleFile(relativePath, managedBody) {
+  const fullPath = path.join(targetDir, relativePath);
+  const block = buildEnvManagedBlock(managedBody);
+  const existing = readTextIfExists(fullPath);
+
+  const header =
+    relativePath === '.env.example'
+      ? '# DigiValt — public / team template (safe to commit). Use `.env` locally if your tooling expects `.env` only.'
+      : '# DigiValt — secrets template (commit as `.env.local.example`). Copy to `.env.local`; never commit real secrets.';
+
+  if (!existing) {
+    const out = `${header}\n\n${block}\n\n# Add project-specific variables below.\n`;
+    writeFileWithMode(fullPath, out);
+    report.refreshedFiles.push(
+      dryRun ? `Would create ${relativePath} with DigiValt env template.` : `Created ${relativePath} with DigiValt env template.`
+    );
+    return;
+  }
+
+  const startIndex = existing.indexOf(ENV_MANAGED_START);
+  const endIndex = existing.indexOf(ENV_MANAGED_END);
+  if (startIndex !== -1 && endIndex !== -1 && endIndex > startIndex) {
+    const before = existing.slice(0, startIndex).replace(/\s*$/, '');
+    const after = existing.slice(endIndex + ENV_MANAGED_END.length);
+    const out = `${before}\n\n${block}${after}`;
+    writeFileWithMode(fullPath, out);
+    report.refreshedFiles.push(
+      dryRun ? `Would update DigiValt block in ${relativePath}.` : `Updated DigiValt block in ${relativePath}.`
+    );
+    return;
+  }
+
+  report.warnings.push(
+    `${relativePath} had no DigiValt managed block; appended at end. Move custom content or merge manually once.`
+  );
+  const out = `${existing.replace(/\s*$/, '')}\n\n${block}\n`;
+  writeFileWithMode(fullPath, out);
+  report.refreshedFiles.push(
+    dryRun ? `Would append DigiValt block to ${relativePath}.` : `Appended DigiValt block to ${relativePath}.`
+  );
+}
+
+function reconcileEnvExampleFiles() {
+  reconcileEnvExampleFile('.env.example', ENV_EXAMPLE_MANAGED_BODY);
+  reconcileEnvExampleFile('.env.local.example', ENV_LOCAL_EXAMPLE_MANAGED_BODY);
+}
+
 function copyTemplateFiles() {
   const templateFiles = listTemplateFiles(sourceDir);
 
@@ -399,10 +460,11 @@ function printSummary() {
   console.log('\n🎉 DigiVAlt init completed.');
   console.log('Next steps:');
   console.log('1. Review any warnings or manual follow-up items above.');
-  console.log('2. Copy `.dev.vars.example` to `.dev.vars` if you need local Wrangler secrets.');
-  console.log('3. Confirm `wrangler.toml` matches your Cloudflare Pages project name.');
-  console.log('4. Run `npm run build` to verify static generation now runs before `vite build`.');
-  console.log('5. Run `node scripts/deploy-secrets.js` when you are ready to sync allowed env vars to Cloudflare.');
+  console.log('2. Copy `.env.local.example` to `.env.local`, fill secrets, and keep `.env.example` as the team-facing public template.');
+  console.log('3. Copy `.dev.vars.example` to `.dev.vars` if you need local Wrangler secrets.');
+  console.log('4. Confirm `wrangler.toml` matches your Cloudflare Pages project name.');
+  console.log('5. Run `npm run build` to verify static generation now runs before `vite build`.');
+  console.log('6. Run `node scripts/deploy-secrets.js` when you are ready to sync allowed env vars to Cloudflare Pages.');
 }
 
 try {
@@ -417,6 +479,7 @@ try {
   patchPackageJson(status);
   reconcileGenerateScript(status, templateGenerateScript);
   copyTemplateFiles();
+  reconcileEnvExampleFiles();
   printSummary();
 } catch (error) {
   console.error('❌ Failed to construct templates:', error);

package/docs/SEO-PERFORMANCE.md

@@ -41,6 +41,10 @@ Read via `getPerformanceConfig()` from `@marvalt/digivalt-core/config`. Set to `
 - `VITE_PERF_SERVICE_WORKER` (default off)
 - `VITE_PERF_CACHING` (default on)
 
+## Sitemap (`/sitemap.xml`)
+
+DigiValt apps ship a **Cloudflare Pages Function** at **`functions/sitemap.xml.ts`** that responds at **`/sitemap.xml`**. It reads **`VITE_SEO_SITE_URL`** (or **`SITE_URL`**) for canonical `<loc>` values and loads path slugs from **`public/sitemap-paths.json`** (shape: `{ "paths": ["/", "/pricing"] }`). Update that JSON when you add marketing routes; avoid a static **`public/sitemap.xml`** file, which would override the Function.
+
 ## Imports
 
 ```ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@marvalt/digivalt-core",
-  "version": "0.2.6",
+  "version": "0.2.9",
   "description": "Core glue logic and shared context for DigiVAlt frontend applications",
   "license": "GPL-3.0-or-later",
   "main": "dist/index.cjs",

package/template/DIGIVALT_SETUP.md

@@ -30,7 +30,15 @@ Change them exactly to this:
 }
 ```
 
-## 🔐 3. Define Secrets (`.env.local`)
+## 📄 3. Env templates (`.env.example` / `.env.local.example`)
+
+After you run `digivalt-init`, the repo root should include **`.env.example`** (public placeholders, safe to commit) and **`.env.local.example`** (secret keys with empty values—also safe to commit as a template).
+
+- Copy **`.env.local.example`** → **`.env.local`** and fill in real credentials. Never commit **`.env.local`**.
+- Keep **`.env.example`** as the team-facing reference for non-secret `VITE_*` defaults and URLs.
+- Variables between the **DigiValt-managed** marker comments are refreshed when you rerun init; add app-specific lines **outside** that block (or merge manually once if init appended a block to an older file without markers).
+
+## 🔐 4. Define Secrets (`.env.local`)
 Create a completely ignored `.env.local` file in the root of your project and populate all of these tightly coupled secrets:
 
 ```env
@@ -52,7 +60,7 @@ VITE_AUTH_MODE="direct"
 ```
 *⚠️ **CRITICAL WARNING:** NEVER place `VITE_IS_LOVABLE=true` inside `.env.local` locally! That variable instructs the application to mute API traffic completely, pretending the data does not exist.*
 
-## 🌩️ 4. Deploy Infrastructure to Cloudflare
+## 🌩️ 5. Deploy Infrastructure to Cloudflare
 Once you connect this GitHub repository to the Cloudflare Pages dashboard:
 1. Open `wrangler.toml` and change `name="digivalt-landing-api"` to match the exact name of your Cloudflare Pages project.
 2. Run this automated script to inject your allowed DigiVAlt `.env` / `.env.local` variables into Cloudflare Pages:
@@ -61,20 +69,22 @@ node scripts/deploy-secrets.js
 ```
 3. If the script fails, fix the reported Wrangler or project-name issue before deploying.
 
-## 🔁 5. Rerunning Init Later
+## 🔁 6. Rerunning Init Later
 Rerun `npx digivalt-init` after upgrading `@marvalt/digivalt-core` when DigiVAlt-managed scaffolding changes.
 
 Init will:
 - patch safe `package.json` script cases automatically
 - refresh older DigiVAlt-managed `scripts/generate.ts` files
+- reconcile the DigiValt-managed sections inside `.env.example` and `.env.local.example`
 - warn instead of overwriting custom build logic or custom generator scripts
 - report stale legacy workarounds that may no longer be needed
 
-## 6. SEO and PageSpeed (optional)
+## 7. SEO and PageSpeed (optional)
 
 1. Install **`react-helmet-async`** and wrap your app with **`HelmetProvider`** at the root (next to the router).
 2. Set at least **`VITE_SEO_SITE_URL`** (no trailing slash), **`VITE_SEO_SITE_NAME`**, **`VITE_SEO_DEFAULT_TITLE`**, **`VITE_SEO_DEFAULT_DESCRIPTION`**, and **`VITE_SEO_DEFAULT_OG_IMAGE`** in Cloudflare Pages / `.env.local`.
 3. Import **`DigiValtSeoHead`** and **`JsonLd`** from **`@marvalt/digivalt-core/seo`** in your layouts or page components; pass **`pathname`** per route for correct canonical URLs.
-4. Read the full guide shipped with the package: **`node_modules/@marvalt/digivalt-core/docs/SEO-PERFORMANCE.md`** (or in the repo: `digivalt-npm-packages/digivalt-core/docs/SEO-PERFORMANCE.md`).
+4. **Sitemap:** After init, **`/sitemap.xml`** is served by **`functions/sitemap.xml.ts`** (Cloudflare Pages). Canonical URLs use **`VITE_SEO_SITE_URL`** (or **`SITE_URL`**); edit **`public/sitemap-paths.json`** (`{ "paths": ["/", "/about"] }`) when you add public routes. Do not add a static **`public/sitemap.xml`** (it would shadow the Function).
+5. Read the full guide shipped with the package: **`node_modules/@marvalt/digivalt-core/docs/SEO-PERFORMANCE.md`** (or in the repo: `digivalt-npm-packages/digivalt-core/docs/SEO-PERFORMANCE.md`).
 
 You are fully onboarded and ready to develop offline!

package/template/functions/sitemap.xml.ts

@@ -0,0 +1,65 @@
+/**
+ * Serves /sitemap.xml from canonical site URL + public/sitemap-paths.json (no WordPress).
+ * Set VITE_SEO_SITE_URL (or SITE_URL) on Cloudflare Pages for production canonical hosts.
+ */
+
+function normalizeBase(raw: string | undefined): string | null {
+  if (!raw || typeof raw !== 'string') return null;
+  const t = raw.trim().replace(/\/+$/, '');
+  return t || null;
+}
+
+function escapeXml(s: string): string {
+  return s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+}
+
+async function loadPaths(request: Request): Promise<string[]> {
+  try {
+    const jsonUrl = new URL('/sitemap-paths.json', request.url);
+    const res = await fetch(jsonUrl.toString());
+    if (!res.ok) return ['/'];
+    const data: unknown = await res.json();
+    const list: string[] = [];
+    if (Array.isArray(data)) {
+      for (const p of data) {
+        if (typeof p === 'string' && p.startsWith('/')) list.push(p);
+      }
+    } else if (data && typeof data === 'object' && Array.isArray((data as { paths?: unknown }).paths)) {
+      for (const p of (data as { paths: unknown[] }).paths) {
+        if (typeof p === 'string' && p.startsWith('/')) list.push(p);
+      }
+    }
+    return list.length ? list : ['/'];
+  } catch {
+    return ['/'];
+  }
+}
+
+function buildSitemap(base: string, paths: string[]): string {
+  const lines = paths.map((p) => {
+    const loc = p === '/' ? base : `${base}${p.startsWith('/') ? p : `/${p}`}`;
+    return `  <url><loc>${escapeXml(loc)}</loc></url>`;
+  });
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
+${lines.join('\n')}
+</urlset>`;
+}
+
+export async function onRequestGet(context: { request: Request; env: Record<string, string | undefined> }) {
+  const { request, env } = context;
+  const fromEnv = normalizeBase(env.VITE_SEO_SITE_URL || env.SITE_URL);
+  const origin = new URL(request.url).origin.replace(/\/+$/, '');
+  const base = fromEnv || origin;
+
+  const rawPaths = await loadPaths(request);
+  const paths = [...new Set(rawPaths.length ? rawPaths : ['/'])];
+
+  const xml = buildSitemap(base, paths);
+  return new Response(xml, {
+    headers: {
+      'Content-Type': 'application/xml; charset=utf-8',
+      'Cache-Control': 'public, max-age=300',
+    },
+  });
+}

package/template/public/sitemap-paths.json

@@ -0,0 +1,3 @@
+{
+  "paths": ["/"]
+}

package/template/scripts/deploy-secrets.js

@@ -17,9 +17,13 @@ const excludedKeys = new Set([
   'VITE_LOCAL_DEVELOPMENT',
 ]);
 
+// VITE_SEO_* are often public (verification meta, titles); allow upload when teams store them as Pages secrets.
+// TURNSTILE_SECRET_KEY is server-only (Pages Functions), not a VITE_ prefix.
 const allowedPatterns = [
   /^CLOUDFLARE_/,
   /^CF_ACCESS_/,
+  /^TURNSTILE_/,
+  /^VITE_SEO_/,
   /^VITE_(WORDPRESS|WP|GF|GRAVITY_FORMS|FRONTEND|FRONTENDS|MAUTIC|SUITECRM|SUPABASE|CLOUDFLARE|AUTH|TURNSTILE|CHATWOOT|THEME|GOOGLE_|FACEBOOK_|LINKEDIN_)/,
 ];