@codeyam-editor/codeyam-editor 0.1.4 → 0.1.6

package/npm/fleet-env.js

@@ -99,6 +99,89 @@ function envToDict(text) {
   return dict;
 }
 
+// Canonicalize a git repo URL for identity comparison. Strips any embedded
+// credentials (`user@` / `user:pass@`), normalizes the two forms GitHub emits
+// — `git@host:owner/repo` (scp-like) and `https://host/owner/repo` — to a
+// single `host/owner/repo` shape, drops a trailing `.git` and trailing
+// slashes, and lowercases the result. Returns '' for null/empty. This makes
+// `https://github.com/sfpatchworks/back-office.git` equal to
+// `git@github.com:sfpatchworks/back-office`, so the per-slot env tag matches
+// the fleet repo regardless of which URL form each was recorded in.
+function normalizeRepoUrl(url) {
+  let s = String(url == null ? '' : url).trim();
+  if (s === '') return '';
+  // scp-like `user@host:owner/repo` → `host/owner/repo` (only when there is no
+  // `://` scheme; `[^@/:]+@[^:/]+:` guarantees a single `host:` colon, not a
+  // scheme's `://`).
+  const scp = s.match(/^[^@/:]+@([^:/]+):(.+)$/);
+  if (scp) {
+    s = `${scp[1]}/${scp[2]}`;
+  } else {
+    s = s.replace(/^[a-zA-Z][a-zA-Z0-9+.-]*:\/\//, ''); // strip scheme
+    s = s.replace(/^[^@/]+@/, '');                       // strip credentials
+  }
+  s = s.replace(/\/+$/, '').replace(/\.git$/i, '');
+  return s.toLowerCase();
+}
+
+// Classify whether a slot's persisted env may be re-applied to the repo the
+// slot now serves. Returns one of:
+//   'apply'         — metaRepo is non-empty and normalizes equal to currentRepo
+//   'skip-mismatch' — metaRepo is non-empty but normalizes differently
+//   'skip-untagged' — metaRepo is empty/absent (a legacy file with no meta
+//                     sidecar; treated as unattributed and never replayed)
+// This is the guard that stops a prior project's env from silently bleeding
+// onto a new, unrelated project that reuses the same VM slot number.
+function classifyEnvApplicability({ metaRepo, currentRepo } = {}) {
+  const tagged = normalizeRepoUrl(metaRepo);
+  if (tagged === '') return 'skip-untagged';
+  return tagged === normalizeRepoUrl(currentRepo) ? 'apply' : 'skip-mismatch';
+}
+
+// Prisma datasource providers we know how to scheme-check a `DATABASE_URL`
+// against. Used to skip the generator block's `provider = "prisma-client-js"`
+// and match only the datasource `provider`.
+const DB_PROVIDERS = new Set([
+  'sqlite', 'postgresql', 'postgres', 'mysql', 'sqlserver', 'mongodb', 'cockroachdb',
+]);
+
+// Advisory: detect a Prisma datasource provider vs `DATABASE_URL` scheme
+// mismatch. Returns a short, actionable warning string, or null. Only fires
+// when `schemaText` declares a recognized datasource `provider` AND `envText`
+// declares a `DATABASE_URL` whose scheme is incompatible with it — currently
+// the two directions that actually broke a live project: provider `sqlite`
+// with a `postgresql`/`postgres` URL, or provider `postgresql`/`postgres`
+// with a `file:` (SQLite) URL. Returns null when there is no schema, no
+// recognized datasource provider, no `DATABASE_URL`, or they agree — so
+// non-Prisma / no-DB projects are a silent no-op. Pure: both texts are passed
+// in by the I/O caller.
+function detectDbProviderMismatch(envText, schemaText) {
+  const schema = String(schemaText == null ? '' : schemaText);
+  let provider = null;
+  const re = /provider\s*=\s*"([^"]+)"/g;
+  let m;
+  while ((m = re.exec(schema)) !== null) {
+    const p = m[1].toLowerCase();
+    if (DB_PROVIDERS.has(p)) { provider = p; break; }
+  }
+  if (!provider) return null;
+  const dict = envToDict(envText) || {};
+  const url = dict.DATABASE_URL;
+  if (!url) return null;
+  const scheme = (String(url).match(/^([a-zA-Z][a-zA-Z0-9+.-]*):/) || [])[1];
+  if (!scheme) return null;
+  const s = scheme.toLowerCase();
+  const isPostgres = s === 'postgresql' || s === 'postgres';
+  const isSqlite = s === 'file';
+  if (provider === 'sqlite' && isPostgres) {
+    return `DATABASE_URL scheme "${scheme}" is a Postgres URL but the Prisma schema declares provider = "sqlite" — the app will fail to open its database. Re-enter env with a file: URL, or fix the schema provider.`;
+  }
+  if ((provider === 'postgresql' || provider === 'postgres') && isSqlite) {
+    return `DATABASE_URL scheme "file" is a SQLite URL but the Prisma schema declares provider = "${provider}" — the app expects a Postgres connection string. Re-enter env accordingly.`;
+  }
+  return null;
+}
+
 // Wrap a parsed launch-form env dict in the cloud:up bootstrap-child-env
 // shape: spreads `envDict` so the keys land in the child's `process.env`, and
 // sets `CY_FORWARD_ENV_KEYS` to the comma-separated key list so
@@ -120,6 +203,9 @@ module.exports = {
   envHasSetupTrigger,
   envToDict,
   buildBootstrapChildEnv,
+  normalizeRepoUrl,
+  classifyEnvApplicability,
+  detectDbProviderMismatch,
   FORWARD_ENV_KEYS_ENV,
   KEY_RE,
 };

package/npm/fleet-ghcr-secret.js

@@ -0,0 +1,129 @@
+'use strict';
+
+// npm/fleet-ghcr-secret.js — pure decisions for sourcing the write:packages GHCR
+// push token from GCP Secret Manager instead of a laptop shell env or a baked
+// unit env.
+//
+// Why this exists: the fleet dashboard needs CODEYAM_GHCR_PUSH_TOKEN
+// (write:packages) for self-feeding — after one VM compiles the editor it
+// publishes the binary so the next VM pulls it (~2 min) instead of recompiling
+// (~10 min). On the GCE operator host the token was never wired in at all, so
+// self-feeding was structurally off and the "Self-feeding disabled" banner
+// (npm/fleet-prewarm.js::pushTokenDiagnostic) was permanent — and every
+// reprovision would drop any hand-set value. Reading it from Secret Manager at
+// boot via the attached service account (metadata creds) means the token never
+// lives in the unit env, a git checkout, or a laptop shell, survives reprovision
+// + rotation (a dashboard restart picks up the latest version), and both the
+// banner and the actual `cloud:up` publish get the token from one source.
+//
+// This module holds only the *decisions* (fetch-or-not, which secret, argv,
+// payload parse) so each case is unit-tested without a live gcloud. The I/O — the
+// `${GCLOUD} secrets versions access` subprocess and assigning the resolved value
+// onto process.env — lives in the dashboard server shell that calls these.
+
+// The default Secret Manager secret id the operator host reads when no explicit
+// name is configured. Kept in sync with the name provision-operator-host.sh
+// grants the SA accessor on and prints in its create-command hint.
+const DEFAULT_PUSH_TOKEN_SECRET = 'codeyam-ghcr-push-token';
+
+// Decide whether to hydrate the push token from Secret Manager, and from which
+// secret. The rule, in precedence order:
+//
+//   token present            → never fetch. An explicit env var always wins, so
+//                              the laptop path and any operator override are
+//                              untouched (strictly back-compatible).
+//   explicit secretNameEnv   → fetch that named secret (works anywhere gcloud
+//                              can reach it, laptop included, if the operator
+//                              opts in by setting CODEYAM_GHCR_PUSH_TOKEN_SECRET).
+//   onGce, no env            → fetch the DEFAULT secret. The operator host runs
+//                              with the SA attached (metadata creds), so this is
+//                              the zero-config self-feeding path.
+//   otherwise                → don't fetch. A plain laptop with neither the token
+//                              nor a secret name configured must NOT fire a
+//                              gcloud call that would just fail — no noise.
+//
+// Returns { fetch:false, reason } or { fetch:true, secretName, reason }.
+function secretFetchPlan({ token, onGce, secretNameEnv } = {}) {
+  if (token && String(token).trim()) {
+    return { fetch: false, reason: 'env token present — Secret Manager not consulted' };
+  }
+  const explicit = secretNameEnv && String(secretNameEnv).trim();
+  const secretName = explicit ? String(secretNameEnv).trim() : (onGce ? DEFAULT_PUSH_TOKEN_SECRET : '');
+  if (!secretName) {
+    return { fetch: false, reason: 'no push token, no secret configured, and not on GCE' };
+  }
+  return {
+    fetch: true,
+    secretName,
+    reason: explicit ? 'explicit CODEYAM_GHCR_PUSH_TOKEN_SECRET' : 'default secret on GCE (SA creds)',
+  };
+}
+
+// The argv suffix (after the ${GCLOUD} chokepoint prefix) that reads the latest
+// version of a secret. `latest` follows rotation: storing a new secret version
+// and restarting the dashboard picks up the new token with no reprovision. A
+// truthy `project` appends `--project <id>` so the read is pinned to the fleet
+// project rather than gcloud's ambient default; omitted when blank. Keeping the
+// project branch here (not at the call site) leaves the dashboard's I/O edge a
+// branch-free passthrough.
+function secretAccessArgv(secretName, project) {
+  const argv = ['secrets', 'versions', 'access', 'latest', '--secret', String(secretName || '')];
+  const proj = project && String(project).trim();
+  if (proj) argv.push('--project', proj);
+  return argv;
+}
+
+// Interpret one `gcloud secrets versions access` result into the outcome the
+// dashboard applies: the resolved token (empty on any failure), the console
+// method to log through ('log' | 'error'), and the operator-facing message. This
+// is where the fail-soft branching lives — a gcloud error, an empty payload, and
+// a real token each map to a distinct outcome — so the dashboard's I/O edge stays
+// thin (exec → interpret → assign) and every branch is unit-tested here.
+//
+//   hadError    truthy when the exec callback received an Error
+//   stdout      gcloud's stdout (the raw secret payload on success)
+//   stderr      gcloud's stderr (or the Error message) — tail is surfaced on error
+//   secretName  the secret that was read, for the message
+//   reason      the secretFetchPlan reason, for the message
+function interpretSecretAccess({ hadError, stdout, stderr, secretName, reason } = {}) {
+  const name = String(secretName || '');
+  const why = reason ? ` (${reason})` : '';
+  if (hadError) {
+    return {
+      token: '',
+      logLevel: 'error',
+      message: `push-token hydrate: could not read Secret Manager secret '${name}'${why}: ${String(stderr || '').slice(-200)}`,
+    };
+  }
+  const token = parseSecretPayload(stdout);
+  if (!token) {
+    return {
+      token: '',
+      logLevel: 'error',
+      message: `push-token hydrate: secret '${name}' resolved empty — self-feeding stays off`,
+    };
+  }
+  return {
+    token,
+    logLevel: 'log',
+    message: `push-token hydrate: loaded write:packages token from Secret Manager secret '${name}'${why} — self-feeding enabled`,
+  };
+}
+
+// Parse gcloud's stdout into the token. gcloud prints the raw secret payload with
+// no added framing, so this is just a trim — which also defends against a secret
+// stored with a trailing newline (the common `echo ... | gcloud secrets create`
+// footgun). A GitHub PAT never contains surrounding whitespace, so trimming is
+// safe. Non-string / null input → '' (fail-soft; the banner simply stays).
+function parseSecretPayload(stdout) {
+  if (typeof stdout !== 'string') return '';
+  return stdout.trim();
+}
+
+module.exports = {
+  DEFAULT_PUSH_TOKEN_SECRET,
+  secretFetchPlan,
+  secretAccessArgv,
+  parseSecretPayload,
+  interpretSecretAccess,
+};

package/npm/fleet-git-maintenance.js

@@ -0,0 +1,142 @@
+'use strict';
+
+/**
+ * Pure helpers for keeping the operator host's git clone healthy across the
+ * dashboard's high-frequency `git fetch origin <branch>` polling.
+ *
+ * The failure mode this exists to break: `pollPlans` fetches every ~12s in
+ * /opt/codeyam-editor. On a full or slow disk an interrupted fetch abandons a
+ * multi-hundred-MB `.git/objects/pack/tmp_pack_*` file. Those accumulate (~3GB
+ * observed), fill the disk, which makes the NEXT fetch fail sooner and leave
+ * another temp pack — a runaway that ends with a 100%-full disk and a wedged
+ * dashboard. Two mechanisms break the loop: prune the abandoned temp packs, and
+ * back off the fetch cadence while the remote keeps failing so a broken remote
+ * costs one attempt a minute instead of five a minute.
+ *
+ * Everything here is pure so it is unit-testable without a git repo or a clock;
+ * server.js owns the exec + the wall clock and passes `nowMs` in.
+ */
+
+// Backoff bounds. The floor is one normal poll interval (no penalty for a
+// single blip) and the ceiling keeps a long outage at a ~5 min retry rather
+// than backing off to effectively never.
+const DEFAULT_BASE_BACKOFF_MS = 30_000;
+const DEFAULT_MAX_BACKOFF_MS = 300_000;
+// Temp packs younger than this may belong to a fetch that is still running —
+// deleting those would sabotage a healthy fetch, so only reap the abandoned.
+const DEFAULT_STALE_PACK_MIN_AGE_MINUTES = 10;
+// `git gc --auto` is cheap when there is nothing to do, but not free; hourly is
+// often enough to retire loose objects the poll churn leaves behind.
+const DEFAULT_GC_INTERVAL_MS = 3_600_000;
+
+/** The zero state for a clone that has not yet been fetched from. */
+function initialFetchState() {
+  return { consecutiveFailures: 0, suppressedUntilMs: 0, lastGcAtMs: 0 };
+}
+
+/**
+ * Exponential backoff for consecutive fetch failures: 0 while healthy, then
+ * base, 2x base, 4x base ... capped at maxMs.
+ * @param {number} consecutiveFailures How many fetches have failed in a row.
+ * @param {Object} [opts] `{ baseMs, maxMs }` overrides.
+ * @returns {number} Milliseconds to suppress fetching for. 0 means "fetch now".
+ */
+function nextBackoffMs(consecutiveFailures, opts) {
+  const baseMs = (opts && opts.baseMs) || DEFAULT_BASE_BACKOFF_MS;
+  const maxMs = (opts && opts.maxMs) || DEFAULT_MAX_BACKOFF_MS;
+  if (!consecutiveFailures || consecutiveFailures < 1) return 0;
+  // 2^30 ms already exceeds any sane maxMs; clamp the exponent so a very long
+  // outage cannot overflow into Infinity before the cap is applied.
+  const exponent = Math.min(consecutiveFailures - 1, 30);
+  return Math.min(baseMs * Math.pow(2, exponent), maxMs);
+}
+
+/**
+ * Whether a fetch should be attempted now, or skipped because the clone is
+ * inside its post-failure backoff window.
+ * @param {Object} state A fetch state from initialFetchState().
+ * @param {number} nowMs Current epoch ms.
+ * @returns {boolean} True when the caller should attempt the fetch.
+ */
+function shouldAttemptFetch(state, nowMs) {
+  if (!state) return true;
+  return nowMs >= (state.suppressedUntilMs || 0);
+}
+
+/**
+ * Advances the state after a failed fetch: one more consecutive failure, and a
+ * suppression window sized by the backoff curve. Returns a NEW state — callers
+ * reassign rather than mutate, so a stale reference can never half-apply.
+ * @param {Object} state The prior fetch state.
+ * @param {number} nowMs Current epoch ms.
+ * @param {Object} [opts] `{ baseMs, maxMs }` backoff overrides.
+ * @returns {Object} The next fetch state.
+ */
+function recordFetchFailure(state, nowMs, opts) {
+  const prior = state || initialFetchState();
+  const consecutiveFailures = (prior.consecutiveFailures || 0) + 1;
+  return {
+    ...prior,
+    consecutiveFailures,
+    suppressedUntilMs: nowMs + nextBackoffMs(consecutiveFailures, opts)
+  };
+}
+
+/**
+ * Clears the failure streak after a successful fetch, so recovery is immediate
+ * — one good fetch drops the clone straight back to the normal poll cadence
+ * rather than walking the backoff curve back down.
+ * @param {Object} state The prior fetch state.
+ * @returns {Object} The next fetch state.
+ */
+function recordFetchSuccess(state) {
+  const prior = state || initialFetchState();
+  return { ...prior, consecutiveFailures: 0, suppressedUntilMs: 0 };
+}
+
+/**
+ * Whether `git gc --auto` is due on this clone.
+ * @param {Object} state The fetch state (carries lastGcAtMs).
+ * @param {number} nowMs Current epoch ms.
+ * @param {number} [intervalMs] How often gc should run.
+ * @returns {boolean} True when gc is due.
+ */
+function shouldRunGc(state, nowMs, intervalMs) {
+  const every = intervalMs || DEFAULT_GC_INTERVAL_MS;
+  const last = (state && state.lastGcAtMs) || 0;
+  return nowMs - last >= every;
+}
+
+/** Stamps the gc clock. Returns a NEW state. */
+function recordGcRun(state, nowMs) {
+  return { ...(state || initialFetchState()), lastGcAtMs: nowMs };
+}
+
+/**
+ * The shell command that reaps abandoned `tmp_pack_*` files from a clone's pack
+ * directory. Age-gated so a temp pack belonging to an in-flight fetch is never
+ * deleted out from under it, and `-maxdepth 1` keeps it from wandering into
+ * whatever else lives under .git.
+ * @param {string} repoRoot Absolute path to the clone's working tree.
+ * @param {number} [minAgeMinutes] Only delete temp packs older than this.
+ * @returns {string} A `find ... -delete` command safe to exec.
+ */
+function stalePackPruneCommand(repoRoot, minAgeMinutes) {
+  const age = minAgeMinutes === undefined ? DEFAULT_STALE_PACK_MIN_AGE_MINUTES : minAgeMinutes;
+  return `find "${repoRoot}/.git/objects/pack" -maxdepth 1 -type f -name 'tmp_pack_*' -mmin +${age} -delete`;
+}
+
+module.exports = {
+  initialFetchState,
+  nextBackoffMs,
+  shouldAttemptFetch,
+  recordFetchFailure,
+  recordFetchSuccess,
+  shouldRunGc,
+  recordGcRun,
+  stalePackPruneCommand,
+  DEFAULT_BASE_BACKOFF_MS,
+  DEFAULT_MAX_BACKOFF_MS,
+  DEFAULT_STALE_PACK_MIN_AGE_MINUTES,
+  DEFAULT_GC_INTERVAL_MS
+};

package/npm/fleet-host-op-limiter.js

@@ -0,0 +1,68 @@
+'use strict';
+// Global host-CPU concurrency limiter for the Fleet Dashboard's gcloud-ssh work
+// (scripts/operator/fleet-dashboard/server.js requires this). No gcloud/SSH I/O
+// itself — this module owns ONE guarantee: at most `concurrency` wrapped tasks
+// run at any instant, the rest queue FIFO. The server funnels its per-VM
+// gcloud-ssh gathers through a single shared instance so the operator host runs
+// a bounded number of `gcloud compute ssh` (Python, ~100 MB RSS + real CPU
+// apiece) processes REGARDLESS of fleet size.
+//
+// The bug this fixes: monitoring fanned out one `gcloud compute ssh … docker
+// exec` per VM per gather with no host-wide cap. `pollEffects` sized its
+// reachable-sweep and launcher-strand-sweep worker pools INDEPENDENTLY
+// (EFFECT_GATHER_CONCURRENCY each), and neither shared a budget with the heavy
+// mutation spawns — so 3 gather SSHs + 3 strand SSHs + N concurrent build SSHs
+// could all run at once. On an 8-vCPU operator host that meant 40–60 load, the
+// gcloud calls hanging in D-state and piling up faster than they completed, and
+// the dashboard itself CPU-starved (local_http=000). A single shared limiter
+// caps the instantaneous gcloud process count so the fan-out can never outrun
+// the host again.
+//
+// Deliberately a general async semaphore (not gcloud-aware): the caller passes a
+// thunk that does the I/O, so this stays pure and unit-testable with no network.
+
+// Build a concurrency limiter. `run(fn)` enqueues the zero-arg thunk `fn` and
+// returns a promise that settles with fn's resolved value (or rejects with its
+// error). At most `concurrency` thunks are in flight at once; the rest wait in a
+// FIFO queue and start as slots free. A thunk's slot is released whether it
+// resolves OR rejects, so one failing gcloud call can never leak a permanent
+// slot and starve the queue. `concurrency` is floored to 1 (a 0 / negative /
+// NaN value would otherwise wedge every task in the queue forever).
+function createHostOpLimiter(opts) {
+  const o = opts || {};
+  const raw = Number(o.concurrency);
+  const concurrency = Number.isFinite(raw) && raw >= 1 ? Math.floor(raw) : 1;
+  let active = 0;
+  const queue = [];
+
+  const pump = () => {
+    while (active < concurrency && queue.length > 0) {
+      const { fn, resolve, reject } = queue.shift();
+      active += 1;
+      // `Promise.resolve().then(fn)` normalizes a thunk that returns a value, a
+      // promise, OR throws synchronously into one promise chain — so a synchronous
+      // throw releases the slot via the reject path instead of escaping `pump`.
+      Promise.resolve().then(fn).then(
+        (val) => { active -= 1; pump(); resolve(val); },
+        (err) => { active -= 1; pump(); reject(err); },
+      );
+    }
+  };
+
+  const run = (fn) => new Promise((resolve, reject) => {
+    queue.push({ fn, resolve, reject });
+    pump();
+  });
+
+  return {
+    run,
+    // Introspection for tests + operator diagnostics; never load-bearing.
+    active: () => active,
+    queued: () => queue.length,
+    concurrency,
+  };
+}
+
+module.exports = {
+  createHostOpLimiter,
+};

package/npm/fleet-host.js

@@ -0,0 +1,74 @@
+'use strict';
+// Pure operator-host placement resolution for the fleet dashboard
+// (vm-dashboard-on-gce).
+//
+// The dashboard runs in two homes: the operator's laptop (legacy fallback) and a
+// dedicated GCE "operator host" (the primary path). Three things differ by home —
+// how gcloud authenticates, what address the dashboard binds, and how a branch
+// pin is read from the env — and each used to be an inline ternary at the top of
+// server.js's 200KB monolith, untestable. This module is the single home for
+// those decisions, so server.js delegates the RULE and keeps only the I/O, the
+// same split npm/fleet-branch.js (resolveFleetBranch) follows.
+//
+// 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/fleet-host.test.js).
+
+// Env var the systemd unit sets on the GCE operator host. Its presence (truthy)
+// is what flips the dashboard from the laptop defaults to the on-GCE defaults.
+const FLEET_ON_GCE_ENV = 'FLEET_ON_GCE';
+
+/** True when the dashboard is running on the GCE operator host, read from the
+ *  `FLEET_ON_GCE` env. Accepts the conventional truthy spellings `1` / `true` /
+ *  `yes` (case-insensitive, trimmed); everything else — unset, empty, `0`,
+ *  `false`, garbage — is false, so a laptop run (which never sets it) stays on
+ *  the loopback + named-configuration defaults. */
+function onGce(env = {}) {
+  return /^(1|true|yes)$/i.test(String(env[FLEET_ON_GCE_ENV] || '').trim());
+}
+
+/** Resolve the gcloud invocation prefix the dashboard's `${GCLOUD}` chokepoint
+ *  uses. On the GCE operator host the attached SA authenticates from instance
+ *  metadata, so a plain `gcloud` is correct (no key file, no named config). Off
+ *  GCE (laptop) it pins the non-expiring SA configuration with
+ *  `--configuration=<config>` so background loops survive OAuth-token expiry.
+ *  Returns `'gcloud'` on GCE; throws if a non-GCE call omits the config name,
+ *  since silently emitting a bare `gcloud` there would run on the operator's
+ *  personal account — the exact regression the chokepoint exists to prevent. */
+function gcloudCommand({ onGce: gce, config } = {}) {
+  if (gce) return 'gcloud';
+  const c = typeof config === 'string' ? config.trim() : '';
+  if (!c) {
+    throw new Error('gcloudCommand requires a config name when not on GCE');
+  }
+  return `gcloud --configuration=${c}`;
+}
+
+/** Resolve the address the dashboard binds. An explicit `bind` (the DASH_BIND
+ *  override) always wins. Otherwise the host serves the LB's zonal NEG so it must
+ *  bind the instance's internal NIC (`0.0.0.0`, firewalled to the LB + IAP
+ *  ranges); a laptop run binds loopback only (`127.0.0.1`). A blank/whitespace
+ *  override counts as absent so a set-but-empty env doesn't bind to an empty
+ *  string. */
+function dashboardBind({ onGce: gce, bind } = {}) {
+  const explicit = typeof bind === 'string' ? bind.trim() : '';
+  if (explicit) return explicit;
+  return gce ? '0.0.0.0' : '127.0.0.1';
+}
+
+/** Resolve the explicit branch pin from the env, or null when unpinned. The
+ *  operator-host name is `FLEET_BRANCH`; `BRANCH` is the legacy laptop alias and
+ *  is honored as a fallback. A blank/whitespace value is "no pin" (so the
+ *  dashboard tracks live git HEAD via resolveFleetBranch). Returns the trimmed
+ *  pin or null. */
+function branchPin(env = {}) {
+  const pin = String(env.FLEET_BRANCH || env.BRANCH || '').trim();
+  return pin === '' ? null : pin;
+}
+
+module.exports = {
+  FLEET_ON_GCE_ENV,
+  onGce,
+  gcloudCommand,
+  dashboardBind,
+  branchPin,
+};