@simon-says-build/harbormaster 0.11.0 → 0.12.0

package/README.md

@@ -131,9 +131,26 @@ block a stack still held. No docker means the empty set, never a failure.
 (systemd, launchd) runs and restarts. It keeps a marker in the state dir
 fresh, touched every minute. While the marker is fresh, clients never replace
 the broker, even an older one, and never spawn their own. If it is briefly
-down, they wait up to 45 s for the service manager to bring it back. Upgrades
+down, they wait up to 2 minutes for the service manager to bring it back. Upgrades
 are the service manager's job: restart it after installing a new version. A
 stale marker means the service is gone, and clients spawn as before. Without
 this, the broker belonged to whichever client happened to start it: on
 simon-linux-1 that was a CI job, whose orphan cleanup killed the broker and
 every emulator it ran for other jobs mid-suite. `python3 test/managed.py`.
+
+## A project's own suite env (0.12.0)
+
+`--fn-env` is per caller, so a setting every suite of a project needs had to
+be repeated by every caller (session tests, e2e, agent runs), and the one that
+forgot ran against production. A project now names it once, in
+`harbormaster.env` next to its `firebase.json`:
+
+    # every emulator suite of this project runs under the TEST service account
+    GOOGLE_APPLICATION_CREDENTIALS=./impulse-test-bq.json
+
+`KEY=VALUE` lines, `#` comments. A value starting with `./` or `../` is made
+absolute against the project, since the emulator runs functions (and
+extensions) in other directories. `acquire`: on top of the daemon's scrubbed
+env, under the caller's explicit `--fn-env`. `exec`: on top of the caller's
+ambient env, so a key exported in some shell can't leak into the suite.
+`python3 test/project_env.py`.

package/harbormaster

@@ -84,7 +84,7 @@ import uuid
 from datetime import datetime, timezone
 from pathlib import Path
 
-VERSION = "0.11.0"
+VERSION = "0.12.0"
 
 # Overridable for tests / parallel installs; default is the shared user daemon.
 # The dir keeps the old "firebase-ports" name: pre-rename binaries still installed
@@ -699,7 +699,7 @@ class Broker:
         # daemon's env — the functions emulator runtime inherits it, which is
         # the only way a CALLER can set per-suite env (e.g. LLM_CACHE_DIR)
         # when the daemon, not the caller, spawns the emulator.
-        spawn_env = {**os.environ, "TMPDIR": str(suite_tmp)}
+        spawn_env = {**os.environ, **project_env(cwd), "TMPDIR": str(suite_tmp)}
         if extra_env:
             spawn_env.update({str(k): str(v) for k, v in dict(extra_env).items()})
         with open(log, "w") as lf:
@@ -1333,6 +1333,46 @@ def _daemon_version():
         return None
 
 
+# A PROJECT'S OWN SUITE ENV: <cwd>/harbormaster.env.
+#
+# --fn-env is per CALLER, so a setting every suite of a project needs (the
+# credentials its emulator must run under, say) had to be repeated by every
+# caller — session tests, e2e, agent runs — and the one that forgot ran
+# against production. impulse-functions (2026-10-16): its BigQuery export
+# extensions run under the Extensions emulator and stream to whatever project
+# the ambient credentials can reach; only a test service account keeps that
+# test-only. So the project names it once, in the repo:
+#
+#   # harbormaster.env, next to firebase.json
+#   GOOGLE_APPLICATION_CREDENTIALS=./impulse-test-bq.json
+#
+# KEY=VALUE lines; blank lines and `#` comments skipped; a value starting
+# with ./ or ../ is a path relative to the project, made absolute (the
+# emulator's functions run in other directories). acquire: on top of the
+# daemon's (scrubbed) env, UNDER the caller's explicit --fn-env. exec: on top
+# of the caller's ambient env, which is not a choice. Pure; missing file = {}.
+PROJECT_ENV_FILE = "harbormaster.env"
+
+
+def project_env(cwd):
+    f = Path(cwd) / PROJECT_ENV_FILE
+    if not f.is_file():
+        return {}
+    out = {}
+    for raw in f.read_text().splitlines():
+        line = raw.strip()
+        if not line or line.startswith("#") or "=" not in line:
+            continue
+        k, v = line.split("=", 1)
+        k, v = k.strip(), v.strip()
+        if len(v) >= 2 and v[0] == v[-1] and v[0] in "'\"":
+            v = v[1:-1]
+        if v.startswith("./") or v.startswith("../"):
+            v = str((Path(cwd) / v).resolve())
+        out[k] = v
+    return out
+
+
 def _ver_tuple(v):
     try:
         return tuple(int(x) for x in str(v).split("."))
@@ -1423,12 +1463,15 @@ def _ensure():
                 f"shut down — kill the 'harbormaster serve' process and retry")
     if managed:
         # Down, but a service runs it: it is restarting. Wait for it rather than
-        # start one of our own that would die with this client.
-        for _ in range(450):
+        # start one of our own that would die with this client. Two minutes: a
+        # busy box's startup sweep is not quick — the studio's first managed
+        # start reaped 75 leftovers and served after ~40 s (2026-10-09), and a
+        # client that gives up early starts a broker that fights the service.
+        for _ in range(1200):
             if _up():
                 return
             time.sleep(0.1)
-        print("harbormaster: the managed broker did not come back in 45s — starting one here", file=sys.stderr)
+        print("harbormaster: the managed broker did not come back in 120s — starting one here", file=sys.stderr)
     _spawn_daemon()
     for _ in range(50):
         if _up():
@@ -1623,7 +1666,10 @@ def main():
             if only:
                 run += ["--only", ",".join(only)]
             run.append(script)
-            rc = subprocess.call(run, cwd=cwd)
+            # The project's env beats the caller's AMBIENT env here: a key
+            # exported in some shell for a one-off script is exactly what
+            # harbormaster.env exists to keep out of the suite (project_env).
+            rc = subprocess.call(run, cwd=cwd, env={**os.environ, **project_env(cwd)})
         finally:
             try:
                 _call("POST", "/release", {"leaseId": lid})

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simon-says-build/harbormaster",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "A localhost daemon that leases each caller its own port block — isolated Firebase emulator sandboxes, Metro/Expo ports, private iOS simulators — reaped when the caller exits. No port collisions, no shared instances, no pkill.",
   "bin": {
     "harbormaster": "harbormaster",