feat(vscode-web): enhance settings management and testing for VS Code Web (#758)

This pull request enhances the VS Code Web module by improving how
machine settings are handled and merged, updating documentation to
clarify the settings behavior, and adding robust automated tests for the
new functionality. The most significant changes are grouped below.

**Machine Settings Handling and Merging:**

* Introduced a new `merge_settings` function in `run.sh` that merges
provided settings with any existing machine settings using `jq` or
`python3` if available, falling back gracefully if neither is present.
Settings are now passed as base64-encoded JSON to avoid quoting issues.
[[1]](diffhunk://#diff-c6d09ac3d801a2417c0e3cf8c2cd0f093ba2cf245bad8c213f70115c75276323R7-R54)
[[2]](diffhunk://#diff-c6d09ac3d801a2417c0e3cf8c2cd0f093ba2cf245bad8c213f70115c75276323L31-R76)
[[3]](diffhunk://#diff-0c7f0791e2c2556eb4ed7666ac44534ea3ff5c7f652e01716e5d7b5c31180d92L180-R184)
[[4]](diffhunk://#diff-0c7f0791e2c2556eb4ed7666ac44534ea3ff5c7f652e01716e5d7b5c31180d92R170-R173)
* Updated the `settings` variable in `main.tf` to clarify that it
applies to VS Code Web's Machine settings and will be merged with any
existing settings on startup.

**Documentation Improvements:**

* Updated the README to clarify that settings are merged with existing
machine settings, not simply overwritten, and added a note about the
requirements (`jq` or `python3`) and limitations regarding persistence
of user settings.
[[1]](diffhunk://#diff-24e2e305e46a08f8a30243bdc916241586e4561d97861b4397b14e871f9f085dL54-R56)
[[2]](diffhunk://#diff-24e2e305e46a08f8a30243bdc916241586e4561d97861b4397b14e871f9f085dR72-R73)

**Automated Testing:**

* Expanded `main.test.ts` to include integration tests that verify
settings file creation and merging behavior inside a container, as well
as improved error handling for invalid configuration combinations.

These changes collectively make machine settings management more robust,
user-friendly, and well-documented.

registry/coder/modules/vscode-web/README.md

@@ -14,7 +14,7 @@ Automatically install [Visual Studio Code Server](https://code.visualstudio.com/
 module "vscode-web" {
   count          = data.coder_workspace.me.start_count
   source         = "registry.coder.com/coder/vscode-web/coder"
-  version        = "1.4.3"
+  version        = "1.5.0"
   agent_id       = coder_agent.example.id
   accept_license = true
 }
@@ -30,7 +30,7 @@ module "vscode-web" {
 module "vscode-web" {
   count          = data.coder_workspace.me.start_count
   source         = "registry.coder.com/coder/vscode-web/coder"
-  version        = "1.4.3"
+  version        = "1.5.0"
   agent_id       = coder_agent.example.id
   install_prefix = "/home/coder/.vscode-web"
   folder         = "/home/coder"
@@ -44,22 +44,22 @@ module "vscode-web" {
 module "vscode-web" {
   count          = data.coder_workspace.me.start_count
   source         = "registry.coder.com/coder/vscode-web/coder"
-  version        = "1.4.3"
+  version        = "1.5.0"
   agent_id       = coder_agent.example.id
   extensions     = ["github.copilot", "ms-python.python", "ms-toolsai.jupyter"]
   accept_license = true
 }
 ```
 
-### Pre-configure Settings
+### Pre-configure Machine Settings
 
-Configure VS Code's [settings.json](https://code.visualstudio.com/docs/getstarted/settings#_settings-json-file) file:
+Configure VS Code's [Machine settings.json](https://code.visualstudio.com/docs/getstarted/settings#_settings-json-file). These settings are merged with any existing machine settings on startup:
 
 ```tf
 module "vscode-web" {
   count      = data.coder_workspace.me.start_count
   source     = "registry.coder.com/coder/vscode-web/coder"
-  version    = "1.4.3"
+  version    = "1.5.0"
   agent_id   = coder_agent.example.id
   extensions = ["dracula-theme.theme-dracula"]
   settings = {
@@ -69,6 +69,9 @@ module "vscode-web" {
 }
 ```
 
+> [!WARNING]
+> Merging settings requires `jq` or `python3`. If neither is available, existing machine settings will be preserved. User settings configured through the VS Code UI are stored in browser local storage and will not persist across different browsers or devices.
+
 ### Pin a specific VS Code Web version
 
 By default, this module installs the latest. To pin a specific version, retrieve the commit ID from the [VS Code Update API](https://update.code.visualstudio.com/api/commits/stable/server-linux-x64-web) and verify its corresponding release on the [VS Code GitHub Releases](https://github.com/microsoft/vscode/releases).
@@ -77,7 +80,7 @@ By default, this module installs the latest. To pin a specific version, retrieve
 module "vscode-web" {
   count          = data.coder_workspace.me.start_count
   source         = "registry.coder.com/coder/vscode-web/coder"
-  version        = "1.4.3"
+  version        = "1.5.0"
   agent_id       = coder_agent.example.id
   commit_id      = "e54c774e0add60467559eb0d1e229c6452cf8447"
   accept_license = true
@@ -93,7 +96,7 @@ Note: Either `workspace` or `folder` can be used, but not both simultaneously. T
 module "vscode-web" {
   count     = data.coder_workspace.me.start_count
   source    = "registry.coder.com/coder/vscode-web/coder"
-  version   = "1.4.3"
+  version   = "1.5.0"
   agent_id  = coder_agent.example.id
   workspace = "/home/coder/coder.code-workspace"
 }

registry/coder/modules/vscode-web/main.test.ts

@@ -1,42 +1,298 @@
-import { describe, expect, it } from "bun:test";
-import { runTerraformApply, runTerraformInit } from "~test";
+import {
+  describe,
+  expect,
+  it,
+  beforeAll,
+  afterEach,
+  setDefaultTimeout,
+} from "bun:test";
+import {
+  runTerraformApply,
+  runTerraformInit,
+  runContainer,
+  execContainer,
+  removeContainer,
+  findResourceInstance,
+} from "~test";
+
+// Set timeout to 2 minutes for tests that install packages
+setDefaultTimeout(2 * 60 * 1000);
+
+let cleanupContainers: string[] = [];
+
+afterEach(async () => {
+  for (const id of cleanupContainers) {
+    try {
+      await removeContainer(id);
+    } catch {
+      // Ignore cleanup errors
+    }
+  }
+  cleanupContainers = [];
+});
 
 describe("vscode-web", async () => {
-  await runTerraformInit(import.meta.dir);
-
-  it("accept_license should be set to true", () => {
-    const t = async () => {
-      await runTerraformApply(import.meta.dir, {
-        agent_id: "foo",
-        accept_license: "false",
-      });
-    };
-    expect(t).toThrow("Invalid value for variable");
+  beforeAll(async () => {
+    await runTerraformInit(import.meta.dir);
   });
 
-  it("use_cached and offline can not be used together", () => {
-    const t = async () => {
+  it("accept_license should be set to true", async () => {
+    try {
       await runTerraformApply(import.meta.dir, {
         agent_id: "foo",
-        accept_license: "true",
-        use_cached: "true",
-        offline: "true",
+        accept_license: false,
       });
-    };
-    expect(t).toThrow("Offline and Use Cached can not be used together");
+      throw new Error("Expected terraform apply to fail");
+    } catch (ex) {
+      expect((ex as Error).message).toContain("Invalid value for variable");
+    }
   });
 
-  it("offline and extensions can not be used together", () => {
-    const t = async () => {
+  it("use_cached and offline can not be used together", async () => {
+    try {
       await runTerraformApply(import.meta.dir, {
         agent_id: "foo",
-        accept_license: "true",
-        offline: "true",
-        extensions: '["1", "2"]',
+        accept_license: true,
+        use_cached: true,
+        offline: true,
       });
-    };
-    expect(t).toThrow("Offline mode does not allow extensions to be installed");
+      throw new Error("Expected terraform apply to fail");
+    } catch (ex) {
+      expect((ex as Error).message).toContain(
+        "Offline and Use Cached can not be used together",
+      );
+    }
   });
 
-  // More tests depend on shebang refactors
+  it("offline and extensions can not be used together", async () => {
+    try {
+      await runTerraformApply(import.meta.dir, {
+        agent_id: "foo",
+        accept_license: true,
+        offline: true,
+        extensions: '["ms-python.python"]',
+      });
+      throw new Error("Expected terraform apply to fail");
+    } catch (ex) {
+      expect((ex as Error).message).toContain(
+        "Offline mode does not allow extensions to be installed",
+      );
+    }
+  });
+
+  it("creates settings file with correct content", async () => {
+    const state = await runTerraformApply(import.meta.dir, {
+      agent_id: "foo",
+      accept_license: true,
+      use_cached: true,
+      settings: '{"editor.fontSize": 14}',
+    });
+
+    const containerId = await runContainer("ubuntu:22.04");
+    cleanupContainers.push(containerId);
+
+    // Create a mock code-server CLI that the script expects
+    await execContainer(containerId, [
+      "bash",
+      "-c",
+      `mkdir -p /tmp/vscode-web/bin && cat > /tmp/vscode-web/bin/code-server << 'MOCKEOF'
+#!/bin/bash
+echo "Mock code-server running"
+exit 0
+MOCKEOF
+chmod +x /tmp/vscode-web/bin/code-server`,
+    ]);
+
+    const script = findResourceInstance(state, "coder_script");
+
+    const scriptResult = await execContainer(containerId, [
+      "bash",
+      "-c",
+      script.script,
+    ]);
+    expect(scriptResult.exitCode).toBe(0);
+
+    // Check that settings file was created
+    const settingsResult = await execContainer(containerId, [
+      "cat",
+      "/root/.vscode-server/data/Machine/settings.json",
+    ]);
+
+    expect(settingsResult.exitCode).toBe(0);
+    expect(settingsResult.stdout).toContain("editor.fontSize");
+    expect(settingsResult.stdout).toContain("14");
+  });
+
+  it("merges settings with existing settings file", async () => {
+    const state = await runTerraformApply(import.meta.dir, {
+      agent_id: "foo",
+      accept_license: true,
+      use_cached: true,
+      settings: '{"new.setting": "new_value"}',
+    });
+
+    const containerId = await runContainer("ubuntu:22.04");
+    cleanupContainers.push(containerId);
+
+    // Install jq and create mock code-server CLI
+    await execContainer(containerId, ["apt-get", "update", "-qq"]);
+    await execContainer(containerId, ["apt-get", "install", "-y", "-qq", "jq"]);
+    await execContainer(containerId, [
+      "bash",
+      "-c",
+      `mkdir -p /tmp/vscode-web/bin && cat > /tmp/vscode-web/bin/code-server << 'MOCKEOF'
+#!/bin/bash
+echo "Mock code-server running"
+exit 0
+MOCKEOF
+chmod +x /tmp/vscode-web/bin/code-server`,
+    ]);
+
+    // Pre-create an existing settings file
+    await execContainer(containerId, [
+      "bash",
+      "-c",
+      `mkdir -p /root/.vscode-server/data/Machine && echo '{"existing.setting": "existing_value"}' > /root/.vscode-server/data/Machine/settings.json`,
+    ]);
+
+    const script = findResourceInstance(state, "coder_script");
+
+    const scriptResult = await execContainer(containerId, [
+      "bash",
+      "-c",
+      script.script,
+    ]);
+    expect(scriptResult.exitCode).toBe(0);
+
+    // Check that settings were merged (both existing and new should be present)
+    const settingsResult = await execContainer(containerId, [
+      "cat",
+      "/root/.vscode-server/data/Machine/settings.json",
+    ]);
+
+    expect(settingsResult.exitCode).toBe(0);
+    // Should contain both existing and new settings
+    expect(settingsResult.stdout).toContain("existing.setting");
+    expect(settingsResult.stdout).toContain("existing_value");
+    expect(settingsResult.stdout).toContain("new.setting");
+    expect(settingsResult.stdout).toContain("new_value");
+  });
+
+  it("merges settings using python3 fallback when jq unavailable", async () => {
+    const state = await runTerraformApply(import.meta.dir, {
+      agent_id: "foo",
+      accept_license: true,
+      use_cached: true,
+      settings: '{"new.setting": "new_value"}',
+    });
+
+    const containerId = await runContainer("ubuntu:22.04");
+    cleanupContainers.push(containerId);
+
+    // Install python3 (ubuntu:22.04 doesn't have it by default)
+    await execContainer(containerId, ["apt-get", "update", "-qq"]);
+    await execContainer(containerId, [
+      "apt-get",
+      "install",
+      "-y",
+      "-qq",
+      "python3",
+    ]);
+
+    // Create mock code-server CLI (no jq installed)
+    await execContainer(containerId, [
+      "bash",
+      "-c",
+      `mkdir -p /tmp/vscode-web/bin && cat > /tmp/vscode-web/bin/code-server << 'MOCKEOF'
+#!/bin/bash
+echo "Mock code-server running"
+exit 0
+MOCKEOF
+chmod +x /tmp/vscode-web/bin/code-server`,
+    ]);
+
+    // Pre-create an existing settings file
+    await execContainer(containerId, [
+      "bash",
+      "-c",
+      `mkdir -p /root/.vscode-server/data/Machine && echo '{"existing.setting": "existing_value"}' > /root/.vscode-server/data/Machine/settings.json`,
+    ]);
+
+    const script = findResourceInstance(state, "coder_script");
+
+    const scriptResult = await execContainer(containerId, [
+      "bash",
+      "-c",
+      script.script,
+    ]);
+    expect(scriptResult.exitCode).toBe(0);
+
+    // Check that settings were merged using python3 fallback
+    const settingsResult = await execContainer(containerId, [
+      "cat",
+      "/root/.vscode-server/data/Machine/settings.json",
+    ]);
+
+    expect(settingsResult.exitCode).toBe(0);
+    // Should contain both existing and new settings
+    expect(settingsResult.stdout).toContain("existing.setting");
+    expect(settingsResult.stdout).toContain("existing_value");
+    expect(settingsResult.stdout).toContain("new.setting");
+    expect(settingsResult.stdout).toContain("new_value");
+  });
+
+  it("preserves existing settings when neither jq nor python3 available", async () => {
+    const state = await runTerraformApply(import.meta.dir, {
+      agent_id: "foo",
+      accept_license: true,
+      use_cached: true,
+      settings: '{"new.setting": "new_value"}',
+    });
+
+    // Use ubuntu without installing jq or python3 (neither available by default)
+    const containerId = await runContainer("ubuntu:22.04");
+    cleanupContainers.push(containerId);
+
+    // Create mock code-server CLI
+    await execContainer(containerId, [
+      "bash",
+      "-c",
+      `mkdir -p /tmp/vscode-web/bin && cat > /tmp/vscode-web/bin/code-server << 'MOCKEOF'
+#!/bin/bash
+echo "Mock code-server running"
+exit 0
+MOCKEOF
+chmod +x /tmp/vscode-web/bin/code-server`,
+    ]);
+
+    // Pre-create an existing settings file
+    await execContainer(containerId, [
+      "bash",
+      "-c",
+      `mkdir -p /root/.vscode-server/data/Machine && echo '{"existing.setting": "existing_value"}' > /root/.vscode-server/data/Machine/settings.json`,
+    ]);
+
+    const script = findResourceInstance(state, "coder_script");
+
+    // Run script - should warn but not fail
+    const scriptResult = await execContainer(containerId, [
+      "bash",
+      "-c",
+      script.script,
+    ]);
+    expect(scriptResult.exitCode).toBe(0);
+    expect(scriptResult.stdout).toContain("Could not merge settings");
+
+    // Existing settings should be preserved (not overwritten)
+    const settingsResult = await execContainer(containerId, [
+      "cat",
+      "/root/.vscode-server/data/Machine/settings.json",
+    ]);
+
+    expect(settingsResult.exitCode).toBe(0);
+    expect(settingsResult.stdout).toContain("existing.setting");
+    expect(settingsResult.stdout).toContain("existing_value");
+    expect(settingsResult.stdout).not.toContain("new.setting");
+    expect(settingsResult.stdout).not.toContain("new_value");
+  });
 });

registry/coder/modules/vscode-web/main.tf

@@ -105,7 +105,7 @@ variable "group" {
 
 variable "settings" {
   type        = any
-  description = "A map of settings to apply to VS Code web."
+  description = "A map of settings to apply to VS Code Web's Machine settings. These settings are merged with any existing machine settings on startup."
   default     = {}
 }
 
@@ -167,6 +167,10 @@ variable "workspace" {
 data "coder_workspace_owner" "me" {}
 data "coder_workspace" "me" {}
 
+locals {
+  settings_b64 = var.settings != {} ? base64encode(jsonencode(var.settings)) : ""
+}
+
 resource "coder_script" "vscode-web" {
   agent_id     = var.agent_id
   display_name = "VS Code Web"
@@ -177,8 +181,7 @@ resource "coder_script" "vscode-web" {
     INSTALL_PREFIX : var.install_prefix,
     EXTENSIONS : join(",", var.extensions),
     TELEMETRY_LEVEL : var.telemetry_level,
-    // This is necessary otherwise the quotes are stripped!
-    SETTINGS : replace(jsonencode(var.settings), "\"", "\\\""),
+    SETTINGS_B64 : local.settings_b64,
     OFFLINE : var.offline,
     USE_CACHED : var.use_cached,
     DISABLE_TRUST : var.disable_trust,

registry/coder/modules/vscode-web/run.sh

@@ -4,13 +4,54 @@ BOLD='\033[0;1m'
 EXTENSIONS=("${EXTENSIONS}")
 VSCODE_WEB="${INSTALL_PREFIX}/bin/code-server"
 
+# Merge settings from module with existing settings file
+# Uses jq if available, falls back to Python3 for deep merge
+merge_settings() {
+  local new_settings="$1"
+  local settings_file="$2"
+
+  if [ -z "$new_settings" ] || [ "$new_settings" = "{}" ]; then
+    return 0
+  fi
+
+  if [ ! -f "$settings_file" ]; then
+    mkdir -p "$(dirname "$settings_file")"
+    printf '%s\n' "$new_settings" > "$settings_file"
+    printf "⚙️ Creating settings file...\n"
+    return 0
+  fi
+
+  local tmpfile
+  tmpfile="$(mktemp)"
+
+  if command -v jq > /dev/null 2>&1; then
+    if jq -s '.[0] * .[1]' "$settings_file" <(printf '%s\n' "$new_settings") > "$tmpfile" 2> /dev/null; then
+      mv "$tmpfile" "$settings_file"
+      printf "⚙️ Merging settings...\n"
+      return 0
+    fi
+  fi
+
+  if command -v python3 > /dev/null 2>&1; then
+    if python3 -c "import json,sys;m=lambda a,b:{**a,**{k:m(a[k],v)if k in a and type(a[k])==type(v)==dict else v for k,v in b.items()}};print(json.dumps(m(json.load(open(sys.argv[1])),json.loads(sys.argv[2])),indent=2))" "$settings_file" "$new_settings" > "$tmpfile" 2> /dev/null; then
+      mv "$tmpfile" "$settings_file"
+      printf "⚙️ Merging settings...\n"
+      return 0
+    fi
+  fi
+
+  rm -f "$tmpfile"
+  printf "Warning: Could not merge settings (jq or python3 required). Keeping existing settings.\n"
+  return 0
+}
+
 # Set extension directory
 EXTENSION_ARG=""
 if [ -n "${EXTENSIONS_DIR}" ]; then
   EXTENSION_ARG="--extensions-dir=${EXTENSIONS_DIR}"
 fi
 
-# Set extension directory
+# Set server base path
 SERVER_BASE_PATH_ARG=""
 if [ -n "${SERVER_BASE_PATH}" ]; then
   SERVER_BASE_PATH_ARG="--server-base-path=${SERVER_BASE_PATH}"
@@ -28,11 +69,14 @@ run_vscode_web() {
   "$VSCODE_WEB" serve-local "$EXTENSION_ARG" "$SERVER_BASE_PATH_ARG" "$DISABLE_TRUST_ARG" --port "${PORT}" --host 127.0.0.1 --accept-server-license-terms --without-connection-token --telemetry-level "${TELEMETRY_LEVEL}" > "${LOG_PATH}" 2>&1 &
 }
 
-# Check if the settings file exists...
-if [ ! -f ~/.vscode-server/data/Machine/settings.json ]; then
-  echo "⚙️ Creating settings file..."
-  mkdir -p ~/.vscode-server/data/Machine
-  echo "${SETTINGS}" > ~/.vscode-server/data/Machine/settings.json
+# Apply machine settings (merge with existing if present)
+SETTINGS_B64='${SETTINGS_B64}'
+if [ -n "$SETTINGS_B64" ]; then
+  if SETTINGS_JSON="$(echo -n "$SETTINGS_B64" | base64 -d 2> /dev/null)" && [ -n "$SETTINGS_JSON" ]; then
+    merge_settings "$SETTINGS_JSON" ~/.vscode-server/data/Machine/settings.json
+  else
+    printf "Warning: Failed to decode settings. Skipping settings configuration.\n"
+  fi
 fi
 
 # Check if vscode-server is already installed for offline or cached mode