mango-cms 0.3.33 → 0.3.35

package/cli.js

@@ -1210,4 +1210,61 @@ To stop: mango proxy stop
         }
     });
 
+// --- Vibe Orchestrator Command (HAP-1253) ---
+// Runs the bundled vibe-orchestrator straight from the installed mango package —
+// no copied source. The orchestrator drives Claude Code headless in each branch
+// worktree, streams the chat to the ⌘K drawer, and verifies the owner token that
+// Mango mints (shared VIBE_ORCH_TOKEN_SECRET). It is dependency-free (node:http
+// only), so it ships inside lib/ and runs in-process from this CLI.
+//
+// Env contract:
+//   VIBE_ORCH_TOKEN_SECRET  (required for owner auth — UNSET ⇒ fails closed, 503)
+//   VIBE_STAGING_ROOT       root holding each <site> clone (default /root/Staging)
+//   VIBE_ALLOWED_SITES      comma-list of site slugs (defaults to this project's
+//                           siteName when run from a mango project root)
+//   CLAUDE_CODE_OAUTH_TOKEN or ~/.claude/.credentials.json  (Claude credentials)
+//   VIBE_ORCH_PORT          loopback listen port (default 7130; --port overrides)
+// See lib/vibe-orchestrator/README.md for the full contract.
+program
+    .command('vibe-orchestrator')
+    .description('Run the bundled Vibe orchestrator (Claude Code headless → ⌘K drawer). '
+        + 'Env: VIBE_ORCH_TOKEN_SECRET (required), VIBE_STAGING_ROOT, VIBE_ALLOWED_SITES, '
+        + 'CLAUDE_CODE_OAUTH_TOKEN (or ~/.claude). See lib/vibe-orchestrator/README.md.')
+    .option('-p, --port <port>', 'loopback port to listen on (overrides VIBE_ORCH_PORT)')
+    .action(async (options) => {
+        const serverPath = path.join(__dirname, 'lib', 'vibe-orchestrator', 'server.js');
+        if (!fs.existsSync(serverPath)) {
+            console.error(`Error: bundled orchestrator not found at ${serverPath}`);
+            process.exit(1);
+        }
+
+        const env = { ...process.env };
+        if (options.port) env.VIBE_ORCH_PORT = String(options.port);
+
+        // Convenience: when run from a mango project root and the site allow-list
+        // isn't set explicitly, default it to this project's siteName so the
+        // orchestrator only touches this site's clones. Explicit env always wins.
+        if (!env.VIBE_ALLOWED_SITES) {
+            const settingsPath = path.join(process.cwd(), 'mango/config/settings.json');
+            try {
+                if (fs.existsSync(settingsPath)) {
+                    const { siteName } = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+                    if (siteName) env.VIBE_ALLOWED_SITES = siteName;
+                }
+            } catch (e) {
+                console.warn(`[vibe-orchestrator] could not read siteName from settings.json: ${e.message}`);
+            }
+        }
+
+        console.log(`[vibe-orchestrator] launching from ${serverPath}`);
+        const child = spawn(process.execPath, [serverPath], { stdio: 'inherit', env });
+        const forward = (sig) => { try { child.kill(sig); } catch { /* already gone */ } };
+        process.on('SIGINT', () => forward('SIGINT'));
+        process.on('SIGTERM', () => forward('SIGTERM'));
+        child.on('exit', (code, signal) => {
+            if (signal) process.kill(process.pid, signal);
+            else process.exit(code ?? 0);
+        });
+    });
+
 program.parse(process.argv);

package/default/infra/vibe/README.md

@@ -0,0 +1,43 @@
+# Vibe infra templates
+
+Default, environment-agnostic templates for the **environment-specific layer** of
+the Vibe drop-in (HAP-1255). The rest of Vibe is portable — you `npm`-upgrade
+mango-cms for the server half, flip `settings.vibe.enabled`, and consume the
+mango-ui Vibe module for the front. These templates cover the one part that can't
+be packaged: the box's reverse proxy, process supervision, and DNS.
+
+Fill in the `__PLACEHOLDERS__` and install. Nothing here is read automatically by
+Mango — they're starting points you copy to `/etc/...` (or your pm2 setup).
+
+| File | What it sets up |
+| --- | --- |
+| `nginx-vibe-staging.conf.template` | nginx vhost: the staging host **and** every `<branch>--<host>` (wildcard `server_name`) → the loopback staging gateway, with the Vite HMR WebSocket upgrade. |
+| `nginx-vibe-orchestrator.conf.template` | nginx vhost: the orchestrator host → loopback `:7130`, tuned for SSE (no buffering, long read timeout). |
+| `vibe-gateway.service` | systemd unit running `lib/staging-gateway.js` from the installed package. |
+| `vibe-orchestrator.service` | systemd unit running `lib/vibe-orchestrator/server.js` from the installed package (secrets via an `EnvironmentFile`). |
+| `ecosystem.vibe.config.cjs` | pm2 alternative that launches both processes. |
+| `cloudflare.ini.template` | the scoped `Zone:DNS:Edit` token file for `settings.vibe.gatewayDns` (per-branch DNS automation). |
+| `vibe.env.template` | the front-build `VITE_*` vars (`VITE_VIBE_SHELL`, `VITE_ORCH_URL`, …). |
+
+## Topology these templates assume
+
+```
+  Browser
+   │  page + HMR  → https://<branch>--staging-vibe.example.com ─┐
+   │  ⌘K chat     → https://vibe-orch.example.com ─────────────┐│
+   ▼                                                           ││
+  nginx ──(staging vhost)──► staging gateway :7123 ────────────┘│  demux <branch>--host
+   │                              │                              │  ├─► per-branch dev server (portRange)
+   │                              └──────────────────────────────┘  └─► shared front :7121 (no branch signal)
+   └────(orchestrator vhost)──► vibe-orchestrator :7130 ──► Claude Code headless in the worktree
+                                                            verifies owner token (VIBE_ORCH_TOKEN_SECRET,
+  Mango backend :7122 ── mints owner token, owns                    shared with Mango)
+   /system/vibe/staging-resolve · /branches · /endpoints/vibe/token
+```
+
+Default ports (all overridable): backend `7122`, shared front `7121`, gateway
+`7123`, orchestrator `7130`, per-branch dev servers from `settings.vibe.portRange`
+(default `[7200, 7399]`). Keep the gateway/orchestrator on loopback; nginx is the
+only public listener.
+
+**Full step-by-step:** see [`docs/VIBE_ACTIVATION.md`](../../../docs/VIBE_ACTIVATION.md).

package/default/infra/vibe/cloudflare.ini.template

@@ -0,0 +1,26 @@
+# ─────────────────────────────────────────────────────────────────────────────
+# Cloudflare credentials for settings.vibe.gatewayDns
+#
+# When settings.vibe.gatewayDns.enabled = true, Mango's per-branch DNS service
+# creates/cleans a proxied DNS record for each `<branch>--<staging-host>` as
+# branches are provisioned and reaped — so you do NOT have to manage a wildcard
+# record by hand. Point settings.vibe.gatewayDns.credentialsFile at a copy of
+# this file (chmod 600, OUTSIDE the repo).
+#
+# This file holds ONLY the token. The zone + control host come from
+# settings.vibe.gatewayDns ({ zone, controlHost }), not from here.
+#
+# The service resolves the token as (first hit wins):
+#   1. env  CF_API_TOKEN
+#   2. the `dns_cloudflare_api_token = …` line below (certbot-style)
+#   3. a file whose entire contents are the bare token
+#
+# The token needs Zone:DNS:Edit on the single zone in settings.vibe.gatewayDns.zone.
+# Create it: Cloudflare → My Profile → API Tokens → Create Token
+#            → "Edit zone DNS" template → scope to your zone.
+#
+# If the feature is enabled but no token resolves, per-branch DNS is logged and
+# DISABLED (provisioning still succeeds) — it never crashes a dev box.
+# ─────────────────────────────────────────────────────────────────────────────
+
+dns_cloudflare_api_token = __CF_ZONE_DNS_EDIT_TOKEN__

package/default/infra/vibe/ecosystem.vibe.config.cjs

@@ -0,0 +1,44 @@
+// ─────────────────────────────────────────────────────────────────────────────
+// pm2 ecosystem — Vibe gateway + orchestrator (alternative to the systemd units)
+//
+//   pm2 start ecosystem.vibe.config.cjs && pm2 save
+//
+// Both processes run the bundled code from node_modules/mango-cms — no copied
+// source. Replace the __PLACEHOLDERS__ (or export them in the shell first).
+// Keep secrets OUT of source control: set VIBE_ORCH_TOKEN_SECRET and the Claude
+// credential in the environment that launches pm2, not inline here.
+// ─────────────────────────────────────────────────────────────────────────────
+const APP_DIR = process.env.VIBE_APP_DIR || '__APP_DIR__';
+
+module.exports = {
+  apps: [
+    {
+      name: 'vibe-gateway',
+      script: `${APP_DIR}/node_modules/mango-cms/lib/staging-gateway.js`,
+      cwd: APP_DIR,
+      env: {
+        BACKEND_PORT: process.env.BACKEND_PORT || '__BACKEND_PORT__', // e.g. 7122
+        LISTEN_PORT: process.env.GATEWAY_PORT || '__GATEWAY_PORT__',  // e.g. 7123
+        LISTEN_HOST: '127.0.0.1',
+        FALLBACK_PORT: process.env.FALLBACK_PORT || '__FALLBACK_PORT__', // e.g. 7121
+        STAGING_DOMAIN: process.env.STAGING_HOST || '__STAGING_HOST__',
+        READINESS_TIMEOUT_MS: '25000',
+      },
+    },
+    {
+      name: 'vibe-orchestrator',
+      script: `${APP_DIR}/node_modules/mango-cms/lib/vibe-orchestrator/server.js`,
+      cwd: APP_DIR,
+      env: {
+        VIBE_ORCH_PORT: process.env.VIBE_ORCH_PORT || '__ORCH_PORT__',     // e.g. 7130
+        VIBE_STAGING_ROOT: process.env.VIBE_STAGING_ROOT || '__STAGING_ROOT__',
+        VIBE_ALLOWED_SITES: process.env.VIBE_ALLOWED_SITES || '__ALLOWED_SITES__',
+        VIBE_ALLOWED_ORIGINS: process.env.VIBE_ALLOWED_ORIGINS || '__ALLOWED_ORIGINS__',
+        // REQUIRED, set in the launching shell — unset ⇒ orchestrator 503s:
+        VIBE_ORCH_TOKEN_SECRET: process.env.VIBE_ORCH_TOKEN_SECRET,
+        // One of these for live runs (else /health reports canRunLive:false):
+        CLAUDE_CODE_OAUTH_TOKEN: process.env.CLAUDE_CODE_OAUTH_TOKEN,
+      },
+    },
+  ],
+};

package/default/infra/vibe/nginx-vibe-orchestrator.conf.template

@@ -0,0 +1,50 @@
+# ─────────────────────────────────────────────────────────────────────────────
+# Vibe orchestrator — nginx vhost template
+#
+# Fronts the bundled vibe-orchestrator (`mango vibe-orchestrator`, loopback
+# :7130). The browser's ⌘K drawer talks to this host (VITE_ORCH_URL). The
+# orchestrator binds loopback only and verifies a server-minted owner token on
+# every route except GET /health, so nginx just needs to forward and NOT buffer
+# (the /prompt response is a long-lived SSE stream).
+#
+# Placeholders to replace:
+#   __ORCH_HOST__        public orchestrator host, e.g. vibe-orch.example.com
+#   __ORCH_PORT__        loopback port (VIBE_ORCH_PORT; default 7130)
+#   __TLS_CERT__ / __TLS_KEY__   cert covering __ORCH_HOST__
+#
+# CORS is handled by the orchestrator itself (VIBE_ALLOWED_ORIGINS) — do not add
+# add_header Access-Control-* here or you will double up the headers.
+# ─────────────────────────────────────────────────────────────────────────────
+
+server {
+    listen 443 ssl;
+    listen [::]:443 ssl;
+    server_name __ORCH_HOST__;
+
+    ssl_certificate     __TLS_CERT__;
+    ssl_certificate_key __TLS_KEY__;
+
+    client_max_body_size 25m;   # screenshot + attachment uploads ride on /prompt
+
+    location / {
+        proxy_pass http://127.0.0.1:__ORCH_PORT__;
+        proxy_http_version 1.1;
+        proxy_set_header Host              $host;
+        proxy_set_header X-Real-IP         $remote_addr;
+        proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+
+        # SSE: stream tokens to the drawer as they arrive, never buffer.
+        proxy_buffering    off;
+        proxy_cache        off;
+        proxy_read_timeout 3600s;   # a long agent turn can run for minutes
+        chunked_transfer_encoding on;
+    }
+}
+
+server {
+    listen 80;
+    listen [::]:80;
+    server_name __ORCH_HOST__;
+    return 301 https://$host$request_uri;
+}

package/default/infra/vibe/nginx-vibe-staging.conf.template

@@ -0,0 +1,73 @@
+# ─────────────────────────────────────────────────────────────────────────────
+# Vibe staging gateway — nginx vhost template
+#
+# Fronts the Mango Vibe staging surface. nginx terminates the public hostname(s)
+# and proxy_passes to the loopback **staging gateway** process
+# (`node node_modules/mango-cms/lib/staging-gateway.js`, default :7123), which
+# demuxes by selected branch into each per-branch dev server, and falls back to
+# the shared front for any request without a deliberate branch signal.
+#
+# This single server block matches BOTH:
+#   • the base staging host        →  staging-vibe.example.com
+#   • every per-branch hostname     →  <branch>--staging-vibe.example.com
+# because the gateway parses `<branch>--<host>` itself. The wildcard server_name
+# means you only manage ONE vhost no matter how many branches exist.
+#
+# Placeholders to replace:
+#   __STAGING_HOST__     base staging host, e.g. staging-vibe.example.com
+#   __GATEWAY_PORT__     loopback port the gateway binds (settings/LISTEN_PORT; default 7123)
+#   __TLS_CERT__ / __TLS_KEY__   wildcard cert covering *.__STAGING_HOST__ and __STAGING_HOST__
+#                        (a Cloudflare Origin cert is simplest when the zone is proxied).
+#
+# DNS: point __STAGING_HOST__ at this box, and EITHER a wildcard
+# `*.__STAGING_HOST__` record OR enable settings.vibe.gatewayDns so Mango creates
+# each `<branch>--__STAGING_HOST__` record on demand (see cloudflare.ini.template).
+# ─────────────────────────────────────────────────────────────────────────────
+
+map $http_upgrade $connection_upgrade {
+    default upgrade;
+    ''      close;
+}
+
+server {
+    listen 443 ssl;
+    listen [::]:443 ssl;
+
+    # Base host AND every per-branch host. The leading dot matches the apex too.
+    server_name __STAGING_HOST__ *.__STAGING_HOST__;
+
+    ssl_certificate     __TLS_CERT__;
+    ssl_certificate_key __TLS_KEY__;
+
+    # Vite dev assets are large and the gateway streams them; don't buffer.
+    proxy_buffering off;
+    client_max_body_size 25m;
+
+    location / {
+        proxy_pass http://127.0.0.1:__GATEWAY_PORT__;
+        proxy_http_version 1.1;
+
+        # Preserve the real Host so the gateway can read `<branch>--<host>`.
+        proxy_set_header Host              $host;
+        proxy_set_header X-Real-IP         $remote_addr;
+        proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+
+        # Vite HMR WebSocket upgrade — required or the preview never hot-reloads.
+        proxy_set_header Upgrade    $http_upgrade;
+        proxy_set_header Connection $connection_upgrade;
+
+        # Cold per-branch boots can take a few seconds (the gateway shows a
+        # branded "starting" page via READINESS_TIMEOUT_MS); keep nginx patient.
+        proxy_read_timeout  120s;
+        proxy_send_timeout  120s;
+    }
+}
+
+# Optional: redirect plain HTTP to HTTPS.
+server {
+    listen 80;
+    listen [::]:80;
+    server_name __STAGING_HOST__ *.__STAGING_HOST__;
+    return 301 https://$host$request_uri;
+}

package/default/infra/vibe/vibe-gateway.service

@@ -0,0 +1,38 @@
+# ─────────────────────────────────────────────────────────────────────────────
+# systemd unit — Vibe staging gateway
+#
+# Runs the bundled gateway from the installed mango-cms package (no copied
+# source). It fronts the per-branch dev servers and the shared front.
+# Install:
+#   cp vibe-gateway.service /etc/systemd/system/
+#   # edit the placeholders below, then:
+#   systemctl daemon-reload && systemctl enable --now vibe-gateway
+#
+# Placeholders:
+#   __APP_DIR__       project root that contains node_modules/mango-cms
+#   __RUN_USER__      unix user to run as
+#   __BACKEND_PORT__  Mango port owning /system/vibe/staging-resolve (e.g. 7122)
+#   __GATEWAY_PORT__  loopback port to bind (must match the nginx vhost; e.g. 7123)
+#   __FALLBACK_PORT__ shared front port for un-signaled requests (e.g. 7121)
+#   __STAGING_HOST__  exact staging host, e.g. staging-vibe.example.com
+# ─────────────────────────────────────────────────────────────────────────────
+[Unit]
+Description=Mango Vibe staging gateway
+After=network.target
+
+[Service]
+Type=simple
+User=__RUN_USER__
+WorkingDirectory=__APP_DIR__
+Environment=BACKEND_PORT=__BACKEND_PORT__
+Environment=LISTEN_PORT=__GATEWAY_PORT__
+Environment=LISTEN_HOST=127.0.0.1
+Environment=FALLBACK_PORT=__FALLBACK_PORT__
+Environment=STAGING_DOMAIN=__STAGING_HOST__
+Environment=READINESS_TIMEOUT_MS=25000
+ExecStart=/usr/bin/node __APP_DIR__/node_modules/mango-cms/lib/staging-gateway.js
+Restart=always
+RestartSec=2
+
+[Install]
+WantedBy=multi-user.target

package/default/infra/vibe/vibe-orchestrator.service

@@ -0,0 +1,44 @@
+# ─────────────────────────────────────────────────────────────────────────────
+# systemd unit — Vibe orchestrator
+#
+# Runs the bundled orchestrator from the installed mango-cms package (no copied
+# source). Drives Claude Code headless and verifies the owner token Mango mints.
+# Install:
+#   cp vibe-orchestrator.service /etc/systemd/system/
+#   # edit the placeholders below, then:
+#   systemctl daemon-reload && systemctl enable --now vibe-orchestrator
+#
+# Placeholders:
+#   __APP_DIR__         project root that contains node_modules/mango-cms
+#   __RUN_USER__        unix user (its $HOME/.claude holds Claude credentials)
+#   __ORCH_PORT__       loopback port (must match the nginx vhost; e.g. 7130)
+#   __STAGING_ROOT__    root holding each <site> clone the orchestrator edits
+#   __ALLOWED_SITES__   comma-list of site slugs (e.g. mysite)
+#   __ALLOWED_ORIGINS__ comma-list of browser origins, e.g.
+#                       https://staging-vibe.example.com,https://example.com
+#
+# Secrets — set VIBE_ORCH_TOKEN_SECRET (MUST equal Mango's settings.vibe secret)
+# and the Claude credential out of band (an EnvironmentFile is shown below so the
+# secret never lives in this unit). Unset token secret ⇒ orchestrator fails
+# closed (every gated route returns 503).
+# ─────────────────────────────────────────────────────────────────────────────
+[Unit]
+Description=Mango Vibe orchestrator (Claude Code headless)
+After=network.target
+
+[Service]
+Type=simple
+User=__RUN_USER__
+WorkingDirectory=__APP_DIR__
+Environment=VIBE_ORCH_PORT=__ORCH_PORT__
+Environment=VIBE_STAGING_ROOT=__STAGING_ROOT__
+Environment=VIBE_ALLOWED_SITES=__ALLOWED_SITES__
+Environment=VIBE_ALLOWED_ORIGINS=__ALLOWED_ORIGINS__
+# Secrets live here, mode 600, root-owned (VIBE_ORCH_TOKEN_SECRET=..., CLAUDE_CODE_OAUTH_TOKEN=...):
+EnvironmentFile=/etc/vibe/orchestrator.env
+ExecStart=/usr/bin/node __APP_DIR__/node_modules/mango-cms/lib/vibe-orchestrator/server.js
+Restart=always
+RestartSec=2
+
+[Install]
+WantedBy=multi-user.target

package/default/infra/vibe/vibe.env.template

@@ -0,0 +1,24 @@
+# ─────────────────────────────────────────────────────────────────────────────
+# Vibe front-build environment (Vite)
+#
+# These VITE_* vars are read at BUILD time of the project's front (the mango-ui
+# chrome that renders <VibeLauncher/>). Set them in the front's build env so the
+# themed Vibe button appears and the drawer points at your orchestrator.
+# (See default/infra/vibe/vibe-orchestrator.service for the SERVER-side secrets.)
+# ─────────────────────────────────────────────────────────────────────────────
+
+# Master switch for the Vibe shell + button. Without this the launcher renders
+# nothing, so a plain Mango build is unaffected. (helpers/vibe/orchestrator.js →
+# vibeShellEnabled())
+VITE_VIBE_SHELL=true
+
+# Public URL of the orchestrator vhost (nginx-vibe-orchestrator.conf.template).
+VITE_ORCH_URL=https://vibe-orch.example.com
+
+# Site slug the drawer edits (defaults to settings.siteName when unset).
+VITE_ORCH_SITE=mysite
+
+# OPTIONAL — encode the branch in the hostname instead of a cookie so it stays
+# sticky across the iframe's sub-resources + HMR WebSocket. Must match the
+# wildcard the staging gateway/nginx serve. `{branch}` is substituted live.
+VITE_VIBE_SHELL_HOST_TEMPLATE={branch}--staging-vibe.example.com

package/default/mango/config/settings.json

@@ -34,5 +34,39 @@
 	"algoliaSearchKey": null,
 	"algoliaIndex": null,
 
-	"corsOrigins": "*"
+	"corsOrigins": "*",
+
+	"_vibeDoc": "Optional in-page Vibe coding feature (HAP-1096). DISABLED by default (vibe.enabled = false): with this block inert the site behaves exactly as a normal Mango project. To turn it on, set vibe.enabled = true and configure workspaceRoot + (for the staging gateway) gatewayDns. Every key is documented inline under vibe._doc. settings.json is strict JSON so guidance lives in these _doc fields rather than comments. The block is validated at boot by validateVibeConfig — an invalid value throws with a clear message. See default/vite.config.js for the matching front-end resilient config loader a Vibe project needs.",
+
+	"vibe": {
+		"_doc": {
+			"enabled": "Master switch. false = feature inert (site behaves as a normal Mango project). Set true to enable per-branch Vibe workspaces.",
+			"portRange": "[min, max] inclusive pool of TCP ports the provisioner allocates to per-branch dev servers. Must not overlap reserved ports 6121, 6122, 7121, 7122, 7130.",
+			"workspaceRoot": "Absolute, writable directory where per-branch git worktrees and their dev servers are created.",
+			"idleTimeoutMs": "Milliseconds of inactivity before the idle reaper tears a workspace down. Default 1800000 (30 min).",
+			"reaperIntervalMs": "How often (ms) the idle reaper sweeps for workspaces past idleTimeoutMs. Default 60000 (1 min).",
+			"allowedRoles": "User roles permitted to open the Vibe panel and spawn workspaces. Non-empty array of role-name strings.",
+			"defaultBranch": "Branch a request resolves to when none travels with it (e.g. a cold load before a branch is picked).",
+			"devServerCommand": "Command the provisioner spawns inside each worktree to start its front dev server. cwd = the worktree; the allocated port is passed in PORT/MANGO_PORT.",
+			"sessionCookieDomain": "Optional shared parent domain (e.g. \".example.com\") so the session cookie rides across the gateway and api subdomains. null = host-scoped (default).",
+			"sessionCookieName": "Optional override for the express-session cookie name. Pair with sessionCookieDomain to stop staging/prod under one parent from colliding. null = default name.",
+			"gatewayDns": "Optional per-branch Cloudflare DNS lifecycle for the staging gateway: { enabled, zone, controlHost, credentialsFile }. enabled = false means no DNS automation (default)."
+		},
+		"enabled": false,
+		"portRange": [7200, 7399],
+		"workspaceRoot": "/Staging",
+		"idleTimeoutMs": 1800000,
+		"reaperIntervalMs": 60000,
+		"allowedRoles": ["admin", "owner"],
+		"defaultBranch": "main",
+		"devServerCommand": "mango dev",
+		"sessionCookieDomain": null,
+		"sessionCookieName": null,
+		"gatewayDns": {
+			"enabled": false,
+			"zone": "example.com",
+			"controlHost": "vibe.example.com",
+			"credentialsFile": "/path/to/.cloudflare.ini"
+		}
+	}
 }

package/default/vite.config.js

@@ -25,9 +25,50 @@ const settingsPath = path.resolve(configPath, 'config/settings.json')
 
 const settings = JSON.parse(fs.readFileSync(settingsPath, 'utf-8'))
 
+/*
+ * Race-safe loader for the regenerated config (Vibe / HAP-1096, HAP-1203).
+ *
+ * `@collections` / `@endpoints` resolve to `mango/config/.collections.json` and
+ * `.endpoints.json`, which mango REWRITES on every rebuild. For a brief window
+ * during that rewrite the file is empty/truncated. The front imports them
+ * (`src/helpers/mango.js`) and the watch plugin below full-reloads on change —
+ * so a reload that lands mid-rewrite makes Vite's `vite:json` throw
+ * "Failed to parse JSON file ... position -1", breaking the module graph and
+ * blanking the app. This `enforce: 'pre'` loader intercepts those two ids before
+ * `vite:json`, caches the last good parse, and serves it whenever the file is
+ * transiently unreadable, so a mid-write read can never break the page. Once the
+ * file settles, the watch -> full-reload re-runs this loader and the fresh
+ * content is picked up. It returns RAW JSON text (not `export default …`) so
+ * vite's built-in `vite:json` transform still converts it to ESM normally —
+ * returning JS here causes a 500 (HAP-1203). Dev/serve only; prod serves a
+ * static `vite build` and is immune.
+ */
+function resilientConfigJson(targets) {
+	const lastGood = new Map() // absolute path -> last successfully parsed value
+	const fallback = (p) => (p === collectionsPath ? [] : {})
+	return {
+		name: 'vibe-resilient-config-json',
+		enforce: 'pre',
+		load(id) {
+			const clean = id.split('?')[0]
+			if (!targets.includes(clean)) return null
+			let value
+			try {
+				value = JSON.parse(fs.readFileSync(clean, 'utf8'))
+				lastGood.set(clean, value)
+			} catch (e) {
+				value = lastGood.has(clean) ? lastGood.get(clean) : fallback(clean)
+				this.warn(`[vibe] ${path.basename(clean)} mid-rewrite/unparseable; served ${lastGood.has(clean) ? 'last-good' : 'empty'} config (${e.message})`)
+			}
+			return JSON.stringify(value)
+		},
+	}
+}
+
 // https://vitejs.dev/config/
 export default defineConfig({
 	plugins: [
+		resilientConfigJson([collectionsPath, endpointsPath]),
 		vue(),
         // VitePWA({
         //     registerType: 'autoUpdate',
@@ -50,6 +91,11 @@ export default defineConfig({
 				server.watcher.add(endpointsPath)
 				server.watcher.on('change', (file) => {
 					if (file === collectionsPath || file === endpointsPath) {
+						// Only reload once the rewrite has SETTLED (file parses). The
+						// 'change' event also fires for the transient empty/truncated
+						// state mid-rewrite; reloading then would just bounce off the
+						// resilient loader's last-good and reload again. Skip those.
+						try { JSON.parse(fs.readFileSync(file, 'utf8')) } catch { return }
 						server.ws.send({
 							type: 'full-reload',
 						})