Squash Odysseus development history

tests/helpers/calendar_routes.py

@@ -0,0 +1,8 @@
+"""Shared imports for calendar route tests."""
+
+
+def import_calendar_routes():
+    """Import the calendar routes module after test stubs are installed."""
+    import routes.calendar_routes as cal
+
+    return cal

tests/helpers/cli_loader.py

@@ -0,0 +1,25 @@
+"""Shared loader for CLI scripts under scripts/."""
+import importlib.machinery
+import importlib.util
+from pathlib import Path
+
+
+_SCRIPTS_DIR = Path(__file__).resolve().parents[2] / "scripts"
+
+
+def load_script(script_name):
+    """Load a script from scripts/ by name and return it as a module.
+
+    The module name is derived from the script name (hyphens become underscores,
+    with a _cli suffix) giving each script a stable, unique import identity.
+
+    Any sys.modules stubs the script needs at import time must be injected via
+    monkeypatch before calling this function.
+    """
+    module_name = script_name.replace("-", "_") + "_cli"
+    path = _SCRIPTS_DIR / script_name
+    loader = importlib.machinery.SourceFileLoader(module_name, str(path))
+    spec = importlib.util.spec_from_loader(loader.name, loader)
+    module = importlib.util.module_from_spec(spec)
+    loader.exec_module(module)
+    return module

tests/helpers/db_stubs.py

@@ -0,0 +1,33 @@
+"""Shared database stub helpers for CLI and unit tests."""
+import sys
+import types
+from unittest.mock import MagicMock
+
+
+def make_core_db_stub(
+    monkeypatch,
+    models=(),
+    *,
+    attributes=None,
+    install_core_package=False,
+):
+    """Create a core.database stub and inject it via monkeypatch.
+
+    Always sets SessionLocal. Pass model class names via `models` to set
+    each as a MagicMock attribute on the stub. Pass `attributes` to override
+    specific values, and `install_core_package` when the import also needs a
+    stub parent package.
+
+    Returns the stub module for optional further configuration.
+    """
+    if install_core_package:
+        monkeypatch.setitem(sys.modules, "core", types.ModuleType("core"))
+
+    db = types.ModuleType("core.database")
+    db.SessionLocal = MagicMock()
+    for name in models:
+        setattr(db, name, MagicMock())
+    for name, value in (attributes or {}).items():
+        setattr(db, name, value)
+    monkeypatch.setitem(sys.modules, "core.database", db)
+    return db

tests/helpers/embedding_lanes.py

@@ -0,0 +1,124 @@
+"""Shared fakes for embedding-lane tests."""
+
+
+class FakeEmbedder:
+    def __init__(self, dim, model, url):
+        self.dim = dim
+        self.model = model
+        self.url = url
+
+    def get_sentence_embedding_dimension(self):
+        return self.dim
+
+    def encode(self, texts, normalize_embeddings=True):
+        return [[float(i + 1)] * self.dim for i, _ in enumerate(texts)]
+
+
+class FailingEmbedder(FakeEmbedder):
+    def encode(self, texts, normalize_embeddings=True):
+        raise RuntimeError("embedding endpoint rate limited")
+
+
+class FakeCollection:
+    def __init__(self, name, metadata=None):
+        self.name = name
+        self.metadata = metadata or {}
+        self.rows = {}
+        self.dim = None
+
+    def count(self):
+        return len(self.rows)
+
+    def add(self, ids, embeddings, documents=None, metadatas=None):
+        self._check_dim(embeddings)
+        documents = documents or [None] * len(ids)
+        metadatas = metadatas or [{}] * len(ids)
+        for row_id, emb, doc, meta in zip(ids, embeddings, documents, metadatas):
+            self.rows[row_id] = {"embedding": emb, "document": doc, "metadata": meta}
+
+    def upsert(self, ids, embeddings, documents=None, metadatas=None):
+        self.add(ids, embeddings, documents=documents, metadatas=metadatas)
+
+    def get(self, ids=None, include=None, where=None, limit=None):
+        selected = list(self.rows.items())
+        if ids is not None:
+            id_set = set(ids)
+            selected = [(row_id, row) for row_id, row in selected if row_id in id_set]
+        if where:
+            selected = [
+                (row_id, row)
+                for row_id, row in selected
+                if all(row["metadata"].get(k) == v for k, v in where.items())
+            ]
+        if limit is not None:
+            selected = selected[:limit]
+        return {
+            "ids": [row_id for row_id, _ in selected],
+            "documents": [row["document"] for _, row in selected],
+            "metadatas": [row["metadata"] for _, row in selected],
+            "embeddings": [row["embedding"] for _, row in selected],
+        }
+
+    def query(self, query_embeddings, n_results, where=None, include=None):
+        self._check_dim(query_embeddings)
+        rows = self.get(where=where)
+        ids = rows["ids"][:n_results]
+        docs = rows["documents"][:n_results]
+        metas = rows["metadatas"][:n_results]
+        return {
+            "ids": [ids],
+            "documents": [docs],
+            "metadatas": [metas],
+            "distances": [[0.1 + i * 0.01 for i in range(len(ids))]],
+        }
+
+    def delete(self, ids):
+        for row_id in ids:
+            self.rows.pop(row_id, None)
+
+    def _check_dim(self, embeddings):
+        if not embeddings:
+            return
+        dim = len(embeddings[0])
+        if self.dim is None:
+            self.dim = dim
+        elif self.dim != dim:
+            raise RuntimeError(f"Collection expecting embedding with dimension of {self.dim}, got {dim}")
+
+
+class FakeChroma:
+    def __init__(self):
+        self.collections = {}
+        self.deleted = []
+        self.fail_next_add_for = {}
+
+    def get_or_create_collection(self, name, metadata=None):
+        if name not in self.collections:
+            self.collections[name] = FakeCollection(name, metadata=metadata)
+            if self.fail_next_add_for.get(name, 0) > 0:
+                original_add = self.collections[name].add
+
+                def fail_once(*args, **kwargs):
+                    self.fail_next_add_for[name] -= 1
+                    self.collections[name].add = original_add
+                    raise RuntimeError("chroma write failed")
+
+                self.collections[name].add = fail_once
+        elif metadata is not None:
+            self.collections[name].metadata = metadata
+        return self.collections[name]
+
+    def get_collection(self, name):
+        if name not in self.collections:
+            raise KeyError(name)
+        return self.collections[name]
+
+    def delete_collection(self, name):
+        self.deleted.append(name)
+        self.collections.pop(name, None)
+
+
+def patch_chroma(monkeypatch, fake):
+    import src.chroma_client as chroma_client
+
+    monkeypatch.setattr(chroma_client, "get_chroma_client", lambda: fake)

tests/helpers/import_state.py

@@ -0,0 +1,169 @@
+"""Shared helper for saving and restoring Python import state in tests.
+
+Use ``preserve_import_state`` as a context manager around any block that needs
+to mutate ``sys.modules`` or parent-package attributes temporarily. On exit
+(normal or exception), every named module is restored to exactly the state it
+had before the block — present, absent, or carrying a parent-package attribute.
+
+Use ``clear_module`` to drop a single module from both ``sys.modules`` and its
+parent-package attribute (e.g. before forcing a fresh import inside the block).
+
+Use ``clear_fake_database_modules`` to evict a *stubbed* ``core.database`` (and
+its companion ``src.database``) that another test left in import state, without
+touching a real ``core.database`` loaded from disk.
+
+Use ``clear_fake_endpoint_resolver_modules`` to evict a *stubbed*
+``src.endpoint_resolver`` (and the route modules that imported it) that another
+test left in import state, without touching a real ``src.endpoint_resolver``
+loaded from disk.
+
+Background: importing ``routes.session_routes`` also sets ``session_routes`` on
+the parent ``routes`` package object. A ``from routes import session_routes``
+or ``import routes.session_routes as X`` statement resolves through that parent
+attribute, so restoring ``sys.modules`` alone is not sufficient — the parent
+attribute must be restored too. This helper handles both.
+
+Restoration in ``preserve_import_state`` is two-phased: all ``sys.modules``
+entries are written back first, then all parent-package attributes. This means
+parent-attr restoration always resolves the parent through the already-restored
+``sys.modules``, so results are deterministic regardless of argument order —
+safe for callers that pass both a parent package and a child module.
+"""
+
+import sys
+from contextlib import contextmanager
+
+_ABSENT = object()
+
+
+def _save_one(dotted_name):
+    saved_mod = sys.modules.get(dotted_name, _ABSENT)
+    pkg_name, _, attr = dotted_name.rpartition(".")
+    pkg = sys.modules.get(pkg_name)
+    saved_attr = getattr(pkg, attr, _ABSENT) if pkg is not None else _ABSENT
+    return saved_mod, saved_attr
+
+
+def _restore_parent_attr(dotted_name, saved_attr):
+    pkg_name, _, attr = dotted_name.rpartition(".")
+    pkg = sys.modules.get(pkg_name)
+    if pkg is None:
+        return
+    if saved_attr is _ABSENT:
+        if hasattr(pkg, attr):
+            delattr(pkg, attr)
+    else:
+        setattr(pkg, attr, saved_attr)
+
+
+def _restore_one(dotted_name, saved_mod, saved_attr):
+    if saved_mod is _ABSENT:
+        sys.modules.pop(dotted_name, None)
+    else:
+        sys.modules[dotted_name] = saved_mod
+    _restore_parent_attr(dotted_name, saved_attr)
+
+
+def clear_module(dotted_name):
+    """Remove a module from sys.modules and its parent-package attribute."""
+    _restore_one(dotted_name, _ABSENT, _ABSENT)
+
+
+def clear_fake_database_modules():
+    """Evict a *stubbed* ``core.database`` (and ``src.database``) from import state.
+
+    Test-only. Some tests install a fake ``core.database`` — a stub module with
+    no on-disk ``__file__`` — into ``sys.modules`` and onto the ``core`` package.
+    A later test that needs the real database module must evict that stub first,
+    or its ``import core.database`` resolves to the fake.
+
+    This is deliberately conservative and mirrors the per-file helpers it
+    replaces:
+
+    * It acts only when ``core.database`` is a fake/stub, detected by a missing
+      string ``__file__``. A real ``core.database`` loaded from disk is left
+      untouched, as is the case where nothing is cached.
+    * When it does act, it also drops the cached ``src.database`` entry.
+    * It removes the ``core.database`` parent-package attribute only when that
+      attribute is the same fake object being evicted.
+    """
+    parent = sys.modules.get("core")
+    attr = getattr(parent, "database", None) if parent is not None else None
+    mod = sys.modules.get("core.database") or attr
+    if mod is None or isinstance(getattr(mod, "__file__", None), str):
+        return
+    sys.modules.pop("core.database", None)
+    sys.modules.pop("src.database", None)
+    if parent is not None and attr is mod:
+        delattr(parent, "database")
+
+
+def clear_fake_endpoint_resolver_modules(*extra_modules):
+    """Evict a *stubbed* ``src.endpoint_resolver`` (and dependent route modules).
+
+    Test-only. Several route tests need the *real* ``src.endpoint_resolver`` URL
+    helpers, but another test may have installed a fake — a stub module with no
+    on-disk ``__file__`` — into ``sys.modules`` and onto the ``src`` package
+    during collection. The route modules (``routes.model_routes`` and any extras
+    passed in, e.g. ``routes.chat_routes``) get cached against that fake on first
+    import, so they must be evicted too.
+
+    Conservative, mirroring ``clear_fake_database_modules`` and the per-file
+    guards it replaces:
+
+    * It acts only when ``src.endpoint_resolver`` is a fake/stub, detected by a
+      falsy ``__file__`` (missing, ``None``, or empty string) — exactly the
+      truthiness check the old inline guards used. A real resolver loaded from
+      disk carries a truthy ``__file__`` and is left untouched, as is the case
+      where nothing is cached. When the resolver is real, the dependent route
+      modules are left untouched too.
+    * When it does act, it drops ``routes.model_routes`` plus every name in
+      ``extra_modules``.
+    * It removes the ``src.endpoint_resolver`` parent-package attribute only when
+      that attribute is the same fake object being evicted.
+
+    Behavior delta vs. the old bare ``sys.modules.pop(...)`` guards: dependent
+    modules are dropped via :func:`clear_module`, which also clears the parent
+    ``routes`` package attribute (e.g. ``routes.model_routes``), not just the
+    ``sys.modules`` entry. This prevents a stale parent attribute from shadowing
+    the fresh import — the same parent-attr handling the rest of this helper
+    family already applies.
+    """
+    parent = sys.modules.get("src")
+    attr = getattr(parent, "endpoint_resolver", None) if parent is not None else None
+    mod = sys.modules.get("src.endpoint_resolver") or attr
+    if mod is None or getattr(mod, "__file__", None):
+        return
+    sys.modules.pop("src.endpoint_resolver", None)
+    if parent is not None and attr is mod:
+        delattr(parent, "endpoint_resolver")
+    clear_module("routes.model_routes")
+    for name in extra_modules:
+        clear_module(name)
+
+
+@contextmanager
+def preserve_import_state(*module_names):
+    """Save and restore sys.modules entries and parent-package attributes.
+
+    Restoration is two-phased: sys.modules entries are written back first,
+    then parent-package attributes. This ensures parent-attr restoration always
+    sees the correctly restored parent in sys.modules, regardless of argument
+    order — safe for callers that pass both a parent and a child module.
+
+    On exit (normal or exception), each named module is restored to its state
+    before the block — whether present, absent, or carrying a parent attribute.
+    """
+    saved = {name: _save_one(name) for name in module_names}
+    try:
+        yield
+    finally:
+        # Phase 1: restore all sys.modules entries.
+        for name, (saved_mod, _) in saved.items():
+            if saved_mod is _ABSENT:
+                sys.modules.pop(name, None)
+            else:
+                sys.modules[name] = saved_mod
+        # Phase 2: restore all parent-package attributes.
+        for name, (_, saved_attr) in saved.items():
+            _restore_parent_attr(name, saved_attr)

tests/helpers/sqlite_db.py

@@ -0,0 +1,29 @@
+"""Construct a file-backed temp sqlite DB for tests.
+
+Only builds the SQLAlchemy objects from the repeated temp-sqlite block. It
+does not patch modules, manage cleanup, or own any global state — the caller
+keeps the returned objects alive and binds ``SessionLocal`` where needed.
+"""
+import tempfile
+
+from sqlalchemy import create_engine
+from sqlalchemy.orm import sessionmaker
+from sqlalchemy.pool import NullPool
+
+
+def make_temp_sqlite(metadata):
+    """Build a file-backed temp sqlite database and create its tables.
+
+    Returns ``(SessionLocal, engine, tmpfile)``. The caller must keep these
+    references alive (temp file and engine GC are the caller's concern) and
+    bind ``SessionLocal`` onto whatever module the code under test reads.
+    """
+    tmpfile = tempfile.NamedTemporaryFile(suffix=".db", delete=False)
+    engine = create_engine(
+        f"sqlite:///{tmpfile.name}",
+        connect_args={"check_same_thread": False},
+        poolclass=NullPool,
+    )
+    metadata.create_all(engine)
+    SessionLocal = sessionmaker(bind=engine, autoflush=False, autocommit=False)
+    return SessionLocal, engine, tmpfile

tests/helpers/test_settings_shell.js

@@ -0,0 +1,775 @@
+const fs = require('fs');
+const path = require('path');
+const vm = require('vm');
+
+class ClassList {
+  constructor() { this.values = new Set(); }
+  add(...names) { names.filter(Boolean).forEach(name => this.values.add(name)); }
+  remove(...names) { names.forEach(name => this.values.delete(name)); }
+  contains(name) { return this.values.has(name); }
+  toggle(name, force) {
+    if (force === undefined) force = !this.contains(name);
+    force ? this.add(name) : this.remove(name);
+    return force;
+  }
+}
+
+class Style {
+  constructor() { this.values = {}; this.display = ''; this.cssText = ''; }
+  setProperty(name, value) { this.values[name] = value; this[name] = value; }
+  removeProperty(name) { delete this.values[name]; delete this[name]; }
+}
+
+class Element {
+  constructor(tagName, documentRef) {
+    this.tagName = String(tagName || 'div').toUpperCase();
+    this.ownerDocument = documentRef;
+    this.children = [];
+    this.parentElement = null;
+    this.attributes = {};
+    this.dataset = {};
+    this.classList = new ClassList();
+    this.style = new Style();
+    this._listeners = new Map();
+    this._innerHTML = '';
+    this._textContent = '';
+  }
+  set id(value) { this.attributes.id = String(value); }
+  get id() { return this.attributes.id || ''; }
+  set className(value) {
+    this.classList.values = new Set(String(value || '').split(/\s+/).filter(Boolean));
+  }
+  get className() { return Array.from(this.classList.values).join(' '); }
+  set innerHTML(value) {
+    this._innerHTML = String(value || '');
+    if (!this._innerHTML) {
+      this.children.forEach(child => { child.parentElement = null; });
+      this.children = [];
+    }
+  }
+  get innerHTML() { return this._innerHTML; }
+  set textContent(value) {
+    this._textContent = String(value ?? '');
+    this.children.forEach(child => { child.parentElement = null; });
+    this.children = [];
+  }
+  get textContent() {
+    return this._textContent + this.children.map(child => child.textContent).join('');
+  }
+  setAttribute(name, value) {
+    const text = String(value);
+    this.attributes[name] = text;
+    if (name === 'class') this.className = text;
+    if (name.startsWith('data-')) {
+      const key = name.slice(5).replace(/-([a-z])/g, (_, char) => char.toUpperCase());
+      this.dataset[key] = text;
+    }
+  }
+  getAttribute(name) { return this.attributes[name] ?? null; }
+  appendChild(child) {
+    child.parentElement = this;
+    this.children.push(child);
+    return child;
+  }
+  append(...children) { children.forEach(child => this.appendChild(child)); }
+  replaceChildren(...children) {
+    this.children.forEach(child => { child.parentElement = null; });
+    this.children = [];
+    children.forEach(child => this.appendChild(child));
+  }
+  contains(candidate) {
+    if (candidate === this) return true;
+    return descendants(this).includes(candidate);
+  }
+  getBoundingClientRect() {
+    const width = Number.parseFloat(
+      this.style.values['--settings-sidebar-width']
+        || this.style.width
+        // This is only a desktop-mode fixture (>620px), not a CSS assertion.
+        || (this.classList.contains('settings-modal-content') ? '800' : '220'),
+    );
+    return { width, height: 600, left: 0, right: width, top: 0, bottom: 600 };
+  }
+  addEventListener(type, handler, options = {}) {
+    if (!this._listeners.has(type)) this._listeners.set(type, []);
+    this._listeners.get(type).push({ handler, once: !!options.once });
+  }
+  removeEventListener(type, handler) {
+    const entries = this._listeners.get(type) || [];
+    this._listeners.set(type, entries.filter(entry => entry.handler !== handler));
+  }
+  dispatchEvent(event) {
+    event.target ||= this;
+    event.currentTarget = this;
+    const entries = [...(this._listeners.get(event.type) || [])];
+    for (const entry of entries) {
+      entry.handler.call(this, event);
+      if (entry.once) this.removeEventListener(event.type, entry.handler);
+    }
+  }
+  click() {
+    this.dispatchEvent({ type: 'click', preventDefault() {}, stopPropagation() {} });
+  }
+  matches(selector) { return matchesSelector(this, selector); }
+  querySelector(selector) { return queryAll(this, selector)[0] || null; }
+  querySelectorAll(selector) { return queryAll(this, selector); }
+  closest(selector) {
+    let node = this;
+    while (node) {
+      if (matchesSelector(node, selector)) return node;
+      node = node.parentElement;
+    }
+    return null;
+  }
+}
+
+function simpleMatch(element, selector) {
+  const text = selector.trim();
+  if (!text) return false;
+  const id = text.match(/#([\w-]+)/);
+  if (id && element.id !== id[1]) return false;
+  for (const match of text.matchAll(/\.([\w-]+)/g)) {
+    if (!element.classList.contains(match[1])) return false;
+  }
+  for (const match of text.matchAll(/\[([\w-]+)(?:="([^"]*)")?\]/g)) {
+    const actual = element.getAttribute(match[1]);
+    if (actual === null) return false;
+    if (match[2] !== undefined && actual !== match[2]) return false;
+  }
+  return true;
+}
+
+function matchesSelector(element, selector) {
+  return selector.split(',').some(part => simpleMatch(element, part));
+}
+
+function descendants(root) {
+  const result = [];
+  const visit = node => {
+    for (const child of node.children || []) {
+      result.push(child);
+      visit(child);
+    }
+  };
+  visit(root);
+  return result;
+}
+
+function queryAll(root, selector) {
+  const selectors = selector.split(',').map(item => item.trim()).filter(Boolean);
+  const nodes = descendants(root);
+  const result = [];
+  for (const candidate of nodes) {
+    if (selectors.some(sel => simpleMatch(candidate, sel))) result.push(candidate);
+  }
+  return result;
+}
+
+class DocumentShim {
+  constructor() {
+    this.body = new Element('body', this);
+    this.head = new Element('head', this);
+    this.listeners = new Map();
+  }
+  createElement(tag) { return new Element(tag, this); }
+  getElementById(id) {
+    return [this.body, this.head, ...descendants(this.body), ...descendants(this.head)]
+      .find(node => node.id === id) || null;
+  }
+  querySelector(selector) {
+    return this.querySelectorAll(selector)[0] || null;
+  }
+  querySelectorAll(selector) {
+    return [...queryAll(this.body, selector), ...queryAll(this.head, selector)];
+  }
+  addEventListener(type, handler) {
+    if (!this.listeners.has(type)) this.listeners.set(type, []);
+    this.listeners.get(type).push(handler);
+  }
+  removeEventListener(type, handler) {
+    this.listeners.set(type, (this.listeners.get(type) || []).filter(item => item !== handler));
+  }
+  dispatch(type, event) {
+    for (const handler of [...(this.listeners.get(type) || [])]) handler(event);
+  }
+}
+
+function buildFixture(document) {
+  const modal = document.createElement('div');
+  modal.id = 'settings-modal';
+  document.body.appendChild(modal);
+
+  const header = document.createElement('div');
+  header.className = 'modal-header';
+  modal.appendChild(header);
+
+  const close = document.createElement('button');
+  close.className = 'close-btn';
+  header.appendChild(close);
+
+  const content = document.createElement('div');
+  content.className = 'settings-modal-content modal-content';
+  modal.appendChild(content);
+
+  const nav = document.createElement('div');
+  nav.className = 'settings-sidebar';
+  content.appendChild(nav);
+
+  const sidebarToggle = document.createElement('button');
+  sidebarToggle.id = 'settings-sidebar-toggle';
+  nav.appendChild(sidebarToggle);
+
+  const sidebarHandle = document.createElement('div');
+  sidebarHandle.id = 'settings-sidebar-resize-handle';
+  nav.appendChild(sidebarHandle);
+
+  const sidebarContent = document.createElement('div');
+  sidebarContent.className = 'settings-sidebar-content';
+  nav.appendChild(sidebarContent);
+
+  const finder = document.createElement('div');
+  sidebarContent.appendChild(finder);
+
+  const searchInput = document.createElement('input');
+  searchInput.id = 'settings-nav-search';
+  finder.appendChild(searchInput);
+
+  const searchResults = document.createElement('div');
+  searchResults.id = 'settings-nav-search-results';
+  searchResults.classList.add('hidden');
+  finder.appendChild(searchResults);
+
+  const panels = document.createElement('div');
+  content.appendChild(panels);
+
+  const makeTab = (id, active = false) => {
+    const button = document.createElement('button');
+    button.setAttribute('data-settings-tab', id);
+    if (active) button.classList.add('active');
+    sidebarContent.appendChild(button);
+    const panel = document.createElement('section');
+    panel.setAttribute('data-settings-panel', id);
+    if (!active) panel.classList.add('hidden');
+    panels.appendChild(panel);
+    return { button, panel };
+  };
+
+  const panelIds = [
+    'services',
+    'added-models',
+    'ai',
+    'search',
+    'integrations',
+    'email',
+    'reminders',
+    'appearance',
+    'shortcuts',
+    'account',
+    'tools',
+    'users',
+    'system',
+  ];
+
+  const settingsPanels = Object.fromEntries(
+    panelIds.map((id, index) => [id, makeTab(id, index === 0)]),
+  );
+
+  return {
+    modal,
+    header,
+    close,
+    content,
+    services: settingsPanels.services,
+    appearance: settingsPanels.appearance,
+    system: settingsPanels.system,
+    settingsPanels,
+    searchInput,
+    searchResults,
+    sidebar: nav,
+    sidebarToggle,
+    sidebarHandle,
+  };
+}
+
+function moduleSource(relativePath) {
+  let source = fs.readFileSync(
+    path.join(__dirname, '../../static/js/settings', relativePath),
+    'utf8',
+  );
+
+  // The production files are real ES modules. This lightweight VM harness
+  // removes imports because dependencies are loaded into the same context,
+  // but each module still needs its own lexical scope so private const/let
+  // bindings do not collide across modules.
+  source = source.replace(/^\s*import[\s\S]*?;\s*$/gm, '');
+
+  // Preserve exported API on globalThis while keeping all non-exported
+  // bindings private inside the module block below.
+  source = source
+    .replace(
+      /\bexport\s+function\s+([A-Za-z_$][\w$]*)\s*\(/g,
+      'globalThis.$1 = function $1(',
+    )
+    .replace(
+      /\bexport\s+const\s+([A-Za-z_$][\w$]*)\s*=/g,
+      'globalThis.$1 =',
+    )
+    .replace(
+      /\bexport\s+let\s+([A-Za-z_$][\w$]*)\s*=/g,
+      'globalThis.$1 =',
+    )
+    .replace(
+      /\bexport\s+var\s+([A-Za-z_$][\w$]*)\s*=/g,
+      'globalThis.$1 =',
+    );
+
+  return `{\n${source}\n}`;
+}
+
+(function runTests() {
+  const document = new DocumentShim();
+  const fixture = buildFixture(document);
+  const dragCalls = [];
+  const dockCalls = [];
+  const removedWindowListeners = [];
+
+  const storage = new Map();
+  const context = {
+    console,
+    document,
+    localStorage: {
+      getItem(key) { return storage.has(key) ? storage.get(key) : null; },
+      setItem(key, value) { storage.set(key, String(value)); },
+      removeItem(key) { storage.delete(key); },
+    },
+    window: {
+      removeEventListener: (...args) => removedWindowListeners.push(args),
+      addEventListener() {},
+    },
+    makeWindowDraggable: (...args) => dragCalls.push(args),
+    clearDockSide: (...args) => dockCalls.push(args),
+    setTimeout: callback => { callback(); return 1; },
+    WeakSet,
+  };
+  vm.createContext(context);
+  vm.runInContext(moduleSource('registry.js'), context, { filename: 'registry.js' });
+  vm.runInContext(moduleSource('search.js'), context, { filename: 'search.js' });
+  vm.runInContext(moduleSource('sidebar.js'), context, { filename: 'sidebar.js' });
+  vm.runInContext(moduleSource('navigation.js'), context, { filename: 'navigation.js' });
+  vm.runInContext(moduleSource('lifecycle.js'), context, { filename: 'lifecycle.js' });
+  vm.runInContext(moduleSource('dom.js'), context, { filename: 'dom.js' });
+
+  const results = [];
+  const check = (test, pass, detail = '') => results.push({ test, pass: Boolean(pass), detail });
+
+  const registryPanelIds = vm.runInContext(
+    'SETTINGS_PANELS.map(panel => panel.id).join(",")',
+    context,
+  );
+  const registryGroupIds = vm.runInContext(
+    'SETTINGS_GROUPS.map(group => group.id).join(",")',
+    context,
+  );
+
+  check(
+    'Settings registry preserves the existing sidebar panel order',
+    registryPanelIds === [
+      'services',
+      'added-models',
+      'ai',
+      'search',
+      'integrations',
+      'email',
+      'reminders',
+      'appearance',
+      'shortcuts',
+      'account',
+      'tools',
+      'users',
+      'system',
+    ].join(','),
+  );
+
+  check(
+    'Settings registry defines the intended information-architecture groups',
+    registryGroupIds === [
+      'models',
+      'communications',
+      'experience',
+      'account',
+      'administration',
+    ].join(','),
+  );
+
+  check(
+    'Settings registry keeps services, models, integrations and admin panels on the existing admin controller',
+    ['services', 'added-models', 'integrations', 'tools', 'users', 'system']
+      .every(id => context.isAdminManagedSettingsTab(id))
+      && ['ai', 'search', 'email', 'reminders', 'appearance', 'shortcuts', 'account']
+        .every(id => !context.isAdminManagedSettingsTab(id)),
+  );
+
+  check(
+    'Settings registry distinguishes admin-only visibility from admin-controlled routing',
+    ['tools', 'users', 'system'].every(id => context.isAdminOnlySettingsTab(id))
+      && ['services', 'added-models', 'integrations']
+        .every(id => !context.isAdminOnlySettingsTab(id)),
+  );
+
+  check(
+    'Settings registry provides search metadata without owning search UI',
+    context.getSettingsPanelSearchText('appearance').includes('theme')
+      && context.getSettingsPanelSearchText('email').includes('smtp')
+      && context.getSettingsPanelSearchText('missing') === '',
+  );
+
+  check(
+    'Settings registry exposes group membership in sidebar order',
+    context.getSettingsPanelsForGroup('communications')
+      .map(panel => panel.id)
+      .join(',') === 'integrations,email,reminders',
+  );
+
+  check(
+    'Settings registry matches every production-style tab and panel in the DOM fixture',
+    context.getSettingsRegistryIssues(fixture.modal).length === 0,
+  );
+
+  check(
+    'Settings search resolves metadata terms in registry order',
+    context.searchSettingsPanels('provider', { isAdmin: true })
+      .map(panel => panel.id)
+      .join(',') === 'services,added-models,search',
+  );
+
+  check(
+    'Settings search excludes admin-only panels for non-admin users',
+    context.searchSettingsPanels('agent tools', { isAdmin: false }).length === 0
+      && context.searchSettingsPanels('agent tools', { isAdmin: true })
+        .map(panel => panel.id)
+        .join(',') === 'tools',
+  );
+
+  check(
+    'Settings search requires all query terms',
+    context.searchSettingsPanels('appearance theme', { isAdmin: false })
+      .map(panel => panel.id)
+      .join(',') === 'appearance',
+  );
+
+  let searchedPanel = null;
+  context.bindSettingsSearch(fixture.modal, {
+    isAdmin: () => false,
+    openPanel(tab) { searchedPanel = tab; },
+  });
+
+  fixture.searchInput.value = 'theme';
+  fixture.searchInput.dispatchEvent({
+    type: 'input',
+    preventDefault() {},
+    stopPropagation() {},
+  });
+
+  check(
+    'Settings finder renders matching production registry results',
+    !fixture.searchResults.classList.contains('hidden')
+      && fixture.searchResults.querySelectorAll('[data-settings-search-result]').length === 1
+      && fixture.searchResults.querySelector('[data-settings-search-result]').dataset.settingsSearchResult === 'appearance',
+  );
+
+  const finderOutsideTarget = document.createElement('div');
+  fixture.content.appendChild(finderOutsideTarget);
+
+  fixture.modal.dispatchEvent({
+    type: 'mousedown',
+    target: finderOutsideTarget,
+    preventDefault() {},
+    stopPropagation() {},
+  });
+
+  check(
+    'Settings finder click-away hides results while retaining the query',
+    fixture.searchInput.value === 'theme'
+      && fixture.searchResults.classList.contains('hidden'),
+  );
+
+  fixture.searchInput.dispatchEvent({
+    type: 'focus',
+    preventDefault() {},
+    stopPropagation() {},
+  });
+
+  check(
+    'Settings finder refocus restores results for an unchanged retained query',
+    fixture.searchInput.value === 'theme'
+      && !fixture.searchResults.classList.contains('hidden')
+      && fixture.searchResults.querySelectorAll('[data-settings-search-result]').length === 1,
+  );
+
+  fixture.searchInput.dispatchEvent({
+    type: 'keydown',
+    key: 'Enter',
+    preventDefault() {},
+    stopPropagation() {},
+  });
+
+  check(
+    'Settings finder Enter opens the first result and resets the finder',
+    searchedPanel === 'appearance'
+      && fixture.searchInput.value === ''
+      && fixture.searchResults.classList.contains('hidden'),
+  );
+
+  searchedPanel = null;
+  fixture.searchInput.value = 'agent tools';
+  fixture.searchInput.dispatchEvent({
+    type: 'input',
+    preventDefault() {},
+    stopPropagation() {},
+  });
+
+  check(
+    'Settings finder does not expose admin-only results to non-admin users',
+    fixture.searchResults.querySelectorAll('[data-settings-search-result]').length === 0
+      && fixture.searchResults.textContent !== '',
+  );
+
+  fixture.searchInput.value = 'theme';
+  fixture.searchInput.dispatchEvent({
+    type: 'input',
+    preventDefault() {},
+    stopPropagation() {},
+  });
+  fixture.searchInput.dispatchEvent({
+    type: 'keydown',
+    key: 'Escape',
+    preventDefault() {},
+    stopPropagation() {},
+  });
+
+  check(
+    'Settings finder Escape clears results without closing Settings',
+    fixture.searchInput.value === ''
+      && fixture.searchResults.classList.contains('hidden'),
+  );
+
+  context.setSettingsSidebarWidth(fixture.modal, 280);
+  check(
+    'Settings sidebar width is clamped and applied through the production controller',
+    fixture.sidebar.style.values['--settings-sidebar-width'] === '280px',
+  );
+
+  const widthStorageKey = 'odysseus-settings-sidebar-width';
+
+  storage.clear();
+  const firstRunSidebar = buildFixture(document);
+  context.bindSettingsSidebar(firstRunSidebar.modal);
+  check(
+    'Settings sidebar first bind uses the declared 220px default when storage is empty',
+    firstRunSidebar.sidebar.style.values['--settings-sidebar-width'] === '220px',
+  );
+
+  storage.clear();
+  storage.set(widthStorageKey, '276');
+  const storedSidebar = buildFixture(document);
+  context.bindSettingsSidebar(storedSidebar.modal);
+  check(
+    'Settings sidebar first bind restores a valid stored width',
+    storedSidebar.sidebar.style.values['--settings-sidebar-width'] === '276px',
+  );
+
+  storage.clear();
+  storage.set(widthStorageKey, 'not-a-number');
+  const malformedSidebar = buildFixture(document);
+  context.bindSettingsSidebar(malformedSidebar.modal);
+  check(
+    'Settings sidebar first bind falls back to default for malformed storage',
+    malformedSidebar.sidebar.style.values['--settings-sidebar-width'] === '220px',
+  );
+
+  storage.clear();
+  storage.set(widthStorageKey, '10');
+  const minimumSidebar = buildFixture(document);
+  context.bindSettingsSidebar(minimumSidebar.modal);
+
+  storage.clear();
+  storage.set(widthStorageKey, '999');
+  const maximumSidebar = buildFixture(document);
+  context.bindSettingsSidebar(maximumSidebar.modal);
+
+  check(
+    'Settings sidebar first bind clamps stored widths to declared bounds',
+    minimumSidebar.sidebar.style.values['--settings-sidebar-width'] === '150px'
+      && maximumSidebar.sidebar.style.values['--settings-sidebar-width'] === '340px',
+  );
+
+  context.setSettingsSidebarCollapsed(fixture.modal, true);
+  check(
+    'Settings sidebar collapse leaves the compact navigation rail state active',
+    fixture.sidebar.classList.contains('settings-sidebar-collapsed')
+      && fixture.sidebarToggle.getAttribute('aria-label') === 'Expand settings navigation',
+  );
+
+  context.setSettingsSidebarCollapsed(fixture.modal, false, { width: 260 });
+  check(
+    'Settings sidebar expansion restores the requested expanded width',
+    !fixture.sidebar.classList.contains('settings-sidebar-collapsed')
+      && fixture.sidebar.style.values['--settings-sidebar-width'] === '260px',
+  );
+
+  // Keyboard behavior must be exercised on a fixture that went through the
+  // real binding path; direct controller calls above intentionally do not bind
+  // event listeners.
+  storage.clear();
+  const keyboardSidebar = buildFixture(document);
+  context.bindSettingsSidebar(keyboardSidebar.modal);
+
+  context.setSettingsSidebarWidth(
+    keyboardSidebar.modal,
+    150,
+    { persist: false },
+  );
+
+  keyboardSidebar.sidebarHandle.dispatchEvent({
+    type: 'keydown',
+    key: 'ArrowLeft',
+    preventDefault() {},
+    stopPropagation() {},
+  });
+
+  check(
+    'ArrowLeft at the sidebar minimum collapses the rail instead of getting stuck at 150px',
+    keyboardSidebar.sidebar.classList.contains('settings-sidebar-collapsed'),
+  );
+
+  context.setSettingsSidebarCollapsed(
+    keyboardSidebar.modal,
+    false,
+    { width: 220, persist: false },
+  );
+
+  check(
+    'resizable Settings separator exposes its current ARIA range and value',
+    keyboardSidebar.sidebarHandle.getAttribute('aria-valuemin') === '150'
+      && keyboardSidebar.sidebarHandle.getAttribute('aria-valuemax') === '340'
+      && keyboardSidebar.sidebarHandle.getAttribute('aria-valuenow') === '220',
+  );
+
+  check('byId resolves elements through the production DOM helper', context.byId('settings-modal') === fixture.modal);
+
+  context.activateSettingsPanel(fixture.modal, 'appearance');
+  check(
+    'activateSettingsPanel switches sidebar and panel state together',
+    fixture.appearance.button.classList.contains('active')
+      && !fixture.appearance.panel.classList.contains('hidden')
+      && !fixture.services.button.classList.contains('active')
+      && fixture.services.panel.classList.contains('hidden'),
+  );
+  check('getActiveSettingsTab reports the active panel', context.getActiveSettingsTab(fixture.modal) === 'appearance');
+
+  let activated = null;
+  let delegated = null;
+  context.bindSettingsNavigation(fixture.modal, {
+    openAdminTab(tab) { delegated = tab; return tab === 'system'; },
+    onPanelActivated(tab) { activated = tab; },
+  });
+  fixture.services.button.click();
+  check(
+    'normal navigation activates locally and notifies the coordinator',
+    activated === 'services' && fixture.services.button.classList.contains('active'),
+  );
+  activated = null;
+  fixture.system.button.click();
+  check(
+    'admin navigation delegates without performing a second local activation',
+    delegated === 'system' && activated === null && fixture.services.button.classList.contains('active'),
+  );
+
+  context.bindSettingsDrag(fixture.modal);
+  check(
+    'drag binding preserves the existing Settings drag contract',
+    dragCalls.length === 1
+      && dragCalls[0][0] === fixture.modal
+      && dragCalls[0][1].content === fixture.content
+      && dragCalls[0][1].header === fixture.header
+      && dragCalls[0][1].enableDock === true
+      && dragCalls[0][1].skipSelector === 'button, input, select, .theme-opacity-wrap',
+  );
+
+  let disconnected = 0;
+  fixture.modal.classList.add('modal-left-docked');
+  fixture.content.style.setProperty('left', '123px');
+  fixture.content.dataset._tileZone = 'left';
+  fixture.content._leftDockNavObs = {
+    navObs: { disconnect() { disconnected += 1; } },
+    reanchor() {},
+  };
+  context.resetSettingsWindowPlacement(fixture.modal);
+  check(
+    'window placement reset clears docking observers and inline placement',
+    !fixture.modal.classList.contains('modal-left-docked')
+      && dockCalls.some(call => call[0] === 'left' && call[1] === fixture.modal)
+      && disconnected === 1
+      && !('_tileZone' in fixture.content.dataset)
+      && fixture.content.style.left === undefined
+      && removedWindowListeners.some(call => call[0] === 'resize'),
+  );
+
+  fixture.modal.classList.add('modal-right-docked', 'hidden');
+  context.showSettingsModal(fixture.modal);
+  check(
+    'showSettingsModal restores a hidden modal before showing it',
+    !fixture.modal.classList.contains('hidden')
+      && !fixture.modal.classList.contains('modal-right-docked')
+      && dockCalls.some(call => call[0] === 'right'),
+  );
+
+  let closeCount = 0;
+  context.bindSettingsClose(fixture.modal, {
+    closeSettings() { closeCount += 1; },
+    isTouchInsideModal() { return false; },
+  });
+
+  const form = document.createElement('div');
+  form.id = 'unified-intg-form';
+  form.style.display = '';
+  form.appendChild(document.createElement('input'));
+  fixture.content.appendChild(form);
+  document.dispatch('keydown', {
+    key: 'Escape',
+    preventDefault() {},
+    stopPropagation() {},
+  });
+  check(
+    'Escape closes an inner integration editor before closing Settings',
+    form.style.display === 'none' && form.children.length === 0 && closeCount === 0,
+  );
+
+  document.dispatch('keydown', {
+    key: 'Escape',
+    preventDefault() {},
+    stopPropagation() {},
+  });
+  check('Escape closes Settings when no nested flow is active', closeCount === 1);
+
+  const popover = document.createElement('div');
+  popover.setAttribute('data-popover-open', '1');
+  popover.style.display = 'block';
+  fixture.content.appendChild(popover);
+  document.dispatch('keydown', {
+    key: 'Escape',
+    preventDefault() {},
+    stopPropagation() {},
+  });
+  check('Escape leaves Settings open while a transient popover is active', closeCount === 1);
+  popover.classList.add('hidden');
+
+  context.hideSettingsModal(fixture.modal);
+  check(
+    'hideSettingsModal preserves the closing animation fallback semantics',
+    fixture.modal.classList.contains('hidden') && !fixture.content.classList.contains('modal-closing'),
+  );
+
+  console.log(JSON.stringify(results));
+  if (results.some(result => !result.pass)) process.exitCode = 1;
+})();