open-in-editor-bridge 0.1.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0ec2cde5e04f7296d806dcfeff4926492de642d4b09983478295b3bc45a68f08
-  data.tar.gz: 60e87f9f41f6207bd75bb58fce1c0daa4118af0b3bbbd4cb64030eedd83a3f56
+  metadata.gz: 7d25bb9c59762f68ee9b164865d324147c717b4b1d5c13bb3163dc57b2c65763
+  data.tar.gz: 85c973a0426c36ece6f5daec5b767380bc4621d0c39e28ccb01e572279c58db0
 SHA512:
-  metadata.gz: 8e767cca6409335c11dee8e522f1ba6b04e973ec638bad090a089ac2e998544ac347287805f4475a9739cd61448d6dbe3cd13577a95dde1733b4def30b040959
-  data.tar.gz: 5b48df59f4d402e62c3cff453ba6523b4c775c4744c00c48324f0cbb145f258a8d97bae825542fd2b44967614c9dfa880955793a5356545107a5a646c4c7e6b8
+  metadata.gz: d35441d1493bfda18b675cacf05e94baa1c2872543d4464492bc8271b4032213b8aa8826e9b567334aa19cc6cdf7f7c1fbfed1bccda78e60a3bcfb66b09d9d1c
+  data.tar.gz: 7d8a2e2aaf8641d415ea9f8cd6a4d78f67735506bcb38a3095d9dca4b1123635661995e2358767d496be9ef13c3d2d81412ca777cb1d815f393c1854c633cd83

data/CHANGELOG.md

@@ -0,0 +1,41 @@
+# Changelog
+
+## 0.3.0 — 2026-10-09
+
+### Added
+
+- `OpenInEditorBridge.compose` for library-owned Docker/Vite integration: generated service overrides mount a bundled Vite plugin and checkout identity, without session environment/query plumbing in applications.
+- Development-only Vite plugin that routes editor requests to the mounted checkout, replacing duplicate caller selectors while preserving encoded file paths and line/column.
+- Minimal adoption instructions and an ELCC migration path for removing its bespoke session transport.
+
+### Security and Lifecycle
+
+- Docker startup still requires explicit network-exposure opt-in. Only non-secret identity/target data and plugin code are mounted read-only; lifecycle credentials stay on the host.
+- Missing/malformed Vite identity fails startup safely; only the editor endpoint is proxied.
+- Foreground cleanup and idempotent detached registration reuse the existing lease protocol. Failed startup releases only a new registration, and failed shutdown retains the active registration.
+- Unrelated Compose commands and production Vite builds do not require editor setup.
+
+## 0.2.0 — 2026-10-09
+
+### Added
+
+- Shared host broker with checkout-specific editor sessions and simultaneous-start coordination.
+- `OPEN_IN_EDITOR_BRIDGE_BIND_ADDRESS` for explicit Docker-reachable binding; loopback remains the default.
+- Stable checkout IDs through `OpenInEditorBridge.session_id`, `--session-id`, and the `with_running` block argument.
+- Independent foreground leases and idempotent detached registration for Compose `up -d` / `down`.
+
+### Changed
+
+- Shutdown releases only the calling checkout's detached registration; the last active lease stops the broker.
+- Shared private runtime state replaces checkout-local PID/log files. Stop 0.1.x bridges before upgrading.
+- Multi-checkout editor links require an explicit `session` query parameter; single-checkout links remain valid.
+- Registration/release use nonce-bound HMAC-authenticated requests/responses and verify protocol/PID identity without transmitting the control secret or signaling disk-sourced PIDs.
+
+### Fixed
+
+- Incorrect host-checkout routing and duplicate-port startup failures for concurrent worktrees.
+- Premature detached-session cleanup when using the documented persistent lifecycle.
+- Path-prefix collisions and double decoding of percent-encoded filenames.
+- Relative editor commands now execute in the requesting checkout, not the checkout that first started the broker.
+- Failed health probes preserve live shared-broker credentials instead of orphaning active sessions.
+- Malformed authentication bytes are rejected without terminating other checkout sessions.

data/README.md

@@ -1,49 +1,146 @@
 # OpenInEditorBridge
 
-A small Ruby gem that runs a local HTTP bridge for opening files from a container in the host editor.
+A Ruby gem that runs a shared local HTTP bridge for opening container files in the correct host checkout's editor. Requires Ruby 3.2 or newer; no runtime gem dependencies.
 
 ## Install
 
 ```ruby
-gem "open-in-editor-bridge"
+gem "open-in-editor-bridge", "~> 0.3"
 ```
 
-## Ruby API
+```sh
+gem install open-in-editor-bridge
+```
+
+## Docker and Vite Integration
 
-Wrap the local development command that needs the bridge:
+Use the host-side Compose adapter and the gem's mounted Vite plugin. The library owns checkout identity transport, the host-gateway entry, and the editor proxy; **do not export a session variable or write a request rewrite**.
+
+Replace the development Compose startup/shutdown call:
 
 ```ruby
 require "open_in_editor_bridge"
 
-OpenInEditorBridge.with_running do
-  # Run the command that emits open-in-editor links.
-end
+# Explicit network-exposure opt-in; use only on a trusted development network.
+ENV["OPEN_IN_EDITOR_BRIDGE_BIND_ADDRESS"] = "0.0.0.0"
+ENV["OPEN_IN_EDITOR_COMMAND"] = "code"
+
+OpenInEditorBridge.compose("up", service: "web")
+# Detached startup: OpenInEditorBridge.compose("up", "-d", service: "web")
+# Shutdown: OpenInEditorBridge.compose("down", service: "web")
+```
+
+Add the plugin to your existing Vite configuration for Docker development:
+
+```js
+import { defineConfig } from "vite";
+
+export default defineConfig(async ({ command, mode }) => {
+  const plugins = [];
+  if (command === "serve" && mode === "development") {
+    const integrationPath = "/open-in-editor-bridge/vite.mjs";
+    const { default: openInEditorBridge } = await import(integrationPath);
+    plugins.push(openInEditorBridge());
+  }
+
+  return { plugins, server: { host: "0.0.0.0" } };
+});
 ```
 
-Use `ensure_running: false` when the wrapped command is responsible for stopping the bridge:
+Keep your application's existing plugins and other Vite settings. The variable-based dynamic import is intentional: production builds and test-mode configuration can load without Docker's development mounts. This path supports Docker-hosted Vite development; native-host Vite and custom development modes need their own explicit opt-in condition. The plugin requires a valid mounted manifest when enabled and fails startup if it is missing or malformed. Vite 6 is exercised by release QA.
+
+### Application Configuration That Remains
+
+- Select the Vite service (`service: "web"` by default); retain its image, command, source mounts, ports, and normal environment.
+- Select Compose files/project options when necessary, for example `compose_options: ["-f", "docker-compose.development.yaml", "-p", "my-checkout"]`. Pass subcommand options after `"up"` / `"down"`, not in `compose_options`.
+- Select checkout/container/host roots and the editor through the existing bridge configuration below. `project_root:` defaults to the current checkout; `env:` supplies bridge configuration and child-process environment overrides.
+- Explicitly select a Docker-reachable bind address. The adapter rejects loopback startup and never changes the default binding itself.
+
+When no explicit `-f` is supplied, the adapter respects `COMPOSE_FILE` / `COMPOSE_PATH_SEPARATOR`, or discovers a standard Compose file and its default override from the project directory upward. `--project-directory` is supported. Compose runs in `project_root:` and inherits normal process input/output. Failures raise; successful commands return `true`.
+
+Only `up` adds editor setup. Foreground `up` owns an independent lease and releases it even on failure. `up -d` / `up --detach` use the existing idempotent detached registration. Failed detached startup releases a newly acquired registration but preserves one that was already active. Successful `down` releases that checkout's detached registration; failed `down` keeps it. Other commands (`config`, `build`, `exec`, `run`, `logs`, and so on) execute ordinary Compose without editor setup or requiring an editor. `stop` does not release detached registration; use `down` or `--shutdown` when done. If a new container needs the editor mounts, create it through `up`.
+
+The generated override mounts just two read-only files at `/open-in-editor-bridge`: the packaged `vite.mjs` and a checkout-specific `session.json` containing identity and target URL. It never mounts broker state, the whole private runtime directory, or lifecycle control credentials. Temporary Compose overrides are removed after each invocation; non-secret manifests remain in the private host runtime directory for existing detached containers.
+
+All checkouts share the standard host port `3333`, bind address, and private runtime directory. Each may use the same container directory `/usr/src/web`: the plugin selects its own host checkout from its mounted identity. It replaces all caller-supplied `session` selectors, including duplicates and encoded selector names, without rewriting other query bytes. Only `/__open-in-editor` is proxied; health and lifecycle endpoints are not. Existing exact editor proxy entries are replaced, and editor routing takes precedence over broader application proxy entries.
+
+### Adopting in ELCC
+
+After installing 0.3.0, ELCC can replace the editor lifecycle/Compose `up` and `down` path in `bin/dev` with `OpenInEditorBridge.compose`, passing its existing development/gateway `-f` options, project name, host user/group variables, and gateway hostname. Keep gateway lifecycle ownership and pipe-input handling for unrelated commands unchanged.
+
+Remove the `OPEN_IN_EDITOR_SESSION_ID` export from `dynamic_environment_variables`, its web-service pass-through in `docker-compose.development.yaml`, and the handwritten `/__open-in-editor` target/rewrite in `web/vite.config.js`. Add the mounted plugin to the existing Vue/Vuetify/gateway plugin list under the development-only condition above. The adapter supplies the host-gateway entry, so an editor-only `extra_hosts` entry is no longer necessary. Keep the explicit trusted-network bind opt-in and existing root/editor settings. No consumer files are changed automatically.
+
+## Low-Level Ruby API
+
+For non-Compose applications or custom integrations:
 
 ```ruby
-OpenInEditorBridge.with_running(ensure_running: false) { run_down_command }
+require "open_in_editor_bridge"
+
+OpenInEditorBridge.with_running do |session_id|
+  # A custom integration may use session_id to select this checkout.
+  system("./bin/app", exception: true)
+end
 ```
 
-The bridge is stopped in the wrapper's `ensure` path. A block exception remains the raised exception.
+The block returns its normal result. Its checkout lease is released in `ensure`, including when the block raises; cleanup does not replace the original exception. Overlapping wrappers have independent leases, even in the same checkout. Finishing one wrapper never releases another wrapper or an existing detached registration.
+
+`OpenInEditorBridge.session_id` returns the stable ID without starting the bridge. `OpenInEditorBridge.new(env: ..., project_root: ...)` supports explicit configuration. `call("--ensure-running")` registers a detached checkout; `call("--shutdown")` releases it. Repeated registration is idempotent. `with_running(ensure_running: false)` runs its block without acquiring a lease and releases detached registration afterward. Do not wrap detached startup in a foreground lease.
+
+## CLI and Session Protocol
 
-## CLI
+Run lifecycle commands from the host checkout (or set `OPEN_IN_EDITOR_PROJECT_ROOT`):
 
 ```sh
+open-in-editor-bridge --session-id
 open-in-editor-bridge --ensure-running
+# Later, with the same configuration:
 open-in-editor-bridge --shutdown
-open-in-editor-bridge --serve
 ```
 
-The server provides `GET /health` and `GET /__open-in-editor?file=...`. Container paths beginning with `/usr/src/web` are mapped to the host `web` directory, preserving optional `:line:column` locations.
+The CLI is the low-level lifecycle interface, not a substitute for the Docker/Vite adapter. `--serve` runs a foreground broker and registers the current checkout; it requires a free port. Manually interrupting it stops all sessions. Prefer the managed API for sharing.
+
+`GET /health` reports PID, protocol, bind address, and active checkout IDs. `GET /__open-in-editor?file=<encoded-target>&session=<checkout-id>` spawns that checkout's editor with `--goto <translated-target>`, preserving optional `:line:column`. Paths equal to or below `/usr/src/web` map to the host `web` directory; other paths pass through unchanged. Query encoding is decoded exactly once, preserving literal percent sequences in filenames.
+
+Custom integrations may use the same session protocol. With exactly one checkout, links without `session` work. With multiple checkouts, missing identity returns HTTP 400 rather than guessing; unknown IDs return HTTP 404. Conflicting roots/editor settings for an active checkout are rejected. Foreground and detached leases are independent; the last released lease shuts down the listener.
 
 ## Configuration
 
-- `OPEN_IN_EDITOR_BRIDGE_PORT` (default `3333`)
-- `OPEN_IN_EDITOR_PROJECT_ROOT` (default current directory)
-- `OPEN_IN_EDITOR_CONTAINER_WEB_ROOT` (default `/usr/src/web`)
-- `OPEN_IN_EDITOR_HOST_WEB_ROOT` (default `<project-root>/web`)
-- `OPEN_IN_EDITOR_COMMAND` (or `EDITOR`)
+| Variable | Default | Purpose |
+|---|---|---|
+| `OPEN_IN_EDITOR_BRIDGE_PORT` | `3333` | Shared host listener port |
+| `OPEN_IN_EDITOR_BRIDGE_BIND_ADDRESS` | `127.0.0.1` | Listener address; `0.0.0.0` allows Docker IPv4 access |
+| `OPEN_IN_EDITOR_PROJECT_ROOT` | Current directory | Checkout identity and default host mapping |
+| `OPEN_IN_EDITOR_CONTAINER_WEB_ROOT` | `/usr/src/web` | Container directory to translate |
+| `OPEN_IN_EDITOR_HOST_WEB_ROOT` | `<project-root>/web` | Corresponding host directory |
+| `OPEN_IN_EDITOR_COMMAND` | `EDITOR` | Editor command, parsed with `Shellwords` |
+| `OPEN_IN_EDITOR_BRIDGE_RUNTIME_DIR` | `<system-tmp>/open-in-editor-bridge-<uid>` | Shared private host runtime state |
+| `OPEN_IN_EDITOR_BRIDGE_STARTUP_TIMEOUT` | `5` seconds | Startup/shutdown deadline |
+
+The editor command is required when registering a checkout, but not for `--session-id` or `--shutdown`. Editors run in their registered checkout's project root, so relative commands such as `./bin/editor` resolve in the correct checkout. Runtime directories must be owned by the current user and private (`0700`). Broker state and its control token use `0600`; runtime files are keyed by port. Checkout IDs derive from the canonical absolute project root.
+
+## Security and Upgrade Notes
+
+Loopback binding is the default. `0.0.0.0` also exposes the listener to other reachable network peers, not only Docker. Use it only on a trusted development network with host firewall restrictions; a specific Docker-reachable host interface can narrow exposure. Editor requests are intentionally unauthenticated and health exposes checkout IDs: anyone who can reach the listener can invoke configured editors. Do not expose it on an untrusted network or forward it publicly.
+
+Registration and release use nonce-bound HMAC signatures derived from a random control token held in the private host runtime directory; the token is never sent over HTTP. Clients authenticate health and control responses and verify broker protocol/PID against shared state. The broker rejects replayed control requests. Shutdown uses authenticated HTTP control, never signals a PID read from disk. Unknown listeners, old bridge versions, mismatched PIDs, and mismatched bind configurations are not reused.
+
+A failed or timed-out health probe does not discard a still-listening broker's credentials. Lifecycle operations fail explicitly until its identity can be verified; retry after the listener becomes responsive.
+
+Version 0.2 replaces checkout-local PID/log files with shared runtime state. Stop any 0.1.x bridge using its original installed version before upgrading; it cannot share the new protocol. Sessions live in the broker's memory. After a broker crash or deliberate manual stop, rerun `--ensure-running` for detached applications. Abruptly killed foreground clients cannot execute `ensure`; stop that broker manually and re-register surviving checkouts if their leases become orphaned.
+
+## Development and Release
+
+Commit the root `Gemfile.lock` to keep development and release-test dependencies reproducible. Regenerate it with Bundler after changing `Gemfile`, and commit both files together when both change. This development lockfile is not included in the gem package and does not constrain applications installing this gem; those applications resolve the gemspec's dependencies using their own lockfiles.
+
+Keep generated `*.gem` packages, `.ruby-lsp/` editor state, and local `pkg/` / `tmp/` artifacts out of version control.
+
+Development checks require Node.js 18+ for the bundled Vite plugin's dependency-free tests; the Ruby library itself remains dependency-free. `rake test` runs both Ruby and Node checks.
+
+```sh
+bundle install
+bundle exec rake test
+gem build open-in-editor-bridge.gemspec
+```
 
-The editor command is required and is parsed with `Shellwords`.
+Release changes on an issue-linked branch and pull request, including the version and changelog. Self-review and exercise real host/container lifecycle and editor invocation before merging. From synchronized `main`, build and push the gem with the maintainer's RubyGems credentials, then create a matching GitHub tag/release. Install the published version from RubyGems into a clean `GEM_HOME`, confirm `OpenInEditorBridge::VERSION`, and repeat foreground, detached, routing, and Docker-reachability checks. A recorded editor process proves invocation and arguments, not that an editor window rendered.

data/lib/open_in_editor_bridge/authentication.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require "openssl"
+
+class OpenInEditorBridge
+  module Authentication
+    def self.signature(token, direction, nonce, method_or_status, path, body)
+      digest = OpenSSL::HMAC.new(token, "SHA256")
+      [direction, nonce, method_or_status, path, body].each do |part|
+        bytes = part.to_s
+        digest << [bytes.bytesize].pack("Q>") << bytes
+      end
+      digest.hexdigest
+    end
+
+    def self.valid_nonce?(nonce)
+      nonce.is_a?(String) && nonce.ascii_only? && nonce.match?(/\A[0-9a-f]{32}\z/)
+    end
+
+    def self.valid?(provided, token, *message)
+      return false unless provided.is_a?(String) && token.is_a?(String) && !token.empty?
+
+      expected = signature(token, *message)
+      return false unless provided.bytesize == expected.bytesize
+
+      OpenSSL.fixed_length_secure_compare(expected, provided)
+    end
+  end
+end

data/lib/open_in_editor_bridge/client.rb

@@ -0,0 +1,172 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "rbconfig"
+require "securerandom"
+
+class OpenInEditorBridge
+  class Client
+    def initialize(configuration)
+      @configuration = configuration
+    end
+
+    def register(lease)
+      session = @configuration.session
+      @configuration.synchronize do
+        state = compatible_state
+        state ||= start_broker
+        payload = control_request("/sessions", state, "session" => session, "lease" => lease)
+        result = payload.fetch("added") ? :started : :reused
+        puts "Editor session #{session.fetch("id")} #{result} on port #{@configuration.port}."
+        result
+      end
+    end
+
+    def release(lease)
+      @configuration.synchronize do
+        state = compatible_state
+        return unless state
+
+        payload = control_request("/release", state, "session_id" => @configuration.session_id, "lease" => lease)
+        wait_until_stopped(state.fetch("pid")) if payload.fetch("stopping")
+      end
+    end
+
+    def serve
+      server = @configuration.synchronize do
+        raise StartupError, "Editor bridge is already running" if compatible_state
+        token = SecureRandom.hex(32)
+        broker = Server.new(@configuration, token: token)
+        broker.start(initial_session: @configuration.session)
+        broker
+      end
+      server.serve
+    end
+
+    private
+
+    def health(state: nil)
+      nonce = SecureRandom.hex(16)
+      request = Net::HTTP::Get.new("/health")
+      request["X-Open-In-Editor-Nonce"] = nonce
+      response = http_request(request)
+      return nil unless response && response.code == "200" && response["X-Open-In-Editor-Bridge"] == Configuration::PROTOCOL.to_s
+      if state
+        return nil unless Authentication.valid?(response["X-Open-In-Editor-Signature"], state["token"],
+          "response", nonce, response.code, "/health", response.body)
+      end
+
+      payload = JSON.parse(response.body)
+      return nil unless payload.is_a?(Hash) && payload["ok"] == true && payload["protocol"] == Configuration::PROTOCOL
+      payload
+    rescue JSON::ParserError
+      nil
+    end
+
+    def compatible_state
+      state = @configuration.read_state
+      current_health = health(state: state)
+      if current_health
+        unless state && state["pid"] == current_health["pid"] && state["protocol"] == Configuration::PROTOCOL &&
+            state["bind_address"] == @configuration.bind_address && current_health["bind_address"] == @configuration.bind_address &&
+            state["token"].is_a?(String) && !state["token"].empty?
+          raise StartupError, "Listener identity or bind address does not match shared runtime state"
+        end
+        return state
+      end
+      if listener_present?
+        raise StartupError, "Port is occupied by an unknown or unresponsive listener; shared state preserved"
+      end
+      if state
+        # Never signal a PID read from disk. Only authenticated broker control can stop it.
+        @configuration.delete_state(expected_pid: state["pid"])
+      end
+      nil
+    end
+
+    def listener_present?
+      Socket.tcp(@configuration.connect_address, @configuration.port, connect_timeout: 0.5) { true }
+    rescue Errno::ECONNREFUSED
+      false
+    rescue SystemCallError, Timeout::Error
+      # An inconclusive connection failure is not proof that shared state is stale.
+      true
+    end
+
+    def start_broker
+      token = SecureRandom.hex(32)
+      library_directory = File.expand_path("..", __dir__)
+      script = "configuration = OpenInEditorBridge::Configuration.new(env: ENV); " \
+        "server = OpenInEditorBridge::Server.new(configuration, token: ENV.fetch('OPEN_IN_EDITOR_BRIDGE_CONTROL_TOKEN')); " \
+        "server.start; server.serve"
+      pid = Process.spawn(@configuration.server_environment(token), RbConfig.ruby, "-I", library_directory,
+        "-ropen_in_editor_bridge", "-e", script, out: @configuration.log_file, err: @configuration.log_file, pgroup: true)
+      # Keep the child waitable until readiness proves we own this live PID.
+      deadline = monotonic_time + @configuration.startup_timeout
+      loop do
+        raise StartupError, "Editor bridge failed to start. See #{@configuration.log_file}." if Process.waitpid(pid, Process::WNOHANG)
+        state = @configuration.read_state
+        current_health = health(state: state)
+        if state && state["pid"] == pid && state["token"] == token && current_health && current_health["pid"] == pid
+          Process.detach(pid)
+          return state
+        end
+        raise StartupError, "Editor bridge did not become ready. See #{@configuration.log_file}." if monotonic_time >= deadline
+        sleep 0.05
+      end
+    rescue StandardError
+      if pid
+        begin
+          unless Process.waitpid(pid, Process::WNOHANG)
+            Process.kill("TERM", pid)
+            Process.waitpid(pid)
+          end
+        rescue Errno::ECHILD, Errno::ESRCH
+          # An exited child is not a PID we still own.
+        end
+        @configuration.delete_state(expected_pid: pid)
+      end
+      raise
+    end
+
+    def control_request(path, state, payload)
+      nonce = SecureRandom.hex(16)
+      request = Net::HTTP::Post.new(path)
+      request["Content-Type"] = "application/json"
+      request.body = JSON.generate(payload)
+      request["X-Open-In-Editor-Nonce"] = nonce
+      request["X-Open-In-Editor-Signature"] = Authentication.signature(state.fetch("token"),
+        "request", nonce, "POST", path, request.body)
+      response = http_request(request)
+      unless response && Authentication.valid?(response["X-Open-In-Editor-Signature"], state.fetch("token"),
+          "response", nonce, response.code, path, response.body)
+        raise StartupError, "Bridge control response failed authentication"
+      end
+      unless response && response.code == "200"
+        raise StartupError, "Bridge session request failed: #{response&.code} #{response&.body}"
+      end
+      JSON.parse(response.body)
+    end
+
+    def http_request(request)
+      Net::HTTP.start(@configuration.connect_address, @configuration.port, nil,
+        open_timeout: 0.5, read_timeout: 0.5, write_timeout: 0.5) { |http| http.request(request) }
+    rescue IOError, SystemCallError, Timeout::Error
+      nil
+    end
+
+    def wait_until_stopped(pid)
+      deadline = monotonic_time + @configuration.startup_timeout
+      loop do
+        state = @configuration.read_state
+        return unless state && state["pid"] == pid
+        raise StartupError, "Editor bridge did not stop" if monotonic_time >= deadline
+        sleep 0.05
+      end
+    end
+
+    def monotonic_time
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+  end
+end

data/lib/open_in_editor_bridge/configuration.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require "digest"
+require "json"
+require "shellwords"
+require "tmpdir"
+
+class OpenInEditorBridge
+  class Configuration
+    PROTOCOL = 2
+
+    attr_reader :port, :bind_address, :connect_address, :runtime_directory, :startup_timeout, :session_id
+
+    def initialize(env:, project_root: nil)
+      @env = env
+      @project_root = File.expand_path(project_root || env.fetch("OPEN_IN_EDITOR_PROJECT_ROOT", Dir.pwd))
+      @project_root = File.realpath(@project_root) if File.directory?(@project_root)
+      @port = Integer(env.fetch("OPEN_IN_EDITOR_BRIDGE_PORT", "3333"))
+      @bind_address = env.fetch("OPEN_IN_EDITOR_BRIDGE_BIND_ADDRESS", "127.0.0.1")
+      @connect_address = { "0.0.0.0" => "127.0.0.1", "::" => "::1" }.fetch(@bind_address, @bind_address)
+      @runtime_directory = env.fetch("OPEN_IN_EDITOR_BRIDGE_RUNTIME_DIR", File.join(Dir.tmpdir, "open-in-editor-bridge-#{Process.uid}"))
+      @startup_timeout = Float(env.fetch("OPEN_IN_EDITOR_BRIDGE_STARTUP_TIMEOUT", "5"))
+      @session_id = Digest::SHA256.hexdigest(@project_root)
+    end
+
+    def session
+      command = @env.fetch("OPEN_IN_EDITOR_COMMAND", @env.fetch("EDITOR", "")).to_s
+      raise ArgumentError, "No editor configured. Set OPEN_IN_EDITOR_COMMAND or EDITOR." if Shellwords.split(command).empty?
+
+      {
+        "id" => session_id,
+        "working_directory" => @project_root,
+        "container_root" => @env.fetch("OPEN_IN_EDITOR_CONTAINER_WEB_ROOT", "/usr/src/web").delete_suffix("/"),
+        "host_root" => File.expand_path(@env.fetch("OPEN_IN_EDITOR_HOST_WEB_ROOT", File.join(@project_root, "web"))),
+        "editor_command" => command,
+      }
+    end
+
+    def state_file
+      File.join(runtime_directory, "#{port}.json")
+    end
+
+    def log_file
+      File.join(runtime_directory, "#{port}.log")
+    end
+
+    def synchronize
+      ensure_runtime_directory
+      File.open(File.join(runtime_directory, "#{port}.lock"), File::RDWR | File::CREAT, 0o600) do |lock|
+        lock.flock(File::LOCK_EX)
+        yield
+      ensure
+        lock.flock(File::LOCK_UN)
+      end
+    end
+
+    def ensure_runtime_directory
+      begin
+        Dir.mkdir(runtime_directory, 0o700)
+      rescue Errno::EEXIST
+        # Shared by all checkout clients of this user.
+      end
+      stat = File.lstat(runtime_directory)
+      unless stat.directory? && stat.uid == Process.uid && (stat.mode & 0o077).zero?
+        raise StartupError, "Bridge runtime directory must be owned by this user and private (0700): #{runtime_directory}"
+      end
+    end
+
+    def read_state
+      state = JSON.parse(File.read(state_file))
+      state if state.is_a?(Hash)
+    rescue Errno::ENOENT, JSON::ParserError
+      nil
+    end
+
+    def write_state(token)
+      state = { "pid" => Process.pid, "token" => token, "protocol" => PROTOCOL, "bind_address" => bind_address }
+      File.open(state_file, File::WRONLY | File::CREAT | File::TRUNC, 0o600) { |file| file.write(JSON.generate(state)) }
+    end
+
+    def delete_state(expected_pid:)
+      File.delete(state_file) if read_state&.fetch("pid", nil) == expected_pid
+    rescue Errno::ENOENT
+      nil
+    end
+
+    def server_environment(token)
+      {
+        "OPEN_IN_EDITOR_BRIDGE_PORT" => port.to_s,
+        "OPEN_IN_EDITOR_BRIDGE_BIND_ADDRESS" => bind_address,
+        "OPEN_IN_EDITOR_BRIDGE_RUNTIME_DIR" => runtime_directory,
+        "OPEN_IN_EDITOR_BRIDGE_CONTROL_TOKEN" => token,
+      }
+    end
+  end
+end