fix(desktop): discover shell environment without blocking startup (#28556)

Author: Yash-Singh1

apps/desktop/src/backend/DesktopBackendConfiguration.test.ts

@@ -8,6 +8,7 @@ import * as Layer from "effect/Layer";
 import * as ManagedRuntime from "effect/ManagedRuntime";
 import * as Option from "effect/Option";
 import * as Path from "effect/Path";
+import * as Stream from "effect/Stream";
 import { ChildProcessSpawner } from "effect/process";
 
 import * as DesktopEnvironment from "../app/DesktopEnvironment.ts";
@@ -22,6 +23,8 @@ import * as DesktopWslServerTree from "../wsl/DesktopWslServerTree.ts";
 const layerShellEnvironment = (prepared = true) =>
   Layer.succeed(DesktopShellEnvironment.DesktopShellEnvironment, {
     installIntoProcess: Effect.succeed(prepared),
+    awaitDiscovery: Effect.succeed(prepared),
+    updates: Stream.empty,
   });
 
 const layerBackendConfiguration = (prepared = true) =>
@@ -237,6 +240,7 @@ describe("DesktopBackendConfiguration", () => {
         assert.equal(first.cwd, environment.backendCwd);
         assert.equal(first.captureOutput, true);
         assert.equal(first.env.ELECTRON_RUN_AS_NODE, "1");
+        assert.equal(first.env.T3CODE_DESKTOP_SHELL_DISCOVERY_PENDING, "1");
         assert.isUndefined(first.env.T3CODE_PORT);
         assert.isUndefined(first.env.T3CODE_MODE);
         assert.isUndefined(first.env.T3CODE_DESKTOP_LAN_HOST);

apps/desktop/src/backend/DesktopBackendConfiguration.ts

@@ -532,6 +532,7 @@ const resolvePrimaryStartConfig = Effect.fn("desktop.backendConfiguration.resolv
       env: {
         ...backendChildEnvPatch(),
         ELECTRON_RUN_AS_NODE: "1",
+        T3CODE_DESKTOP_SHELL_DISCOVERY_PENDING: "1",
         T3CODE_CLI_PATH: Option.getOrUndefined(input.cliPath),
       },
       extendEnv: true,

apps/desktop/src/main.ts

@@ -186,10 +186,10 @@ const layerDesktopAppActivation = DesktopAppActivation.layer.pipe(
 const layerDesktopBackend = DesktopBackendPool.layer.pipe(
   Layer.provideMerge(DesktopAppIdentity.layer),
   Layer.provideMerge(DesktopBackendConfiguration.layer),
-  Layer.provideMerge(DesktopShellEnvironment.layer),
   Layer.provideMerge(DesktopWslEnvironment.layer),
   Layer.provideMerge(DesktopWslServerTree.layer),
   Layer.provideMerge(DesktopTelemetryPublisher.layer),
+  Layer.provideMerge(DesktopShellEnvironment.layer),
   Layer.provideMerge(layerDesktopWindow),
 );
 

apps/desktop/src/shell/DesktopShellEnvironment.test.ts

@@ -3,11 +3,15 @@ import * as NodeServices from "@effect/platform-node/NodeServices";
 import { assert, describe, it } from "@effect/vitest";
 import * as HostProcess from "@t3tools/shared/HostProcess";
 import * as Effect from "effect/Effect";
+import * as Deferred from "effect/Deferred";
+import * as FileSystem from "effect/FileSystem";
 import * as Layer from "effect/Layer";
 import * as Logger from "effect/Logger";
 import * as PlatformError from "effect/PlatformError";
 import * as Sink from "effect/Sink";
 import * as Stream from "effect/Stream";
+import * as Schema from "effect/Schema";
+import * as Option from "effect/Option";
 import * as ChildProcess from "effect/process/ChildProcess";
 import * as ChildProcessSpawner from "effect/process/ChildProcessSpawner";
 import * as NodeOS from "node:os";
@@ -19,6 +23,15 @@ import * as DesktopShellEnvironment from "./DesktopShellEnvironment.ts";
 vi.mock("node:os", { spy: true });
 
 const textEncoder = new TextEncoder();
+const cacheCodec = Schema.fromJsonString(
+  Schema.Struct({
+    version: Schema.Number,
+    key: Schema.String,
+    environment: Schema.Record(Schema.String, Schema.NullOr(Schema.String)),
+  }),
+);
+const encodeCache = Schema.encodeSync(cacheCodec);
+const decodeCache = Schema.decodeUnknownEffect(cacheCodec);
 
 function envOutput(values: Readonly<Record<string, string>>): string {
   return Object.entries(values)
@@ -69,18 +82,28 @@ function runShellEnvironment(input: {
   readonly env: NodeJS.ProcessEnv;
   readonly platform: NodeJS.Platform;
   readonly userShell?: string;
+  readonly stateDir?: string;
+  readonly use?: (
+    service: DesktopShellEnvironment.DesktopShellEnvironment["Service"],
+  ) => Effect.Effect<boolean, never, import("effect/Scope").Scope>;
   readonly handler: (
     command: ChildProcess.Command,
   ) => string | { output: string; exitCode: number };
   readonly failure?: PlatformError.PlatformError;
   readonly processSpawner?: ChildProcessSpawner.ChildProcessSpawner["Service"];
 }) {
-  const layerEnvironment = Layer.succeed(
+  const layerEnvironment = Layer.effect(
     DesktopEnvironment.DesktopEnvironment,
-    DesktopEnvironment.DesktopEnvironment.of({
-      platform: input.platform,
-    } as DesktopEnvironment.DesktopEnvironment["Service"]),
-  );
+    Effect.gen(function* () {
+      const fs = yield* FileSystem.FileSystem;
+      const stateDir = input.stateDir ?? (yield* fs.makeTempDirectoryScoped());
+      return DesktopEnvironment.DesktopEnvironment.of({
+        platform: input.platform,
+        stateDir,
+        homeDirectory: "/test-home",
+      } as DesktopEnvironment.DesktopEnvironment["Service"]);
+    }),
+  ).pipe(Layer.provide(NodeServices.layer));
   const layerSpawner = Layer.succeed(
     ChildProcessSpawner.ChildProcessSpawner,
     ChildProcessSpawner.make((command) => {
@@ -97,8 +120,9 @@ function runShellEnvironment(input: {
 
   const program = Effect.gen(function* () {
     const shellEnvironment = yield* DesktopShellEnvironment.DesktopShellEnvironment;
-    const prepared = yield* shellEnvironment.installIntoProcess;
-    assert.equal(yield* shellEnvironment.installIntoProcess, prepared);
+    if (input.use) return yield* input.use(shellEnvironment);
+    const prepared = yield* shellEnvironment.awaitDiscovery;
+    assert.equal(yield* shellEnvironment.awaitDiscovery, prepared);
     return prepared;
   }).pipe(
     Effect.provide(
@@ -121,6 +145,247 @@ function runShellEnvironment(input: {
 }
 
 describe("DesktopShellEnvironment", () => {
+  it.effect("does not wait for discovery when the cache is missing", () =>
+    Effect.gen(function* () {
+      const started = yield* Deferred.make<void>();
+      const release = yield* Deferred.make<void>();
+      yield* runShellEnvironment({
+        env: { SHELL: "/test-shell", PATH: "/usr/bin" },
+        platform: "darwin",
+        handler: () => "",
+        processSpawner: ChildProcessSpawner.make(() =>
+          Deferred.succeed(started, undefined).pipe(
+            Effect.andThen(Deferred.await(release)),
+            Effect.as(makeProcess(envOutput({ PATH: "/fresh/bin" }))),
+          ),
+        ),
+        use: (service) =>
+          Effect.gen(function* () {
+            const startup = yield* service.installIntoProcess.pipe(Effect.forkChild);
+            yield* Deferred.await(started);
+            assert.isDefined(startup.pollUnsafe());
+            yield* Deferred.succeed(release, undefined);
+            return yield* service.awaitDiscovery;
+          }),
+      });
+    }),
+  );
+
+  it.effect(
+    "reuses cached paths immediately and streams fresh discovery without keeping removed paths",
+    () =>
+      Effect.gen(function* () {
+        const fs = yield* FileSystem.FileSystem;
+        const stateDir = yield* fs.makeTempDirectoryScoped();
+        const spawner = yield* ChildProcessSpawner.ChildProcessSpawner.pipe(
+          Effect.provide(NodeServices.layer),
+        );
+        const executable = yield* HostProcess.ExecutablePath;
+        const first = { SHELL: "/bin/zsh", PATH: "/usr/bin" };
+        yield* runShellEnvironment({
+          env: first,
+          stateDir,
+          platform: "darwin",
+          handler: () =>
+            envOutput({
+              PATH: "/old/bin:/usr/bin",
+              __MISE_DIFF: "old-mise",
+              SSH_AUTH_SOCK: "/old-session.sock",
+              JAVA_HOME: "/old/java",
+              SSL_CERT_FILE: "/old/cert.pem",
+            }),
+        });
+        const cachePath = `${stateDir}/shell-environment-cache.json`;
+        const cached = yield* fs.readFileString(cachePath).pipe(Effect.flatMap(decodeCache));
+        assert.equal(cached.environment.PATH, "/old/bin:/usr/bin");
+        assert.notProperty(cached.environment, "SSH_AUTH_SOCK");
+        const started = yield* Deferred.make<void>();
+        const release = yield* Deferred.make<void>();
+        const env: NodeJS.ProcessEnv = {
+          SHELL: "/bin/zsh",
+          PATH: "/launcher/bin",
+          SSH_AUTH_SOCK: "/current-session.sock",
+        };
+        const source = [
+          "const values = { PATH: '/fresh/bin:' + process.env.PATH, __MISE_DIFF: 'fresh-mise', JAVA_HOME: process.env.JAVA_HOME, SSL_CERT_FILE: process.env.SSL_CERT_FILE };",
+          "for (const [name, value] of Object.entries(values)) {",
+          "  if (value !== undefined) process.stdout.write('__T3CODE_ENV_' + name + '_START__\\n' + value + '\\n__T3CODE_ENV_' + name + '_END__\\n');",
+          "}",
+        ].join("\n");
+        let calls = 0;
+        yield* runShellEnvironment({
+          env,
+          stateDir,
+          platform: "darwin",
+          handler: () => "",
+          processSpawner: ChildProcessSpawner.make((command) => {
+            calls++;
+            return Deferred.succeed(started, undefined).pipe(
+              Effect.andThen(Deferred.await(release)),
+              Effect.andThen(
+                command._tag === "StandardCommand"
+                  ? spawner.spawn(ChildProcess.make(executable, ["-e", source], command.options))
+                  : Effect.succeed(makeProcess("")),
+              ),
+            );
+          }),
+          use: (service) =>
+            Effect.gen(function* () {
+              yield* service.installIntoProcess;
+              yield* service.installIntoProcess;
+              assert.equal(env.PATH, "/old/bin:/usr/bin:/launcher/bin");
+              assert.equal(env.SSH_AUTH_SOCK, "/current-session.sock");
+              const replay = yield* Stream.runHead(service.updates);
+              assert.isTrue(Option.isSome(replay));
+              if (Option.isSome(replay))
+                assert.equal(replay.value.environment.__MISE_DIFF, "old-mise");
+              yield* Deferred.await(started);
+              assert.equal(calls, 1);
+              yield* Deferred.succeed(release, undefined);
+              yield* service.awaitDiscovery;
+              assert.equal(env.PATH, "/fresh/bin:/launcher/bin");
+              assert.equal(env.__MISE_DIFF, "fresh-mise");
+              assert.isUndefined(env.JAVA_HOME);
+              assert.isUndefined(env.SSL_CERT_FILE);
+              const fresh = yield* Stream.runHead(service.updates);
+              assert.isTrue(Option.isSome(fresh));
+              if (Option.isSome(fresh)) {
+                assert.equal(fresh.value.environment.PATH, env.PATH);
+                assert.isTrue(fresh.value.discovered);
+              }
+              return true;
+            }),
+        });
+        const refreshed = yield* fs.readFileString(cachePath).pipe(Effect.flatMap(decodeCache));
+        assert.equal(refreshed.environment.PATH, "/fresh/bin:/launcher/bin");
+        assert.notProperty(refreshed.environment, "JAVA_HOME");
+        assert.notProperty(refreshed.environment, "SSL_CERT_FILE");
+      }).pipe(Effect.provide(NodeServices.layer)),
+  );
+
+  it.effect.each([
+    "not json",
+    '{"version":2,"key":"old","environment":{"PATH":"/bad/bin"}}',
+    '{"version":1,"key":"other-shell","environment":{"PATH":"/bad/bin"}}',
+  ])("ignores an unusable cache and still starts before discovery: %s", (contents) =>
+    Effect.gen(function* () {
+      const fs = yield* FileSystem.FileSystem;
+      const stateDir = yield* fs.makeTempDirectoryScoped();
+      yield* fs.writeFileString(`${stateDir}/shell-environment-cache.json`, contents);
+      const started = yield* Deferred.make<void>();
+      const release = yield* Deferred.make<void>();
+      const env: NodeJS.ProcessEnv = { SHELL: "/bin/zsh", PATH: "/usr/bin" };
+      yield* runShellEnvironment({
+        env,
+        stateDir,
+        platform: "darwin",
+        handler: () => "",
+        processSpawner: ChildProcessSpawner.make(() =>
+          Deferred.succeed(started, undefined).pipe(
+            Effect.andThen(Deferred.await(release)),
+            Effect.as(makeProcess(envOutput({ PATH: "/fresh/bin" }))),
+          ),
+        ),
+        use: (service) =>
+          Effect.gen(function* () {
+            const startup = yield* service.installIntoProcess.pipe(Effect.forkChild);
+            yield* Deferred.await(started);
+            assert.isDefined(startup.pollUnsafe());
+            assert.equal(env.PATH, "/usr/bin");
+            yield* Deferred.succeed(release, undefined);
+            return yield* service.awaitDiscovery;
+          }),
+      });
+      assert.equal(env.PATH, "/fresh/bin:/usr/bin");
+    }).pipe(Effect.provide(NodeServices.layer)),
+  );
+
+  it.effect(
+    "retains the last successful cache on refresh failure and ignores session values in the cache",
+    () =>
+      Effect.gen(function* () {
+        const fs = yield* FileSystem.FileSystem;
+        const stateDir = yield* fs.makeTempDirectoryScoped();
+        const contents = encodeCache({
+          version: 1,
+          key: '["darwin","/test-home","/bin/zsh",""]',
+          environment: {
+            PATH: "/cached/bin",
+            __MISE_DIFF: "cached-mise",
+            JAVA_HOME: "/cached/java",
+            NODE_EXTRA_CA_CERTS: "/cached/ca.pem",
+            SSL_CERT_FILE: "/cached/cert.pem",
+            SSL_CERT_DIR: "/cached/certs",
+            SSH_AUTH_SOCK: "/stale.sock",
+            NODE_OPTIONS: "--bad",
+          },
+        });
+        const cachePath = `${stateDir}/shell-environment-cache.json`;
+        yield* fs.writeFileString(cachePath, contents);
+        const env: NodeJS.ProcessEnv = {
+          SHELL: "/bin/zsh",
+          PATH: "/usr/bin",
+          __MISE_DIFF: "launcher-mise",
+          JAVA_HOME: "/launcher/java",
+          NODE_EXTRA_CA_CERTS: "/launcher/ca.pem",
+          SSL_CERT_FILE: "",
+          SSH_AUTH_SOCK: "/current.sock",
+        };
+        const prepared = yield* runShellEnvironment({
+          env,
+          stateDir,
+          platform: "darwin",
+          handler: () => "",
+          use: (service) =>
+            Effect.gen(function* () {
+              yield* service.installIntoProcess;
+              const replay = yield* Stream.runHead(service.updates);
+              assert.isTrue(Option.isSome(replay));
+              if (Option.isSome(replay)) {
+                assert.equal(replay.value.environment.JAVA_HOME, "/launcher/java");
+                assert.equal(replay.value.environment.NODE_EXTRA_CA_CERTS, "/launcher/ca.pem");
+              }
+              return yield* service.awaitDiscovery;
+            }),
+        });
+        assert.isFalse(prepared);
+        assert.equal(env.PATH, "/cached/bin:/usr/bin");
+        assert.equal(env.__MISE_DIFF, "cached-mise");
+        assert.equal(env.JAVA_HOME, "/launcher/java");
+        assert.equal(env.NODE_EXTRA_CA_CERTS, "/launcher/ca.pem");
+        assert.equal(env.SSL_CERT_FILE, "");
+        assert.equal(env.SSL_CERT_DIR, "/cached/certs");
+        assert.equal(env.SSH_AUTH_SOCK, "/current.sock");
+        assert.isUndefined(env.NODE_OPTIONS);
+        assert.equal(yield* fs.readFileString(cachePath), contents);
+      }).pipe(Effect.provide(NodeServices.layer)),
+  );
+
+  it.effect("cancels background discovery when the application scope closes", () =>
+    Effect.gen(function* () {
+      const started = yield* Deferred.make<void>();
+      const stopped = yield* Deferred.make<void>();
+      yield* runShellEnvironment({
+        env: { SHELL: "/bin/zsh", PATH: "/usr/bin" },
+        platform: "darwin",
+        handler: () => "",
+        processSpawner: ChildProcessSpawner.make(() =>
+          Deferred.succeed(started, undefined).pipe(
+            Effect.andThen(Effect.never),
+            Effect.ensuring(Deferred.succeed(stopped, undefined)),
+          ),
+        ),
+        use: (service) =>
+          Effect.gen(function* () {
+            yield* service.installIntoProcess;
+            yield* Deferred.await(started);
+            return true;
+          }),
+      });
+      yield* Deferred.await(stopped);
+    }),
+  );
+
   it.effect(
     "captures the login-shell PATH when startup writes more than a pipe buffer to stderr",
     () =>