@marvalt/digivalt-core 0.2.9 → 0.2.12

package/CHANGELOG.md

@@ -5,6 +5,35 @@ 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.12] - 2026-04-13
+
+### Added
+- `GLOBAL-SHORTCODES.md`: consolidated shortcode reference covering DigiValt core form/popup shortcodes (`gf_embed`, `popupbtn_gf`, `popupbtn_mautic`, aliases) plus `@marvalt/shcoder` member/testimonial/event shortcodes and legacy event aliases.
+- `docs/LOVABLE-MASTER-PROMPT.md`: promoted to a tool-agnostic AI master prompt (Cursor / Claude Code / Antigravity / Lovable) for full local WordPress-control scaffolds with explicit AI-vs-human responsibilities and first-run `build` + `dev` expectations.
+- `docs/AI-LOCAL-WORDPRESS-BOOTSTRAP.md`: new local-first runbook with minimum env matrix, first-run commands, artifact checks, and common recovery steps.
+- Template starter fixtures for Lovable-first app bootstraps:
+  - `template/public/wordpress-data.json`
+  - `template/public/gravity-forms-data.json`
+  - `template/src/data/mautic-data.json`
+  These placeholder files are safe defaults that prevent first-run runtime failures before real generated exports are available.
+- Cross-links added from package README and `digivalt-landing/DIGIVALT_SETUP.md` to the new unified AI docs.
+
+## [0.2.11] - 2026-04-03
+
+### Added
+- **`generateSitemapPaths` / `generateSitemapPathsSafe`** ([`src/generators/sitemap-paths.ts`](src/generators/sitemap-paths.ts)): build-time merge of **`public/sitemap-static-paths.json`**, WP **`navigation_menu`** URLs, and CPT/post **`link`** pathnames from **`wordpress-data.json`** (via **`config.post_types`** keys, with fallback scanning). Writes **`public/sitemap-paths.json`**. Host filter uses CMS URL from env; **`generateSitemapPathsSafe`** falls back to **`/`** on error.
+- **Template + landing:** **`public/sitemap-static-paths.json`**; **`scripts/generate.ts`** runs sitemap refresh when **`VITE_IS_LOVABLE=true`** or after a failed generate try/catch.
+- **`npm run smoke:sitemap`:** fixture test for merged paths.
+
+### Changed
+- **`generateAllData`:** runs **`generateSitemapPathsSafe`** after successful static generation.
+- **Docs:** `DIGIVALT_SETUP.md`, `SEO-PERFORMANCE.md`, repo **`AGENTS.md`** (sitemap conventions).
+
+## [0.2.10] - 2026-04-03
+
+### Changed
+- **Template `scripts/deploy-secrets.js`:** **`VITE_AUTH_MODE`** and **`VITE_DEFAULT_MAX_ITEMS`** are excluded from bulk Cloudflare upload (set locally or in the Pages dashboard). **`NODE_ENV`** was already excluded. Excluded keys log a dedicated skip reason.
+
 ## [0.2.9] - 2026-04-03
 
 ### Added

package/README.md

@@ -55,6 +55,14 @@ When to rerun it:
 - after upgrading `@marvalt/digivalt-core` when scaffolded build wiring changes
 - before publishing a new app if you want a quick preflight of the DigiVAlt setup
 
+**Sitemap:** Each build regenerates **`public/sitemap-paths.json`** from **`public/sitemap-static-paths.json`** (paths you add for SPA-only routes) plus WordPress menu and CPT links in **`wordpress-data.json`**. See **[docs/SEO-PERFORMANCE.md](./docs/SEO-PERFORMANCE.md)**.
+
+**Google Reviews static data:** `generateAllData()` also fetches `vibune-google-reviews` and writes **`public/google-reviews-data.json`**. By default it derives the endpoint from `WORDPRESS_API_URL` / `VITE_WORDPRESS_API_URL` and calls `/wp-json/vibune-google-reviews/v1/reviews`. Override with `GOOGLE_REVIEWS_API_URL` / `VITE_GOOGLE_REVIEWS_API_URL` when needed.
+
+**AI builders (Cursor / Claude Code / Antigravity / Lovable):**
+- Tool-agnostic master prompt: **[docs/LOVABLE-MASTER-PROMPT.md](./docs/LOVABLE-MASTER-PROMPT.md)**
+- Local-first human runbook: **[docs/AI-LOCAL-WORDPRESS-BOOTSTRAP.md](./docs/AI-LOCAL-WORDPRESS-BOOTSTRAP.md)**
+
 ## Developing this package
 
 This repo uses **`.npmrc`** with `legacy-peer-deps=true` so `react-helmet-async` installs cleanly alongside **React 19**-compatible transitive deps during local builds. Consumers of the published package only need to satisfy peers (`react`, `react-dom`, `react-helmet-async`).
@@ -66,5 +74,5 @@ Use `node scripts/deploy-secrets.js` after `digivalt-init`.
 The helper now:
 
 - 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`
+- skips **`NODE_ENV`**, **`VITE_IS_LOVABLE`**, **`VITE_LOCAL_DEVELOPMENT`**, **`VITE_AUTH_MODE`**, and **`VITE_DEFAULT_MAX_ITEMS`** (set those locally or in the Pages dashboard instead of bulk upload)
 - fails with a non-zero exit code when Wrangler or project detection fails

package/bin/env-example-fragments.cjs

@@ -9,6 +9,9 @@ VITE_WORDPRESS_API_URL=https://cms.example.com/wp-json
 VITE_AUTH_MODE=direct
 VITE_CLOUDFLARE_WORKER_URL=
 VITE_LOCAL_DEVELOPMENT=false
+# Optional explicit endpoint for vibune-google-reviews static generation.
+# Defaults to <WORDPRESS_API_URL>/vibune-google-reviews/v1/reviews.
+# VITE_GOOGLE_REVIEWS_API_URL=https://cms.example.com/wp-json/vibune-google-reviews/v1/reviews
 
 # Multi-frontend (digivalt-multi-frontends)
 VITE_FRONTEND_ID=my-app

package/dist/generators/google-reviews.d.ts

@@ -0,0 +1,5 @@
+interface GenerateGoogleReviewsOptions {
+    outputPath?: string;
+}
+export declare function generateGoogleReviewsData(options?: GenerateGoogleReviewsOptions): Promise<boolean>;
+export {};

package/dist/generators/index.d.ts

@@ -2,4 +2,6 @@ export * from './wp';
 export * from './gf';
 export * from './mautic';
 export * from './suitecrm';
+export * from './google-reviews';
+export * from './sitemap-paths';
 export declare function generateAllData(): Promise<void>;

package/dist/generators/sitemap-paths.d.ts

@@ -0,0 +1,11 @@
+export type GenerateSitemapPathsOptions = {
+    cwd?: string;
+    wpDataPath?: string;
+    staticInputPath?: string;
+    outputPath?: string;
+};
+/**
+ * Merge sitemap-static-paths.json, navigation_menu URLs, and CPT/post links from wordpress-data.json.
+ */
+export declare function generateSitemapPaths(options?: GenerateSitemapPathsOptions): Promise<void>;
+export declare function generateSitemapPathsSafe(options?: GenerateSitemapPathsOptions): Promise<void>;

package/dist/generators.cjs

@@ -4,6 +4,7 @@ var dotenv = require('dotenv');
 var path = require('path');
 var fs = require('fs');
 var sadapter = require('@marvalt/sadapter');
+var promises = require('fs/promises');
 
 /**
  * @license GPL-3.0-or-later
@@ -2453,6 +2454,302 @@ async function generateSuiteCRMData(options) {
     }
 }
 
+function trimTrailingSlash(value) {
+    return value.replace(/\/+$/, '');
+}
+function resolveEndpointUrl() {
+    const explicit = process.env.GOOGLE_REVIEWS_API_URL ||
+        process.env.VITE_GOOGLE_REVIEWS_API_URL ||
+        '';
+    if (explicit) {
+        return explicit;
+    }
+    const wpApiBase = process.env.WORDPRESS_API_URL ||
+        process.env.VITE_WORDPRESS_API_URL ||
+        '';
+    if (!wpApiBase) {
+        return '';
+    }
+    const normalizedBase = trimTrailingSlash(wpApiBase);
+    if (normalizedBase.endsWith('/wp-json')) {
+        return `${normalizedBase}/vibune-google-reviews/v1/reviews`;
+    }
+    return `${normalizedBase}/wp-json/vibune-google-reviews/v1/reviews`;
+}
+function buildHeaders() {
+    const headers = {
+        Accept: 'application/json',
+    };
+    const username = process.env.WP_API_USERNAME || process.env.VITE_WP_API_USERNAME || '';
+    const password = process.env.WP_APP_PASSWORD || process.env.VITE_WP_APP_PASSWORD || '';
+    if (username && password) {
+        headers.Authorization = `Basic ${Buffer.from(`${username}:${password}`).toString('base64')}`;
+    }
+    const cfAccessClientId = process.env.CF_ACCESS_CLIENT_ID || process.env.VITE_CF_ACCESS_CLIENT_ID || '';
+    const cfAccessClientSecret = process.env.CF_ACCESS_CLIENT_SECRET || process.env.VITE_CF_ACCESS_CLIENT_SECRET || '';
+    if (cfAccessClientId && cfAccessClientSecret) {
+        headers['CF-Access-Client-Id'] = cfAccessClientId;
+        headers['CF-Access-Client-Secret'] = cfAccessClientSecret;
+    }
+    return headers;
+}
+function hasExpectedShape(payload) {
+    if (!payload || typeof payload !== 'object') {
+        return false;
+    }
+    const obj = payload;
+    return Array.isArray(obj.reviews) && typeof obj.business === 'object' && obj.business !== null;
+}
+function truncateBody(body, max = 1200) {
+    if (body.length <= max) {
+        return body;
+    }
+    return `${body.slice(0, max)}...`;
+}
+async function generateGoogleReviewsData(options) {
+    const outputPath = options?.outputPath || './public/google-reviews-data.json';
+    const endpointUrl = resolveEndpointUrl();
+    if (!endpointUrl) {
+        console.error('❌ Missing Google Reviews endpoint. Set GOOGLE_REVIEWS_API_URL or VITE_GOOGLE_REVIEWS_API_URL, or configure WORDPRESS_API_URL/VITE_WORDPRESS_API_URL.');
+        return false;
+    }
+    try {
+        const response = await fetch(endpointUrl, {
+            method: 'GET',
+            headers: buildHeaders(),
+        });
+        if (!response.ok) {
+            const body = truncateBody(await response.text());
+            console.error(`❌ Google Reviews generation failed (HTTP ${response.status}): ${body}`);
+            return false;
+        }
+        const payload = (await response.json());
+        if (!hasExpectedShape(payload)) {
+            console.error('❌ Google Reviews generation failed: endpoint returned unexpected payload shape.');
+            return false;
+        }
+        const outputFilePath = path.join(process.cwd(), outputPath);
+        await promises.mkdir(path.dirname(outputFilePath), { recursive: true });
+        await promises.writeFile(outputFilePath, `${JSON.stringify(payload, null, 2)}\n`, 'utf-8');
+        console.log(`📁 Google Reviews data written to: ${outputFilePath}`);
+        return true;
+    }
+    catch (e) {
+        console.error('❌ Google Reviews generation failed:', e.message);
+        return false;
+    }
+}
+
+const SITEMAP_SKIP_TOP_LEVEL_KEYS = new Set([
+    'config',
+    'site_settings',
+    'header',
+    'footer',
+    'theme_styles',
+    'navigation_menu',
+    'menus',
+    'categories',
+    'tags',
+    'generated_at',
+    'frontend_id',
+    'frontend_name',
+    'front_page',
+]);
+function normalizePathname(pathname) {
+    const decoded = decodeURIComponent(pathname);
+    if (!decoded || decoded === '/')
+        return '/';
+    const stripped = decoded.replace(/\/+$/, '');
+    return stripped === '' ? '/' : stripped;
+}
+function getAllowedHosts() {
+    const hosts = new Set();
+    const api = process.env.VITE_WORDPRESS_API_URL || process.env.WORDPRESS_API_URL;
+    if (api) {
+        try {
+            hosts.add(new URL(api).hostname);
+        }
+        catch {
+            /* ignore */
+        }
+    }
+    return hosts;
+}
+/**
+ * When CMS host is unknown, accept any http(s) URL so local/offline merges still produce paths.
+ */
+function urlToPath(urlStr, allowedHosts) {
+    const t = urlStr.trim();
+    if (!t || t === '#' || t.toLowerCase().startsWith('mailto:') || t.toLowerCase().startsWith('tel:')) {
+        return null;
+    }
+    if (!/^https?:\/\//i.test(t)) {
+        return null;
+    }
+    let u;
+    try {
+        u = new URL(t);
+    }
+    catch {
+        return null;
+    }
+    if (allowedHosts.size > 0 && !allowedHosts.has(u.hostname)) {
+        return null;
+    }
+    return normalizePathname(u.pathname);
+}
+function parsePathsJson(raw) {
+    try {
+        const data = JSON.parse(raw);
+        if (Array.isArray(data)) {
+            return data.filter((p) => typeof p === 'string' && p.startsWith('/'));
+        }
+        if (data && typeof data === 'object' && Array.isArray(data.paths)) {
+            return data.paths.filter((p) => typeof p === 'string' && p.startsWith('/'));
+        }
+    }
+    catch {
+        /* ignore */
+    }
+    return [];
+}
+function loadStaticPaths(cwd, staticInputPath, allowedHosts) {
+    const full = path.join(cwd, staticInputPath);
+    if (!fs.existsSync(full)) {
+        return [];
+    }
+    const raw = fs.readFileSync(full, 'utf8');
+    const paths = parsePathsJson(raw);
+    const out = [];
+    for (const p of paths) {
+        if (p.startsWith('http://') || p.startsWith('https://')) {
+            const normalized = urlToPath(p, allowedHosts);
+            if (normalized)
+                out.push(normalized);
+        }
+        else {
+            out.push(normalizePathname(p));
+        }
+    }
+    return out;
+}
+function walkMenuItems(items, allowedHosts, out) {
+    if (!Array.isArray(items))
+        return;
+    for (const item of items) {
+        if (!item || typeof item !== 'object')
+            continue;
+        const rec = item;
+        if (typeof rec.url === 'string') {
+            const p = urlToPath(rec.url, allowedHosts);
+            if (p)
+                out.add(p);
+        }
+        if (Array.isArray(rec.children)) {
+            walkMenuItems(rec.children, allowedHosts, out);
+        }
+    }
+}
+function collectLinksFromArray(arr, allowedHosts, out) {
+    for (const item of arr) {
+        if (!item || typeof item !== 'object')
+            continue;
+        const link = item.link;
+        if (typeof link === 'string') {
+            const p = urlToPath(link, allowedHosts);
+            if (p)
+                out.add(p);
+        }
+    }
+}
+function collectPathsFromWpData(data, allowedHosts) {
+    const out = new Set();
+    const menu = data.navigation_menu;
+    if (menu?.items) {
+        walkMenuItems(menu.items, allowedHosts, out);
+    }
+    const config = data.config;
+    const postTypeKeys = config?.post_types && typeof config.post_types === 'object'
+        ? Object.keys(config.post_types)
+        : null;
+    if (postTypeKeys && postTypeKeys.length > 0) {
+        for (const key of postTypeKeys) {
+            const arr = data[key];
+            if (Array.isArray(arr)) {
+                collectLinksFromArray(arr, allowedHosts, out);
+            }
+        }
+    }
+    else {
+        for (const [key, value] of Object.entries(data)) {
+            if (SITEMAP_SKIP_TOP_LEVEL_KEYS.has(key))
+                continue;
+            if (Array.isArray(value)) {
+                collectLinksFromArray(value, allowedHosts, out);
+            }
+        }
+    }
+    return out;
+}
+function writeFallback(cwd, outputPath) {
+    const full = path.join(cwd, outputPath);
+    fs.mkdirSync(path.dirname(full), { recursive: true });
+    fs.writeFileSync(full, `${JSON.stringify({ paths: ['/'] }, null, 2)}\n`, 'utf8');
+}
+/**
+ * Merge sitemap-static-paths.json, navigation_menu URLs, and CPT/post links from wordpress-data.json.
+ */
+async function generateSitemapPaths(options = {}) {
+    dotenv.config();
+    dotenv.config({ path: '.env.local' });
+    const cwd = options.cwd ?? process.cwd();
+    const wpDataPath = options.wpDataPath ?? 'public/wordpress-data.json';
+    const staticInputPath = options.staticInputPath ?? 'public/sitemap-static-paths.json';
+    const outputPath = options.outputPath ?? 'public/sitemap-paths.json';
+    const allowedHosts = getAllowedHosts();
+    const merged = new Set();
+    for (const p of loadStaticPaths(cwd, staticInputPath, allowedHosts)) {
+        merged.add(normalizePathname(p));
+    }
+    const wpFull = path.join(cwd, wpDataPath);
+    if (fs.existsSync(wpFull)) {
+        try {
+            const raw = fs.readFileSync(wpFull, 'utf8');
+            const data = JSON.parse(raw);
+            const fromWp = collectPathsFromWpData(data, allowedHosts);
+            for (const p of fromWp) {
+                merged.add(p);
+            }
+        }
+        catch (e) {
+            console.warn('⚠️  Could not parse wordpress-data.json for sitemap paths:', e.message);
+        }
+    }
+    merged.add('/');
+    const sorted = [...merged].sort((a, b) => {
+        if (a === '/')
+            return -1;
+        if (b === '/')
+            return 1;
+        return a.localeCompare(b);
+    });
+    const outFull = path.join(cwd, outputPath);
+    fs.mkdirSync(path.dirname(outFull), { recursive: true });
+    fs.writeFileSync(outFull, `${JSON.stringify({ paths: sorted }, null, 2)}\n`, 'utf8');
+    console.log(`📍 Sitemap paths written (${sorted.length} URLs): ${outFull}`);
+}
+async function generateSitemapPathsSafe(options = {}) {
+    try {
+        await generateSitemapPaths(options);
+    }
+    catch (e) {
+        console.error('❌ Sitemap path generation failed; writing minimal / only:', e.message);
+        const cwd = options.cwd ?? process.cwd();
+        const outputPath = options.outputPath ?? 'public/sitemap-paths.json';
+        writeFallback(cwd, outputPath);
+    }
+}
+
 async function generateAllData() {
     // Load .env files if they exist (for local development)
     dotenv.config();
@@ -2466,16 +2763,21 @@ async function generateAllData() {
     const gfSuccess = await generateGravityFormsData();
     const mauticSuccess = await generateMauticData();
     const suitecrmSuccess = await generateSuiteCRMData();
-    if (!wpSuccess || !gfSuccess || !mauticSuccess || !suitecrmSuccess) {
+    const googleReviewsSuccess = await generateGoogleReviewsData();
+    if (!wpSuccess || !gfSuccess || !mauticSuccess || !suitecrmSuccess || !googleReviewsSuccess) {
         console.error('❌ Some generation tasks failed. See above for details.');
         process.exit(1);
     }
+    await generateSitemapPathsSafe();
     console.log('✅ Generation complete!');
 }
 
 exports.generateAllData = generateAllData;
+exports.generateGoogleReviewsData = generateGoogleReviewsData;
 exports.generateGravityFormsData = generateGravityFormsData;
 exports.generateMauticData = generateMauticData;
+exports.generateSitemapPaths = generateSitemapPaths;
+exports.generateSitemapPathsSafe = generateSitemapPathsSafe;
 exports.generateSuiteCRMData = generateSuiteCRMData;
 exports.generateWordPressData = generateWordPressData;
 //# sourceMappingURL=generators.cjs.map