@marvalt/digivalt-core 0.2.11 → 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@marvalt/digivalt-core",
-  "version": "0.2.11",
+  "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",

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

@@ -1,3 +1,3 @@
-{
-  "paths": []
-}
+{
+  "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/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": []
+}