@marvalt/digivalt-core 0.2.32 → 0.2.34

package/CHANGELOG.md

@@ -5,6 +5,22 @@ 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.34] - 2026-09-22
+
+### Added
+- `digivalt-init` reports the app's dependency lockfile in preflight, warns when `.gitignore` excludes `package-lock.json`, and gives a manual action when no supported lockfile exists.
+- Cloudflare Pages setup and AI scaffold guidance now require committing the package-manager lockfile so deployments install the tested dependency tree.
+- Init smoke coverage for missing and ignored lockfiles.
+
+**Publish/deploy:** publish **`@marvalt/digivalt-core@0.2.34`**. Consumer apps should upgrade and rerun `npx digivalt-init`; no WordPress plugin publish is required.
+
+## [0.2.33] - 2026-09-19
+
+### Added
+- **`docs/SEO-AIO.md`** — developer/AI playbook for DigiValt SEO plugin + env + prerender. Linked from `docs/README.md` and `SEO-PERFORMANCE.md`.
+
+**Publish/deploy:** publish **`@marvalt/digivalt-core@0.2.33`**. No required app code change; upgrade when you want the packaged handbook.
+
 ## [0.2.32] - 2026-09-18
 
 ### Added

package/README.md

@@ -30,7 +30,7 @@ The root package export remains as a thin compatibility layer for generator-focu
 
 - **Subpath:** `import { DigiValtRouteSeo, DigiValtSeoHead, JsonLd, buildPageJsonLd, ... } from '@marvalt/digivalt-core/seo'`
 - **Peer dependency:** `react-helmet-async` (v2+). Wrap the app in **`HelmetProvider`**.
-- **Env:** **`VITE_SEO_*`** site identity (`VITE_SEO_SITE_URL`, `VITE_SEO_SITE_NAME`, `VITE_SEO_DEFAULT_TITLE`, …). Per-URL fields come from WordPress **`digivalt_seo`**. See **[docs/SEO-PERFORMANCE.md](./docs/SEO-PERFORMANCE.md)**.
+- **Env:** **`VITE_SEO_*`** site identity. Per-URL fields come from WordPress **`digivalt_seo`**. Playbook: **[docs/SEO-AIO.md](./docs/SEO-AIO.md)**. Env table / PageSpeed: **[docs/SEO-PERFORMANCE.md](./docs/SEO-PERFORMANCE.md)**.
 - **Config:** `getSEOConfig()` / `getPerformanceConfig()` in `@marvalt/digivalt-core/config` read the same `VITE_*` values.
 
 ## Init Workflow
@@ -51,6 +51,7 @@ What init now does:
 - refreshes `scripts/generate.ts` when it matches an older DigiVAlt-managed version
 - warns instead of overwriting custom build logic or custom generator scripts
 - warns when a local `wpRegistry.tsx` / `createAppRegistry` is present; use the published `/registry` helpers when practical
+- reports a missing dependency lockfile or a `package-lock.json` excluded by `.gitignore`; commit the lockfile before Cloudflare Pages deployment
 - reports stale legacy workarounds such as alias-link scripts and old root package generator imports
 
 When to rerun it:

package/bin/init.cjs

@@ -51,6 +51,15 @@ const LEGACY_BUILD_MARKERS = [
   '@marvalt/digivalt-core',
 ];
 
+const LOCKFILE_NAMES = [
+  'package-lock.json',
+  'npm-shrinkwrap.json',
+  'pnpm-lock.yaml',
+  'yarn.lock',
+  'bun.lock',
+  'bun.lockb',
+];
+
 function getArgValue(flag) {
   const index = args.indexOf(flag);
   return index >= 0 ? args[index + 1] : undefined;
@@ -223,6 +232,24 @@ function findLocalRegistryFiles(srcDir) {
   return matches;
 }
 
+function packageLockIsIgnored() {
+  const gitignore = readTextIfExists(path.join(targetDir, '.gitignore'));
+  if (!gitignore) return false;
+
+  let ignored = false;
+  for (const rawLine of gitignore.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith('#')) continue;
+
+    const negated = line.startsWith('!');
+    const pattern = (negated ? line.slice(1) : line).replace(/^\//, '');
+    if (pattern === 'package-lock.json') {
+      ignored = !negated;
+    }
+  }
+  return ignored;
+}
+
 function inspectTargetApp(targetPackageJsonPath, templateGenerateScript) {
   const packageJson = readJson(targetPackageJsonPath);
   const scripts = packageJson.scripts || {};
@@ -295,6 +322,8 @@ function inspectTargetApp(targetPackageJsonPath, templateGenerateScript) {
     legacyRootImport: Boolean(generateScriptContent && generateScriptContent.includes("import { generators } from '@marvalt/digivalt-core';")),
     legacyViteConfigs,
     localRegistryFiles: findLocalRegistryFiles(path.join(targetDir, 'src')),
+    lockfiles: LOCKFILE_NAMES.filter((name) => fs.existsSync(path.join(targetDir, name))),
+    packageLockIgnored: packageLockIsIgnored(),
   };
 }
 
@@ -305,6 +334,7 @@ function printPreflight(status) {
   console.log(`- scripts.build: ${status.buildState}`);
   console.log(`- scripts.build:dev: ${status.buildDevState}`);
   console.log(`- scripts/generate.ts: ${status.generateState}`);
+  console.log(`- dependency lockfile: ${status.lockfiles.length > 0 ? status.lockfiles.join(', ') : 'missing'}`);
 
   if (status.legacyHackFiles.length > 0 || status.legacyPostinstall || status.legacyRootImport || status.legacyViteConfigs.length > 0) {
     console.log('- legacy DigiVAlt wiring detected: yes');
@@ -477,6 +507,18 @@ function collectLegacyWarnings(status) {
       `Local WordPress registry detected (${status.localRegistryFiles.join(', ')}). Prefer \`@marvalt/digivalt-core/registry\`; existing files were not overwritten.`
     );
   }
+
+  if (status.packageLockIgnored) {
+    report.warnings.push(
+      '`package-lock.json` is ignored by `.gitignore`. Remove that rule and commit the lockfile so Cloudflare Pages installs the tested dependency tree.'
+    );
+  }
+
+  if (status.lockfiles.length === 0) {
+    report.manualActions.push(
+      'Generate and commit a dependency lockfile before deploying (for npm: run `npm install` and commit `package-lock.json`).'
+    );
+  }
 }
 
 function printList(title, items) {
@@ -503,9 +545,10 @@ function printSummary() {
   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.');
-  console.log('7. Run `node scripts/deploy-pages.js` (or `npm run deploy:pages`) to build and deploy via Wrangler.');
+  console.log('5. Commit your dependency lockfile so Cloudflare Pages installs the same dependency tree.');
+  console.log('6. Run `npm run build` to verify static generation now runs before `vite build`.');
+  console.log('7. Run `node scripts/deploy-secrets.js` when you are ready to sync allowed env vars to Cloudflare Pages.');
+  console.log('8. Run `node scripts/deploy-pages.js` (or `npm run deploy:pages`) to build and deploy via Wrangler.');
 }
 
 try {

package/docs/AI-MASTER-PROMPT.md

@@ -14,6 +14,7 @@ Build a DigiValt consumer app with React, TypeScript, Vite, Tailwind, and Cloudf
 - Render WordPress page bodies with `DigiValtWpPage` or `createContentRegistry` from `@marvalt/digivalt-core/registry`.
 - Read app chrome with `getAppChrome()` from `@marvalt/digivalt-core/static`.
 - Keep `functions/`, `wrangler.toml`, SEO helpers, sitemap + robots Functions, prerender script, and generated sitemap flow enabled.
+- Generate and commit the package-manager lockfile. For npm, do not ignore `package-lock.json`; Cloudflare Pages must install the tested tree rather than re-resolve dependency ranges.
 - Never commit `.env`, `.env.local`, `.env.*.local`, or `.dev.vars`.
 - Update `public/sitemap-static-paths.json` for public app routes. Never hand-edit generated `public/sitemap-paths.json`.
 

package/docs/README.md

@@ -7,7 +7,8 @@ Read these in order for DigiValt app setup, deploy, and SEO.
 | [ENVIRONMENT.md](./ENVIRONMENT.md) | Devs + DevOps | Env vars, `.env` model, Cloudflare secrets, React 19 install |
 | [AI-LOCAL-WORDPRESS-BOOTSTRAP.md](./AI-LOCAL-WORDPRESS-BOOTSTRAP.md) | Humans | Local WordPress handover runbook |
 | [AI-MASTER-PROMPT.md](./AI-MASTER-PROMPT.md) | AI tools | Vite + Cloudflare scaffold prompt |
-| [SEO-PERFORMANCE.md](./SEO-PERFORMANCE.md) | Devs | `DigiValtRouteSeo`, sitemap, prerender, `VITE_SEO_*` |
+| [SEO-AIO.md](./SEO-AIO.md) | Devs + AI | End-to-end SEO/AIO: WP plugin, env, `DigiValtRouteSeo`, generate, prerender |
+| [SEO-PERFORMANCE.md](./SEO-PERFORMANCE.md) | Devs | `VITE_SEO_*` table, sitemap XML, PageSpeed |
 | [PATH-MOUNT.md](./PATH-MOUNT.md) | Devs | Path mounts via digivalt-uworker + Vite `base` + `withBasePath` |
 | [CLOUDFLARE-STREAM.md](./CLOUDFLARE-STREAM.md) | Devs | Stream helpers + `CloudflareStreamPlayer` (`/media`) |
 | [SHORTCODES.md](./SHORTCODES.md) | Devs + editors | How WP shortcodes are parsed and merged; links to adapter docs |
@@ -20,7 +21,7 @@ Package root [README.md](../README.md) covers `digivalt-init`, generators, and e
 | Subpath | Use |
 |---------|-----|
 | `@marvalt/digivalt-core/generators` | Build-time static data (`generateAllData`) |
-| `@marvalt/digivalt-core/seo` | `DigiValtSeoHead`, JSON-LD helpers |
+| `@marvalt/digivalt-core/seo` | `DigiValtRouteSeo`, `DigiValtSeoHead`, JSON-LD helpers |
 | `@marvalt/digivalt-core/registry` | Page-body registry, `DigiValtWpPage`, providers |
 | `@marvalt/digivalt-core/integrations` | Browser-only: `DigiValtTracker`, `MauticTracking`, `ChatwootWidget` |
 | `@marvalt/digivalt-core/media` | Cloudflare Stream helpers + `CloudflareStreamPlayer` |

package/docs/SEO-AIO.md

@@ -0,0 +1,59 @@
+# SEO / AIO in DigiValt apps
+
+Playbook for **developers and AI agents** wiring `@marvalt/digivalt-core` with the **DigiValt SEO** WordPress plugin. Content-manager steps: `digivalt-collaboration-docs/DIGIVALT_SEO_AIO.md`. Env tables and PageSpeed: [SEO-PERFORMANCE.md](./SEO-PERFORMANCE.md). REST field list: WordPress plugin `digivalt-seo/README.md`.
+
+## What “good” looks like
+
+- **Site identity** in `VITE_SEO_*` (one set per frontend / Cloudflare project).
+- **Per-URL** overrides in WordPress `digivalt_seo` (pages, posts, public REST CPTs).
+- **Same HTML** for humans and crawlers: prerender snapshots, not user-agent cloaking, not Yoast.
+- Visible copy and JSON-LD stay in sync (same generate JSON).
+
+## Install
+
+| Piece | Action |
+|-------|--------|
+| WordPress | Activate **DigiValt SEO**. Editors get a meta box and a Dashboard widget. |
+| App | `@marvalt/digivalt-core` with `react-helmet-async`. `npx digivalt-init` for sitemap/robots Functions and `scripts/prerender-seo.ts`. |
+| PageSync | Plugin ≥ 1.1.2 if briefs should seed `_digivalt_seo_*` meta. |
+
+## Env vs WordPress
+
+Keep in env: `VITE_SEO_SITE_URL`, `SITE_NAME`, `DEFAULT_*`, Twitter/Facebook, verification, optional `VITE_SEO_ROUTE_PREFIXES`, `VITE_SEO_FRONT_PAGE_SLUG`, `VITE_PHPLIST_NEWSLETTER_ROUTE_BASE`.
+
+Never put per-page title/description in env.
+
+## App checklist
+
+```tsx
+import { DigiValtRouteSeo } from '@marvalt/digivalt-core/seo';
+
+<DigiValtRouteSeo pathname="/about" entity={page} />
+```
+
+- One instance per route. Pass the WordPress object from static JSON (`digivalt_seo` is already on it after generate).
+- Utility routes (`subscribe`, `preferences`, 404): `noindex` and **omit** from `sitemap-static-paths.json`.
+- Front page: app `/` + `VITE_SEO_FRONT_PAGE_SLUG` or WP Reading Settings `front_page`, never also `/<frontpage-slug>` in the sitemap.
+
+`resolvePageSeo` / `buildPageJsonLd` if you need props without the React helper.
+
+## Generate and deploy
+
+`generateAllData()` (including fixture mode) writes:
+
+- `public/sitemap-paths.json` — `{ urls: [{ path, lastmod?, image? }] }`
+- `public/seo-manifest.json` — titles, descriptions, JSON-LD, body HTML for snapshots
+
+Then `vite build` then `prerenderSeoHtml()` → `dist/index.html` and `dist/{path}/index.html`.
+
+Cloudflare Pages Functions serve `/sitemap.xml` and `/robots.txt`. Do not commit those as static files.
+
+CPT URLs other than pages are **opt-in**: `VITE_SEO_ROUTE_PREFIXES=eventbrite_event:/events,member:/members/profile`.
+
+## AI agents: do not
+
+- Do not add Yoast/Rank Math.
+- Do not serve different HTML to bots vs users.
+- Do not invent `changefreq` / `priority`.
+- Do not hand-edit `sitemap-paths.json` or `seo-manifest.json`.
+- Do not register DigiValt SEO fields as WordPress PHP shortcodes.

package/docs/SEO-PERFORMANCE.md

@@ -2,6 +2,8 @@
 
 This guide is for **Vite + React** apps that use DigiValt static generation. It complements WordPress content with **document metadata**, **structured data**, and **performance-minded image/font patterns**.
 
+**How the system fits together** (WP vs env, prerender, editor workflow): **[SEO-AIO.md](./SEO-AIO.md)**. Team handbook: `digivalt-collaboration-docs/DIGIVALT_SEO_AIO.md`.
+
 ## Prerequisites
 
 1. Install the peer dependency (required for `DigiValtSeoHead`):

package/package.json

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

@@ -62,6 +62,9 @@ VITE_AUTH_MODE="direct"
 
 ## 🌩️ 5. Deploy Infrastructure to Cloudflare
 Once you connect this GitHub repository to the Cloudflare Pages dashboard:
+
+Before connecting the build, generate and commit your dependency lockfile. For npm, run `npm install`, ensure `.gitignore` does **not** exclude `package-lock.json`, and commit it. Pages must install the tested dependency tree rather than resolve fresh `^` ranges on every deployment.
+
 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:
 ```bash
@@ -73,6 +76,7 @@ node scripts/deploy-secrets.js
 Rerun `npx digivalt-init` after upgrading `@marvalt/digivalt-core` when DigiVAlt-managed scaffolding changes.
 
 Init will:
+- report a missing dependency lockfile or a `package-lock.json` excluded by `.gitignore`
 - 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`