// Pool registry for multiple backend processes. This file is the entry
// point for the concurrent-Windows+WSL-backend feature; see the design
// notes below before extending it.
//
// Current state:
//   - `DesktopBackendManager.ts` exposes a per-instance factory
//     (`makeBackendInstance(spec)`); the pool calls it once for the
//     Windows primary at startup, and `DesktopWslBackend.reconcile`
//     calls it through `pool.register` to bring up the WSL instance
//     when the user enables it.
//   - The primary spec wires `configResolve` to
//     `DesktopBackendConfiguration.resolvePrimary` and the
//     `onReady`/`onShutdown` callbacks to the window service. WSL
//     instances wire `configResolve: configuration.resolveWsl(...)`
//     and skip onReady/onShutdown — the window only follows the primary.
//   - The pool exposes `register(spec)` and `unregister(id)`. Each
//     registered instance gets its own child scope, so unregister can
//     stop it cleanly without tearing down the pool. The primary's id
//     refuses unregister.
//   - Settings: `wslBackendEnabled: boolean` + `wslDistro: string | null`.
//     The legacy `wslMode: "local" | "wsl"` swap setting is migrated on
//     load. IPC surface is `setWslBackendEnabled(boolean)` +
//     `setWslDistro(string | null)`; both persist and then call the
//     orchestrator's reconcile. No swap, no rollback, primary stays up.
//   - `getLocalEnvironmentBootstraps()` (plural) returns one entry per
//     pool instance currently registered with bootstrap info. The
//     primary keeps the "primary" id; WSL instances are "wsl:default"
//     or "wsl:<distro>".
//   - `pickFolder` accepts an optional `targetEnvironmentId`. Omitting
//     it gives the Windows picker — what every existing caller gets,
//     and what non-WSL users see. WSL targets route to the wsl helpers.
//   - Web settings UX: a plain toggle for "WSL backend" plus a distro
//     picker that shows up when the toggle is on. Default-off, so
//     users who never opted in see the same surface as before.
//
// Renderer-side wiring (apps/web/src/environments/local/):
//   - reconcileLocalSecondaryEnvironments() runs at app boot and after
//     WSL settings changes. It reads getLocalEnvironmentBootstraps(),
//     skips the primary (which the existing primary/ runtime owns),
//     and for every other entry POSTs the shared bootstrap token to
//     /api/auth/bootstrap/bearer on that backend's URL, fetches the
//     descriptor, builds a SavedEnvironmentRecord marked desktopLocal,
//     writes the bearer to the secret store, and opens a connection
//     through the same saved-env path remote envs use.
//   - The desktopLocal marker filters records out of saved-env
//     persistence, so toggling WSL off or switching distros doesn't
//     pollute the user's settings file. The sidebar, CommandPalette,
//     env switcher, and project-id routing all read the saved-env
//     registry, so the WSL backend shows up there without any
//     per-surface changes.
//
// Browser validation (2026-05-17, dev:desktop with wslBackendEnabled=true,
// wslDistro="Ubuntu"):
//   - Two backends listening on distinct loopback ports
//     (server.log: 13773 primary, 13774 wsl).
//   - Per-instance log files: server-child.log + server-child-wsl_Ubuntu.log.
//   - Distinct environment ids reported by each backend's
//     /.well-known/t3/environment (Windows vs Linux platform).
//   - Renderer completes the bearer-token bootstrap against the WSL
//     backend (POST /api/auth/bootstrap/bearer 200), obtains a
//     ws-token (POST /api/auth/ws-token 200), and holds an
//     ESTABLISHED WebSocket connection to both ports (netstat).
//
// Migration history (commits):
//   1. Reshape `DesktopBackendManager` into an instance factory and route
//      consumers through the pool. Pool held a single instance. (a8fc7845)
//   2. Drop `DesktopState.backendReady`. The window owns its own
//      readiness latch via onReady / onShutdown callbacks. (425c7d0b)
//   3. Per-instance log routing via DesktopBackendOutputLogFactory. (563820ed)
//   4. Add register/unregister to the pool. (a0eaf560)
//   5. Wire WSL through the pool: settings rename, BackendConfiguration
//      split, DesktopWslBackend orchestrator, new IPC, web compat.
//      (b1622191 + 31ce3add + 627c80cb)
//   6. Widen getLocalEnvironmentBootstrap to *Bootstraps (plural). (bad66041)
//   7. pickFolder takes optional targetEnvironmentId. (5d80468d)
//   8. Settings UX: toggle + distro picker, no swap dialog. (eb5a03ea)
//   9. Register WSL backend as desktop-local saved env via
//      reconcileLocalSecondaryEnvironments. (1c7e7873 + c17897bd)
//   10. CommandPalette enables file-manager picker for desktop-local
//       envs, routes pickFolder by env id. (38e8477a)

import * as Context from "effect/Context";
import * as Deferred from "effect/Deferred";
import * as Effect from "effect/Effect";
import * as Exit from "effect/Exit";
import * as Layer from "effect/Layer";
import * as Option from "effect/Option";
import * as Schema from "effect/Schema";
import * as Scope from "effect/Scope";
import * as SynchronizedRef from "effect/SynchronizedRef";

import * as FileSystem from "effect/FileSystem";
import { HttpClient } from "effect/unstable/http";
import { ChildProcessSpawner } from "effect/unstable/process";

import * as DesktopBackendConfiguration from "./DesktopBackendConfiguration.ts";
import * as DesktopBackendManager from "./DesktopBackendManager.ts";
import * as DesktopObservability from "../app/DesktopObservability.ts";
import * as DesktopAppSettings from "../settings/DesktopAppSettings.ts";
import * as DesktopWindow from "../window/DesktopWindow.ts";
import * as ElectronDialog from "../electron/ElectronDialog.ts";

const { logWarning: logBackendPoolWarning } =
  DesktopObservability.makeComponentLogger("desktop-backend-pool");

export type BackendInstanceId = DesktopBackendManager.BackendInstanceId;
export const BackendInstanceId = DesktopBackendManager.BackendInstanceId;
export const PRIMARY_INSTANCE_ID = DesktopBackendManager.PRIMARY_INSTANCE_ID;
export type DesktopBackendInstance = DesktopBackendManager.DesktopBackendInstance;
export type BackendInstanceSpec = DesktopBackendManager.BackendInstanceSpec;

// Caller tried to register an id that's already in the pool. The pool
// refuses overwrites so two independent orchestrators racing on the
// same id surface as a typed failure instead of one silently winning.
export class DesktopBackendPoolInstanceAlreadyRegisteredError extends Schema.TaggedErrorClass<DesktopBackendPoolInstanceAlreadyRegisteredError>()(
  "DesktopBackendPoolInstanceAlreadyRegisteredError",
  {
    id: Schema.String,
  },
) {
  override get message() {
    return `Backend instance "${this.id}" is already registered in the pool.`;
  }
}

// Primary instance is registered for the pool's lifetime. Unregister is
// a no-op for it today (no real callers), but if someone wires it up
// later it's a clear bug rather than something to "handle".
export class DesktopBackendPoolCannotUnregisterPrimaryError extends Schema.TaggedErrorClass<DesktopBackendPoolCannotUnregisterPrimaryError>()(
  "DesktopBackendPoolCannotUnregisterPrimaryError",
  {},
) {
  override get message() {
    return "Refusing to unregister the primary backend from the pool.";
  }
}

export class DesktopBackendPool extends Context.Service<
  DesktopBackendPool,
  {
    // Look up a registered instance. None when no backend with that id is
    // currently registered (e.g. WSL backend disabled).
    readonly get: (id: BackendInstanceId) => Effect.Effect<Option.Option<DesktopBackendInstance>>;
    // Snapshot of all currently-registered instances. Order is unspecified;
    // callers that need a canonical "primary first" view should sort by id.
    readonly list: Effect.Effect<readonly DesktopBackendInstance[]>;
    // Convenience accessor for the always-registered primary instance.
    // Currently equivalent to `get(PRIMARY_INSTANCE_ID)` unwrapped, but
    // exposed as a typed effect so consumers don't have to handle the
    // Option for the case that's guaranteed to be present.
    readonly primary: Effect.Effect<DesktopBackendInstance>;
    // Build a fresh DesktopBackendInstance from `spec` and add it to the
    // registry. The pool owns the instance's scope: unregister(id) or pool
    // teardown closes it and runs the instance's auto-stop finalizer. The
    // returned instance has not been started — callers decide when to
    // start it (and can call start more than once if a retry-after-failure
    // story makes sense for them).
    readonly register: (
      spec: BackendInstanceSpec,
    ) => Effect.Effect<DesktopBackendInstance, DesktopBackendPoolInstanceAlreadyRegisteredError>;
    // Stop the named instance and remove it from the registry. Closing the
    // instance's scope triggers its auto-stop finalizer; the registry is
    // updated atomically with the scope close so subsequent get(id) calls
    // observe the unregister before the underlying child process has fully
    // exited.
    readonly unregister: (
      id: BackendInstanceId,
    ) => Effect.Effect<void, DesktopBackendPoolCannotUnregisterPrimaryError>;
  }
>()("@t3tools/desktop/backend/DesktopBackendPool") {}

// Services required by makeBackendInstance — exported so caller
// orchestrators that build their own specs can confirm the layer graph
// satisfies them at compile time.
export type BackendInstanceFactoryRequirements =
  | FileSystem.FileSystem
  | ChildProcessSpawner.ChildProcessSpawner
  | HttpClient.HttpClient
  | DesktopObservability.DesktopBackendOutputLogFactory;

interface ActiveRegisteredInstance {
  readonly _tag: "Active";
  readonly instance: DesktopBackendInstance;
  // None for the primary (which lives in the pool's own layer scope and
  // is never unregistered); Some for instances added via register, whose
  // scope unregister closes to stop them.
  readonly scope: Option.Option<Scope.Closeable>;
}

interface ClosingRegisteredInstance {
  readonly _tag: "Closing";
  readonly done: Deferred.Deferred<void>;
}

type RegisteredInstance = ActiveRegisteredInstance | ClosingRegisteredInstance;

type RegisterAction =
  | { readonly _tag: "Registered"; readonly instance: DesktopBackendInstance }
  | { readonly _tag: "Wait"; readonly done: Deferred.Deferred<void> };

type UnregisterAction =
  | { readonly _tag: "Absent" }
  | { readonly _tag: "Wait"; readonly done: Deferred.Deferred<void> }
  | { readonly _tag: "Close"; readonly entry: ActiveRegisteredInstance };

export const layer = Layer.effect(
  DesktopBackendPool,
  Effect.gen(function* () {
    const configuration = yield* DesktopBackendConfiguration.DesktopBackendConfiguration;
    const desktopWindow = yield* DesktopWindow.DesktopWindow;
    const electronDialog = yield* ElectronDialog.ElectronDialog;
    const appSettings = yield* DesktopAppSettings.DesktopAppSettings;
    // Anchor the pool's lifetime to its layer scope so registered
    // instance scopes can be forked off it. Without this, instance
    // scopes are orphaned: they only close via explicit unregister()
    // calls, so on app shutdown the WSL backend child process gets
    // hard-killed by the OS instead of receiving the graceful
    // SIGTERM + grace period the instance's stop finalizer would
    // otherwise run.
    const layerScope = yield* Scope.Scope;
    // Capture the services needed to build any future instance from the
    // pool's layer scope. register() runs `makeBackendInstance` against
    // a fresh child scope but reuses these services so the instance gets
    // the same FileSystem, spawner, HTTP client and log factory the
    // primary instance uses.
    const factoryContext = yield* Effect.context<BackendInstanceFactoryRequirements>();

    // A WSL preflight failure on the primary only happens in wsl-only mode.
    // Fatal configuration failures persist the Windows fallback. Bounded
    // transport failures use an in-memory fallback for this launch so the app
    // opens without overwriting the user's WSL preference.
    const handlePrimaryPreflightFailure = Effect.fn("desktop.backendPool.primaryPreflightFailed")(
      function* (failure: DesktopBackendManager.PreflightFailure) {
        const { reason, fatal } = failure;
        if (!fatal) {
          yield* logBackendPoolWarning(
            "primary WSL preflight retry window exhausted; using Windows for this launch",
            { reason },
          );
          yield* electronDialog.showErrorBox(
            "WSL backend is still unavailable",
            `${reason}\n\nT3 Code will use the Windows backend for this launch and retry WSL the next time the app starts.`,
          );
          yield* appSettings.applyWslWindowsFallbackInMemory;
          return true;
        }

        yield* logBackendPoolWarning("primary WSL preflight failed; falling back to Windows", {
          reason,
        });
        yield* electronDialog.showErrorBox(
          "WSL backend couldn't start",
          `${reason}\n\nFalling back to the Windows backend so T3 Code can open. Re-enable the WSL backend from Settings > Connections once the WSL distro is fixed.`,
        );
        // Fully disable the WSL backend — both flags, matching the "Switch to
        // Windows" recovery path — so the manager's next restart re-resolves the
        // primary as Windows and reconcile won't register a secondary WSL backend
        // against the same broken setup. Clearing wslBackendEnabled alone would
        // leave a stale wslOnly:true that silently re-traps the user in wsl-only
        // mode the next time they enable WSL. If the persisted write fails, keep
        // this process recoverable by applying the fallback to in-memory settings.
        yield* appSettings.applyWslWindowsFallback.pipe(
          Effect.catch((error) =>
            logBackendPoolWarning(
              "failed to persist Windows fallback after WSL preflight failure",
              {
                error: error.message,
              },
            ).pipe(Effect.andThen(appSettings.applyWslWindowsFallbackInMemory)),
          ),
        );
        return true;
      },
    );

    const primary = yield* DesktopBackendManager.makeBackendInstance({
      id: DesktopBackendManager.PRIMARY_INSTANCE_ID,
      // Keep this lazy. The pool layer is initialized before startup loads
      // persisted desktop settings, so resolving the primary label here would
      // permanently capture DEFAULT_DESKTOP_SETTINGS and mislabel WSL-only
      // primaries as Windows.
      label: configuration.resolvePrimaryLabel,
      configResolve: configuration.resolvePrimary,
      // Window creation errors propagating out of handleBackendReady must
      // not block the readiness callback (that would prevent restartAttempt
      // from being reset), so we absorb them here. The window service only
      // logs on success, so log the failure here before swallowing it —
      // otherwise a post-readiness window-open failure vanishes silently and
      // is near-impossible to diagnose in production.
      onReady: (httpBaseUrl) =>
        desktopWindow.handleBackendReady(httpBaseUrl).pipe(
          Effect.catch((error) =>
            logBackendPoolWarning("failed to open main window after backend readiness", {
              error: error.message,
            }),
          ),
        ),
      onShutdown: () => desktopWindow.handleBackendNotReady,
      onPreflightFailed: handlePrimaryPreflightFailure,
    });

    const instancesRef = yield* SynchronizedRef.make<
      ReadonlyMap<BackendInstanceId, RegisteredInstance>
    >(
      new Map([
        [
          DesktopBackendManager.PRIMARY_INSTANCE_ID,
          { _tag: "Active", instance: primary, scope: Option.none() },
        ],
      ]),
    );

    const register: DesktopBackendPool["Service"]["register"] = (spec) =>
      Effect.suspend(() =>
        SynchronizedRef.modifyEffect(
          instancesRef,
          (
            current,
          ): Effect.Effect<
            readonly [RegisterAction, ReadonlyMap<BackendInstanceId, RegisteredInstance>],
            DesktopBackendPoolInstanceAlreadyRegisteredError
          > => {
            const existing = current.get(spec.id);
            if (existing?._tag === "Active") {
              return Effect.fail(
                new DesktopBackendPoolInstanceAlreadyRegisteredError({ id: spec.id }),
              );
            }
            if (existing?._tag === "Closing") {
              return Effect.succeed([
                { _tag: "Wait", done: existing.done } as const,
                current,
              ] as const);
            }
            return Effect.gen(function* () {
              // Provide the captured factory services first, then the child scope
              // last so instance finalizers are owned by the unregisterable scope.
              const instanceScope = yield* Scope.fork(layerScope, "sequential");
              const instance = yield* DesktopBackendManager.makeBackendInstance(spec).pipe(
                Effect.provide(factoryContext),
                Scope.provide(instanceScope),
              );
              const next = new Map(current);
              next.set(spec.id, {
                _tag: "Active",
                instance,
                scope: Option.some(instanceScope),
              });
              return [
                { _tag: "Registered", instance } as const,
                next as ReadonlyMap<BackendInstanceId, RegisteredInstance>,
              ] as const;
            });
          },
        ).pipe(
          Effect.flatMap((result) =>
            result._tag === "Registered"
              ? Effect.succeed(result.instance)
              : Deferred.await(result.done).pipe(Effect.andThen(register(spec))),
          ),
        ),
      );

    const unregister: DesktopBackendPool["Service"]["unregister"] = (id) =>
      Effect.gen(function* () {
        if (id === DesktopBackendManager.PRIMARY_INSTANCE_ID) {
          return yield* new DesktopBackendPoolCannotUnregisterPrimaryError();
        }
        const done = yield* Deferred.make<void>();
        const action = yield* SynchronizedRef.modifyEffect(
          instancesRef,
          (
            current,
          ): Effect.Effect<
            readonly [UnregisterAction, ReadonlyMap<BackendInstanceId, RegisteredInstance>]
          > => {
            const entry = current.get(id);
            if (entry === undefined) {
              return Effect.succeed([{ _tag: "Absent" } as const, current] as const);
            }
            if (entry._tag === "Closing") {
              return Effect.succeed([
                { _tag: "Wait", done: entry.done } as const,
                current,
              ] as const);
            }
            const next = new Map(current);
            next.set(id, { _tag: "Closing", done });
            return Effect.succeed([
              { _tag: "Close", entry } as const,
              next as ReadonlyMap<BackendInstanceId, RegisteredInstance>,
            ] as const);
          },
        );

        if (action._tag === "Absent") return;
        if (action._tag === "Wait") {
          yield* Deferred.await(action.done);
          return;
        }

        const finish = SynchronizedRef.modifyEffect(instancesRef, (current) => {
          const closing = current.get(id);
          if (closing?._tag !== "Closing" || closing.done !== done) {
            return Effect.succeed([undefined, current] as const);
          }
          const next = new Map(current);
          next.delete(id);
          return Effect.succeed([
            undefined,
            next as ReadonlyMap<BackendInstanceId, RegisteredInstance>,
          ] as const);
        }).pipe(Effect.andThen(Deferred.succeed(done, undefined)), Effect.asVoid);
        yield* Option.match(action.entry.scope, {
          onNone: () => Effect.void,
          onSome: (scope) => Scope.close(scope, Exit.void).pipe(Effect.ignore),
        }).pipe(Effect.ensuring(finish));
      });

    return DesktopBackendPool.of({
      get: (id) =>
        SynchronizedRef.get(instancesRef).pipe(
          Effect.map((instances) => {
            const entry = instances.get(id);
            return entry?._tag === "Active" ? Option.some(entry.instance) : Option.none();
          }),
        ),
      list: SynchronizedRef.get(instancesRef).pipe(
        Effect.map((instances) =>
          Array.from(instances.values()).flatMap((entry) =>
            entry._tag === "Active" ? [entry.instance] : [],
          ),
        ),
      ),
      primary: Effect.succeed(primary),
      register,
      unregister,
    });
  }),
);

// Test layer for unit tests that want to assert against a known pool
// composition without standing up the full manager. Each provided
// instance is registered under its own id; the first one is also
// surfaced as `primary` so callers can stub a single-instance pool.
// `register` and `unregister` are stubbed to die so tests that
// accidentally exercise pool registration fail loudly instead of
// silently noop'ing.
export const layerTest = (
  instances: readonly DesktopBackendInstance[],
): Layer.Layer<DesktopBackendPool> =>
  Layer.effect(
    DesktopBackendPool,
    Effect.gen(function* () {
      if (instances.length === 0) {
        return yield* Effect.die("DesktopBackendPool.layerTest requires at least one instance");
      }
      const byId = new Map<BackendInstanceId, DesktopBackendInstance>(
        instances.map((instance) => [instance.id, instance] as const),
      );
      const primary = instances[0]!;
      return DesktopBackendPool.of({
        get: (id) => Effect.succeed(Option.fromNullishOr(byId.get(id))),
        list: Effect.succeed(Array.from(byId.values())),
        primary: Effect.succeed(primary),
        register: () => Effect.die("DesktopBackendPool.layerTest does not support register"),
        unregister: () => Effect.die("DesktopBackendPool.layerTest does not support unregister"),
      });
    }),
  );