@marvalt/digivalt-core 0.2.13 → 0.2.15

package/CHANGELOG.md

@@ -5,6 +5,15 @@ 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.14] - 2026-04-23
+
+### Added
+- **`docs/ENVIRONMENT.md`:** handover doc for developers and DevOps (two-file model, `digivalt-init` managed block, `deploy-secrets` allowlist/excludes, wrangler, variable groups). Linked from the package README.
+- **Reference templates:** [`.env.example`](.env.example) and [`.env.local.example`](.env.local.example) at the package root (same shape as `npx digivalt-init`); keep in sync with [`bin/env-example-fragments.cjs`](bin/env-example-fragments.cjs) when changing managed lines.
+
+### Changed
+- **`bin/env-example-fragments.cjs`:** optional commented lines for `VITE_THEME` and `VITE_SUITECRM_TOKEN_URL` to match `loadTheme` in `config/themes` and SuiteCRM direct-mode token URL support.
+
 ## [0.2.13] - 2026-04-20
 
 ### Added

package/README.md

@@ -8,7 +8,9 @@ Core DigiVAlt package for static data generation, runtime service wiring, and Cl
 npm install @marvalt/digivalt-core
 ```
 
-In the **DigiValt monorepo**, **`digivalt-landing`** is the reference Vite app used to test this package with WordPress plugins and Cloudflare Pages.
+Full handover reference for env vars (developers and DevOps): **[docs/ENVIRONMENT.md](./docs/ENVIRONMENT.md)**.
+
+In the **DigiVAlt monorepo**, **`digivalt-landing`** is the reference Vite app used to test this package with WordPress plugins and Cloudflare Pages.
 
 ## Entry Points
 

package/bin/env-example-fragments.cjs

@@ -20,6 +20,8 @@ VITE_FRONTEND_NAME=My App
 VITE_ENABLED_POST_TYPES=posts,pages
 VITE_DEFAULT_MAX_ITEMS=200
 VITE_USE_DSTYLER=true
+# Optional theme name (default digivalt_core; see loadTheme in config/themes)
+# VITE_THEME=
 
 # Optional: Gravity Forms API base if not derived from WordPress URL
 # VITE_GRAVITY_FORMS_API_URL=
@@ -29,6 +31,8 @@ VITE_MAUTIC_URL=
 VITE_MAUTIC_PROXY_URL=
 VITE_SUITECRM_URL=
 VITE_SUITECRM_PROXY_URL=
+# Optional; OAuth token endpoint if not the default for your SuiteCRM
+# VITE_SUITECRM_TOKEN_URL=
 VITE_SUPABASE_URL=
 VITE_SUPABASE_ANON_KEY=
 

package/docs/ENVIRONMENT.md

@@ -0,0 +1,51 @@
+# DigiVAlt environment variables
+
+This document is the handover reference for **DevOps** (Cloudflare, secrets) and **app developers** using `@marvalt/digivalt-core`. The **canonical list of variable lines** that `npx digivalt-init` installs lives in the package at [`bin/env-example-fragments.cjs`](../bin/env-example-fragments.cjs). The same content is committed as [`.env.example`](../.env.example) and [`.env.local.example`](../.env.local.example) for browsing in Git or the IDE; **when you change the fragments file, update those two files in the same change**.
+
+## Two-file model (developers)
+
+- **`.env.example`** — team-safe, public-style placeholders. Copy to **`.env`** if your tools only read `.env`.
+- **`.env.local.example`** — same idea for secrets. Copy to **`.env.local`** and fill real values. **Never commit** `.env` or `.env.local` with production secrets.
+- Vite exposes only variables whose names are prefixed with **`VITE_`** to the browser (except where Node-only scripts read `process.env` at build or in Pages Functions; see below).
+
+## `npx digivalt-init` and the managed block
+
+Run **`npx digivalt-init`** in the app root after first adding DigiVAlt or after upgrading `@marvalt/digivalt-core` when you want the latest scaffolded env template.
+
+The command **creates or updates** `.env.example` and `.env.local.example`. The DigiValt content is wrapped in markers (see [`bin/init.cjs`](../bin/init.cjs): `ENV_MANAGED_START` / `ENV_MANAGED_END`). **Lines you add outside that block are preserved**; the block itself is replaced when you rerun init so teams stay aligned with the package. If an old file has no markers, init **appends** the block and warns you to merge manually once.
+
+**Node / static generation aliases:** Generators and some scripts also accept un-prefixed names (e.g. `WORDPRESS_API_URL`, `WP_API_USERNAME`) as alternatives to `VITE_*` when running under Node. Prefer the `VITE_` names in app repos for consistency.
+
+**`VITE_IS_LOVABLE` (generators only):** Used in hosted Lovable/CI “fixture” flows to skip live API fetches. **Do not set this in local full-data development.** See [SEO-PERFORMANCE.md](./SEO-PERFORMANCE.md) and your app’s `DIGIVALT_SETUP.md`. It is **not** part of the managed example block; it is listed in `deploy-secrets` excluded keys (below).
+
+## Handover to DevOps (Cloudflare and secrets)
+
+### `node scripts/deploy-secrets.js`
+
+After `digivalt-init`, the app has [`scripts/deploy-secrets.js`](../template/scripts/deploy-secrets.js) (from the template). It reads **`.env`** and **`.env.local`**, then uploads only keys that pass an **allowlist** to Cloudflare Pages via Wrangler `pages secret bulk`.
+
+- **Allowlist (summary):** patterns include `CLOUDFLARE_*`, `CF_ACCESS_*`, `TURNSTILE_*`, `VITE_SEO_*`, and `VITE_`-prefixed keys for WordPress, Gravity Forms, Mautic, SuiteCRM, Supabase, Cloudflare worker URL, auth, Turnstile, Chatwoot, theme, and similar integrations (see the `allowedPatterns` array in the script).
+- **Excluded from bulk upload (set in the Pages UI or locally instead):** `NODE_ENV`, `VITE_IS_LOVABLE`, `VITE_LOCAL_DEVELOPMENT`, `VITE_AUTH_MODE`, `VITE_DEFAULT_MAX_ITEMS` — so environment-specific or non-secret toggles are not mass-synced.
+- **Empty values** are skipped. **`CLOUDFLARE_ACCOUNT_ID`** in env is used when invoking Wrangler; the **project name** comes from **`wrangler.toml`** in the app root.
+- **Turnstile:** `VITE_TURNSTILE_SITE_KEY` is for the browser; **`TURNSTILE_SECRET_KEY`** is server-only for Pages Functions (not a `VITE_` var). Both can appear in the allowlist path when set in your env files.
+
+### Wrangler and Pages
+
+Align **`name`** in `wrangler.toml` with your **Cloudflare Pages** project. Local Functions development may use **`.dev.vars.example`** (from the template) copied to `.dev.vars`.
+
+## Variable groups (what they’re for)
+
+| Area | Notes |
+|------|--------|
+| **WordPress / static gen** | `VITE_WORDPRESS_API_URL`, `VITE_AUTH_MODE`, `VITE_CLOUDFLARE_WORKER_URL`, `VITE_LOCAL_DEVELOPMENT`, `VITE_ENABLED_POST_TYPES`, `VITE_DEFAULT_MAX_ITEMS`, `VITE_USE_DSTYLER`, `VITE_FRONTEND_ID` / `VITE_FRONTEND_NAME` — used by hooks, generators, and `getIntegrationConfig` / `getAppEnvironmentConfig`. |
+| **Theme** | `VITE_THEME` — optional; see `loadTheme` in `config/themes`. |
+| **Integrations (URLs often public; secrets in `.env.local`)** | Mautic, SuiteCRM, Supabase, Chatwoot, Gravity Forms — see `getIntegrationConfig` in `src/config/integrations.ts`. `VITE_SUITECRM_TOKEN_URL` is optional for non-default OAuth token endpoints (`environment.ts`). |
+| **SEO** | `VITE_SEO_*` — see [SEO-PERFORMANCE.md](./SEO-PERFORMANCE.md) and `getSEOConfig`. |
+| **Performance** | `VITE_PERF_*` — optional toggles; see [SEO-PERFORMANCE.md](./SEO-PERFORMANCE.md) and `getPerformanceConfig`. |
+| **Secrets (typical in `.env.local`)** | WordPress app password, Cloudflare Access, Mautic API keys, GF keys, SuiteCRM creds, `VITE_FRONTEND_SECRET` / `VITE_WP_REFRESH_SECRET` (webhook), `VITE_TURNSTILE_SITE_KEY` + `TURNSTILE_SECRET_KEY`. |
+
+## Further reading
+
+- [SEO-PERFORMANCE.md](./SEO-PERFORMANCE.md) — `VITE_SEO_*`, `VITE_PERF_*`, sitemap, Lovable / `VITE_IS_LOVABLE` behavior
+- [Template `DIGIVALT_SETUP.md`](../template/DIGIVALT_SETUP.md) — onboarding in a Vite app
+- [README.md](../README.md) — init workflow and `deploy-secrets` overview

package/package.json

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