[kyo-config] FlagPlatform: browser-safe process probe (#1832)

## Problem

`Flag` crashes on Scala.js in browsers. `FlagPlatform.env`/`envNames`
bind the `process` global to a `val` before their `typeof` guard runs:

```scala
val proc = js.Dynamic.global.process
if (js.typeOf(proc) == "undefined" || ...) ...
```

Scala.js compiles the first line to a bare `process` identifier read. In
Node that yields the process object, but in a browser (no bundler shim)
it throws `ReferenceError: process is not defined` before the guard on
the next line ever executes. Any browser app that resolves a flag during
startup dies with that error.

This is the same defect #1823 fixed in `kyo-core`'s
`SystemPlatformSpecific`. That PR carried both modules; the merge took
the `kyo-core` half, so `kyo-config` still has the crashing pattern.
This is the remaining half.

## Solution

Keep the `typeof` guard inline on the global selection, which Scala.js
compiles to a plain `typeof process` expression (safe on undeclared
identifiers by JS semantics), and only bind the `val` after the guard
passes — the same idiom `osName()`/`osArch()` and the merged
`System.env` already use. Extracted as a `hasProcess` probe since both
readers need it.

## Tests

`FlagPlatformTest` gains the missing-global topology, reproduced by
deleting `process` from the global object for the duration of the read:
`process` then becomes an *undeclared* identifier, which is exactly the
state that makes a bare read throw while `typeof process` still answers
`"undefined"`. Restoring it in a `finally` keeps the test runner (which
talks over `process.stdout`) alive even when an assertion fails.

Both new cases fail with `ReferenceError: process is not defined`
against the current code and pass with the fix. `envNames` had no
coverage at all before, so its Node-path case comes along.

`SystemPlatformSpecificJsWasmTest` is new and adds the same coverage for
the guard #1823 already merged — `env`, `osName` and `osArch` all read
`process` and none of them had a test for the browser topology.

## Notes

No behavior change on Node: the same values are returned for present,
absent and null variables.

The two modules are deliberately separate concerns here: `kyo-config`
carries the fix, `kyo-core` only gains test coverage for code already on
`main`.

Author: xsistens

kyo-config/js-wasm/src/main/scala/kyo/FlagPlatform.scala

@@ -11,24 +11,37 @@ private[kyo] object FlagPlatform {
     def properties: Iterable[String] =
         java.lang.System.getProperties.propertyNames().asScala.map(_.toString).toList
 
+    /** Must stay INLINE on the global selection: only then does Scala.js emit a plain `typeof process`, which
+      * JS semantics make safe on an undeclared identifier. Binding the selection to a val first emits a bare
+      * `process` read, which throws `ReferenceError` before any guard can run.
+      */
+    private def hasProcess: Boolean =
+        js.typeOf(js.Dynamic.global.process) != "undefined"
+
     // A host with no `process` global (a browser, or a Wasm host with no Node shim) or a missing variable
     // falls back to the stdlib read: `java.lang.System.getenv` always returns null under Scala.js-Node, but
     // a Wasm host may resolve it through its own environment binding, so the fallback still gives the
     // caller its best answer instead of a hardcoded null.
     def env(name: String): String = {
-        val proc = js.Dynamic.global.process
-        if (js.typeOf(proc) == "undefined" || js.typeOf(proc.env) == "undefined") java.lang.System.getenv(name)
+        if (!hasProcess) java.lang.System.getenv(name)
         else {
-            val value = proc.env.selectDynamic(name)
-            if (js.isUndefined(value) || value == null) java.lang.System.getenv(name)
-            else value.asInstanceOf[String]
+            val proc = js.Dynamic.global.process
+            if (js.typeOf(proc.env) == "undefined") java.lang.System.getenv(name)
+            else {
+                val value = proc.env.selectDynamic(name)
+                if (js.isUndefined(value) || value == null) java.lang.System.getenv(name)
+                else value.asInstanceOf[String]
+            }
         }
     }
 
     def envNames: Iterable[String] = {
-        val proc = js.Dynamic.global.process
-        if (js.typeOf(proc) == "undefined" || js.typeOf(proc.env) == "undefined") Iterable.empty
-        else js.Object.keys(proc.env.asInstanceOf[js.Object]).toSeq
+        if (!hasProcess) Iterable.empty
+        else {
+            val proc = js.Dynamic.global.process
+            if (js.typeOf(proc.env) == "undefined") Iterable.empty
+            else js.Object.keys(proc.env.asInstanceOf[js.Object]).toSeq
+        }
     }
 
 }

kyo-config/js-wasm/src/test/scala/kyo/FlagPlatformTest.scala

@@ -11,6 +11,19 @@ import scala.scalajs.js
   */
 class FlagPlatformTest extends AnyFreeSpec {
 
+    /** Runs `f` with `process` deleted from the global object, so it is an UNDECLARED identifier — the state a
+      * browser is in, and the one where a bare read throws while `typeof process` still answers "undefined".
+      * Restored in a `finally` because the test runner talks over `process.stdout`.
+      */
+    private def withoutProcessGlobal[A](f: => A): A = {
+        // `globalThis`, not `js.Dynamic.global`, which Scala.js allows only left of a `.`-selection.
+        val global = js.Dynamic.global.globalThis
+        val saved  = js.Dynamic.global.process
+        js.special.delete(global, "process")
+        try f
+        finally global.updateDynamic("process")(saved)
+    }
+
     "env" - {
         "reads a variable set in Node process.env" in {
             js.Dynamic.global.process.env.updateDynamic("KYO_FLAGPLATFORM_PROBE")("enabled")
@@ -23,6 +36,21 @@ class FlagPlatformTest extends AnyFreeSpec {
         "returns null for a name that is not set in Node process.env" in {
             assert(FlagPlatform.env("KYO_FLAGPLATFORM_UNSET") eq null)
         }
+
+        "falls back to the stdlib read with no process global, instead of throwing ReferenceError" in {
+            assert(withoutProcessGlobal(FlagPlatform.env("KYO_FLAGPLATFORM_PROBE")) eq null)
+        }
+    }
+
+    "envNames" - {
+        "lists the names Node process.env carries" in {
+            js.Dynamic.global.process.env.updateDynamic("KYO_FLAGPLATFORM_NAMES_PROBE")("1")
+            assert(FlagPlatform.envNames.exists(_ == "KYO_FLAGPLATFORM_NAMES_PROBE"))
+        }
+
+        "is empty with no process global, instead of throwing ReferenceError" in {
+            assert(withoutProcessGlobal(FlagPlatform.envNames).isEmpty)
+        }
     }
 
 }

kyo-core/js-wasm/src/test/scala/kyo/internal/SystemPlatformSpecificJsWasmTest.scala

@@ -0,0 +1,48 @@
+package kyo.internal
+
+import kyo.*
+import kyo.AllowUnsafe.embrace.danger
+import scala.scalajs.js as sjs
+
+class SystemPlatformSpecificJsWasmTest extends kyo.test.Test[Any]:
+
+    /** Runs `f` with `process` deleted from the global object, so it is an UNDECLARED identifier — the state a
+      * browser is in, and the one where a bare read throws while `typeof process` still answers "undefined".
+      * Restored in a `finally` because the test runner talks over `process.stdout`.
+      */
+    private def withoutProcessGlobal[A](f: => A): A =
+        // `globalThis`, not `sjs.Dynamic.global`, which Scala.js allows only left of a `.`-selection.
+        val global = sjs.Dynamic.global.globalThis
+        val saved  = sjs.Dynamic.global.process
+        sjs.special.delete(global, "process")
+        try f
+        finally global.updateDynamic("process")(saved)
+        end try
+    end withoutProcessGlobal
+
+    "with no process global" - {
+        "env returns null instead of throwing ReferenceError" in {
+            assert(withoutProcessGlobal(SystemPlatformSpecific.env("PATH")) == null)
+        }
+
+        "osName falls back to the empty string instead of throwing ReferenceError" in {
+            assert(withoutProcessGlobal(SystemPlatformSpecific.osName()) == "")
+        }
+
+        "osArch falls back to the empty string instead of throwing ReferenceError" in {
+            assert(withoutProcessGlobal(SystemPlatformSpecific.osArch()) == "")
+        }
+    }
+
+    "on Node" - {
+        "env resolves a variable set in process.env" in {
+            sjs.Dynamic.global.process.env.updateDynamic("KYO_SYSTEMPLATFORM_PROBE")("enabled")
+            assert(SystemPlatformSpecific.env("KYO_SYSTEMPLATFORM_PROBE") == "enabled")
+        }
+
+        "env returns null for a name that is not set" in {
+            assert(SystemPlatformSpecific.env("KYO_SYSTEMPLATFORM_UNSET") == null)
+        }
+    }
+
+end SystemPlatformSpecificJsWasmTest