@codeyam-editor/codeyam-editor 0.1.3 → 0.1.5

package/npm/fleet-vm-slugs.js

@@ -0,0 +1,116 @@
+'use strict';
+
+// npm/fleet-vm-slugs.js — the per-VM custom-slug sidecar
+// (`.codeyam/logs/fleet-vm-slugs.json`). A slug is an optional human-readable
+// override for a VM's leftmost hostname label, so its public URLs become
+// `<slug>.editor.<domain>` instead of the number-derived `vm-<N>.editor.<domain>`.
+//
+// Why a sidecar and not the roster: the roster (`npm/fleet-roster.js`) is a flat
+// integer array with a hard "sorted, de-duped set of integers" invariant that
+// bash consumers (`vm-urls.sh`, the watchdog) depend on. Rather than break that
+// shape, slugs live in a SEPARATE map `{ "<N>": "<slug>" }`, fronted by a
+// read+write seam modeled exactly on fleet-roster.js (atomic temp-file + rename,
+// tolerant of a missing/malformed file).
+//
+// The slug is purely a public-hostname override — internal GCP resource names
+// (NEG / backend service / path matcher) stay keyed off the VM number, so a VM
+// added without a slug keeps its `vm-<N>` URLs unchanged.
+//
+// Env override: `VM_SLUGS_FILE` relocates the file (mirrors fleet-roster.js's
+// `VMS_STATE_FILE`); resolved once at module load.
+
+const fs = require('fs');
+const path = require('path');
+
+const { rootDir } = require('./utils');
+const { normalizeVmNumber, normalizeVmSlug } = require('./vm-urls');
+
+const VM_SLUGS_FILE = process.env.VM_SLUGS_FILE
+  || path.join(rootDir, '.codeyam', 'logs', 'fleet-vm-slugs.json');
+
+// Read the slug sidecar, returning a `{ [vmNumber]: slug }` object, or null if
+// the file is missing or malformed (treated as "no slugs"). Keys are kept as the
+// string form JSON emits; callers look them up by `String(n)`.
+function readSlugs() {
+  try {
+    const data = JSON.parse(fs.readFileSync(VM_SLUGS_FILE, 'utf8'));
+    if (data && typeof data === 'object' && !Array.isArray(data)) return data;
+  } catch { /* missing or malformed */ }
+  return null;
+}
+
+// Persist `map` as the sidecar, atomically: write a temp file then `rename` it
+// over the target so a concurrent reader never observes a half-written file. The
+// temp name carries the pid so two processes writing at once don't clobber each
+// other's temp file before their renames land. Returns the written map.
+function writeSlugs(map) {
+  const next = map && typeof map === 'object' && !Array.isArray(map) ? map : {};
+  fs.mkdirSync(path.dirname(VM_SLUGS_FILE), { recursive: true });
+  const tmp = `${VM_SLUGS_FILE}.${process.pid}.tmp`;
+  fs.writeFileSync(tmp, JSON.stringify(next));
+  fs.renameSync(tmp, VM_SLUGS_FILE); // atomic replace
+  return next;
+}
+
+/** The slug mapped to VM `n`, or null when it has none (or the file is absent).
+ *  This is the resolver every hostname derivation funnels through:
+ *  `slugFor(n) || ('vm-' + n)`. */
+function slugFor(n) {
+  const num = normalizeVmNumber(n);
+  const map = readSlugs();
+  const slug = map && map[String(num)];
+  return typeof slug === 'string' && slug.length > 0 ? slug : null;
+}
+
+/** The VM number currently mapped to `slug`, or null when no VM owns it. Used to
+ *  reject a duplicate slug BEFORE it is assigned (a slug must be unique across
+ *  the fleet, else two VMs would claim the same hostname). `slug` is normalized
+ *  first so the comparison is case-insensitive. */
+function vmForSlug(slug) {
+  const want = normalizeVmSlug(slug);
+  const map = readSlugs() || {};
+  for (const [k, v] of Object.entries(map)) {
+    if (typeof v === 'string' && v.toLowerCase() === want) {
+      const num = Number(k);
+      if (Number.isInteger(num) && num > 0) return num;
+    }
+  }
+  return null;
+}
+
+/** Assign `slug` to VM `n`, validating the slug (via `normalizeVmSlug`) and
+ *  rejecting a slug already mapped to a DIFFERENT VM. Returns the written map.
+ *  Re-assigning a VM its own existing slug is an idempotent no-op-shaped write. */
+function setSlug(n, slug) {
+  const num = normalizeVmNumber(n);
+  const norm = normalizeVmSlug(slug);
+  const owner = vmForSlug(norm);
+  if (owner != null && owner !== num) {
+    throw new Error(
+      `VM slug "${norm}" is already assigned to VM-${owner} — pick another name`,
+    );
+  }
+  const map = { ...(readSlugs() || {}) };
+  map[String(num)] = norm;
+  return writeSlugs(map);
+}
+
+/** Remove VM `n`'s slug mapping, returning the new map. Removing an absent entry
+ *  is a no-op. Called on Destroy so a number freed and later re-used doesn't
+ *  inherit a stale slug. */
+function removeSlug(n) {
+  const num = normalizeVmNumber(n);
+  const map = { ...(readSlugs() || {}) };
+  delete map[String(num)];
+  return writeSlugs(map);
+}
+
+module.exports = {
+  VM_SLUGS_FILE,
+  readSlugs,
+  writeSlugs,
+  slugFor,
+  vmForSlug,
+  setSlug,
+  removeSlug,
+};

package/npm/google-ingress.js

@@ -0,0 +1,211 @@
+'use strict';
+// Deterministic Google Cloud HTTPS-LB resource-name derivation for the fleet.
+//
+// The fleet's public browser ingress moves from cloudflared named tunnels to a
+// single Google external HTTPS Load Balancer (one URL map, host-based routing).
+// Reaching a specific port on a specific VM needs a zonal NEG + backend service
+// per (VM, surface); the URL map then routes each `vm-<N>.<surface>.<domain>`
+// host to that backend. This module is the single source of truth for those
+// Google resource NAMES so the bash provisioners (scripts/gcp/google-ingress.sh,
+// scripts/gcp/vm-ingress.sh) and any node caller derive identical strings and a
+// unit test guards them against drift — exactly the contract npm/vm-urls.js and
+// npm/launch-config.js follow.
+//
+// Pure logic only — no I/O, no env reads beyond the explicit `env` argument a
+// caller passes in, so it stays unit-testable in isolation
+// (npm/google-ingress.test.js). The HOSTNAMES it routes to are reused verbatim
+// from npm/vm-urls.js (vmHostnames / dashboardHostname): the Google migration is
+// a serving-layer swap, not a URL-scheme change, so hostnames must never drift
+// from the cert/DNS that vm-urls.js already defines.
+//
+// Stack note: this is fleet-operator infrastructure (the cloud GCE fleet that
+// runs codeyam-editor itself), not a per-app-stack assumption. A project that
+// never joins a Google fleet never sets FLEET_DOMAIN / FLEET_INGRESS=google and
+// never derives a name here; the legacy cloudflared path stays the fallback.
+
+const {
+  normalizeVmNumber,
+  vmHostnames,
+  dashboardHostname,
+} = require('./vm-urls');
+
+// The two per-VM ingress surfaces. `editor` fronts the in-VM editor control API
+// (a fixed port); `preview` fronts the VM's dev server (a per-project port).
+// Keep this list as the single definition both name derivation and the host-rule
+// builder iterate, so a third surface is one edit, not three.
+const SURFACES = Object.freeze(['editor', 'preview']);
+
+// The in-VM editor control API port. Fixed across the fleet (matches
+// named-tunnel-config.sh's EDITOR_PORT default and cloud.js's `-L …:14199`), so
+// the editor backend NEG always targets this port regardless of project.
+const EDITOR_PORT = 14199;
+
+/** The fixed in-VM editor control-API port the editor backend NEG targets. A
+ *  function (not a bare constant export) so callers read it the same way they
+ *  read the per-VM appPort — a uniform "resolve the port for this surface" shape. */
+function editorPort() {
+  return EDITOR_PORT;
+}
+
+/** Validate an ingress surface against SURFACES. The NEG / backend-service /
+ *  host-rule derivations all key off it, so a typo'd surface would mint a
+ *  resource that nothing routes to — reject it loudly at the boundary, mirroring
+ *  how vm-urls.js rejects a bad VM number or domain. Returns the surface. */
+function normalizeSurface(surface) {
+  if (!SURFACES.includes(surface)) {
+    throw new Error(
+      `surface must be one of ${SURFACES.join('|')}, got: ${surface}`,
+    );
+  }
+  return surface;
+}
+
+/** The zonal NEG name for a (VM, surface): `vm-<N>-<surface>-neg`. One network
+ *  endpoint group per surface points at the VM's internal IP + that surface's
+ *  port — the Google-native analog of a cloudflared ingress rule's local origin. */
+function negName(n, surface) {
+  const num = normalizeVmNumber(n);
+  return `vm-${num}-${normalizeSurface(surface)}-neg`;
+}
+
+/** The backend-service name for a (VM, surface): `vm-<N>-<surface>-bes`. One
+ *  backend service per host rule wraps the matching NEG (with IAP + a health
+ *  check); the URL map's host rule points at this name. */
+function backendServiceName(n, surface) {
+  const num = normalizeVmNumber(n);
+  return `vm-${num}-${normalizeSurface(surface)}-bes`;
+}
+
+/** The URL-map host rules for a VM: one `{ host, surface, backendService }` per
+ *  surface, where `host` is the EXACT hostname vm-urls.js derives (so the LB
+ *  routes the same hostnames the cert covers and DNS resolves) and
+ *  `backendService` is this module's name for that surface. Reusing
+ *  `vmHostnames` rather than re-deriving keeps the hostname scheme single-sourced.
+ *  Returns the surfaces in SURFACES order so the provisioner's output is stable.
+ *
+ *  An optional `slug` overrides the routed `host` with the VM's custom hostname
+ *  (`<slug>.<surface>.<domain>`) while the NEG / `backendService` names stay
+ *  keyed off the VM NUMBER — the slug changes only what the URL map matches, not
+ *  the internal GCP resource names. */
+function urlMapHostRules(n, domain, slug) {
+  const hosts = vmHostnames(n, domain, slug); // also validates n, domain, slug
+  return SURFACES.map((surface) => ({
+    host: hosts[surface],
+    surface,
+    backendService: backendServiceName(n, surface),
+  }));
+}
+
+/** Decide which gcloud URL-map operation reconciles a single `(host,
+ *  pathMatcher)` against the map's CURRENT state, given `hostRules` — the
+ *  flattened `[{ host, pathMatcher }]` projection of the URL map's host rules
+ *  (one entry per host, since one host rule can list several hosts). Returns
+ *  `{ op }`, one of:
+ *    - `skip`            — `host` already routes to `pathMatcher`; nothing to do.
+ *    - `add-host-rule`   — `pathMatcher` already exists (some other host points
+ *                          at it, e.g. the numeric `vmN.<surface>` host) but
+ *                          `host` is not attached: attach it. Fixes the
+ *                          `Duplicate path matcher` failure on a reused slug.
+ *    - `repoint`         — `host` exists but aims at a DIFFERENT matcher (a stale
+ *                          rule left by a destroyed VM): remove it, then attach
+ *                          `host` to the correct matcher. Fixes a reused slug
+ *                          silently skipped as "already configured" while it
+ *                          still routed to a dead backend.
+ *    - `add-path-matcher`— neither `host` nor `pathMatcher` is present: create
+ *                          the matcher and attach the host (the original path).
+ *
+ *  Pure and side-effect-free — no gcloud, no I/O — so vm-ingress.sh can read the
+ *  URL-map state in bash, ask this helper for the op, and run the matching
+ *  gcloud command, keeping the four-way decision unit-testable (the same
+ *  bash↔node contract the name derivations above follow). Tolerates a
+ *  missing/empty `hostRules`. */
+function hostRuleOperation({ hostRules, host, pathMatcher } = {}) {
+  if (!host) throw new Error('hostRuleOperation requires a host');
+  if (!pathMatcher) throw new Error('hostRuleOperation requires a pathMatcher');
+  const rules = Array.isArray(hostRules) ? hostRules : [];
+  const existing = rules.find((r) => r && r.host === host);
+  if (existing) {
+    return { op: existing.pathMatcher === pathMatcher ? 'skip' : 'repoint' };
+  }
+  const matcherExists = rules.some((r) => r && r.pathMatcher === pathMatcher);
+  return { op: matcherExists ? 'add-host-rule' : 'add-path-matcher' };
+}
+
+/** Decide whether a NEG must be attached as a backend to its backend service,
+ *  given `backends` — the BES's CURRENT `backends[].group` self-links (what
+ *  `gcloud compute backend-services describe --format='value(backends[].group)'`
+ *  emits) — and `neg`, the bare NEG name this surface expects. Returns `{ op }`:
+ *    - `skip`   — some current backend already resolves to `neg`; nothing to do.
+ *    - `attach` — `neg` is not yet a backend (an empty BES, or one wired to a
+ *                 different group): `add-backend` it.
+ *
+ *  `backends[].group` is a full self-link
+ *  (`.../networkEndpointGroups/vm-3-editor-neg`), so the match compares by
+ *  basename — the bare NEG name — not the whole URL. Pure and side-effect-free
+ *  (no gcloud, no I/O), so vm-ingress.sh reads the BES's backends in bash, asks
+ *  this helper for the op, and `add-backend`s only when it returns `attach`: the
+ *  same bash↔node contract `hostRuleOperation` follows. This is what makes `up`
+ *  *converge* a BES that pre-exists with zero backends (the permanent-503 empty-
+ *  backend bug) instead of skipping the attach as "already configured". Throws on
+ *  a missing `neg` (mirrors `hostRuleOperation`'s guard); tolerates a
+ *  missing/empty `backends`. */
+function backendNegAttachOperation({ backends, neg } = {}) {
+  if (!neg) throw new Error('backendNegAttachOperation requires a neg');
+  const groups = Array.isArray(backends) ? backends : [];
+  const basename = (g) => String(g).split('/').pop();
+  const attached = groups.some((g) => g && basename(g) === neg);
+  return { op: attached ? 'skip' : 'attach' };
+}
+
+/** The dashboard's backend-service name: `dashboard-bes`. The dashboard is a
+ *  single fleet-wide surface (not per-VM), so its name carries no VM number. The
+ *  backend itself is only fully wired once the dashboard moves onto GCE
+ *  (vm-dashboard-on-gce), but the name is defined here so the shared provisioner
+ *  and that dependent plan agree. */
+function dashboardBackendServiceName() {
+  return 'dashboard-bes';
+}
+
+/** The dashboard's zonal NEG name: `dashboard-neg`. One network endpoint group
+ *  points at the operator host's internal IP + the dashboard port (8787) — the
+ *  Google-native analog of the dashboard's old ngrok upstream. Single fleet-wide
+ *  surface, so (like the backend-service name) it carries no VM number. Wired by
+ *  scripts/gcp/dashboard-ingress.sh once the dashboard moves onto GCE. */
+function dashboardNegName() {
+  return 'dashboard-neg';
+}
+
+/** The dashboard's dedicated health-check name: `dashboard-hc`. The per-VM
+ *  surfaces share `fleet-ingress-hc` (port 14199), but the dashboard backend
+ *  health-checks its own port (8787, path /healthz), so it needs its own check
+ *  rather than reusing the editor-port one. */
+function dashboardHealthCheckName() {
+  return 'dashboard-hc';
+}
+
+/** The dashboard's single URL-map host rule: `{ host, backendService }`, where
+ *  `host` is `dashboard.<domain>` from vm-urls.js. Separate from
+ *  `urlMapHostRules` because the dashboard is fleet-wide, not keyed off a VM
+ *  number. */
+function dashboardHostRule(domain) {
+  return {
+    host: dashboardHostname(domain), // validates domain
+    backendService: dashboardBackendServiceName(),
+  };
+}
+
+module.exports = {
+  SURFACES,
+  EDITOR_PORT,
+  editorPort,
+  normalizeSurface,
+  negName,
+  backendServiceName,
+  urlMapHostRules,
+  hostRuleOperation,
+  backendNegAttachOperation,
+  dashboardBackendServiceName,
+  dashboardNegName,
+  dashboardHealthCheckName,
+  dashboardHostRule,
+};

package/npm/ingress-invoke.js

@@ -0,0 +1,292 @@
+'use strict';
+// Pure builders for the LOCAL shell invocations that wire the fleet's Google
+// HTTPS Load Balancer ingress: the shared, VM-independent infra
+// (scripts/gcp/google-ingress.sh) and one VM's per-surface backends
+// (scripts/gcp/vm-ingress.sh). cloud.js calls these to decide WHEN to wire and
+// to build the exact `{ command, args, env }` it spawns — keeping the decision
+// and the argv/env shape unit-testable without ever spawning a process, exactly
+// like npm/vm-urls.js and npm/google-ingress.js single-source their derivations.
+//
+// Pure logic only — no I/O, no env reads beyond the explicit `env`/`cfg`
+// arguments callers pass in. The fleet domain governing ingress comes from the
+// project's `.codeyam/cloud.json` (`fleetDomain`, persisted by cloud.js) with a
+// `FLEET_DOMAIN` env fallback; when neither is set every builder reports the
+// legacy quick-tunnel mode (resolveIngressDomain → null) and cloud.js leaves the
+// Add/Destroy path byte-for-byte unchanged.
+//
+// Stack note: this is fleet-operator infrastructure (the cloud GCE fleet that
+// runs codeyam-editor itself), GCP-specific by design — the same posture as the
+// scripts it invokes. A project that never joins the fleet never sets
+// fleetDomain and never reaches a builder here.
+
+const { resolveFleetDomain } = require('./vm-urls');
+
+// Cloud DNS managed-zone name google-ingress.sh defaults to. Mirrored here so a
+// cloud.json without an explicit `dnsZone` resolves to the same zone the script
+// would, rather than passing an empty DNS_ZONE that shadows the script default.
+const DEFAULT_DNS_ZONE = 'fleet-zone';
+
+/** Resolve the fleet domain that governs ingress wiring, or null when none is
+ *  configured (legacy quick-tunnel mode). `cfg.fleetDomain` (persisted in
+ *  cloud.json) wins; the `FLEET_DOMAIN` env value is the fallback. Both paths go
+ *  through vm-urls.js::resolveFleetDomain, so a present-but-malformed value
+ *  throws here (a typo'd domain must fail loud, never bake a dead host into the
+ *  URL map) and a blank value reads as "unset". */
+function resolveIngressDomain(cfg = {}, env = {}) {
+  const fromCfg = cfg.fleetDomain;
+  if (fromCfg != null && String(fromCfg).trim() !== '') {
+    return resolveFleetDomain({ FLEET_DOMAIN: fromCfg });
+  }
+  return resolveFleetDomain(env);
+}
+
+/** Resolve the Cloud DNS managed-zone name: `cfg.dnsZone`, then a `DNS_ZONE`
+ *  env override, then the `fleet-zone` default google-ingress.sh itself uses. */
+function resolveDnsZone(cfg = {}, env = {}) {
+  const fromCfg = cfg.dnsZone;
+  if (fromCfg != null && String(fromCfg).trim() !== '') return String(fromCfg).trim();
+  const fromEnv = env.DNS_ZONE;
+  if (fromEnv != null && String(fromEnv).trim() !== '') return String(fromEnv).trim();
+  return DEFAULT_DNS_ZONE;
+}
+
+/** Derive the GCE region from a zone (`us-central1-a` → `us-central1`), or null
+ *  when the zone is missing/unparseable so the caller omits REGION and lets
+ *  google-ingress.sh apply its own default. A GCE zone is a region plus a
+ *  trailing `-<letter>`. */
+function regionFromZone(zone) {
+  if (zone == null) return null;
+  const z = String(zone).trim();
+  if (z === '') return null;
+  const m = /^(.+)-[a-z]$/.exec(z);
+  return m ? m[1] : null;
+}
+
+/** Build the local invocation for `scripts/gcp/vm-ingress.sh <N> <up|down>` —
+ *  one VM's per-surface NEG → IAP backend → URL-map host rule. Returns
+ *  `{ command, args, env }`; `env` carries only the keys the script reads beyond
+ *  its own defaults (GCP_PROJECT, ZONE, FLEET_DOMAIN, APP_PORT, INSTANCE_PREFIX,
+ *  VM_SLUG). `appPort` is the resolved per-project dev-server port the preview
+ *  NEG targets; omit it (down, or unknown) to let the script's bootstrap default
+ *  stand. An optional `slug` becomes `VM_SLUG`, which makes the script route the
+ *  VM's custom `<slug>.<surface>.<domain>` host (the same slug must be passed on
+ *  `down` so the matching host rule is removed); omit it to keep the numeric
+ *  `vm-<N>` host. */
+function vmIngressInvocation({
+  scriptPath,
+  vmNumber,
+  action,
+  domain,
+  project,
+  zone,
+  appPort,
+  instancePrefix,
+  slug,
+} = {}) {
+  if (!scriptPath) throw new Error('vmIngressInvocation requires scriptPath');
+  if (action !== 'up' && action !== 'down') {
+    throw new Error(`vm-ingress action must be 'up' or 'down', got: ${action}`);
+  }
+  const n = Number(vmNumber);
+  if (!Number.isInteger(n) || n <= 0) {
+    throw new Error(`vm-ingress requires a positive VM number, got: ${vmNumber}`);
+  }
+  if (!domain) throw new Error('vmIngressInvocation requires a fleet domain');
+  const env = { FLEET_DOMAIN: domain };
+  if (project) env.GCP_PROJECT = project;
+  if (zone) env.ZONE = zone;
+  if (appPort != null && String(appPort).trim() !== '') env.APP_PORT = String(appPort);
+  if (instancePrefix) env.INSTANCE_PREFIX = instancePrefix;
+  if (slug != null && String(slug).trim() !== '') env.VM_SLUG = String(slug).trim();
+  return { command: 'bash', args: [scriptPath, String(n), action], env };
+}
+
+/** Build the local invocation for `scripts/gcp/vm-ingress.sh <N> status` — the
+ *  read-only probe that reports which of {NEG, backend service, host rule} exist
+ *  per surface plus an overall `verdict=wired|partial|unwired`. Returns
+ *  `{ command, args, env }`. Like `vmIngressInvocation` but the action is fixed
+ *  to `status` and APP_PORT is omitted — status describes resources by NAME, and
+ *  names key off the VM number, never the port. An optional `slug` rides through
+ *  as VM_SLUG so the host-rule presence check matches the VM's custom
+ *  `<slug>.<surface>.<domain>` host rather than the numeric `vm-<N>` one. */
+function vmIngressStatusInvocation({
+  scriptPath,
+  vmNumber,
+  domain,
+  project,
+  zone,
+  slug,
+} = {}) {
+  if (!scriptPath) throw new Error('vmIngressStatusInvocation requires scriptPath');
+  const n = Number(vmNumber);
+  if (!Number.isInteger(n) || n <= 0) {
+    throw new Error(`vm-ingress status requires a positive VM number, got: ${vmNumber}`);
+  }
+  if (!domain) throw new Error('vmIngressStatusInvocation requires a fleet domain');
+  const env = { FLEET_DOMAIN: domain };
+  if (project) env.GCP_PROJECT = project;
+  if (zone) env.ZONE = zone;
+  if (slug != null && String(slug).trim() !== '') env.VM_SLUG = String(slug).trim();
+  return { command: 'bash', args: [scriptPath, String(n), 'status'], env };
+}
+
+/** Parse the `verdict=<wired|partial|unwired>` line vm-ingress.sh `status`
+ *  prints, returning that verdict or null when the output carries none (e.g. the
+ *  script errored before emitting it). Pure string parsing so the reconcile
+ *  decision below stays unit-testable without spawning the script. */
+function parseIngressStatusVerdict(stdout) {
+  if (typeof stdout !== 'string') return null;
+  for (const line of stdout.split('\n')) {
+    const m = /^verdict=(wired|partial|unwired)\s*$/.exec(line.trim());
+    if (m) return m[1];
+  }
+  return null;
+}
+
+/** Pick which rostered VMs reconcile must re-wire from their status verdicts.
+ *  `statuses` is `[{ vmNumber, verdict, ... }]`; a VM is selected iff its verdict
+ *  is `unwired` or `partial` (it has missing LB resources). `wired` VMs are left
+ *  untouched — no redundant gcloud churn — and an unknown/null verdict (the probe
+ *  failed) is conservatively SKIPPED rather than blindly re-wired. Returns the
+ *  selected entries in their input order, preserving any extra fields (slug) the
+ *  caller threads through. Pure. */
+function selectIngressReconcileTargets(statuses) {
+  if (!Array.isArray(statuses)) return [];
+  return statuses.filter((s) => s && (s.verdict === 'unwired' || s.verdict === 'partial'));
+}
+
+// =============================================================================
+// Async add-time wiring (vm--async-add-time-lb-ingress-wiring)
+// =============================================================================
+// The Add used to BLOCK ~10 min on synchronous LB ingress wiring even after the
+// container was healthy and serving. The fix returns the Add at container-healthy
+// and converges the wiring in a DETACHED background tail (wire → access, the same
+// ordering cmdUp ran inline) that outlives `cloud:up` — so the dashboard's reap of
+// `cloud:up` can never SIGTERM an in-flight `backend-services create` (the add-time
+// 503 strand the old 900s synchronous await was protecting against). The
+// already-existing per-VM auto-rewire gather is the convergence backstop; it must
+// NOT race the in-flight detached tail, so the tail drops an in-flight marker the
+// dashboard reads via the pure `isWiringInflight` below.
+
+/** Build the local invocation that re-execs THIS node entry (`scriptPath`, i.e.
+ *  cloud.js) as a DETACHED `wire-add-tail` child: it runs the slow wiring + access
+ *  grant in the background so the Add returns at container-healthy. Returns
+ *  `{ command, args, env }`; the child reads `cfg`/`appPort` back out of the env
+ *  (`CY_WIRE_ADD_CFG` JSON, `CY_WIRE_ADD_PORT`) rather than re-deriving them, so the
+ *  background tail wires EXACTLY what the foreground Add would have. `nodePath` is
+ *  the node executable to re-exec (caller passes `process.execPath`); kept a
+ *  parameter so this stays pure/testable without reading the ambient env. */
+function detachedAddTailInvocation({ nodePath, scriptPath, cfg, appPort } = {}) {
+  if (!nodePath) throw new Error('detachedAddTailInvocation requires nodePath');
+  if (!scriptPath) throw new Error('detachedAddTailInvocation requires scriptPath');
+  const env = { CY_WIRE_ADD_CFG: JSON.stringify(cfg || {}) };
+  if (appPort != null && String(appPort).trim() !== '') {
+    env.CY_WIRE_ADD_PORT = String(appPort);
+  }
+  return { command: nodePath, args: [scriptPath, 'wire-add-tail'], env };
+}
+
+/** The per-VM marker file the detached add-tail holds while its wiring is still
+ *  running, so the dashboard's auto-rewire gather skips a VM whose FIRST wiring
+ *  attempt is in flight (never firing a competing `vm-ingress.sh up`). Pure path
+ *  derivation; the create/unlink/stat I/O lives at the call sites (cloud.js writes
+ *  it, server.js reads it), mirroring how the status/verdict split keeps the
+ *  decision testable without touching the filesystem. */
+function ingressInflightMarkerPath(dir, vmNumber) {
+  const n = Number(vmNumber);
+  if (!Number.isInteger(n) || n <= 0) {
+    throw new Error(`ingressInflightMarkerPath requires a positive VM number, got: ${vmNumber}`);
+  }
+  return `${dir.replace(/\/+$/, '')}/cy-ingress-inflight-vm-${n}`;
+}
+
+/** Decide whether a freshly-added VM's detached wiring is still in flight, given
+ *  the marker file's CONTENTS (the unix-ms start timestamp the tail wrote) and the
+ *  current time. Returns false when the marker is missing/empty (`content` null) —
+ *  no tail running — or STALE (older than `maxAgeMs`): a tail that crashed without
+ *  unlinking its marker must not pin auto-rewire off forever, so once the staleness
+ *  bound (comfortably past the ~10-min worst-case wiring) elapses the backstop takes
+ *  over. Pure: the caller does the `readFileSync`/`existsSync`. */
+function isWiringInflight(content, now, maxAgeMs) {
+  if (content == null) return false;
+  const started = Number(String(content).trim());
+  if (!Number.isFinite(started) || started <= 0) return false;
+  return (Number(now) - started) < Number(maxAgeMs);
+}
+
+/** Build the local invocation for `scripts/gcp/iap-access.sh <N> <grant|revoke>`
+ *  — grant or revoke `roles/iap.httpsResourceAccessor` on one VM's per-surface
+ *  backend services for a set of principals (the per-VM access whitelist).
+ *  Returns `{ command, args, env }`; `env.VM_ACCESS` is the comma-joined,
+ *  trimmed principal list the script reads (omitted when empty, so a revoke with
+ *  nothing to remove is a clean no-op), plus GCP_PROJECT / ZONE when supplied.
+ *  Mirrors `vmIngressInvocation` so the spawn shape stays unit-testable without
+ *  ever invoking gcloud. The principal STRINGS are passed through verbatim —
+ *  validation/normalization is the sidecar's job (npm/fleet-vm-access.js); this
+ *  builder only shapes the argv/env. */
+function iapAccessInvocation({
+  scriptPath,
+  vmNumber,
+  action,
+  principals,
+  project,
+  zone,
+} = {}) {
+  if (!scriptPath) throw new Error('iapAccessInvocation requires scriptPath');
+  if (action !== 'grant' && action !== 'revoke') {
+    throw new Error(`iap-access action must be 'grant' or 'revoke', got: ${action}`);
+  }
+  const n = Number(vmNumber);
+  if (!Number.isInteger(n) || n <= 0) {
+    throw new Error(`iap-access requires a positive VM number, got: ${vmNumber}`);
+  }
+  const list = Array.isArray(principals)
+    ? principals
+    : String(principals == null ? '' : principals).split(',');
+  const joined = list.map((p) => String(p).trim()).filter(Boolean).join(',');
+  const env = {};
+  if (joined) env.VM_ACCESS = joined;
+  if (project) env.GCP_PROJECT = project;
+  if (zone) env.ZONE = zone;
+  return { command: 'bash', args: [scriptPath, String(n), action], env };
+}
+
+/** Build the local invocation for `scripts/gcp/google-ingress.sh` — the shared,
+ *  VM-independent LB infra (static IP, wildcard cert, Cloud DNS, URL map, IAP
+ *  brand). Returns `{ command, args, env }`; `env` carries only the keys the
+ *  script reads beyond its defaults (GCP_PROJECT, REGION, ZONE, FLEET_DOMAIN,
+ *  DNS_ZONE). The script is idempotent, so re-invoking against existing infra is
+ *  a safe no-op. */
+function sharedIngressInvocation({
+  scriptPath,
+  domain,
+  project,
+  zone,
+  dnsZone,
+  region,
+} = {}) {
+  if (!scriptPath) throw new Error('sharedIngressInvocation requires scriptPath');
+  if (!domain) throw new Error('sharedIngressInvocation requires a fleet domain');
+  const env = { FLEET_DOMAIN: domain };
+  if (project) env.GCP_PROJECT = project;
+  if (region) env.REGION = region;
+  if (zone) env.ZONE = zone;
+  if (dnsZone) env.DNS_ZONE = dnsZone;
+  return { command: 'bash', args: [scriptPath], env };
+}
+
+module.exports = {
+  DEFAULT_DNS_ZONE,
+  resolveIngressDomain,
+  resolveDnsZone,
+  regionFromZone,
+  vmIngressInvocation,
+  vmIngressStatusInvocation,
+  parseIngressStatusVerdict,
+  selectIngressReconcileTargets,
+  detachedAddTailInvocation,
+  ingressInflightMarkerPath,
+  isWiringInflight,
+  iapAccessInvocation,
+  sharedIngressInvocation,
+};