Dodaios is an open-source agent OS for your desktop: it runs your coding agents, browser and apps by voice or chat, on your own machine. Formerly Personal Jarvis.
Python agent-orchestrationai-agentai-coding-assistantclaude-codecoding-agentcomputer-usedesktop-applocal-firstmcppersonal-jarvisvoice-assistantvoice-coding
"""``dodaios.core.update_contract`` — where a release tells its updater to look.
Two things are pinned here. The tracked ``install/update-contract.json`` must
describe THIS tree truthfully, because the version before a release believes
it. And the reader must fall back to the default locations for anything it
cannot trust, because those locations are what an update is checked against.
"""
from __future__ import annotations
import json
import re
import subprocess
import sys
from dataclasses import asdict, replace
from pathlib import Path
import pytest
import dodaios
from dodaios.core.branding import (
CONFIG_FILE_NAME,
LEGACY_CONFIG_FILE_NAMES,
MACOS_APP_DIR_NAME,
MACOS_BUNDLE_ID,
)
from dodaios.core.process_utils import NO_WINDOW_CREATIONFLAGS
from dodaios.core.update_contract import (
CONTRACT_PATH,
CONTRACT_SCHEMA,
DEFAULT_CONTRACT,
VERSION_PATTERN,
UpdateContract,
parse_update_contract,
read_update_contract,
)
REPO = Path(__file__).resolve().parents[3]
def _document(**overrides: object) -> str:
return json.dumps({"schema": CONTRACT_SCHEMA, **overrides})
# --------------------------------------------------------------------------- #
# The tracked contract describes this tree
# --------------------------------------------------------------------------- #
def test_the_tracked_contract_is_the_default_contract() -> None:
"""A release without the file must behave exactly like this one.
Except for the rollback hook: it belongs to the release that ships it, and
a tree that states none has nothing to undo.
"""
payload = json.loads((REPO / CONTRACT_PATH).read_text(encoding="utf-8"))
assert payload.pop("schema") == CONTRACT_SCHEMA
hook = payload.pop("rollback_hook")
stated = {
key: list(value) if isinstance(value, tuple) else value
for key, value in asdict(DEFAULT_CONTRACT).items()
if value is not None
}
assert payload == stated
assert read_update_contract(REPO) == replace(DEFAULT_CONTRACT, rollback_hook=hook)
def test_the_rollback_hook_is_a_file_this_tree_tracks() -> None:
# The updater runs only a tracked file; a hook it skips undoes nothing.
hook = read_update_contract(REPO).rollback_hook
assert hook is not None
assert (REPO / hook).is_file()
tracked = subprocess.run(
["git", "ls-files", "--error-unmatch", "--", hook],
cwd=REPO,
capture_output=True,
check=False,
creationflags=NO_WINDOW_CREATIONFLAGS,
)
assert tracked.returncode == 0, f"{hook} is not tracked"
def test_the_contract_points_at_files_this_tree_really_has() -> None:
contract = read_update_contract(REPO)
# main tracks no bundle (release tags carry it): the contract names the
# directory the frontend build writes, next to its sources.
bundle = REPO / contract.ui_bundle_dir
vite = (bundle.parent / "frontend" / "vite.config.ts").read_text(encoding="utf-8")
assert f'outDir: "../{bundle.name}"' in vite
assert (REPO / (contract.launcher_module.replace(".", "/") + ".py")).is_file()
version_text = (REPO / contract.version_file).read_text(encoding="utf-8")
match = re.search(VERSION_PATTERN, version_text)
assert match is not None
assert match.group(1) == dodaios.__version__
def test_a_package_move_publishes_a_contract_this_reader_follows() -> None:
"""The codemod that moves the package rewrites the tracked contract. An
installed copy of THIS version reads the result from the new release, so
it has to parse - under this reader - to the moved locations."""
from scripts.rename import rewrite_package as codemod
package = dodaios.__name__
moved = "pkg_after_the_move"
layout = ["__init__.py", "ui/web/launcher.py", "ui/web/dist/index.html"]
# The bundle is only built, never tracked on main; its sources are.
assert all((REPO / package / path).is_file() for path in layout[:2])
assert (REPO / package / "ui/web/frontend/package.json").is_file()
shipped = (REPO / CONTRACT_PATH).read_bytes()
published = codemod.Rewriter(package, moved, layout).transform(CONTRACT_PATH, shipped)
hook = read_update_contract(REPO).rollback_hook
assert hook is not None and hook.startswith(f"{package}/")
assert parse_update_contract(published.decode("utf-8")) == replace(
read_update_contract(REPO),
ui_bundle_dir=f"{moved}/ui/web/dist",
launcher_module=f"{moved}.ui.web.launcher",
version_file=f"{moved}/__init__.py",
rollback_hook=f"{moved}/{hook.removeprefix(f'{package}/')}",
)
def test_the_contract_agrees_with_every_other_copy_of_these_names() -> None:
from dodaios.autostart.command import LAUNCHER_MODULE as autostart_launcher
from dodaios.ui import relauncher
# Legacy name first: an existing jarvis.toml stays the configuration, and
# an updater from before ``config_files`` reads the one name it knows.
assert DEFAULT_CONTRACT.config_files == (*LEGACY_CONFIG_FILE_NAMES, CONFIG_FILE_NAME)
assert DEFAULT_CONTRACT.config_file == LEGACY_CONFIG_FILE_NAMES[0]
assert DEFAULT_CONTRACT.macos_app_dir_name == MACOS_APP_DIR_NAME
assert DEFAULT_CONTRACT.macos_bundle_id == MACOS_BUNDLE_ID
assert DEFAULT_CONTRACT.launcher_module == autostart_launcher
assert relauncher.LAUNCHER_MODULE == DEFAULT_CONTRACT.launcher_module
assert DEFAULT_CONTRACT.rollback_hook is None
def test_the_reader_is_standard_library_only() -> None:
"""The restart helper loads it; it must not drag the runtime in."""
probe = (
"import sys\n"
"import dodaios.core.update_contract\n"
"print('\\n'.join(sorted(m for m in sys.modules if m.split('.')[0] in "
"{'pydantic', 'fastapi', 'httpx', 'loguru'})))\n"
)
proc = subprocess.run( # noqa: S603 - fixed argv, this interpreter
[sys.executable, "-c", probe],
capture_output=True,
text=True,
encoding="utf-8",
errors="replace",
timeout=120,
cwd=str(REPO),
creationflags=NO_WINDOW_CREATIONFLAGS,
)
assert proc.returncode == 0, proc.stderr
assert proc.stdout.strip() == ""
# --------------------------------------------------------------------------- #
# Reading
# --------------------------------------------------------------------------- #
def test_a_tree_without_the_file_gets_the_default_locations(tmp_path: Path) -> None:
assert read_update_contract(tmp_path) == DEFAULT_CONTRACT
def test_a_moved_tree_is_read_as_it_describes_itself(tmp_path: Path) -> None:
(tmp_path / "install").mkdir()
(tmp_path / CONTRACT_PATH).write_text(
_document(
ui_bundle_dir="newpkg/ui/web/dist",
launcher_module="newpkg.ui.web.launcher",
version_file="newpkg/__init__.py",
config_file="newpkg.toml",
macos_app_dir_name="New Product.app",
macos_bundle_id="com.new-product.desktop",
rollback_hook="install/rollback.py",
),
encoding="utf-8",
)
assert read_update_contract(tmp_path) == UpdateContract(
ui_bundle_dir="newpkg/ui/web/dist",
launcher_module="newpkg.ui.web.launcher",
version_file="newpkg/__init__.py",
config_file="newpkg.toml",
config_files=("newpkg.toml",),
macos_app_dir_name="New Product.app",
macos_bundle_id="com.new-product.desktop",
rollback_hook="install/rollback.py",
)
def test_a_key_the_document_leaves_out_keeps_its_default() -> None:
contract = parse_update_contract(_document(launcher_module="newpkg.launcher"))
assert contract.launcher_module == "newpkg.launcher"
assert contract.ui_bundle_dir == DEFAULT_CONTRACT.ui_bundle_dir
assert contract.config_file == DEFAULT_CONTRACT.config_file
def test_an_unknown_key_is_ignored() -> None:
contract = parse_update_contract(_document(config_file="x.toml", data_dir="somewhere"))
assert contract.config_file == "x.toml"
def test_an_explicit_null_hook_means_no_hook() -> None:
assert parse_update_contract(_document(rollback_hook=None)).rollback_hook is None
def test_a_byte_order_mark_does_not_hide_the_contract(tmp_path: Path) -> None:
(tmp_path / "install").mkdir()
(tmp_path / CONTRACT_PATH).write_bytes(
b"\xef\xbb\xbf" + _document(config_file="x.toml").encode("utf-8")
)
assert read_update_contract(tmp_path).config_file == "x.toml"
# --------------------------------------------------------------------------- #
# Refusing
# --------------------------------------------------------------------------- #
@pytest.mark.parametrize(
"text",
[
"",
"not json",
"[]",
'"dodaios/ui/web/dist"',
json.dumps({"ui_bundle_dir": "newpkg/dist"}), # no schema at all
json.dumps({"schema": 2, "ui_bundle_dir": "newpkg/dist"}),
json.dumps({"schema": "1", "ui_bundle_dir": "newpkg/dist"}),
json.dumps({"schema": True, "ui_bundle_dir": "newpkg/dist"}),
json.dumps({"schema": 1.0, "ui_bundle_dir": "newpkg/dist"}),
],
)
def test_an_unreadable_or_unknown_document_is_the_default_contract(text: str) -> None:
assert parse_update_contract(text) == DEFAULT_CONTRACT
@pytest.mark.parametrize(
"bad_path",
[
"/etc/passwd",
"../outside/dist",
"pkg/../../outside",
"pkg/./dist",
"./pkg/dist",
"pkg//dist",
"pkg/dist/",
"C:/Windows/System32",
"C:\\Windows\\System32",
"pkg\\ui\\dist",
"pkg/ui dist",
"~/dist",
"$HOME/dist",
"pkg/dist\n",
"",
"x" * 300,
42,
None,
["pkg", "dist"],
],
)
@pytest.mark.parametrize("field", ["ui_bundle_dir", "version_file"])
def test_a_path_that_could_leave_the_checkout_rejects_the_document(
field: str, bad_path: object
) -> None:
text = _document(**{field: bad_path, "launcher_module": "newpkg.launcher"})
# The valid launcher is dropped too: a document is believed whole or not at all.
assert parse_update_contract(text) == DEFAULT_CONTRACT
@pytest.mark.parametrize(
"bad_module",
[
"newpkg.launcher; import os",
"newpkg launcher",
"newpkg..launcher",
".newpkg.launcher",
"newpkg.launcher.",
"1newpkg.launcher",
"newpkg/launcher",
"-c",
"newpkg.launcher\n",
"",
7,
None,
],
)
def test_a_launcher_that_is_not_a_module_name_rejects_the_document(
bad_module: object,
) -> None:
assert parse_update_contract(_document(launcher_module=bad_module)) == DEFAULT_CONTRACT
@pytest.mark.parametrize(
"bad_name", ["sub/dir.toml", "..", ".", "a\\b.toml", "", "name with space.toml", 3, None]
)
def test_a_config_name_that_is_not_a_plain_file_name_rejects_the_document(
bad_name: object,
) -> None:
assert parse_update_contract(_document(config_file=bad_name)) == DEFAULT_CONTRACT
@pytest.mark.parametrize(
"bad_name", ["Product", "../Evil.app", "sub/Product.app", ".app", " Product.app", "", 5, None]
)
def test_an_app_name_that_is_not_one_bundle_directory_rejects_the_document(
bad_name: object,
) -> None:
assert parse_update_contract(_document(macos_app_dir_name=bad_name)) == DEFAULT_CONTRACT
@pytest.mark.parametrize(
"bad_id",
["desktop", "com..desktop", ".com.app", "com.app.", "com/app", "com.app name", "", 9, None],
)
def test_a_bundle_id_that_is_not_a_reverse_dns_name_rejects_the_document(
bad_id: object,
) -> None:
assert parse_update_contract(_document(macos_bundle_id=bad_id)) == DEFAULT_CONTRACT
@pytest.mark.parametrize(
"bad_hook",
["../rollback.py", "/opt/rollback.py", "install/rollback.sh", "install/rollback", "", 1, []],
)
def test_a_hook_that_is_not_a_script_inside_the_tree_rejects_the_document(
bad_hook: object,
) -> None:
assert parse_update_contract(_document(rollback_hook=bad_hook)) == DEFAULT_CONTRACT
def test_an_oversized_file_is_not_a_contract(tmp_path: Path) -> None:
(tmp_path / "install").mkdir()
padded = json.dumps(
{"schema": CONTRACT_SCHEMA, "config_file": "x.toml", "padding": "p" * 20_000}
)
(tmp_path / CONTRACT_PATH).write_text(padded, encoding="utf-8")
assert read_update_contract(tmp_path) == DEFAULT_CONTRACT
def test_a_file_that_is_not_utf8_is_not_a_contract(tmp_path: Path) -> None:
(tmp_path / "install").mkdir()
(tmp_path / CONTRACT_PATH).write_bytes(b'{"schema": 1, "config_file": "\xff\xfe.toml"}')
assert read_update_contract(tmp_path) == DEFAULT_CONTRACT
# --------------------------------------------------------------------------- #
# Schema 1, frozen
# --------------------------------------------------------------------------- #
# The exact document this version ships, and documents a later release may
# publish for this version to read. An installed copy keeps the reader it was
# released with, so these must keep parsing to these values: tightening a rule
# here silently turns a published contract into "use the defaults", which for a
# release that moved its files means every update rolls back.
# The contract this tree ships: the earlier single name for the updaters that
# read only ``config_file``, and every name for the ones that read the list.
# The macOS bundle has its current name (the installer renames it in place,
# under the bundle id it always had), and a failed update gives it back the
# name the revision it falls back to knows.
SHIPPED_DOCUMENT = """{
"schema": 1,
"ui_bundle_dir": "dodaios/ui/web/dist",
"launcher_module": "dodaios.ui.web.launcher",
"version_file": "dodaios/__init__.py",
"config_file": "jarvis.toml",
"config_files": ["jarvis.toml", "dodaios.toml"],
"macos_app_dir_name": "Dodaios.app",
"macos_bundle_id": "com.personal-jarvis.desktop",
"rollback_hook": "dodaios/setup/update_rollback.py"
}
"""
SCHEMA_1_GOLDEN = [
(
"""{
"schema": 1,
"ui_bundle_dir": "dodaios/ui/web/dist",
"launcher_module": "dodaios.ui.web.launcher",
"version_file": "dodaios/__init__.py",
"config_file": "jarvis.toml",
"macos_app_dir_name": "Personal Jarvis.app",
"macos_bundle_id": "com.personal-jarvis.desktop"
}
""",
UpdateContract(
ui_bundle_dir="dodaios/ui/web/dist",
launcher_module="dodaios.ui.web.launcher",
version_file="dodaios/__init__.py",
config_file="jarvis.toml",
config_files=("jarvis.toml",),
macos_app_dir_name="Personal Jarvis.app",
macos_bundle_id="com.personal-jarvis.desktop",
rollback_hook=None,
),
),
(
SHIPPED_DOCUMENT,
UpdateContract(
ui_bundle_dir="dodaios/ui/web/dist",
launcher_module="dodaios.ui.web.launcher",
version_file="dodaios/__init__.py",
config_file="jarvis.toml",
config_files=("jarvis.toml", "dodaios.toml"),
macos_app_dir_name="Dodaios.app",
macos_bundle_id="com.personal-jarvis.desktop",
rollback_hook="dodaios/setup/update_rollback.py",
),
),
(
'{"schema": 1, "ui_bundle_dir": "dodaios/ui/web/dist",'
' "launcher_module": "dodaios.ui.web.launcher",'
' "version_file": "dodaios/__init__.py", "config_file": "dodaios.toml",'
' "macos_app_dir_name": "Dodaios.app", "macos_bundle_id": "ai.dodaios.desktop",'
' "rollback_hook": "install/rollback_hook.py", "a_key_from_the_future": [1, 2]}',
UpdateContract(
ui_bundle_dir="dodaios/ui/web/dist",
launcher_module="dodaios.ui.web.launcher",
version_file="dodaios/__init__.py",
config_file="dodaios.toml",
config_files=("dodaios.toml",),
macos_app_dir_name="Dodaios.app",
macos_bundle_id="ai.dodaios.desktop",
rollback_hook="install/rollback_hook.py",
),
),
(
'{"schema": 1, "ui_bundle_dir": "src/app_2/ui.web/dist-prod",'
' "launcher_module": "_app2.ui.web.launcher_v2",'
' "version_file": "src/app_2/_version.py", "config_file": ".app-2.toml",'
' "macos_app_dir_name": "App 2 (beta)-x.app"}',
None, # the app name carries parentheses, which no rule allows
),
(
'{"schema": 1, "ui_bundle_dir": "src/app_2/ui.web/dist-prod",'
' "launcher_module": "_app2.ui.web.launcher_v2",'
' "version_file": "src/app_2/_version.py", "config_file": ".app-2.toml",'
' "macos_app_dir_name": "App 2 beta-x.app", "macos_bundle_id": "io.app-2.Desktop"}',
UpdateContract(
ui_bundle_dir="src/app_2/ui.web/dist-prod",
launcher_module="_app2.ui.web.launcher_v2",
version_file="src/app_2/_version.py",
config_file=".app-2.toml",
config_files=(".app-2.toml",),
macos_app_dir_name="App 2 beta-x.app",
macos_bundle_id="io.app-2.Desktop",
rollback_hook=None,
),
),
]
@pytest.mark.parametrize(("document", "expected"), SCHEMA_1_GOLDEN)
def test_schema_1_documents_keep_their_meaning(
document: str, expected: UpdateContract | None
) -> None:
assert parse_update_contract(document) == (expected or DEFAULT_CONTRACT)
def test_the_shipped_contract_is_the_first_golden_document() -> None:
"""Byte for byte: what an installed copy of the previous version will read."""
shipped = (REPO / CONTRACT_PATH).read_bytes().replace(b"\r\n", b"\n")
assert shipped.decode("utf-8") == SHIPPED_DOCUMENT
# The single name an older updater reads is a file such an install has.
assert json.loads(SHIPPED_DOCUMENT)["config_file"] == LEGACY_CONFIG_FILE_NAMES[0]
def test_a_document_that_names_one_config_file_means_only_that_one() -> None:
contract = parse_update_contract(_document(config_file="x.toml"))
assert contract.config_files == ("x.toml",)
def test_the_config_file_list_is_read_in_order() -> None:
contract = parse_update_contract(_document(config_files=["b.toml", "a.toml"]))
assert contract.config_files == ("b.toml", "a.toml")
# A list stated without the single name keeps that name's default.
assert contract.config_file == DEFAULT_CONTRACT.config_file
@pytest.mark.parametrize(
"bad",
[[], "jarvis.toml", ["../jarvis.toml"], ["a.toml", "a.toml"], [1], ["a.toml"] * 9],
)
def test_an_invalid_config_file_list_rejects_the_document(bad: object) -> None:
assert parse_update_contract(_document(config_files=bad)) == DEFAULT_CONTRACT