@marvalt/digivalt-core 0.2.9 → 0.2.12

package/docs/AI-LOCAL-WORDPRESS-BOOTSTRAP.md

@@ -0,0 +1,116 @@
+# AI local bootstrap runbook — full WordPress control
+
+This runbook is for projects scaffolded by AI tools (Cursor, Claude Code, Antigravity, Lovable) when you want full control from WordPress-managed static pages, menus, header/footer blocks, and theme styles.
+
+Primary goal: after AI scaffolding is complete, the human should only need env values before first local run:
+
+```bash
+npm run build && npm run dev
+```
+
+---
+
+## What AI must already have done
+
+Before using this runbook, the generated project should already include:
+
+- `@marvalt/digivalt-core@latest`
+- `vite-node` and `react-helmet-async`
+- `npx digivalt-init` output (or equivalent)
+- `scripts/generate.ts` wired to `@marvalt/digivalt-core/generators`
+- `functions/` + `wrangler.toml` for Pages Functions
+- `.gitignore` rules for `.env`, `.env.local`, `.env.*.local`, `.dev.vars`
+
+If missing, run:
+
+```bash
+npm install @marvalt/digivalt-core@latest
+npm install -D vite-node
+npm install react-helmet-async
+npx digivalt-init
+```
+
+---
+
+## Human-only step: set env values
+
+Create/update `.env` and `.env.local` from the generated examples (`.env.example`, `.env.local.example`) and set values.
+
+Important local rule:
+
+- Do **not** set `VITE_IS_LOVABLE=true` locally for full-data mode.
+
+### Minimum env matrix for first successful full-data build
+
+| Group | Required for first local `build` | Keys |
+|------|------|------|
+| WordPress static generation | Yes | `VITE_WORDPRESS_API_URL` (or `WORDPRESS_API_URL`) |
+| WordPress auth | Usually yes (if API protected) | `VITE_WP_API_USERNAME` + `VITE_WP_APP_PASSWORD` (or `WP_API_USERNAME` + `WP_APP_PASSWORD`) |
+| Gravity Forms | Uses WP creds by default | Optional dedicated keys: `VITE_GRAVITY_FORMS_API_URL`, `VITE_GRAVITY_FORMS_USERNAME`, `VITE_GRAVITY_FORMS_PASSWORD` |
+| Mautic | Optional; generator skips when URL missing | `VITE_MAUTIC_URL` (+ optional `VITE_MAUTIC_API_PUBLIC_KEY`, `VITE_MAUTIC_API_SECRET_KEY`) |
+| Cloudflare Access (if WP/API behind Zero Trust) | Conditional | `VITE_CF_ACCESS_CLIENT_ID`, `VITE_CF_ACCESS_CLIENT_SECRET` |
+| SEO defaults | Recommended | `VITE_SEO_SITE_URL`, `VITE_SEO_SITE_NAME`, `VITE_SEO_DEFAULT_TITLE`, `VITE_SEO_DEFAULT_DESCRIPTION`, `VITE_SEO_DEFAULT_OG_IMAGE` |
+
+---
+
+## First local run
+
+From app root:
+
+```bash
+npm install
+npm run build
+npm run dev
+```
+
+`npm run build` runs generation first and should produce/update:
+
+- `public/wordpress-data.json`
+- `public/gravity-forms-data.json`
+- `src/data/mautic-data.json` (if Mautic configured)
+- `public/sitemap-paths.json`
+
+---
+
+## Verification checklist
+
+- Build succeeds without missing env errors.
+- WordPress shell renders (menu/header/footer/theme) from static data.
+- `public/sitemap-paths.json` is generated.
+- No static `public/sitemap.xml` exists when using `functions/sitemap.xml.ts`.
+- Local secrets are not tracked by git.
+
+---
+
+## Quick failure recovery
+
+### `Missing WordPress API URL`
+
+Set `VITE_WORDPRESS_API_URL` (or `WORDPRESS_API_URL`) in env and rerun build.
+
+### WordPress or Gravity Forms auth failures
+
+Verify app password credentials:
+
+- `VITE_WP_API_USERNAME`
+- `VITE_WP_APP_PASSWORD`
+
+Or set dedicated GF credentials if needed.
+
+### No Mautic output
+
+If `VITE_MAUTIC_URL` is missing, Mautic generation is skipped by design. Set it only if needed for your app.
+
+### Build behaves like fixture mode
+
+Ensure `VITE_IS_LOVABLE` is not set to `true` locally.
+
+---
+
+## References
+
+- [digivalt-npm-packages/digivalt-core/src/generators/wp.ts](../src/generators/wp.ts)
+- [digivalt-npm-packages/digivalt-core/src/generators/gf.ts](../src/generators/gf.ts)
+- [digivalt-npm-packages/digivalt-core/src/generators/mautic.ts](../src/generators/mautic.ts)
+- [digivalt-npm-packages/digivalt-core/src/generators/sitemap-paths.ts](../src/generators/sitemap-paths.ts)
+- [digivalt-landing/DIGIVALT_SETUP.md](../../../digivalt-landing/DIGIVALT_SETUP.md)

package/docs/LOVABLE-MASTER-PROMPT.md

@@ -0,0 +1,140 @@
+# AI master prompt — DigiVAlt full local WordPress control
+
+Use this as a single copy-paste master prompt in Cursor, Claude Code, Antigravity, Lovable, or similar AI coding tools.
+
+The objective is a DigiValt app scaffold that is production-shaped from day one, where after generation a human only needs to set `.env` / `.env.local` values before first local run:
+
+```bash
+npm run build && npm run dev
+```
+
+## Scope
+
+- **AI responsibilities:** scaffold code, install/wire dependencies, run `digivalt-init`, ensure scripts/files are correct, keep cloud/function wiring and SEO enabled, and build a WordPress-driven shell.
+- **Human responsibilities:** set real env values on local PC and cloud dashboard, run first local build/dev, replace placeholder static data with real generated exports as needed.
+
+## Canonical sources
+
+- [README.md](../README.md)
+- [template/DIGIVALT_SETUP.md](../template/DIGIVALT_SETUP.md)
+- [template/scripts/generate.ts](../template/scripts/generate.ts)
+- [docs/SEO-PERFORMANCE.md](./SEO-PERFORMANCE.md)
+- [digivalt-landing/DIGIVALT_SETUP.md](../../../digivalt-landing/DIGIVALT_SETUP.md)
+
+---
+
+## Master prompt text (paste below into your AI tool)
+
+You are a senior full-stack engineer scaffolding a DigiValt consumer app (Vite + React + TypeScript) with full WordPress-controlled static content behavior. This workflow must work the same whether run from Cursor, Claude Code, Antigravity, Lovable, or another AI assistant.
+
+### Non-negotiables
+
+- Install `@marvalt/digivalt-core@latest`.
+- Use `npx digivalt-init` to enforce DigiValt-managed scaffold files and scripts.
+- Keep Cloudflare Pages Functions + `wrangler.toml` enabled.
+- Keep SEO enabled by default (Helmet provider + DigiValt SEO helpers).
+- Keep local secrets out of git and ignore `.env`, `.env.local`, `.env.*.local`, `.dev.vars`.
+- Do not hand-maintain `public/sitemap-paths.json`; it is generated.
+- Do not create `public/sitemap.xml` when using `functions/sitemap.xml.ts`.
+
+### File/path requirements
+
+Use these exact static data paths:
+
+- `public/wordpress-data.json`
+- `public/gravity-forms-data.json`
+- `src/data/mautic-data.json`
+
+If real exports are unavailable, use template starter fixtures (or equivalent minimal placeholders) so the app boots. Mark placeholders clearly.
+
+### Build wiring requirements
+
+Ensure these commands exist and are used:
+
+```bash
+npm install @marvalt/digivalt-core@latest
+npm install -D vite-node
+npx digivalt-init
+npm install react-helmet-async
+```
+
+Expected scripts:
+
+- `generate`: `npx vite-node --options.deps.inline="@marvalt/digivalt-core/generators" scripts/generate.ts`
+- `build`: `npx vite-node --options.deps.inline="@marvalt/digivalt-core/generators" scripts/generate.ts && vite build`
+- `build:dev`: `npx vite-node --options.deps.inline="@marvalt/digivalt-core/generators" scripts/generate.ts && vite build --mode development`
+- `dev`: `vite`
+
+### `scripts/generate.ts` behavior
+
+Import from `@marvalt/digivalt-core/generators` only:
+
+- In hosted fixture mode (`VITE_IS_LOVABLE=true`): skip fetch, run `generateSitemapPathsSafe()`.
+- In normal local mode (default): run `generateAllData()` then sitemap; on fetch failure still run sitemap safe fallback.
+
+### WordPress-driven runtime wiring (must implement)
+
+After `loadWordPressData()` from `@marvalt/digivalt-core/static`, wire the app shell and routes using WordPress static data:
+
+1. Menus from `getNavigationMenu()` / `getMenuById()` (+ `getParsedHeader()` / `getHeaderMenuId()`).
+2. Header/footer template blocks from `getHeader()` / `getFooter()`.
+3. Site identity from `getSiteSettings()` / `getLogoUrl()` / `getSiteIconUrl()`.
+4. Theme styles from `getWordPressData().theme_styles` mapped into app styling/tokens.
+5. Pages/posts/CPT routes from `getWordPressPages()`, `getWordPressPageBySlug()`, `getWordPressPosts()`, and `front_page`.
+
+For forms, support Gravity Forms and Mautic via `@marvalt/digivalt-core/services` and/or JSON static stores.
+
+### Cloudflare and sitemap requirements
+
+- Keep `functions/sitemap.xml.ts`.
+- Keep `functions/api/*` handlers from template and keep `wrangler.toml`.
+- Ensure sitemap flow is active:
+  - input: `public/sitemap-static-paths.json`
+  - generated output: `public/sitemap-paths.json`
+  - runtime endpoint: `/sitemap.xml` from Pages Function
+
+### AI output constraints
+
+- Do not request humans to hand-edit code before first run.
+- After scaffolding, the only required manual step before first run is env values in `.env` / `.env.local`.
+- Provide a final validation checklist and commands:
+  - `npm run build`
+  - `npm run dev`
+
+---
+
+## Built-in defaults (use unless humans override later)
+
+- Package: `@marvalt/digivalt-core@latest`
+- Static data: template starter fixtures for WordPress, Gravity Forms, Mautic
+- SEO: ON
+- Cloudflare Functions + `wrangler.toml`: ON
+- Form/page mapping: derive from WordPress content and shortcodes first
+
+---
+
+## Pre-flight checklist
+
+| Step | Done |
+|------|------|
+| `@marvalt/digivalt-core@latest` installed | ☐ |
+| `digivalt-init` run and scripts verified | ☐ |
+| Required static data files exist (`wordpress`, `gravity-forms`, `mautic`) | ☐ |
+| `sitemap-static-paths.json` exists and `sitemap-paths.json` is generated | ☐ |
+| Cloudflare functions/wrangler files present | ☐ |
+| SEO imports + `HelmetProvider` wired | ☐ |
+| `.gitignore` excludes local secret files | ☐ |
+
+---
+
+## Reference paths in this monorepo
+
+| Concern | File |
+|---------|------|
+| Local setup baseline | [digivalt-landing/DIGIVALT_SETUP.md](../../../digivalt-landing/DIGIVALT_SETUP.md) |
+| Template setup baseline | [template/DIGIVALT_SETUP.md](../template/DIGIVALT_SETUP.md) |
+| Init behavior and script expectations | [README.md](../README.md) |
+| Generator script template | [template/scripts/generate.ts](../template/scripts/generate.ts) |
+| Landing generator implementation | [digivalt-landing/scripts/generate.ts](../../../digivalt-landing/scripts/generate.ts) |
+| SEO and sitemap behavior | [docs/SEO-PERFORMANCE.md](./SEO-PERFORMANCE.md) |
+| WP static getters and shell helpers | [src/static/wpStatic.ts](../src/static/wpStatic.ts) |

package/docs/SEO-PERFORMANCE.md

@@ -43,7 +43,15 @@ Read via `getPerformanceConfig()` from `@marvalt/digivalt-core/config`. Set to `
 
 ## 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.
+**Runtime:** A **Cloudflare Pages Function** at **`functions/sitemap.xml.ts`** serves **`/sitemap.xml`**. It **`fetch`es `/sitemap-paths.json`** from the deployed static assets and uses **`VITE_SEO_SITE_URL`** (or **`SITE_URL`**) for canonical `<loc>` values (fallback: request origin). Do not add **`public/sitemap.xml`**; it would shadow the Function.
+
+**Build time:** **`public/sitemap-paths.json`** is **generated** by **`@marvalt/digivalt-core/generators`** (`generateSitemapPaths`) at the end of **`generateAllData`**, and when **`VITE_IS_LOVABLE=true`** the app’s **`scripts/generate.ts`** still runs that step so paths stay in sync with committed **`wordpress-data.json`**. Sources merged:
+
+1. **`public/sitemap-static-paths.json`** — you maintain this for **React-only / Lovable** public routes (not inferred from code).
+2. **`navigation_menu`** items in **`wordpress-data.json`** (recursive `url` fields), filtered to **`http(s)`** and the CMS host from **`VITE_WORDPRESS_API_URL`** / **`WORDPRESS_API_URL`**.
+3. **`link`** on entities in top-level arrays whose keys match **`config.post_types`** (fallback: other top-level arrays minus a fixed skip list). Taxonomy archives are omitted by default.
+
+Paths are normalized (no trailing slash except **`/`**), deduped, and sorted. If generation fails, a safe fallback writes **`{ "paths": ["/"] }`**.
 
 ## Imports
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@marvalt/digivalt-core",
-  "version": "0.2.9",
+  "version": "0.2.12",
   "description": "Core glue logic and shared context for DigiVAlt frontend applications",
   "license": "GPL-3.0-or-later",
   "main": "dist/index.cjs",
@@ -65,7 +65,8 @@
     "clean": "rimraf dist",
     "smoke:imports": "node ./scripts/smoke-imports.mjs",
     "smoke:init": "node ./scripts/smoke-init.cjs",
-    "smoke": "npm run smoke:imports && npm run smoke:init",
+    "smoke:sitemap": "node ./scripts/test-sitemap-paths.cjs",
+    "smoke": "npm run smoke:imports && npm run smoke:init && npm run smoke:sitemap",
     "prepublishOnly": "npm run clean && npm run build && npm run smoke"
   },
   "devDependencies": {

package/template/DIGIVALT_SETUP.md

@@ -84,7 +84,7 @@ Init will:
 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. **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).
+4. **Sitemap:** **`/sitemap.xml`** is served by **`functions/sitemap.xml.ts`**. **`public/sitemap-paths.json`** is **generated** when you run **`npm run build`** (or `generate`): it merges (a) **`public/sitemap-static-paths.json`** — edit this for Lovable/SPA-only routes, (b) URLs from **`navigation_menu`** in **`wordpress-data.json`**, (c) **`link`** pathnames from CPT/post arrays listed under **`config.post_types`**. Only CMS links whose host matches **`VITE_WORDPRESS_API_URL`** / **`WORDPRESS_API_URL`** are included. Canonical `<loc>` values use **`VITE_SEO_SITE_URL`** (or **`SITE_URL`**). Do not add **`public/sitemap.xml`** (it would shadow the Function). With **`VITE_IS_LOVABLE=true`**, static fetch is skipped but sitemap paths are still regenerated from committed JSON.
 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

@@ -1,5 +1,5 @@
 /**
- * Serves /sitemap.xml from canonical site URL + public/sitemap-paths.json (no WordPress).
+ * Serves /sitemap.xml from canonical site URL + public/sitemap-paths.json (generated at build).
  * Set VITE_SEO_SITE_URL (or SITE_URL) on Cloudflare Pages for production canonical hosts.
  */
 

package/template/public/gravity-forms-data.json

@@ -0,0 +1,7 @@
+{
+  "_placeholder": true,
+  "_placeholder_note": "Replace with generated Gravity Forms data before production.",
+  "generated_at": "1970-01-01T00:00:00.000Z",
+  "total_forms": 0,
+  "forms": []
+}

package/template/public/sitemap-static-paths.json

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

package/template/public/wordpress-data.json

@@ -0,0 +1,44 @@
+{
+  "_placeholder": true,
+  "_placeholder_note": "Replace with generated WordPress data before production.",
+  "generated_at": "1970-01-01T00:00:00.000Z",
+  "frontend_id": "lovable-starter",
+  "frontend_name": "Lovable Starter",
+  "front_page": null,
+  "site_settings": {
+    "site_name": "DigiValt Starter",
+    "site_description": "Placeholder data",
+    "logo": null,
+    "site_icon": null
+  },
+  "theme_styles": {
+    "colors": {
+      "theme_palette": []
+    },
+    "typography": {}
+  },
+  "header": {
+    "slug": "header",
+    "area": "header",
+    "blocks": [],
+    "blocks_count": 0
+  },
+  "footer": {
+    "slug": "footer",
+    "area": "footer",
+    "blocks": [],
+    "blocks_count": 0
+  },
+  "navigation_menu": {
+    "id": 0,
+    "name": "Primary",
+    "slug": "primary",
+    "items": []
+  },
+  "menus": {},
+  "pages": [],
+  "posts": [],
+  "config": {
+    "post_types": {}
+  }
+}

package/template/scripts/deploy-secrets.js

@@ -11,10 +11,13 @@ import { execSync } from 'child_process';
  */
 
 const secrets = {};
+/** Keys we never push from .env / .env.local (local dev or set manually on Cloudflare Pages). */
 const excludedKeys = new Set([
   'NODE_ENV',
   'VITE_IS_LOVABLE',
   'VITE_LOCAL_DEVELOPMENT',
+  'VITE_AUTH_MODE',
+  'VITE_DEFAULT_MAX_ITEMS',
 ]);
 
 // VITE_SEO_* are often public (verification meta, titles); allow upload when teams store them as Pages secrets.
@@ -27,13 +30,7 @@ const allowedPatterns = [
   /^VITE_(WORDPRESS|WP|GF|GRAVITY_FORMS|FRONTEND|FRONTENDS|MAUTIC|SUITECRM|SUPABASE|CLOUDFLARE|AUTH|TURNSTILE|CHATWOOT|THEME|GOOGLE_|FACEBOOK_|LINKEDIN_)/,
 ];
 
-const isAllowedSecretKey = (key) => {
-  if (excludedKeys.has(key)) {
-    return false;
-  }
-
-  return allowedPatterns.some((pattern) => pattern.test(key));
-};
+const isAllowedSecretKey = (key) => allowedPatterns.some((pattern) => pattern.test(key));
 
 const parseEnvFile = (filePath) => {
   if (!fs.existsSync(filePath)) return;
@@ -51,6 +48,11 @@ const parseEnvFile = (filePath) => {
     const key = match[1].trim();
     let value = match[2].trim();
 
+    if (excludedKeys.has(key)) {
+      console.log(`⚠️ Skipping ${key} (DigiVAlt: excluded from Cloudflare bulk upload)`);
+      return;
+    }
+
     if (!isAllowedSecretKey(key)) {
       console.log(`⚠️ Skipping ${key} (not in DigiVAlt allowlist)`);
       return;

package/template/scripts/generate.ts

@@ -1,18 +1,22 @@
-import { generateAllData } from '@marvalt/digivalt-core/generators';
+import { generateAllData, generateSitemapPathsSafe } from '@marvalt/digivalt-core/generators';
 
 async function runGenerators() {
   console.log('🚀 Starting DigiVAlt static data generation for Landing Project...');
-  
+
   if (process.env.VITE_IS_LOVABLE === 'true') {
-     console.log('⚡ Lovable Environment Detected (VITE_IS_LOVABLE). Skipping static data generation to use GitHub synced files.');
-     return;
+    console.log(
+      '⚡ Lovable Environment Detected (VITE_IS_LOVABLE). Skipping static data fetch; refreshing sitemap paths from committed JSON.'
+    );
+    await generateSitemapPathsSafe();
+    return;
   }
-  
+
   try {
     await generateAllData();
     console.log('✅ Customized static generation complete!');
   } catch (error) {
     console.error('❌ Data fetching encountered an error, but continuing build gracefully:', error);
+    await generateSitemapPathsSafe();
   }
 }
 

package/template/src/data/mautic-data.json

@@ -0,0 +1,7 @@
+{
+  "_placeholder": true,
+  "_placeholder_note": "Replace with generated Mautic data before production.",
+  "generated_at": "1970-01-01T00:00:00.000Z",
+  "total_forms": 0,
+  "forms": []
+}